pr-shepherd 0.52.0 → 0.53.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.52.0",
+  "version": "0.53.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -147,20 +147,24 @@ needed, every selected PR is complete, the bounded timeout expires, or `--until-
 configured GraphQL quota-warning band. Explicit PR sets give each actionable row an exact single-PR
 `pollCommand`, so independent rows can proceed before the next aggregate poll.
 
-Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself; only
-`--stack --merge` can emit a complete-stack merge command for the agent. An unready layer (draft, missing a READY
-receipt, conflicting, failing, or stale) returns stack-level `SHEPHERD` with one-PR Shepherd instructions for
-the affected layers. A draft or other unready lower layer marks every higher open layer with
-`blockedByPr`; review and CI sessions on independent layers may proceed concurrently, but an upper
-draft cannot transition to ready until every lower layer has its READY receipt. A queued stack
-returns `WAIT`. A terminal READY or fully merged stack returns `CANCEL`. Closed or unverified
+Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself. Every
+layer that still has work gets its own one-PR session on the same tick, including a clean draft
+whose session marks it ready. Layers do not wait for a lower layer's READY receipt, so their
+ready-delays overlap. With automatic mark-ready disabled, the instructions ask the agent to mark
+a clean draft ready after its probe. A queued stack, or one whose remaining layers can only wait,
+returns `WAIT`; an idle `WAIT` that stays unchanged past the stall timeout returns `ESCALATE` with
+`stall-timeout`. A terminal READY or fully merged stack returns `CANCEL`. Closed or unverified
 topology returns `ESCALATE` for human direction after any other shepherdable PRs are handled;
 until then, `SHEPHERD` remains the immediate action and lists the human blockers too.
 
-With `--stack --merge`, a fully reconciled and READY stack returns `MERGE` with a `gh stack merge`
-command for the agent to run, checking and installing the optional `github/gh-stack` extension first
-when necessary. It then rechecks until every layer merges and returns `CANCEL`. API and MCP
-aggregate calls perform one summary tick and leave recurrence to the caller.
+With `--stack --merge`, the highest open layer whose open lower layers all have current READY
+receipts, and whose bottom open layer GitHub has retargeted onto the stack base, returns `MERGE`
+with `gh stack merge <that PR number> --yes --squash`. That lands the named layer and every
+unmerged layer below it. When the base uses a merge queue, the same command queues the prefix
+together and GitHub evaluates each layer from the bottom; a failure ejects that layer and those
+above it. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
+the next layer, so the rerun continues until the stack returns `CANCEL`. API and MCP aggregate
+calls perform one summary tick and leave recurrence to the caller.
 
 Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds`, `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default.
 
@@ -199,7 +203,7 @@ Unsupported platforms fail closed with that same exit code.
 
 ### Clean Local State
 
-`pr-shepherd` stores seen markers, fix-attempt counters, stall fingerprints, ready-delay markers, and logs under `$PR_SHEPHERD_STATE_DIR` (default `$TMPDIR/pr-shepherd-state`).
+`pr-shepherd` stores seen markers, fix-attempt counters, stall fingerprints, ready-delay markers, and logs under `$PR_SHEPHERD_STATE_DIR` (default: `pr-shepherd-state` in the per-user temp dir; see [configuration](docs/configuration.md#environment-variables)).
 
 ```sh
 pr-shepherd admin clean current
@@ -271,6 +275,7 @@ Replace `<version>` with a published version. Full config-file examples, tool sc
 Create `.pr-shepherdrc.yml` in your project root, an ancestor directory, or `$HOME`. Every file on the walk is deep-merged; closer directories override farther ones.
 
 ```yaml
+cliCommand: [pnpm, exec, pr-shepherd] # launcher for emitted commands; defaults to [pr-shepherd]
 ignoreChecks:
   - "Kilo Code Review"
 iterate:

package/bin/cli/help-command-pages.d.mts

@@ -194,7 +194,7 @@ Flags:
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.

package/bin/cli/help-iterate-poll-pages.d.mts

@@ -1,4 +1,4 @@
 export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
 /** Public help page for the default PR polling invocation. */
 export declare const DEFAULT_USAGE: string;

package/bin/cli/help-iterate-poll-pages.mjs

@@ -53,10 +53,10 @@ Poll flags:
   --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.
   --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).
   --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).
-  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.
+  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.
   --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.
   --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.
-  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
+  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.
 
 Forwarded iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
@@ -71,7 +71,7 @@ Forwarded iterate flags:
 Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
 for --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
 an explicit unit (4.5m).
-Each WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.
+Each WAIT tick writes a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.
 FIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.
 With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.
 
@@ -83,6 +83,7 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   13  ESCALATE
   14  CANCEL (closed without merging)
   15  MERGE
+  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 /** Public help page for the default PR polling invocation. */
 export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]")

package/bin/cli/help-top-page.d.mts

@@ -1 +1 @@
-export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd --stack PR [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd --stack PR [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";

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

@@ -48,10 +48,10 @@ Iterate flags:
 Polling flags:
   --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).
   --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).
-  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.
+  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.
   --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.
   --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.
-  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
+  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.
 
 Clean variants:
   pr [number]          Remove state for one PR. Defaults to current branch PR.
@@ -68,6 +68,7 @@ Exit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).
   13  ESCALATE
   14  CANCEL (closed without merging)
   15  MERGE
+  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)
 See docs/exit-codes.md for the full sysexits.h error-code table.
 
 Duration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).

package/bin/cli/help.d.mts

@@ -194,7 +194,7 @@ Flags:
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
@@ -258,7 +258,7 @@ On POSIX, the final body-file path entry must be a readable regular file in a tr
 symlinks, FIFOs, devices, and unreadable paths exit 66. Unsupported platforms fail closed with exit 66.
 --help, -h                      Print this help and exit before any I/O.`;
     readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
-    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd --stack PR [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd --stack PR [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
 };
 /** Resolve help keys for nested public commands before any command I/O. */
 export declare function helpKeyForArgs(args: string[]): keyof typeof USAGE;

package/bin/cli/iterate-instructions.mjs

@@ -1,9 +1,14 @@
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 import { inlineCode } from "../util/markdown.mjs";
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
+import { AUTO_MARK_READY_DISABLED_HOLD } from "../commands/stack-work.mjs";
+import { buildPrShepherdCommand } from "./runner.mjs";
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
+            if (result.stackDraftHold)
+                return [buildStackDraftHoldInstruction(result, result.stackDraftHold)];
             if (result.quotaWarning) {
                 return [
                     buildQuotaAwareContinuation(result.quotaWarning, "Non-terminal — no action needed this tick."),
@@ -49,6 +54,23 @@ export function buildSimpleIterateInstructions(result) {
         }
     }
 }
+/**
+ * A held stack draft cannot advance by repeating its one-PR session, so hand control back
+ * to the stack selector instead of asking for another immediate iteration.
+ */
+function buildStackDraftHoldInstruction(result, hold) {
+    const stackCommand = buildPrShepherdCommand([
+        "--stack",
+        formatPrUrl(result.repo, result.pr),
+        "--until-terminal",
+    ]).text;
+    const handoff = `a \`--stack\` selector listed this session, finish that selector's remaining steps and rerun it with its original flags; otherwise run ${inlineCode(stackCommand)}, adding \`--merge\` when merging was requested.`;
+    const reason = hold.kind === "auto-mark-ready-disabled" ? AUTO_MARK_READY_DISABLED_HOLD : hold.kind;
+    const instruction = `PR #${result.pr} stays in draft because ${reason}, so repeating this one-PR session cannot advance it. If ${handoff}`;
+    return result.quotaWarning
+        ? buildQuotaAwareContinuation(result.quotaWarning, instruction)
+        : instruction;
+}
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }

package/bin/cli/iterate-lean.mjs

@@ -72,6 +72,7 @@ export function projectIterateLean(result, opts) {
             return {
                 ...base,
                 ...(result.deferredWork && { deferredWork: result.deferredWork }),
+                ...(result.stackDraftHold && { stackDraftHold: result.stackDraftHold }),
                 log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };

package/bin/cli/poll-summary-formatter.mjs

@@ -43,12 +43,11 @@ function formatItem(item) {
         : "";
     const readyDelay = item.remainingSeconds !== undefined ? ` · ready delay \`${item.remainingSeconds}s\`` : "";
     const readyReceipt = item.readyReceipt ? " · Shepherd READY completion `verified`" : "";
-    const blockedBy = item.blockedByPr ? ` · stack blocked by PR #${item.blockedByPr}` : "";
     const checks = item.checks;
     const review = item.review;
     return [
         `- [PR #${item.pr}: ${escapeMarkdownText(item.title)}](${item.url}) [${item.action.toUpperCase()}]`,
-        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${blockedBy}${stack}`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${stack}`,
         `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
         ...(checks
             ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]
@@ -62,7 +61,9 @@ function formatItem(item) {
             ]
             : []),
         `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
-        ...(item.pollCommand ? [`  - pollCommand: \`${item.pollCommand}\``] : []),
+        ...(item.pollCommand
+            ? [`  - pollCommand: \`${item.pollCommand}\`${item.pollProbe ? " · bounded probe" : ""}`]
+            : []),
     ].join("\n");
 }
 function formatCounts(counts, suffix) {

package/bin/cli/runner.d.mts

@@ -2,6 +2,7 @@ interface PrShepherdCommand {
     argv: string[];
     text: string;
 }
+/** Every emitted pr-shepherd command starts with the configured `cliCommand` launcher. */
 export declare function buildPrShepherdCommand(args: string[]): PrShepherdCommand;
 export declare function renderShellCommand(argv: string[]): string;
 export {};

package/bin/cli/runner.mjs

@@ -1,5 +1,7 @@
+import { loadConfig } from "../config/load.mjs";
+/** Every emitted pr-shepherd command starts with the configured `cliCommand` launcher. */
 export function buildPrShepherdCommand(args) {
-    const argv = ["pr-shepherd", ...args];
+    const argv = [...loadConfig().cliCommand, ...args];
     return { argv, text: renderShellCommand(argv) };
 }
 export function renderShellCommand(argv) {

package/bin/commands/check.mjs

@@ -1,4 +1,5 @@
 import { fetchPrBatch } from "../github/batch.mjs";
+import { queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
 import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
 import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
@@ -64,11 +65,19 @@ export async function runCheck(opts) {
     // historical event forever. When GitHub omits the removed queue commit for that old event
     // (e.g. after the synthetic commit is garbage collected), freshness is unverifiable — treat
     // it as stale/updated rather than as still current, so Shepherd doesn't escalate
-    // `merge-queue-removed` permanently on data it can no longer check. The raw removal fields
-    // still render in the merge-queue header regardless of this flag.
+    // `merge-queue-removed` permanently on data it can no longer check. A squash or rebase
+    // queue commit has one parent and does not list the PR head; that removal stays current
+    // until the head's committer time is later than the removal. The raw removal fields still
+    // render in the merge-queue header regardless of this flag.
+    const headCommittedAtUnix = batchData.activity?.latestCommitCommittedAtUnix;
     const headUpdatedAfterRemoval = Boolean(latestRemoval &&
-        (!latestRemoval.beforeCommitParentOids ||
-            !latestRemoval.beforeCommitParentOids.includes(batchData.headRefOid)));
+        !queueRemovalAppliesToHead({
+            parentOids: latestRemoval.beforeCommitParentOids,
+            headOid: batchData.headRefOid,
+            ...(headCommittedAtUnix !== undefined &&
+                headCommittedAtUnix !== null && { headCommittedAtUnix }),
+            removedAtUnix: latestRemoval.createdAtUnix,
+        }));
     const queueRawChecks = batchData.isInMergeQueue
         ? (batchData.mergeQueueChecks ?? [])
         : latestRemoval && !headUpdatedAfterRemoval

package/bin/commands/clean.mjs

@@ -1,8 +1,7 @@
 import { rm, readdir, realpath, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { resolveStateBase } from "../state/base.mjs";
+import { resolveRepoStateDir, resolveStateBase } from "../state/base.mjs";
 import { getRepoInfo, getCurrentPrNumber, getCurrentBranch, getPrNumberForBranch, } from "../github/client.mjs";
-import { SAFE_SEGMENT } from "../util/path-segment.mjs";
 export async function runClean(opts) {
     const dryRun = opts.dryRun ?? false;
     const rawBase = resolveStateBase();
@@ -107,20 +106,15 @@ async function resolveTarget(base, opts) {
     }
     const repo = await getRepoInfo();
     const { owner, name } = repo;
-    for (const [field, val] of [
-        ["owner", owner],
-        ["repo", name],
-    ]) {
-        if (!SAFE_SEGMENT.test(val)) {
-            throw new Error(`Invalid repository segment "${field}": ${val}`);
-        }
-    }
-    const ownerRepo = `${owner}-${name}`;
+    // Same segment rules as every other state path. The directory itself stays under
+    // `base`, which runClean has already realpath'd.
+    resolveRepoStateDir({ owner, repo: name });
+    const repoDir = join(base, owner, name);
     if (variant === "repo") {
         if (value !== undefined) {
             throw new Error(`"clean repo" does not accept a positional argument; got "${value}". Did you mean "clean pr" or "clean branch"?`);
         }
-        return join(base, ownerRepo);
+        return repoDir;
     }
     let prNumber;
     if (variant === "pr") {
@@ -152,5 +146,5 @@ async function resolveTarget(base, opts) {
             throw new Error(`No open PR found for branch: ${branchName}`);
         prNumber = n;
     }
-    return join(base, ownerRepo, String(prNumber));
+    return join(repoDir, String(prNumber));
 }

package/bin/commands/iterate/api-usage.mjs

@@ -1,5 +1,5 @@
 import { loadConfig } from "../../config/load.mjs";
-import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
+import { summarizeApiTelemetry, withGraphqlCredentialFingerprint, } from "../../github/api-telemetry.mjs";
 import { evaluateWorktreeGraphqlQuotaWarning } from "../../state/graphql-quota-warnings.mjs";
 import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 function shouldWarn(result) {
@@ -17,7 +17,7 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
                 ...band,
                 pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
             }));
-            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, apiUsage.graphql, persistWarning);
+            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, withGraphqlCredentialFingerprint(apiUsage.graphql), persistWarning);
         }
     }
     const { quotaWarning: _deferredWarning, ...baseResult } = result;

package/bin/commands/iterate/check-instructions.d.mts

@@ -19,7 +19,7 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
 export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch: string, hasExhaustedWorkflowRerun: boolean, branch: {
     isBehind: boolean;
     hasConflicts: boolean;
-}): string[];
+}, stackRebase?: string): string[];
 /**
  * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
  * whenever the *unmodified, as-printed* command is unsafe without them:
@@ -33,4 +33,4 @@ export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBran
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
 /** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
-export declare function buildFixCompletionInstruction(checks: AgentCheck[], hasConflicts?: boolean, hasShaGatedReviewMutations?: boolean): string;
+export declare function buildFixCompletionInstruction(checks: AgentCheck[], hasConflicts?: boolean, hasShaGatedReviewMutations?: boolean, pushesRewrittenStack?: boolean): string;

package/bin/commands/iterate/check-instructions.mjs

@@ -25,16 +25,17 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
  * The fetched PR base branch is raw context; the caller still owns repository-specific git
  * mechanics and decides whether the base contains a relevant fix.
  */
-export function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, branch) {
+export function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, branch, stackRebase) {
     if (!hasExhaustedWorkflowRerun || (!branch.isBehind && !branch.hasConflicts))
         return [];
     const state = branch.hasConflicts ? "conflicts with" : "is behind";
     const instructions = [
         `The workflow rerun still fails while the branch ${state} PR base branch \`${baseBranch}\`. Inspect the current base branch for an existing fix before choosing a remediation.`,
     ];
-    instructions.push(branch.hasConflicts
-        ? `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions, resolving conflicts as part of that update.`
-        : `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions.`);
+    instructions.push(stackRebase ??
+        (branch.hasConflicts
+            ? `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions, resolving conflicts as part of that update.`
+            : `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions.`));
     return instructions;
 }
 /**
@@ -79,11 +80,14 @@ export function buildFailingCheckInstructions(checks) {
     }
     return instructions;
 }
-export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false) {
+export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false, pushesRewrittenStack = false) {
+    const push = pushesRewrittenStack
+        ? "push the rewritten stack with `gh stack push`"
+        : "push to the PR head branch";
     if (hasConflicts)
-        return "`[FIX_CODE]` is non-terminal: resolve the conflicts, commit, push to the PR head branch, then iterate immediately with the same options.";
+        return `\`[FIX_CODE]\` is non-terminal: resolve the conflicts, commit, ${push}, then iterate immediately with the same options.`;
     if (hasShaGatedReviewMutations) {
-        return "`[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run the review mutations using the pushed commit SHA and iterate immediately with the same options; if you did not change code, complete the authorized review mutations and iterate immediately with the same options.";
+        return `\`[FIX_CODE]\` is non-terminal: if you changed code, commit and ${push}, then run the review mutations using the pushed commit SHA and iterate immediately with the same options; if you did not change code, complete the authorized review mutations and iterate immediately with the same options.`;
     }
     if (checks.some((check) => check.rerunCommand)) {
         return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate immediately with the same options to continue.";

package/bin/commands/iterate/escalate.mjs

@@ -240,6 +240,10 @@ export function buildEscalateSuggestion(triggers, detail) {
         const duration = detail ?? "60 minutes";
         return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
+    if (triggers.includes("stall-state-unavailable")) {
+        const reason = detail ?? "unknown error";
+        return `The stall timer could not be saved (${reason}). Fix PR_SHEPHERD_STATE_DIR or the directory permissions, then resume. Automated polling is paused because a stuck loop would not be detected.`;
+    }
     if (triggers.includes("base-branch-unknown")) {
         const reason = detail ? ` (${detail})` : "";
         return `Could not determine the PR's base branch${reason} — automated rebases are paused because branch safety is unclear. Run the rebase manually against the PR's real target branch.`;

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

@@ -6,6 +6,7 @@ import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, bui
 import { buildResolveCommand } from "./classify.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
+import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
@@ -271,7 +272,11 @@ 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, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0);
+    // Conflicts, and a behind branch whose rerun already failed, both ask for a branch update.
+    const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0)
+        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, report.mergeStatus.mergeRequirements?.stack)
+        : undefined;
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase);
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }

package/bin/commands/iterate/helpers.d.mts

@@ -7,6 +7,5 @@ export declare function buildTerminalCancelResult(report: ShepherdReport): Itera
 /** Build completed, non-skipped checks relevant to PR readiness. */
 export declare function buildRelevantChecks(report: ShepherdReport): RelevantCheck[];
 export declare function buildActiveChecks(report: ShepherdReport): ActiveCheck[];
-export declare function getCurrentHeadSha(): Promise<string | null>;
 export declare function buildWaitLog(base: IterateResultBase): string;
 export declare function blockedCancelNote(base: IterateResultBase): string;

package/bin/commands/iterate/helpers.mjs

@@ -1,8 +1,4 @@
-import { execFile as execFileCb } from "node:child_process";
-import { promisify } from "node:util";
-import { getExecutionCwd } from "../../execution-context.mjs";
 import { blockedReasonFromRequirements } from "../../merge-status/requirements-format.mjs";
-const execFile = promisify(execFileCb);
 export function buildSummary(report) {
     return {
         passing: report.checks.passing.length,
@@ -104,17 +100,6 @@ export function buildActiveChecks(report) {
         ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
     }));
 }
-export async function getCurrentHeadSha() {
-    try {
-        const { stdout } = await execFile("git", ["rev-parse", "HEAD"], {
-            cwd: getExecutionCwd(),
-        });
-        return stdout.trim();
-    }
-    catch {
-        return null;
-    }
-}
 export function buildWaitLog(base) {
     const { summary, remainingSeconds } = base;
     const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];