pr-shepherd 0.42.0 → 0.44.0

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

@@ -10,7 +10,8 @@ Iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
-  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.
+  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
@@ -23,6 +24,7 @@ Actions:
   FIX_CODE    Agent action is required; follow the instructions, then continue polling.
   CANCEL      Stop polling: merged/closed or ready-delay elapsed.
   ESCALATE    Stop polling until a human provides direction.
+  MERGE       Run the emitted merge/queue command, then continue monitoring.
 
 Exit codes:
   0   CANCEL (merged or ready-delay elapsed)
@@ -31,6 +33,7 @@ Exit codes:
   12  FIX_CODE
   13  ESCALATE
   14  CANCEL (closed without merging)
+  15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 export const POLL_USAGE = `pr-shepherd poll
 
@@ -39,7 +42,7 @@ final tick to stdout.
 Poll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout
 returns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps
 iterating at --interval, then runs one more tick after the window and returns that result.
-With --until-terminal, poll also continues through MARK_READY.
+With --until-terminal or --merge, poll also continues through MARK_READY.
 
 Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
@@ -55,7 +58,8 @@ Forwarded iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
-  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.
+  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields and detailed per-tick lines.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
@@ -65,7 +69,7 @@ for --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout);
 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.
 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.
+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.
 
 Exit codes: same as iterate (the final tick's action/reason decides the code).
   0   CANCEL (merged or ready-delay elapsed)
@@ -74,6 +78,7 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   12  FIX_CODE
   13  ESCALATE
   14  CANCEL (closed without merging)
+  15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 /** Public help page for the default PR polling invocation. */
 export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]").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-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 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-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    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-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          Select changed files; no viewed-state mutation is attempted.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\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\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

@@ -18,7 +18,7 @@ Commands:
   [PR]                 Poll until non-WAIT or timeout. This is the default command.
   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 files          Select changed files; no viewed-state mutation is attempted.
   apply journal        Append a list item to the Shepherd Journal details block of a PR body.
   build-suggestion-patches
                        Convert ordered GitHub suggestion threads into patches and commit instructions.
@@ -38,7 +38,7 @@ Iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
-  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.
 
 Polling flags:
   --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.

package/bin/cli/help.d.mts

@@ -2,7 +2,7 @@ export declare const USAGE: {
     readonly default: string;
     readonly apply: `pr-shepherd apply
 
-Apply a review mutation, mark changed files as viewed, or append a PR journal item.
+Apply a review mutation, select changed files for authorization diagnostics, or append a PR journal item.
 
 Usage:
   pr-shepherd apply review [PR] [review-flags]
@@ -36,7 +36,8 @@ At least one action flag is required.
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply files": `pr-shepherd apply files
 
-Mark changed files as viewed in the GitHub pull request diff.
+Select changed files and report that viewed-state authorization cannot be verified.
+No file viewed-state mutation is attempted.
 
 Usage:
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
@@ -139,7 +140,8 @@ Flags:
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.
-                                  Must be a full 40-character lowercase hex SHA. Use $(git rev-parse HEAD).
+                                  Must be a full 40-character lowercase hex SHA. Local HEAD is valid
+                                  only when it equals the current remote PR head.
   --format text|json              Output format. Default: text.
   --help, -h                      Print this help and exit before GitHub I/O.
 
@@ -174,7 +176,8 @@ Exit codes:
   See docs/exit-codes.md for the full sysexits.h table.`;
     readonly "mark-files-as-viewed": `pr-shepherd mark-files-as-viewed
 
-Mark changed files as viewed in the GitHub pull request diff.
+Deprecated compatibility alias for selection-only file-view authorization diagnostics.
+No file viewed-state mutation is attempted.
 
 Usage:
   pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]
@@ -192,8 +195,8 @@ 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 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 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 clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
@@ -244,7 +247,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-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 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-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    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-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          Select changed files; no viewed-state mutation is attempted.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\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\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/iterate-flags.d.mts

@@ -6,6 +6,7 @@ interface IterateFlags {
     stallTimeoutSeconds: number;
     noAutoMarkReady: boolean;
     noAutoCancelActionable: boolean;
+    merge: boolean;
 }
 export declare function parseIterateFlags(extra: string[], cfg: ReturnType<typeof loadConfig>): IterateFlags;
 export {};

package/bin/cli/iterate-flags.mjs

@@ -10,6 +10,7 @@ export function parseIterateFlags(extra, cfg) {
     const readyDelaySeconds = parseDurationToSeconds(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes * 60, MINUTE_FLAG_OPTS);
     const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
     const noAutoCancelActionable = hasFlag(extra, "--no-auto-cancel-actionable");
+    const merge = hasFlag(extra, "--merge");
     const stallTimeoutStr = getFlag(extra, "--stall-timeout");
     const stallTimeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--stall-timeout", stallTimeoutStr, hasFlag(extra, "--stall-timeout"), MINUTE_FLAG_OPTS);
     const stallTimeoutSeconds = parseDurationToSeconds(stallTimeoutSuffix ?? "", cfg.iterate.stallTimeoutMinutes * 60, MINUTE_FLAG_OPTS);
@@ -20,5 +21,6 @@ export function parseIterateFlags(extra, cfg) {
         stallTimeoutSeconds,
         noAutoMarkReady,
         noAutoCancelActionable,
+        merge,
     };
 }

package/bin/cli/iterate-formatter.d.mts

@@ -6,7 +6,7 @@ import type { IterateResult } from "../types.mts";
  *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
  *      the output for logging and validation. Behavior is driven by `## Instructions`,
  *      not by dispatching on the tag.
- *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix push` in
+ *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix actions` in
  *      backticks — the skill extracts the backticked content for execution.
  *   3. Every action ends with a `## Instructions` section — numbered `1.`, `2.`, … —
  *      that tells the agent exactly what to do with this output. The section is

package/bin/cli/iterate-formatter.mjs

@@ -2,6 +2,7 @@ import { formatFixCodeResult } from "./fix-formatter.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, } from "./iterate-instructions.mjs";
 import { formatMergeRequirementLines } from "../merge-status/requirements-format.mjs";
+import { appendMergeQueueHeader, formatMergeAction } from "./iterate-merge-formatter.mjs";
 function formatActivityLine(result) {
     const activity = result.activity ?? {
         commitCount: 0,
@@ -35,7 +36,7 @@ function formatActivityLine(result) {
  *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
  *      the output for logging and validation. Behavior is driven by `## Instructions`,
  *      not by dispatching on the tag.
- *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix push` in
+ *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix actions` in
  *      backticks — the skill extracts the backticked content for execution.
  *   3. Every action ends with a `## Instructions` section — numbered `1.`, `2.`, … —
  *      that tells the agent exactly what to do with this output. The section is
@@ -54,10 +55,10 @@ export function formatIterateResult(result, opts) {
     if (verbose) {
         let verboseBranch = "";
         if (result.mergeStatus === "BEHIND" && result.baseBranch) {
-            verboseBranch = ` · **branch** behind \`origin/${result.baseBranch}\``;
+            verboseBranch = ` · **branch** behind PR base \`${result.baseBranch}\``;
         }
         else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
-            verboseBranch = ` · **branch** conflicts with \`origin/${result.baseBranch}\``;
+            verboseBranch = ` · **branch** conflicts with PR base \`${result.baseBranch}\``;
         }
         summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}`;
     }
@@ -80,16 +81,15 @@ export function formatIterateResult(result, opts) {
         if (result.isDraft)
             segs.push(`**isDraft**`);
         if (result.mergeStatus === "BEHIND" && result.baseBranch) {
-            segs.push(`**branch** behind \`origin/${result.baseBranch}\``);
+            segs.push(`**branch** behind PR base \`${result.baseBranch}\``);
         }
         else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
-            segs.push(`**branch** conflicts with \`origin/${result.baseBranch}\``);
+            segs.push(`**branch** conflicts with PR base \`${result.baseBranch}\``);
         }
         summaryLine = segs.join(" · ");
     }
     // Surface an explicit `--ready-delay` override (set only when the user passed the flag)
     // so the active settle window stays visible on every tick. Replaces the rerun command
-    // that previously carried the suffix in the (now removed) recheck instruction.
     if (readyDelaySuffix) {
         summaryLine += ` · **ready-delay** \`${readyDelaySuffix}\` (override)`;
     }
@@ -127,6 +127,7 @@ export function formatIterateResult(result, opts) {
         const names = result.supersededNames.map((n) => "`" + n + "`").join(", ");
         headerLines.push(`**superseded** ${names}`);
     }
+    appendMergeQueueHeader(headerLines, result);
     const activityLine = formatActivityLine(result);
     if (activityLine)
         headerLines.push(activityLine);
@@ -144,6 +145,8 @@ export function formatIterateResult(result, opts) {
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
+        case "merge":
+            return formatMergeAction(header, result);
         case "cancel": {
             const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
             if (result.mergeRequirements) {

package/bin/cli/iterate-instructions.mjs

@@ -1,3 +1,5 @@
+import { renderMergeCommand } from "../commands/iterate/merge.mjs";
+import { inlineCode } from "../util/markdown.mjs";
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
@@ -8,6 +10,19 @@ export function buildSimpleIterateInstructions(result) {
             return [
                 "The CLI marked the PR ready for review. Iterate again with the same options to continue.",
             ];
+        case "merge": {
+            const instructions = [
+                `Run the \`${result.merge.mode === "queue" ? "merge queue" : "auto-merge"}\` command shown above exactly as printed.`,
+            ];
+            if (result.merge.mode === "queue" && result.merge.queueApiFallbackCommand) {
+                instructions.push(`If the gh CLI says auto-merge is disabled instead of adding the PR to the queue, run the \`queue API fallback\` command: ${inlineCode(renderMergeCommand(result.merge.queueApiFallbackCommand))}.`);
+            }
+            else if (result.merge.fallbackCommand) {
+                instructions.push(`Only if GitHub reports that auto-merge is unavailable, run the \`plain merge fallback\` command: ${inlineCode(renderMergeCommand(result.merge.fallbackCommand))}.`);
+            }
+            instructions.push("Then iterate again with the same options to monitor until the PR merges or needs work.");
+            return instructions;
+        }
         case "cancel":
             return ["Stop — the PR loop is complete. No further polling is needed."];
         case "escalate":

package/bin/cli/iterate-lean.d.mts

@@ -8,5 +8,4 @@ interface IterateProjectionOptions {
  * outside the state where they are meaningful.
  */
 export declare function projectIterateLean(result: IterateResult, opts?: IterateProjectionOptions): unknown;
-export declare function projectIterateVerbose(result: IterateResult, opts?: IterateProjectionOptions): unknown;
-export {};
+export { projectIterateVerbose } from "./iterate-verbose.mts";

package/bin/cli/iterate-lean.mjs

@@ -42,6 +42,7 @@ export function projectIterateLean(result, opts) {
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
         ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
         ...(result.mergeRequirements && { mergeRequirements: result.mergeRequirements }),
+        ...(result.mergeQueue && { mergeQueue: result.mergeQueue }),
         ...(hasActivity && {
             activity: {
                 commitCount: activity.commitCount,
@@ -85,6 +86,12 @@ export function projectIterateLean(result, opts) {
                 log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
+        case "merge":
+            return {
+                ...base,
+                merge: result.merge,
+                instructions: simpleInstructions(result),
+            };
         case "fix_code":
             return {
                 ...base,
@@ -122,6 +129,7 @@ export function projectIterateLean(result, opts) {
                     ...(result.fix.protectedRuns.length > 0 && {
                         protectedRuns: result.fix.protectedRuns,
                     }),
+                    ...(result.fix.requeue && { requeue: result.fix.requeue }),
                     ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
                     ...(result.fix.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.fix.changesRequestedReviews,
@@ -157,6 +165,13 @@ export function projectIterateLean(result, opts) {
                         result.escalate.thrashHistory.length > 0 && {
                         thrashHistory: result.escalate.thrashHistory,
                     }),
+                    ...(result.escalate.mergeQueueRemoval && {
+                        mergeQueueRemoval: result.escalate.mergeQueueRemoval,
+                    }),
+                    ...(result.escalate.authorization &&
+                        result.escalate.authorization.length > 0 && {
+                        authorization: result.escalate.authorization,
+                    }),
                     suggestion: result.escalate.suggestion,
                     humanMessage: result.escalate.humanMessage,
                 },
@@ -164,20 +179,4 @@ export function projectIterateLean(result, opts) {
             };
     }
 }
-export function projectIterateVerbose(result, opts) {
-    const readyDelaySuffix = opts?.readyDelaySuffix;
-    const readyDelayOverride = readyDelaySuffix ? { readyDelayOverride: readyDelaySuffix } : {};
-    if (result.action === "fix_code") {
-        return {
-            ...result,
-            ...readyDelayOverride,
-        };
-    }
-    const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
-    return {
-        ...result,
-        ...log,
-        ...readyDelayOverride,
-        instructions: buildSimpleIterateInstructions(result),
-    };
-}
+export { projectIterateVerbose } from "./iterate-verbose.mjs";

package/bin/cli/iterate-merge-formatter.d.mts

@@ -0,0 +1,3 @@
+import type { IterateResult, IterateResultMerge } from "../types.mts";
+export declare function appendMergeQueueHeader(lines: string[], result: IterateResult): void;
+export declare function formatMergeAction(header: string, result: IterateResultMerge): string;

package/bin/cli/iterate-merge-formatter.mjs

@@ -0,0 +1,52 @@
+import { renderMergeCommand } from "../commands/iterate/merge.mjs";
+import { inlineCode, joinSections } from "../util/markdown.mjs";
+import { buildSimpleIterateInstructions, numberInstructions } from "./iterate-instructions.mjs";
+export function appendMergeQueueHeader(lines, result) {
+    const queue = result.mergeQueue;
+    if (!queue)
+        return;
+    const parts = [`enabled \`${queue.enabled}\``, `inQueue \`${queue.inQueue}\``];
+    if (queue.entry) {
+        parts.push(`state \`${queue.entry.state}\``, `position \`${queue.entry.position}\``);
+        if (queue.entry.estimatedTimeToMerge !== null) {
+            parts.push(`estimatedTimeToMerge \`${queue.entry.estimatedTimeToMerge}\``);
+        }
+        if (queue.entry.enqueuedAtUnix !== undefined) {
+            parts.push(`enqueuedAtUnix \`${queue.entry.enqueuedAtUnix}\``);
+        }
+        if (queue.entry.enqueuer)
+            parts.push(`enqueuer \`@${queue.entry.enqueuer}\``);
+        if (queue.entry.headCommitOid)
+            parts.push(`headCommit \`${queue.entry.headCommitOid}\``);
+    }
+    if (queue.checkCommitOid)
+        parts.push(`checkCommit \`${queue.checkCommitOid}\``);
+    if (queue.checksIncomplete)
+        parts.push("checks incomplete (first 100 shown)");
+    if (queue.headUpdatedAfterRemoval)
+        parts.push("head updated after removal");
+    lines.push(`**merge queue** ${parts.join(" · ")}`);
+    if (queue.autoMergeRequest) {
+        lines.push(`**auto-merge** method \`${queue.autoMergeRequest.mergeMethod}\` · enabledAtUnix \`${queue.autoMergeRequest.enabledAtUnix}\`${queue.autoMergeRequest.enabledBy ? ` · by \`@${queue.autoMergeRequest.enabledBy}\`` : ""}`);
+    }
+    if (queue.latestRemoval) {
+        const removal = queue.latestRemoval;
+        lines.push(`**queue removal** reason \`${removal.reason ?? "not provided"}\` · createdAtUnix \`${removal.createdAtUnix}\`${removal.actor ? ` · actor \`@${removal.actor}\`` : ""}${removal.beforeCommitOid ? ` · commit \`${removal.beforeCommitOid}\`` : ""}${removal.beforeCommitParentOids ? ` · parents \`${removal.beforeCommitParentOids.join(",")}\`` : ""}`);
+    }
+}
+export function formatMergeAction(header, result) {
+    const commandLines = [
+        `- ${result.merge.mode === "queue" ? "merge queue" : "auto-merge"}: ${inlineCode(renderMergeCommand(result.merge.command))}`,
+    ];
+    if (result.merge.fallbackCommand) {
+        commandLines.push(`- plain merge fallback: ${inlineCode(renderMergeCommand(result.merge.fallbackCommand))}`);
+    }
+    if (result.merge.queueApiFallbackCommand) {
+        commandLines.push(`- queue API fallback: ${inlineCode(renderMergeCommand(result.merge.queueApiFallbackCommand))}`);
+    }
+    return joinSections([
+        header,
+        `## Merge command\n\n${commandLines.join("\n")}`,
+        `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
+    ]);
+}

package/bin/cli/iterate-verbose.d.mts

@@ -0,0 +1,6 @@
+import type { IterateResult } from "../types.mts";
+interface IterateProjectionOptions {
+    readyDelaySuffix?: string;
+}
+export declare function projectIterateVerbose(result: IterateResult, opts?: IterateProjectionOptions): unknown;
+export {};

package/bin/cli/iterate-verbose.mjs

@@ -0,0 +1,14 @@
+import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
+export function projectIterateVerbose(result, opts) {
+    const readyDelaySuffix = opts?.readyDelaySuffix;
+    const readyDelayOverride = readyDelaySuffix ? { readyDelayOverride: readyDelaySuffix } : {};
+    if (result.action === "fix_code")
+        return { ...result, ...readyDelayOverride };
+    const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
+    return {
+        ...result,
+        ...log,
+        ...readyDelayOverride,
+        instructions: buildSimpleIterateInstructions(result),
+    };
+}

package/bin/cli/journal-formatter.mjs

@@ -1,4 +1,7 @@
 export function formatJournalResult(result) {
+    if (result.authorizationSkipped) {
+        return `Authorization denied or unverifiable — Shepherd Journal in PR #${result.prNumber} was not updated.`;
+    }
     if (result.dryRun) {
         const lines = ["Dry run — no body change written."];
         if (result.previewBody !== undefined) {

package/bin/cli/journal-handler.mjs

@@ -1,7 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { EXIT, errorToExitCode } from "../exit-codes.mjs";
 import { runJournal } from "../commands/journal/index.mjs";
-import { getFlag, parsePrNumber } from "./args.mjs";
+import { getFlag } from "./args.mjs";
+import { parseCliPrReference, resolveParsedPrTarget } from "../pr-reference.mjs";
 import { USAGE } from "./help.mjs";
 import { formatJournalResult } from "./journal-formatter.mjs";
 export async function handleJournal(args, command = "apply journal") {
@@ -16,7 +17,7 @@ export async function handleJournal(args, command = "apply journal") {
         process.exitCode = EXIT.USAGE;
         return;
     }
-    const { prNumber, extra } = parseJournalArgs(args);
+    const { prNumber, targetRepository, extra } = parseJournalArgs(args);
     const filePath = getFlag(args, "--file");
     if (filePath !== null && extra[0]) {
         process.stderr.write(`pr-shepherd: ${command}: provide the entry as a positional argument or via --file, not both\n`);
@@ -41,7 +42,7 @@ export async function handleJournal(args, command = "apply journal") {
     const jsonOut = args.some((a) => a === "--format=json") ||
         args.some((a, i) => a === "--format" && args[i + 1] === "json");
     try {
-        const result = await runJournal({ prNumber, rawItem, dryRun });
+        const result = await runJournal({ prNumber, targetRepository, rawItem, dryRun });
         if (jsonOut) {
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         }
@@ -79,6 +80,7 @@ function parseJournalArgs(args) {
         }
     }
     let prNumber;
+    let targetRepository;
     const extra = [];
     for (let i = 0; i < args.length; i++) {
         if (flagConsumedIndices.has(i))
@@ -87,13 +89,15 @@ function parseJournalArgs(args) {
         if (a.startsWith("--"))
             continue;
         if (prNumber === undefined) {
-            const n = parsePrNumber(a);
-            if (n !== null) {
-                prNumber = n;
+            const parsed = parseCliPrReference(a);
+            if (parsed !== null) {
+                const target = resolveParsedPrTarget(parsed);
+                prNumber = target.prNumber;
+                targetRepository = target.targetRepository;
                 continue;
             }
         }
         extra.push(a);
     }
-    return { prNumber, extra };
+    return { prNumber, targetRepository, extra };
 }

package/bin/cli/list-formatters.d.mts

@@ -1,6 +1,6 @@
 import type { AuthorType, CommentAuthorAssociation, SuggestionBlock } from "../types.mts";
 import type { FirstLookThread, FirstLookComment } from "../types/report.mts";
-export declare function renderAuthor(author: string, authorType?: AuthorType, authorAssociation?: CommentAuthorAssociation): string;
+export declare function renderAuthor(author: string, authorType?: AuthorType, authorAssociation?: CommentAuthorAssociation, viewerDidAuthor?: boolean): string;
 export declare function renderBodyPreview(body: string): string;
 export declare function renderThreadResolutionStatusTag(t: {
     isOutdated?: boolean;
@@ -16,12 +16,14 @@ interface ThreadBulletInput {
     author: string;
     authorType?: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     comments?: Array<{
         id: string;
         author: string;
         authorType?: AuthorType;
         authorAssociation?: CommentAuthorAssociation;
+        viewerDidAuthor?: true;
         body: string;
         url: string;
     }>;

package/bin/cli/list-formatters.mjs

@@ -1,8 +1,10 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
 import { threadComments } from "../threads/transcript.mjs";
 const BODY_PREVIEW_MAX = 100;
-export function renderAuthor(author, authorType, authorAssociation) {
-    return [`@${author}`, authorType, authorAssociation].filter(Boolean).join(" · ");
+export function renderAuthor(author, authorType, authorAssociation, viewerDidAuthor) {
+    return [`@${author}`, authorType, authorAssociation, viewerDidAuthor ? "viewer-authored" : null]
+        .filter(Boolean)
+        .join(" · ");
 }
 export function renderBodyPreview(body) {
     const normalizedBody = body.replace(/\r\n?/g, "\n");
@@ -30,7 +32,7 @@ export function renderThreadBullet(t, opts = {}) {
     const editedMarker = t.edited && !opts.suppressEditedMarker ? " [edited since first look]" : "";
     const reviewMarker = t.reviewId ? ` [reviewId=${t.reviewId}]` : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType, t.authorAssociation)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType, t.authorAssociation, t.viewerDidAuthor)})${reviewMarker}${suggestionMarker}${editedMarker}${statusSuffix}`;
     if (!opts.noBody && (!t.comments || t.comments.length === 0)) {
         const legacyLine = `${bulletLine}: ${renderBodyPreview(t.body)}`;
         return t.suggestion && opts.renderSuggestion
@@ -53,9 +55,9 @@ export function renderThreadConversation(t) {
         .map((c) => {
         const heading = c.id
             ? c.url
-                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
-                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`
-            : `#### (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`;
+                ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`
+                : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`
+            : `#### (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`;
         return `${heading}\n\n${blockquote(c.body)}`;
     })
         .join("\n\n");
@@ -73,7 +75,7 @@ function renderThreadCommentBullets(t) {
         const link = c.url ? ` [↗](${c.url})` : "";
         const id = c.id ? `\`commentId=${c.id}\`` : "comment";
         return [
-            `  - ${id}${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})`,
+            `  - ${id}${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`,
             indentBlockquote(c.body, "    "),
         ].join("\n");
     })

package/bin/cli/mark-files-as-viewed-formatter.mjs

@@ -1,8 +1,14 @@
 export function formatMarkFilesAsViewedResult(result) {
     const lines = [];
-    lines.push(`# PR #${result.prNumber} — Mark files as viewed (${result.markedPaths.length} marked)`);
+    lines.push(`# PR #${result.prNumber} — File-view selection (${result.matchedPaths.length} selected)`);
     lines.push("");
     lines.push(`repo: ${result.repo}`);
+    if (result.authorizationSkipped) {
+        lines.push("");
+        lines.push("## Authorization");
+        lines.push("");
+        lines.push("- Not marked: GitHub does not expose a capability that confirms the current viewer may mark PR files as viewed.");
+    }
     appendPathSection(lines, "Matched files", result.matchedPaths);
     appendPathSection(lines, "Marked viewed", result.markedPaths);
     appendPathSection(lines, "Already viewed", result.alreadyViewedPaths);