pr-shepherd 0.37.2 → 0.38.1

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.37.2",
+  "version": "0.38.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

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

@@ -50,7 +50,7 @@ Selectors:
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply journal": `pr-shepherd apply journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 
 Usage:
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -177,7 +177,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    Do not cancel in-progress runs before actionable fixes.\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\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  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, 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    Do not cancel in-progress runs before actionable fixes.\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 single dot 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, CANCEL, or ESCALATE.\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  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, 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    Do not cancel in-progress runs before actionable fixes.\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, CANCEL, or ESCALATE.\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  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.
@@ -205,7 +205,7 @@ Flags:
 Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly journal: `pr-shepherd journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 Creates the section at the end if absent. Idempotent — duplicate items are skipped.
 
 Usage:

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

@@ -53,7 +53,7 @@ Selectors:
 --help, -h                      Print this help and exit before GitHub I/O.`,
     "apply journal": `pr-shepherd apply journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 
 Usage:
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -208,7 +208,7 @@ Flags:
 Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`,
     journal: `pr-shepherd journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 Creates the section at the end if absent. Idempotent — duplicate items are skipped.
 
 Usage:

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    Do not cancel in-progress runs before actionable fixes.\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\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  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, 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    Do not cancel in-progress runs before actionable fixes.\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 single dot 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, CANCEL, or ESCALATE.\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  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, 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    Do not cancel in-progress runs before actionable fixes.\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, CANCEL, or ESCALATE.\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  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

@@ -63,7 +63,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 a single dot 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; --quiet-status prints only changed WAIT snapshots, 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, CANCEL, or ESCALATE.
 
@@ -76,4 +76,4 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   14  CANCEL (closed without merging)
   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.replaceAll("pr-shepherd poll", "pr-shepherd [PR]");
+export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]").replace(/^ {2}pr-shepherd poll \[PR\]/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 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 build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\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 changed files as viewed in GitHub.\n  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch 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    Do not cancel in-progress runs before actionable fixes.\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)\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 build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\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 changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch 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    Do not cancel in-progress runs before actionable fixes.\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)\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

@@ -19,7 +19,7 @@ Commands:
   iterate              Run one iterate tick (single-tick alias).
   apply review         Apply review-state mutations after fixes.
   apply files          Mark changed files as viewed in GitHub.
-  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.
+  apply journal        Append a list item to the Shepherd Journal details block of a PR body.
   build-suggestion-patch
                        Convert one GitHub suggestion thread into a patch and commit instructions.
   admin clean          Remove pr-shepherd state files.

package/bin/cli/help.d.mts

@@ -50,7 +50,7 @@ Selectors:
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply journal": `pr-shepherd apply journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 
 Usage:
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -177,7 +177,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    Do not cancel in-progress runs before actionable fixes.\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\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  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, 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    Do not cancel in-progress runs before actionable fixes.\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 single dot 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, CANCEL, or ESCALATE.\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  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, 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    Do not cancel in-progress runs before actionable fixes.\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, CANCEL, or ESCALATE.\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  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.
@@ -205,7 +205,7 @@ Flags:
 Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly journal: `pr-shepherd journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 Creates the section at the end if absent. Idempotent — duplicate items are skipped.
 
 Usage:
@@ -228,7 +228,7 @@ Flags:
 
 Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     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 build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\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 changed files as viewed in GitHub.\n  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch 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    Do not cancel in-progress runs before actionable fixes.\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)\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 build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\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 changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch 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    Do not cancel in-progress runs before actionable fixes.\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)\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/journal-formatter.mjs

@@ -9,7 +9,7 @@ export function formatJournalResult(result) {
     if (!result.mutated)
         return "No change — entry already present.";
     if (!result.sectionExisted) {
-        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
+        return `Created Shepherd Journal details in PR #${result.prNumber}.`;
     }
-    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
+    return `Appended to Shepherd Journal details in PR #${result.prNumber}.`;
 }

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

@@ -1,5 +1,5 @@
 import type { CheckAnnotation, ClassifiedCheck, ShepherdReport, TriagedCheck } from "../types.mts";
-export declare function checksWithUnseenAnnotations(report: ShepherdReport): TriagedCheck[];
+export declare function checksWithActionableAnnotations(report: ShepherdReport): TriagedCheck[];
 export declare function attachAndMergeCheckAnnotations(buckets: {
     passing: ClassifiedCheck[];
     failing: TriagedCheck[];

package/bin/commands/check-annotations.mjs

@@ -2,14 +2,14 @@ import { fetchCheckRunAnnotations } from "../github/check-annotations.mjs";
 function shouldFetchCheckAnnotations(check) {
     return check.id != null && check.status === "COMPLETED" && check.hasAnnotations === true;
 }
-export function checksWithUnseenAnnotations(report) {
+export function checksWithActionableAnnotations(report) {
     return [
         ...report.checks.failing,
         ...report.checks.passing,
         ...report.checks.skipped,
         ...report.checks.filtered,
         ...(report.checks.ignored ?? []),
-    ].filter((c) => (c.annotations?.length ?? 0) > 0);
+    ].filter((c) => c.conclusion !== "SUCCESS" && (c.annotations?.length ?? 0) > 0);
 }
 export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber) {
     const candidates = [

package/bin/commands/check.mjs

@@ -7,7 +7,7 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { attachAndMergeCheckAnnotations } from "./check-annotations.mjs";
+import { annotationMarkerBody, attachAndMergeCheckAnnotations } from "./check-annotations.mjs";
 import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
@@ -85,7 +85,16 @@ export async function runCheck(opts) {
     const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     if (opts.persistSeen !== false) {
+        const successfulAnnotations = [
+            ...merged.passing,
+            ...merged.skipped,
+            ...merged.filtered,
+            ...merged.ignored,
+        ]
+            .filter((check) => check.conclusion === "SUCCESS")
+            .flatMap((check) => check.annotations ?? []);
         await Promise.allSettled([
+            ...successfulAnnotations.map((a) => markSeen(stateKey, a.id, annotationMarkerBody(a))),
             ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
             ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
             ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
@@ -117,6 +126,9 @@ export async function runCheck(opts) {
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
+        if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
+            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        }
     }
     const blockedByFilteredCheck = isBlockedByFilteredCheck(mergeStatus, verdict);
     return {

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

@@ -8,7 +8,7 @@ import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./helpers.mjs";
-import { annotationMarkerBody, checksWithUnseenAnnotations } from "../check-annotations.mjs";
+import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { loadConfig } from "../../config/load.mjs";
@@ -30,7 +30,7 @@ function nextFixAttempts(stored, headSha, threads) {
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
     const failingChecks = report.checks.failing;
-    const annotatedExtra = checksWithUnseenAnnotations(report).filter((c) => c.category !== "failing");
+    const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
     const { protectedRunIds, protectedRuns } = buildRunProtection([...failingChecks, ...report.checks.inProgress], opts.neverCancelRuns);
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);

package/bin/commands/iterate/index.mjs

@@ -12,7 +12,7 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
-import { checksWithUnseenAnnotations } from "../check-annotations.mjs";
+import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
@@ -70,7 +70,7 @@ export async function runIterate(opts) {
         report.comments.firstLook.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
         report.checks.failing.length > 0 ||
-        checksWithUnseenAnnotations(report).length > 0 ||
+        checksWithActionableAnnotations(report).length > 0 ||
         report.mergeStatus.status === "CONFLICTS" ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||

package/bin/commands/iterate/stall.mjs

@@ -1,7 +1,7 @@
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
-import { checksWithUnseenAnnotations } from "../check-annotations.mjs";
+import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
@@ -14,7 +14,7 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
     const reviews = report.changesRequestedReviews.map((r) => r.id).sort();
     const summaries = [...reviewSummaryIds].sort();
     const ruleAutoResolveSummaries = (report.ruleAutoResolveReviewSummaryIds ?? []).sort((a, b) => a.localeCompare(b));
-    const annotations = checksWithUnseenAnnotations(report)
+    const annotations = checksWithActionableAnnotations(report)
         .flatMap((c) => (c.annotations ?? []).map((a) => a.id))
         .sort((a, b) => a.localeCompare(b));
     return JSON.stringify({

package/bin/commands/journal/journal-item.d.mts

@@ -0,0 +1,11 @@
+type ValidationOk = {
+    ok: true;
+    item: string;
+};
+type ValidationError = {
+    ok: false;
+    error: string;
+};
+export type ValidationResult = ValidationOk | ValidationError;
+export declare function validateJournalItem(input: string): ValidationResult;
+export {};

package/bin/commands/journal/journal-item.mjs

@@ -0,0 +1,29 @@
+import { isJournalLikeSummary, isReservedJournalMarker } from "./journal-markdown.mjs";
+export function validateJournalItem(input) {
+    const lines = input.split("\n").map((line) => line.trimEnd());
+    const nonBlank = lines.filter((line) => line.trim() !== "");
+    if (nonBlank.length === 0) {
+        return { ok: false, error: 'journal item must not be empty; expected a "- <text>" list item' };
+    }
+    if (!/^- \S/.test(nonBlank[0])) {
+        return {
+            ok: false,
+            error: `journal item must start with "- <text>"; got: ${JSON.stringify(nonBlank[0].slice(0, 40))}`,
+        };
+    }
+    for (const line of nonBlank.slice(1)) {
+        if (line.startsWith("#")) {
+            return {
+                ok: false,
+                error: "journal item lines must not start with # (would break section structure)",
+            };
+        }
+        if (isReservedJournalMarker(line.trim()) || isJournalLikeSummary(line.trim())) {
+            return {
+                ok: false,
+                error: `journal item must not contain standalone journal container marker ${JSON.stringify(line.trim())}`,
+            };
+        }
+    }
+    return { ok: true, item: lines.join("\n").trim() };
+}

package/bin/commands/journal/journal-markdown.d.mts

@@ -0,0 +1,13 @@
+type Fence = {
+    marker: "`" | "~";
+    length: number;
+};
+export type MarkdownScanState = {
+    comment: boolean;
+    fence: Fence | null;
+};
+export declare function findDetailsClose(lines: string[], startIdx: number): number;
+export declare function isJournalLikeSummary(line: string): boolean;
+export declare function isReservedJournalMarker(line: string): boolean;
+export declare function skipMarkdownLine(state: MarkdownScanState, line: string): boolean;
+export {};

package/bin/commands/journal/journal-markdown.mjs

@@ -0,0 +1,66 @@
+import { SHEPHERD_JOURNAL_DETAILS_CLOSE, SHEPHERD_JOURNAL_DETAILS_SUMMARY, } from "../shepherd-journal.mjs";
+export function findDetailsClose(lines, startIdx) {
+    let depth = 1;
+    const state = { fence: null, comment: false };
+    for (let i = startIdx; i < lines.length; i++) {
+        if (skipMarkdownLine(state, lines[i]))
+            continue;
+        if (isJournalLikeSummary(lines[i].trimStart())) {
+            throw new Error("duplicate Shepherd Journal details summary inside canonical container");
+        }
+        if (isDetailsOpening(lines[i]))
+            depth++;
+        if (lines[i].trim() === SHEPHERD_JOURNAL_DETAILS_CLOSE) {
+            if (lines[i] !== SHEPHERD_JOURNAL_DETAILS_CLOSE) {
+                throw new Error("malformed Shepherd Journal details container: closing marker must be unindented");
+            }
+            if (--depth === 0)
+                return i;
+        }
+    }
+    throw new Error("unterminated or unsafe nested Shepherd Journal details container");
+}
+export function isJournalLikeSummary(line) {
+    return /^<summary>\s*Shepherd\s+Journal\b/i.test(line);
+}
+export function isReservedJournalMarker(line) {
+    return (isDetailsOpening(line) ||
+        line === SHEPHERD_JOURNAL_DETAILS_SUMMARY ||
+        line === SHEPHERD_JOURNAL_DETAILS_CLOSE);
+}
+function isDetailsOpening(line) {
+    return /^<details(?:\s+[^>]*)?>$/.test(line);
+}
+function advanceHtmlComment(active, line) {
+    return active ? !line.includes("-->") : line.includes("<!--") && !line.includes("-->");
+}
+export function skipMarkdownLine(state, line) {
+    if (state.comment) {
+        state.comment = advanceHtmlComment(true, line);
+        return true;
+    }
+    if (state.fence) {
+        state.fence = advanceFence(state.fence, line);
+        return true;
+    }
+    if (line.includes("<!--")) {
+        state.comment = advanceHtmlComment(false, line);
+        return true;
+    }
+    state.fence = advanceFence(null, line);
+    return state.fence !== null;
+}
+function advanceFence(activeFence, line) {
+    const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (!activeFence) {
+        if (match?.[1][0] === "`" && match[2].includes("`"))
+            return null;
+        return match ? { marker: match[1][0], length: match[1].length } : null;
+    }
+    return match &&
+        match[1][0] === activeFence.marker &&
+        match[1].length >= activeFence.length &&
+        /^[ \t]*$/.test(match[2])
+        ? null
+        : activeFence;
+}

package/bin/commands/journal/transform.d.mts

@@ -1,22 +1,7 @@
+export { validateJournalItem } from "./journal-item.mts";
 export interface AppendResult {
     body: string;
     mutated: boolean;
     sectionExisted: boolean;
 }
-type ValidationOk = {
-    ok: true;
-    item: string;
-};
-type ValidationError = {
-    ok: false;
-    error: string;
-};
-export type ValidationResult = ValidationOk | ValidationError;
-/** Validates that the input is a properly formed markdown list item. */
-export declare function validateJournalItem(input: string): ValidationResult;
-/**
- * Appends a validated list item to the ## Shepherd Journal section of a PR body.
- * Creates the section at the end if absent. Skips if the exact item is already present (idempotent).
- */
 export declare function appendJournalItem(body: string, item: string): AppendResult;
-export {};

package/bin/commands/journal/transform.mjs

@@ -1,112 +1,135 @@
-import { SHEPHERD_JOURNAL_SECTION, SHEPHERD_JOURNAL_SECTION_PATTERN, } from "../shepherd-journal.mjs";
-/** Validates that the input is a properly formed markdown list item. */
-export function validateJournalItem(input) {
-    const lines = input.split("\n").map((l) => l.trimEnd());
-    const nonBlank = lines.filter((l) => l.trim() !== "");
-    if (nonBlank.length === 0) {
-        return { ok: false, error: 'journal item must not be empty; expected a "- <text>" list item' };
-    }
-    if (!/^- \S/.test(nonBlank[0])) {
-        return {
-            ok: false,
-            error: `journal item must start with "- <text>"; got: ${JSON.stringify(nonBlank[0].slice(0, 40))}`,
-        };
-    }
-    for (const line of nonBlank.slice(1)) {
-        if (line.startsWith("#")) {
-            return {
-                ok: false,
-                error: "journal item lines must not start with # (would break section structure)",
-            };
-        }
-    }
-    const trimmed = lines
-        .map((l) => l.trimEnd())
-        .join("\n")
-        .trim();
-    return { ok: true, item: trimmed };
-}
-/**
- * Appends a validated list item to the ## Shepherd Journal section of a PR body.
- * Creates the section at the end if absent. Skips if the exact item is already present (idempotent).
- */
+import { SHEPHERD_JOURNAL_DETAILS_OPEN, SHEPHERD_JOURNAL_DETAILS_CLOSE, SHEPHERD_JOURNAL_DETAILS_SUMMARY, SHEPHERD_JOURNAL_SECTION_PATTERN, } from "../shepherd-journal.mjs";
+import { findDetailsClose, isJournalLikeSummary, skipMarkdownLine, } from "./journal-markdown.mjs";
+export { validateJournalItem } from "./journal-item.mjs";
 export function appendJournalItem(body, item) {
-    const lines = body.split("\n");
-    const bounds = findSectionBounds(lines);
-    if (!bounds) {
-        return createSection(lines, item);
-    }
-    const { headingIdx, endIdx } = bounds;
-    const sectionLines = lines.slice(headingIdx + 1, endIdx);
-    if (itemAlreadyPresent(sectionLines, item)) {
-        return { body, mutated: false, sectionExisted: true };
+    const lines = body.replaceAll("\r\n", "\n").split("\n");
+    const canonical = findCanonicalJournal(lines);
+    const legacy = findLegacyJournal(lines);
+    if (canonical && legacy)
+        throw new Error("ambiguous Shepherd Journal: both canonical details and legacy ## section exist");
+    if (canonical)
+        return appendToCanonical(lines, canonical, item, body);
+    if (legacy)
+        return migrateLegacyJournal(lines, legacy, item);
+    return createCanonicalJournal(lines, item);
+}
+function findCanonicalJournal(lines) {
+    const journals = [];
+    const state = { fence: null, comment: false };
+    for (let i = 0; i < lines.length; i++) {
+        if (skipMarkdownLine(state, lines[i]) || !isJournalLikeSummary(lines[i].trimStart()))
+            continue;
+        if (lines[i] !== SHEPHERD_JOURNAL_DETAILS_SUMMARY) {
+            throw new Error("malformed Shepherd Journal details container: expected exact summary line");
+        }
+        if (i === 0 || lines[i - 1] !== SHEPHERD_JOURNAL_DETAILS_OPEN) {
+            throw new Error("malformed Shepherd Journal details container: summary must immediately follow <details>");
+        }
+        if (lines[i + 1] !== "") {
+            throw new Error("malformed Shepherd Journal details container: expected blank line after summary");
+        }
+        const closeIdx = findDetailsClose(lines, i + 1);
+        journals.push({ summaryIdx: i, closeIdx });
+        i = closeIdx;
     }
-    return appendToSection(lines, headingIdx, endIdx, sectionLines, item);
+    if (journals.length > 1)
+        throw new Error("duplicate Shepherd Journal details containers");
+    return journals[0] ?? null;
 }
-function findSectionBounds(lines) {
-    let inFence = false;
+function findLegacyJournal(lines) {
+    const state = { fence: null, comment: false };
     let headingIdx = -1;
+    let endIdx = null;
     for (let i = 0; i < lines.length; i++) {
-        const trimmed = lines[i].trim();
-        if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
-            inFence = !inFence;
+        if (skipMarkdownLine(state, lines[i]))
             continue;
+        if (SHEPHERD_JOURNAL_SECTION_PATTERN.test(lines[i].trimEnd())) {
+            if (headingIdx !== -1)
+                throw new Error("duplicate legacy Shepherd Journal sections");
+            headingIdx = i;
+        }
+        else if (headingIdx !== -1 &&
+            endIdx === null &&
+            lines[i].trim() === SHEPHERD_JOURNAL_DETAILS_CLOSE) {
+            throw new Error("unsafe legacy Shepherd Journal section: standalone </details> line");
         }
-        if (!inFence) {
-            if (headingIdx === -1) {
-                if (SHEPHERD_JOURNAL_SECTION_PATTERN.test(lines[i].trimEnd())) {
-                    headingIdx = i;
-                }
-            }
-            else if (/^#{1,2} /.test(lines[i])) {
-                return { headingIdx, endIdx: i };
-            }
+        else if (headingIdx !== -1 && endIdx === null && /^#{1,2} /.test(lines[i])) {
+            endIdx = i;
         }
     }
-    if (headingIdx === -1)
-        return null;
-    return { headingIdx, endIdx: lines.length };
+    return headingIdx === -1 ? null : { headingIdx, endIdx: endIdx ?? lines.length };
 }
-function itemAlreadyPresent(sectionLines, item) {
-    const itemLines = item.split("\n").map((l) => l.trimEnd());
-    const normalizedSection = sectionLines.map((l) => l.trimEnd());
-    for (let i = 0; i <= normalizedSection.length - itemLines.length; i++) {
-        let match = true;
-        for (let j = 0; j < itemLines.length; j++) {
-            if (normalizedSection[i + j] !== itemLines[j]) {
-                match = false;
-                break;
-            }
-        }
-        if (match)
+function appendToCanonical(lines, bounds, item, originalBody) {
+    const journalLines = lines.slice(bounds.summaryIdx + 1, bounds.closeIdx);
+    if (itemAlreadyPresent(journalLines, item))
+        return { body: originalBody, mutated: false, sectionExisted: true };
+    const trimmed = trimTrailingBlankLines(journalLines);
+    const content = trimmed.length === 0 ? ["", ...item.split("\n")] : [...trimmed, ...item.split("\n")];
+    return {
+        body: [
+            ...lines.slice(0, bounds.summaryIdx + 1),
+            ...content,
+            ...lines.slice(bounds.closeIdx),
+        ].join("\n"),
+        mutated: true,
+        sectionExisted: true,
+    };
+}
+function migrateLegacyJournal(lines, bounds, item) {
+    const journalLines = trimBlankLines(lines.slice(bounds.headingIdx + 1, bounds.endIdx));
+    const content = itemAlreadyPresent(journalLines, item)
+        ? journalLines
+        : journalLines.length === 0
+            ? ["", ...item.split("\n")]
+            : [...journalLines, ...item.split("\n")];
+    const canonical = [
+        SHEPHERD_JOURNAL_DETAILS_OPEN,
+        SHEPHERD_JOURNAL_DETAILS_SUMMARY,
+        "",
+        ...content,
+        SHEPHERD_JOURNAL_DETAILS_CLOSE,
+    ];
+    const after = lines.slice(bounds.endIdx);
+    return {
+        body: [
+            ...lines.slice(0, bounds.headingIdx),
+            ...canonical,
+            ...(after.length > 0 ? ["", ...after] : []),
+        ].join("\n"),
+        mutated: true,
+        sectionExisted: true,
+    };
+}
+function createCanonicalJournal(lines, item) {
+    const existing = trimTrailingBlankLines(lines);
+    const canonical = [
+        SHEPHERD_JOURNAL_DETAILS_OPEN,
+        SHEPHERD_JOURNAL_DETAILS_SUMMARY,
+        "",
+        ...item.split("\n"),
+        SHEPHERD_JOURNAL_DETAILS_CLOSE,
+    ];
+    return {
+        body: [...existing, ...(existing.length > 0 ? [""] : []), ...canonical].join("\n"),
+        mutated: true,
+        sectionExisted: false,
+    };
+}
+function itemAlreadyPresent(journalLines, item) {
+    const itemLines = item.split("\n").map((line) => line.trimEnd());
+    for (let i = 0; i <= journalLines.length - itemLines.length; i++) {
+        if (itemLines.every((line, offset) => journalLines[i + offset].trimEnd() === line))
             return true;
     }
     return false;
 }
-function appendToSection(lines, headingIdx, endIdx, sectionLines, item) {
-    const before = lines.slice(0, headingIdx + 1);
-    const after = lines.slice(endIdx);
-    // Strip trailing blank lines from section body.
-    let sectionEnd = sectionLines.length;
-    while (sectionEnd > 0 && sectionLines[sectionEnd - 1].trim() === "") {
-        sectionEnd--;
-    }
-    const trimmedSection = sectionLines.slice(0, sectionEnd);
-    // Insert blank line after heading when section was empty, then the item.
-    const newSection = trimmedSection.length === 0
-        ? ["", ...item.split("\n")]
-        : [...trimmedSection, ...item.split("\n")];
-    // One blank line before the next section (or trailing newline at EOF).
-    const newBody = [...before, ...newSection, ...(after.length > 0 ? ["", ...after] : [])].join("\n");
-    return { body: newBody, mutated: true, sectionExisted: true };
-}
-function createSection(lines, item) {
-    // Strip trailing blank lines from the existing body.
+function trimTrailingBlankLines(lines) {
     let end = lines.length;
-    while (end > 0 && lines[end - 1].trim() === "") {
+    while (end > 0 && lines[end - 1].trim() === "")
         end--;
-    }
-    const trimmedLines = lines.slice(0, end);
-    const newBody = [...trimmedLines, "", SHEPHERD_JOURNAL_SECTION, "", ...item.split("\n")].join("\n");
-    return { body: newBody, mutated: true, sectionExisted: false };
+    return lines.slice(0, end);
+}
+function trimBlankLines(lines) {
+    const first = lines.findIndex((line) => line.trim() !== "");
+    return first === -1 ? [] : trimTrailingBlankLines(lines.slice(first));
 }

package/bin/commands/poll.mjs

@@ -6,7 +6,7 @@ function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
         process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
     }
     else {
-        process.stderr.write(".");
+        process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — still running; next tick in ${sleepSeconds}s\n`);
     }
 }
 function waitSignature(result) {
@@ -73,7 +73,6 @@ export async function runPoll(opts) {
     const verbose = opts.verbose === true;
     const quietStatus = quietStatusOpt === true;
     const untilTerminal = untilTerminalOpt === true;
-    let dotsPrinted = false;
     let lastWaitSignature = null;
     // When prNumber is omitted, iterateOpts.prNumber starts undefined and each tick would otherwise
     // re-infer the PR from the current branch. That inference query only matches OPEN PRs, so once
@@ -110,8 +109,6 @@ export async function runPoll(opts) {
                 verbose,
                 lastWaitSignature,
             });
-            if (!quietStatus && !verbose)
-                dotsPrinted = true;
             await sleep(intervalMs);
             continue;
         }
@@ -124,10 +121,6 @@ export async function runPoll(opts) {
             debounceUntil ??= Date.now() + debounceMs;
             const remainingMs = debounceUntil - Date.now();
             if (remainingMs > 0) {
-                if (dotsPrinted) {
-                    process.stderr.write("\n");
-                    dotsPrinted = false;
-                }
                 writeDebounceProgress(tick, Date.now() - start, remainingMs);
                 await sleep(Math.min(intervalMs, remainingMs));
             }
@@ -138,7 +131,5 @@ export async function runPoll(opts) {
         }
         break;
     }
-    if (dotsPrinted)
-        process.stderr.write("\n");
     return lastResult;
 }

package/bin/commands/ready-mergeability.mjs

@@ -24,6 +24,7 @@ async function readMergeability(prNumber, repo, batchData) {
     const restState = await getMergeableState(prNumber, repo.owner, repo.name);
     return {
         ...batchData,
+        state: restState.state ?? batchData.state,
         mergeable: restState.mergeable ?? batchData.mergeable,
         mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
     };

package/bin/commands/shepherd-journal.d.mts

@@ -1,6 +1,9 @@
-export declare const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
+export declare const SHEPHERD_JOURNAL_SECTION = "Shepherd Journal";
 export declare const SHEPHERD_JOURNAL_SECTION_PATTERN: RegExp;
-export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, append your entries under it instead of creating a duplicate heading.";
+export declare const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
+export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
+export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
+export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
 export declare function buildShepherdJournalInstruction(prNumber: number, itemReferenceGuidance: string): string[];
 export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "Link threads and comments from their headings. Cite reviews by ID.";

package/bin/commands/shepherd-journal.mjs

@@ -1,10 +1,13 @@
-export const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
+export const SHEPHERD_JOURNAL_SECTION = "Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
-export const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, append your entries under it instead of creating a duplicate heading.";
+export const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
+export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
+export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
+export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
 export function buildShepherdJournalInstruction(prNumber, itemReferenceGuidance) {
     return [
-        `For any substantial decision or rejection, append \`- <decision>\` to \`${SHEPHERD_JOURNAL_SECTION}\` with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`.`,
+        `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`.`,
         itemReferenceGuidance,
     ];
 }

package/bin/github/client.d.mts

@@ -34,13 +34,15 @@ export declare function getPullRequestBody(pr: number, owner: string, name: stri
 /** Overwrites the PR body. */
 export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;
 /**
- * Fetches `mergeable` and `mergeStateStatus` via the REST API.
+ * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
- * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
- * a known GitHub quirk where GraphQL lags behind the REST layer.
+ * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
+ * READY handoff. The same response carries state so a concurrent merge or
+ * close can supersede the earlier GraphQL snapshot without another request.
  */
 export declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{
     mergeable: MergeableState;
     mergeStateStatus: MergeStateStatus;
+    state?: "OPEN" | "CLOSED" | "MERGED";
 }>;
 export declare function getCurrentBranch(): Promise<string>;

package/bin/github/client.mjs

@@ -83,16 +83,23 @@ export async function updatePullRequestBody(pullRequestId, body) {
     await httpGraphql(UPDATE_PR_BODY_MUTATION, { pullRequestId, body });
 }
 /**
- * Fetches `mergeable` and `mergeStateStatus` via the REST API.
+ * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
- * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
- * a known GitHub quirk where GraphQL lags behind the REST layer.
+ * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
+ * READY handoff. The same response carries state so a concurrent merge or
+ * close can supersede the earlier GraphQL snapshot without another request.
  */
 export async function getMergeableState(pr, owner, repo) {
     const data = await rest("GET", `/repos/${owner}/${repo}/pulls/${pr}`);
     const mergeable = data.mergeable === true ? "MERGEABLE" : data.mergeable === false ? "CONFLICTING" : "UNKNOWN";
     const mergeStateStatus = data.mergeable_state.toUpperCase();
-    return { mergeable, mergeStateStatus };
+    const rawState = data.state?.toUpperCase();
+    const state = data.merged_at != null
+        ? "MERGED"
+        : rawState === "OPEN" || rawState === "CLOSED"
+            ? rawState
+            : undefined;
+    return { mergeable, mergeStateStatus, ...(state !== undefined && { state }) };
 }
 // ---------------------------------------------------------------------------
 // Internal helpers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.37.2",
+  "version": "0.38.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.37.2",
+  "version": "0.38.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

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

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.37.2", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.38.1", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.37.2", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.38.1", "pr-shepherd-mcp"]
   }
 }