pr-shepherd 0.46.8 → 0.48.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.46.8",
+  "version": "0.48.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -137,6 +137,8 @@ pr-shepherd owner/repo#42              # poll a PR in an explicit repository
 pr-shepherd https://github.com/owner/repo/pull/42
 ```
 
+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.
+
 ### Apply Review And Journal Changes, Or Select Files
 
 Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, mark selected changed files as viewed, or append an idempotent Shepherd Journal item. Explicit operations are attempted and surface GitHub's per-operation results; generated iterate guidance remains capability-filtered. Use `build_suggestion_patches` to turn ordered review suggestions into checked patches and commit metadata; it never changes the worktree or git history.

package/bin/api.d.mts

@@ -8,7 +8,7 @@ export interface CreatePrShepherdOptions {
 }
 /** A positive PR number, GitHub pull-request URL, or owner/repo#number reference. */
 export type PrReference = number | string;
-export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "deferQuotaWarning"> & {
+export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "fingerprintCache" | "deferQuotaWarning" | "quotaWarningMinimumPollIntervalMinutes"> & {
     pr?: PrReference;
 };
 export interface ReviewMutationsOperation {

package/bin/cli/args.mjs

@@ -30,6 +30,7 @@ const BOOLEAN_FLAGS = new Set([
     "--no-auto-mark-ready",
     "--no-auto-cancel-actionable",
     "--quiet-status",
+    "--no-quiet-status",
     "--until-terminal",
     "--merge",
     "--dry-run",

package/bin/cli/default-poll.mjs

@@ -15,6 +15,7 @@ const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--no-auto-mark-ready",
     "--no-auto-cancel-actionable",
     "--quiet-status",
+    "--no-quiet-status",
     "--until-terminal",
     "--merge",
 ]);

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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\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 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\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\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; --quiet-status prints only changed WAIT snapshots, 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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\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 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\nPoll flags:\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 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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\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 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\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\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; --quiet-status prints only changed WAIT snapshots, 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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\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 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\nPoll flags:\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).";
 /** Public help page for the default PR polling invocation. */
 export declare const DEFAULT_USAGE: string;

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

@@ -48,10 +48,11 @@ Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
 
 Poll flags:
-  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.
-  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.
-  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.
-  --quiet-status                 During WAIT polling, print only changed status snapshots.
+  --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.
+  --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.
 
 Forwarded iterate flags:
@@ -67,7 +68,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; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
+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.
 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.
 

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 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 until non-WAIT or timeout. This is the default command.\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 such as 42 or a GitHub pull request URL.\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: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\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 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 until non-WAIT or timeout. This is the default command.\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 such as 42 or a GitHub pull request URL.\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.";

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

@@ -44,10 +44,11 @@ Iterate flags:
   --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
 
 Polling flags:
-  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.
-  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.
-  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.
-  --quiet-status                 During WAIT polling, print only changed status snapshots.
+  --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.
+  --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.
 
 Clean variants:

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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\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 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\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\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; --quiet-status prints only changed WAIT snapshots, 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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\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 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\nPoll flags:\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 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 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 until non-WAIT or timeout. This is the default command.\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 such as 42 or a GitHub pull request URL.\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: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\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 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 until non-WAIT or timeout. This is the default command.\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 such as 42 or a GitHub pull request URL.\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.";
 };
 /** Resolve help keys for nested public commands before any command I/O. */
 export declare function helpKeyForArgs(args: string[]): keyof typeof USAGE;

package/bin/cli/poll-handler.mjs

@@ -5,9 +5,7 @@ import { parseDurationToSeconds } from "./duration.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
-const DEFAULT_POLL_INTERVAL_SECONDS = 60;
-const DEFAULT_POLL_TIMEOUT_SECONDS = 270;
-const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
+import { EXIT } from "../exit-codes.mjs";
 export async function handlePoll(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();
@@ -18,17 +16,27 @@ export async function handlePoll(args) {
     const intervalSuffix = validateSecondsDurationFlag("pr-shepherd", "--interval", intervalStr, hasFlag(extra, "--interval"));
     if (intervalSuffix === null)
         return;
-    const intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", DEFAULT_POLL_INTERVAL_SECONDS);
+    const intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", cfg.poll.intervalSeconds);
     const timeoutStr = getFlag(extra, "--timeout");
     const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
     if (timeoutSuffix === null)
         return;
-    const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", DEFAULT_POLL_TIMEOUT_SECONDS);
+    const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", cfg.poll.timeoutSeconds);
     const debounceStr = getFlag(extra, "--debounce");
     const debounceSuffix = validateSecondsDurationFlag("pr-shepherd", "--debounce", debounceStr, hasFlag(extra, "--debounce"), { allowZero: true });
     if (debounceSuffix === null)
         return;
-    const debounceSeconds = parseDurationToSeconds(debounceSuffix ?? "", DEFAULT_POLL_DEBOUNCE_SECONDS, { allowZero: true });
+    const debounceSeconds = parseDurationToSeconds(debounceSuffix ?? "", cfg.poll.debounceSeconds, {
+        allowZero: true,
+    });
+    const quietStatusFlag = hasFlag(extra, "--quiet-status");
+    const noQuietStatusFlag = hasFlag(extra, "--no-quiet-status");
+    if (quietStatusFlag && noQuietStatusFlag) {
+        process.stderr.write("pr-shepherd: --quiet-status and --no-quiet-status cannot be used together\n");
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const quietStatus = quietStatusFlag || (!noQuietStatusFlag && cfg.poll.quietStatus);
     const result = await runPoll({
         ...globalOpts,
         prNumber,
@@ -40,7 +48,7 @@ export async function handlePoll(args) {
         intervalSeconds,
         timeoutSeconds,
         debounceSeconds,
-        quietStatus: hasFlag(extra, "--quiet-status"),
+        quietStatus,
         untilTerminal: hasFlag(extra, "--until-terminal"),
     });
     emitIterateResult(result, {

package/bin/commands/check-fingerprint.d.mts

@@ -0,0 +1,8 @@
+import { type RepoInfo } from "../github/client.mts";
+import type { PrShepherdConfig } from "../config/load.mts";
+import type { ShepherdReport } from "../types.mts";
+export declare function tryReuseFingerprintReport(prNumber: number, repo: RepoInfo, stateKey: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, config: PrShepherdConfig): Promise<ShepherdReport | null>;

package/bin/commands/check-fingerprint.mjs

@@ -0,0 +1,69 @@
+import { getMergeableState } from "../github/client.mjs";
+import { fetchPrFingerprint, fingerprintsEqual, } from "../github/fingerprint.mjs";
+import { fingerprintInputDigest, loadPrFingerprint } from "../state/pr-fingerprint.mjs";
+import { hasCheckDrivenActionableWork } from "./check-annotations.mjs";
+function reportAllowsFingerprintSkip(report) {
+    if (report.status === "READY")
+        return false;
+    if (report.mergeStatus.state !== "OPEN")
+        return false;
+    if (report.mergeQueue?.inQueue === true)
+        return false;
+    return (report.threads.actionable.length === 0 &&
+        report.threads.resolutionOnly.length === 0 &&
+        report.threads.firstLook.length === 0 &&
+        (report.threads.ruleAutoResolveIds?.length ?? 0) === 0 &&
+        report.comments.actionable.length === 0 &&
+        (report.comments.minimizeIds?.length ?? 0) === 0 &&
+        report.comments.firstLook.length === 0 &&
+        report.changesRequestedReviews.length === 0 &&
+        report.approvedReviews.length === 0 &&
+        report.firstLookSummaries.length === 0 &&
+        report.editedSummaries.length === 0 &&
+        (report.ruleAutoResolveReviewSummaryIds?.length ?? 0) === 0 &&
+        !hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status));
+}
+export async function tryReuseFingerprintReport(prNumber, repo, stateKey, config) {
+    const cached = await loadPrFingerprint(stateKey);
+    if (cached?.inputDigest == null || cached.inputDigest !== fingerprintInputDigest(config)) {
+        return null;
+    }
+    if (!reportAllowsFingerprintSkip(cached.report))
+        return null;
+    const live = await fetchPrFingerprint(prNumber, repo);
+    if (live.isInMergeQueue || cached.fingerprint.isInMergeQueue)
+        return null;
+    if (!live.checkSuitesComplete || !cached.fingerprint.checkSuitesComplete)
+        return null;
+    if (live.commentCount > 100 || cached.fingerprint.commentCount > 100)
+        return null;
+    if (live.reviewCount > 100 || cached.fingerprint.reviewCount > 100)
+        return null;
+    if (live.threadCount > 20 || cached.fingerprint.threadCount > 20)
+        return null;
+    if (live.hasMultiCommentThreads || cached.fingerprint.hasMultiCommentThreads)
+        return null;
+    if (!live.rulesComplete || !cached.fingerprint.rulesComplete)
+        return null;
+    if (!fingerprintsEqual(cached.fingerprint, live))
+        return null;
+    if (!(await cachedReportSurvivesMergeabilityRefresh(prNumber, repo, cached.report, cached.fingerprint))) {
+        return null;
+    }
+    return { ...cached.report, fingerprintReused: true };
+}
+async function cachedReportSurvivesMergeabilityRefresh(prNumber, repo, report, fingerprint) {
+    const restDerived = fingerprint.mergeable !== report.mergeStatus.mergeable ||
+        fingerprint.mergeStateStatus !== report.mergeStatus.mergeStateStatus;
+    if (report.status !== "READY" && report.mergeStatus.status !== "UNKNOWN" && !restDerived) {
+        return true;
+    }
+    const rest = await getMergeableState(prNumber, repo.owner, repo.name);
+    if (rest.state === "MERGED" || rest.state === "CLOSED")
+        return false;
+    if (rest.mergeable !== report.mergeStatus.mergeable)
+        return false;
+    if (rest.mergeStateStatus !== report.mergeStatus.mergeStateStatus)
+        return false;
+    return true;
+}

package/bin/commands/check.d.mts

@@ -4,5 +4,6 @@ export declare function runCheck(opts: GlobalOptions & {
     autoMinimizeSuppressed?: boolean;
     skipTriage?: boolean;
     persistSeen?: boolean;
+    fingerprintCache?: boolean;
     merge?: boolean;
 }): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -1,4 +1,6 @@
 import { fetchPrBatch } from "../github/batch.mjs";
+import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
+import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
@@ -30,6 +32,12 @@ export async function runCheck(opts) {
     }
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const config = loadConfig();
+    const reuseFingerprint = opts.fingerprintCache === true;
+    if (reuseFingerprint) {
+        const cached = await tryReuseFingerprintReport(prNumber, repo, stateKey, config);
+        if (cached)
+            return cached;
+    }
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
     let batchData = result.data;
@@ -38,7 +46,11 @@ export async function runCheck(opts) {
     const didRefreshMergeability = unknownRefresh.didRefresh;
     let mergeStatus = deriveMergeStatus(batchData);
     if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
-        return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        const terminal = buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        if (result.fingerprint) {
+            await storePrFingerprint(stateKey, result.fingerprint, terminal, config);
+        }
+        return terminal;
     }
     const startupFailuresNeedAttempt = batchData.checks.some((check) => check.source === "startup_failure" && check.runAttempt === undefined);
     const startupFailureChecks = result.checkSuitesComplete && !startupFailuresNeedAttempt
@@ -145,7 +157,11 @@ export async function runCheck(opts) {
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
         if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
-            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+            const terminal = buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+            if (result.fingerprint) {
+                await storePrFingerprint(stateKey, result.fingerprint, terminal, config);
+            }
+            return terminal;
         }
     }
     // Mirrors the deferral gate in commands/iterate/index.mts exactly (via the shared
@@ -225,7 +241,7 @@ export async function runCheck(opts) {
         batchData.isInMergeQueue ||
         batchData.autoMergeRequest ||
         batchData.latestMergeQueueRemoval);
-    return {
+    const report = {
         pr: prNumber,
         nodeId: batchData.nodeId,
         headSha: batchData.headRefOid,
@@ -290,6 +306,10 @@ export async function runCheck(opts) {
             },
         }),
     };
+    if (result.fingerprint) {
+        await storePrFingerprint(stateKey, result.fingerprint, report, config);
+    }
+    return report;
 }
 async function remainingRuleAutoResolveIds(partition, autoMinimizeSuppressed = false) {
     const consumedIds = autoMinimizeSuppressed

package/bin/commands/iterate/api-usage.d.mts

@@ -1,2 +1,2 @@
 import type { IterateResult } from "../../types.mts";
-export declare function attachApiUsage(result: IterateResult, persistWarning: boolean, preservePersistedWarning?: boolean): Promise<IterateResult>;
+export declare function attachApiUsage(result: IterateResult, persistWarning: boolean, preservePersistedWarning?: boolean, minimumPollIntervalMinutes?: number): Promise<IterateResult>;

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

@@ -5,7 +5,7 @@ import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 function shouldWarn(result) {
     return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
 }
-export async function attachApiUsage(result, persistWarning, preservePersistedWarning = false) {
+export async function attachApiUsage(result, persistWarning, preservePersistedWarning = false, minimumPollIntervalMinutes = 0) {
     const apiUsage = summarizeApiTelemetry();
     if (apiUsage === undefined)
         return result;
@@ -13,7 +13,11 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
     if (quotaWarning === undefined && apiUsage.graphql !== undefined && shouldWarn(result)) {
         const [owner, repo] = result.repo.split("/");
         if (owner && repo) {
-            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, loadConfig().watch.graphqlQuotaWarnings, apiUsage.graphql, persistWarning);
+            const bands = loadConfig().watch.graphqlQuotaWarnings.map((band) => ({
+                ...band,
+                pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
+            }));
+            quotaWarning = await evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands, apiUsage.graphql, persistWarning);
         }
     }
     const { quotaWarning: _deferredWarning, ...baseResult } = result;

package/bin/commands/iterate/base.mjs

@@ -21,5 +21,6 @@ export function buildIterateBase(report, readyState) {
         ...buildSuppressedCheckFields(report),
         activity: report.activity,
         mergeQueue: report.mergeQueue,
+        ...(report.fingerprintReused === true && { fingerprintReused: true }),
     };
 }

package/bin/commands/iterate/mark-ready.mjs

@@ -4,6 +4,14 @@ import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.m
 export async function markReadyIfAuthorized(enabled, base, report) {
     if (!enabled)
         return null;
+    if (report.fingerprintReused === true) {
+        return {
+            ...base,
+            action: "mark_ready",
+            markedReady: false,
+            log: `READY: PR #${report.pr} is ready to mark; refresh required before converting draft`,
+        };
+    }
     if (report.viewerAuthorization?.viewerCanUpdate === true) {
         await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
         return {

package/bin/commands/iterate/run.mjs

@@ -3,6 +3,6 @@ import { attachApiUsage } from "./api-usage.mjs";
 export function withIterateApiUsage(opts, runCore) {
     return withApiTelemetryScope(async () => {
         const result = await runCore();
-        return attachApiUsage(result, opts.deferQuotaWarning !== true);
+        return attachApiUsage(result, opts.deferQuotaWarning !== true, false, opts.quotaWarningMinimumPollIntervalMinutes);
     });
 }

package/bin/commands/poll-progress.d.mts

@@ -0,0 +1,11 @@
+import type { IterateResult } from "../types.mts";
+export declare function writeWaitProgress(opts: {
+    tick: number;
+    elapsedMs: number;
+    sleepMs: number;
+    result: IterateResult;
+    quietStatus: boolean;
+    verbose: boolean;
+    lastWaitSignature: string | null;
+}): string | null;
+export declare function writeDebounceProgress(tick: number, elapsedMs: number, remainingMs: number): void;

package/bin/commands/poll-progress.mjs

@@ -0,0 +1,52 @@
+function writeTickProgress(tick, elapsedSeconds, detail) {
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — ${detail}\n`);
+}
+function waitSignature(result) {
+    const activity = result.activity ?? {
+        commitCount: 0,
+        reviewRoundCount: 0,
+        latestCommitCommittedAtUnix: null,
+        reviewItemsSinceLatestCommit: [],
+    };
+    return JSON.stringify({
+        status: result.status,
+        mergeStateStatus: result.mergeStateStatus,
+        reviewDecision: result.reviewDecision,
+        state: result.state,
+        active: (result.inProgressChecks ?? []).map((c) => [c.name, c.status, c.runId]),
+        commitCount: activity.commitCount,
+        latestCommitCommittedAtUnix: activity.latestCommitCommittedAtUnix,
+        reviewRoundCount: activity.reviewRoundCount,
+        reviewItemsSinceLatestCommit: activity.reviewItemsSinceLatestCommit.length,
+    });
+}
+function writeQuietStatus(tick, elapsedSeconds, sleepSeconds, result) {
+    const activeChecks = result.inProgressChecks ?? [];
+    const activeCheckText = activeChecks.map((c) => `${c.name} (${c.status})`).join(", ");
+    const active = activeChecks.length > 0 ? ` · active: ${activeCheckText}` : "";
+    const commitCount = result.activity?.commitCount ?? 0;
+    const reviewItems = result.activity?.reviewItemsSinceLatestCommit.length ?? 0;
+    const reviewRounds = result.activity?.reviewRoundCount ?? 0;
+    const commitSeg = commitCount > 0 ? ` · ${commitCount} commits` : "";
+    const reviewRoundSeg = reviewRounds > 0 ? ` · ${reviewRounds} review rounds` : "";
+    const reviewSeg = reviewItems > 0 ? ` · ${reviewItems} review items since latest commit` : "";
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT ${result.status}/${result.mergeStateStatus}/${result.reviewDecision ?? "NO_REVIEW_DECISION"}${active}${commitSeg}${reviewRoundSeg}${reviewSeg} — sleeping ${sleepSeconds}s\n`);
+}
+export function writeWaitProgress(opts) {
+    const elapsedSeconds = Math.round(opts.elapsedMs / 1000);
+    const sleepSeconds = Math.round(opts.sleepMs / 1000);
+    if (!opts.quietStatus) {
+        writeTickProgress(opts.tick, elapsedSeconds, opts.verbose ? `sleeping ${sleepSeconds}s` : `still running; next tick in ${sleepSeconds}s`);
+        return opts.lastWaitSignature;
+    }
+    const signature = waitSignature(opts.result);
+    if (signature !== opts.lastWaitSignature) {
+        writeQuietStatus(opts.tick, elapsedSeconds, sleepSeconds, opts.result);
+    }
+    return signature;
+}
+export function writeDebounceProgress(tick, elapsedMs, remainingMs) {
+    const elapsedSeconds = Math.round(elapsedMs / 1000);
+    const remainingSeconds = Math.round(remainingMs / 1000);
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] FIX_CODE — debounce ${remainingSeconds}s remaining\n`);
+}

package/bin/commands/poll-quota.d.mts

@@ -0,0 +1,9 @@
+import type { GraphqlQuotaWarningBand } from "../config/load.mts";
+import type { GraphqlApiUsage } from "../types.mts";
+/** Sleep at least `--interval`, and at least the active crossed quota band. */
+export declare function graphqlQuotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: Pick<GraphqlApiUsage, "remaining" | "limit"> | undefined, fallbackMs: number, maxMs: number): number;
+/**
+ * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
+ * limit. `null` means the error is not a retryable rate limit.
+ */
+export declare function pollGraphQlRetryAfterMs(err: unknown): number | null;

package/bin/commands/poll-quota.mjs

@@ -0,0 +1,36 @@
+import { GitHubRequestError } from "../github/errors.mjs";
+import { isRateLimitMessage } from "../comments/rate-limit.mjs";
+const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
+/** Sleep at least `--interval`, and at least the active crossed quota band. */
+export function graphqlQuotaPollIntervalMs(bands, usage, fallbackMs, maxMs) {
+    if (usage === undefined || usage.limit <= 0 || bands.length === 0) {
+        return Math.min(fallbackMs, maxMs);
+    }
+    const crossed = bands.filter((band) => usage.remaining * 100 <= usage.limit * band.remainingPercent);
+    if (crossed.length === 0)
+        return Math.min(fallbackMs, maxMs);
+    const active = crossed.reduce((lowest, band) => band.remainingPercent < lowest.remainingPercent ? band : lowest);
+    const bandMs = active.pollIntervalMinutes * 60_000;
+    return Math.min(Math.max(fallbackMs, bandMs), maxMs);
+}
+/**
+ * Retry delay for `--until-terminal` when GitHub returns a GraphQL 429 / secondary
+ * limit. `null` means the error is not a retryable rate limit.
+ */
+export function pollGraphQlRetryAfterMs(err) {
+    if (!(err instanceof GitHubRequestError))
+        return null;
+    const retryable = err.status === 429 ||
+        err.retryAfterSeconds !== undefined ||
+        isRateLimitMessage(err.message) ||
+        (err.graphqlErrors?.some((error) => isRateLimitMessage(error.message)) ?? false) ||
+        (err.rateLimit !== undefined && err.rateLimit.remaining <= 0);
+    if (!retryable)
+        return null;
+    if (err.retryAfterSeconds !== undefined)
+        return Math.max(err.retryAfterSeconds, 0) * 1000;
+    if (err.rateLimit !== undefined && err.rateLimit.remaining <= 0) {
+        return Math.max(err.rateLimit.resetAt * 1000 - Date.now(), 0);
+    }
+    return GRAPHQL_RETRY_AFTER_DEFAULT_MS;
+}

package/bin/commands/poll-run.d.mts

@@ -1,2 +1,2 @@
 import type { IterateResult } from "../types.mts";
-export declare function withPollApiUsage(runCore: () => Promise<IterateResult>, preservePersistedWarning: boolean): Promise<IterateResult>;
+export declare function withPollApiUsage(runCore: () => Promise<IterateResult>, preservePersistedWarning: boolean, minimumPollIntervalMinutes: number): Promise<IterateResult>;

package/bin/commands/poll-run.mjs

@@ -1,8 +1,8 @@
 import { withApiTelemetryScope } from "../github/api-telemetry.mjs";
 import { attachApiUsage } from "./iterate/api-usage.mjs";
-export function withPollApiUsage(runCore, preservePersistedWarning) {
+export function withPollApiUsage(runCore, preservePersistedWarning, minimumPollIntervalMinutes) {
     return withApiTelemetryScope(async () => {
         const result = await runCore();
-        return attachApiUsage(result, true, preservePersistedWarning);
+        return attachApiUsage(result, true, preservePersistedWarning, minimumPollIntervalMinutes);
     });
 }