pr-shepherd 0.46.0 → 0.46.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.46.0",
+  "version": "0.46.2",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -25,14 +25,14 @@ Full reference: [docs/README.md](docs/README.md). Feature matrix: [docs/features
 
 `pr-shepherd` moves deterministic PR orchestration into a local MCP server, with a CLI for shells and CI. Both interfaces fetch the same GitHub state, emit raw-enough context, and return a numbered plan for the calling agent to follow.
 
-The MCP server exposes canonical `iterate`, `apply`, and `build_suggestion_patches` tools. `apply` accepts ordered review mutations, selection-only file-view diagnostics, and journal entries; the deprecated singular suggestion tool remains temporarily as an adapter. Direct MCP calls require a repository-qualified `pr`: a GitHub PR URL or `owner/repo#N`; the explicit repository is the target for GitHub I/O, even when it differs from the local checkout. The CLI and programmatic API also retain bare-number and current-branch PR discovery. The shipped skills are thin dispatchers for those tools.
+The MCP server exposes canonical `iterate`, `apply`, and `build_suggestion_patches` tools. `apply` accepts ordered review mutations, file-view mutations, and journal entries; the deprecated singular suggestion tool remains temporarily as an adapter. Direct MCP calls require a repository-qualified `pr`: a GitHub PR URL or `owner/repo#N`; the explicit repository is the target for GitHub I/O, even when it differs from the local checkout. The CLI and programmatic API also retain bare-number and current-branch PR discovery. The shipped skills are thin dispatchers for those tools.
 
 Each tick returns exactly one action:
 
 - `WAIT` — no immediate action; continue with the next poll.
 - `MARK_READY` — the CLI converted an eligible draft PR to ready; continue polling.
 - `FIX_CODE` — agent work is required; complete it, push when needed, then continue polling. Push access to the PR head branch is a usage precondition.
-- `MERGE` — run the emitted auto-merge command only when GitHub reports `viewerCanEnableAutoMerge`; missing authorization returns `ESCALATE`.
+- `MERGE` — run the emitted head-pinned auto-merge or queue command. Ordinary merges include a plain-merge fallback; queue merges include a GraphQL enqueue fallback. GitHub is authoritative for the result and reports any authorization failure.
 - `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
 - `ESCALATE` — stop polling until a human provides direction.
 
@@ -84,12 +84,12 @@ See [docs/actions.md](docs/actions.md) for the complete output contract and [doc
 This system is opinionated and works best with PRs that use required status checks and conversation resolution.
 
 - A human inline thread whose original comment has `viewerDidAuthor: true` is replied to and resolved when its latest comment is unmarked. An unmarked other-human inline thread remains reply-only; a marker-ended other-human thread is already acknowledged and receives no further mutation. Human items are never minimized.
-- Detected bots and configured `botUsernames` review threads are returned until resolved when the required mutation is authorized and the thread has a source location. Unauthorized or unlocated items are surfaced once and then marker-gated until edited. Bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
+- Detected bots and configured `botUsernames` review threads are returned until resolved when the required mutation is authorized and the thread has a source location. Authorized outdated bot threads remain resolution-only work even when GitHub clears their source line, because resolving by thread ID does not require that location. Unauthorized or other unlocated items are surfaced once and then marker-gated until edited. Bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
 - Shepherd identifies its own latest reply only when that comment begins `<!-- pr-shepherd -->`, not from author equality. A marked viewer-authored thread can be resolved without another reply as a retry.
 - Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
 - The CLI never performs git mutations itself — it only emits commit/push instructions for the agent to run. Push access to the PR head is a usage precondition; GitHub viewer fields do not create a separate push-authorization handoff.
-- Every GitHub mutation is permission-aware. Shepherd uses raw viewer capability fields, omits unauthorized commands, and repeats authorization checks in direct `apply` commands. Missing capability data fails closed.
+- Generated iterate mutations and automatic actions are capability-aware and omit unauthorized commands. Explicit `apply` operations honor the caller's intent and surface GitHub's result; semantic human-content protections still apply.
 - `build_suggestion_patches` turns one or more ordered GitHub suggestion threads into checked patches and commit metadata, but never edits the working tree or git history. Local HEAD may be ahead when the live PR head is its ancestor.
 
 ## Usage
@@ -128,7 +128,7 @@ pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshot
 pr-shepherd 42 --until-terminal        # continue through WAIT/MARK_READY until work or terminal state
 pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE, then return one batched tick
 pr-shepherd 42 --ready-delay 15m
-pr-shepherd 42 --merge                  # enable auto-merge when GitHub confirms viewer authorization
+pr-shepherd 42 --merge                  # request head-pinned auto-merge/queue; GitHub reports the result
 pr-shepherd iterate 42                 # single tick
 pr-shepherd owner/repo#42              # poll a PR in an explicit repository
 pr-shepherd https://github.com/owner/repo/pull/42
@@ -136,7 +136,7 @@ pr-shepherd https://github.com/owner/repo/pull/42
 
 ### Apply Review And Journal Changes, Or Select Files
 
-Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, select changed files for viewed-state authorization diagnostics, or append an idempotent Shepherd Journal item. File-view selection never mutates viewed state because GitHub exposes no exact viewer capability. Use `build_suggestion_patches` to turn ordered review suggestions into checked patches and commit metadata; it never changes the worktree or git history.
+Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, mark selected changed files as viewed, or append an idempotent Shepherd Journal item. Explicit operations are attempted and surface GitHub's per-operation results; generated iterate guidance remains capability-filtered. Use `build_suggestion_patches` to turn ordered review suggestions into checked patches and commit metadata; it never changes the worktree or git history.
 
 ### Extract Shepherd Journal Entries
 

package/bin/api.d.mts

@@ -22,7 +22,7 @@ export interface ReviewMutationsOperation {
     requireSha?: string;
 }
 export interface MarkFilesViewedOperation {
-    /** Compatibility-named selection only; always skips mutation because authorization is unverifiable. */
+    /** Marks selected changed files as viewed. GitHub authorizes the requested mutation. */
     type: "mark_files_viewed";
     files?: string[];
     tests?: boolean;
@@ -33,7 +33,7 @@ export interface AppendJournalOperation {
     item: string;
     dryRun?: boolean;
 }
-/** Operations run in this exact list order after validation; file-view selection is non-mutating. */
+/** Operations run in this exact list order after validation. */
 export type ApplyOperation = ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation;
 export interface ApplyInput {
     /** PR shared by every operation in this ordered apply request. */

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

@@ -2,7 +2,7 @@ export declare const COMMAND_USAGE: {
     readonly default: string;
     readonly apply: `pr-shepherd apply
 
-Apply a review mutation, select changed files for authorization diagnostics, or append a PR journal item.
+Apply review mutations, mark selected changed files as viewed, or append a PR journal item.
 
 Usage:
   pr-shepherd apply review [PR] [review-flags]
@@ -36,8 +36,7 @@ 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
 
-Select changed files and report that viewed-state authorization cannot be verified.
-No file viewed-state mutation is attempted.
+Mark selected changed files as viewed.
 
 Usage:
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
@@ -176,8 +175,7 @@ Exit codes:
   See docs/exit-codes.md for the full sysexits.h table.`;
     readonly "mark-files-as-viewed": `pr-shepherd mark-files-as-viewed
 
-Deprecated compatibility alias for selection-only file-view authorization diagnostics.
-No file viewed-state mutation is attempted.
+Deprecated compatibility alias for marking selected PR files as viewed.
 
 Usage:
   pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]

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

@@ -5,7 +5,7 @@ export const COMMAND_USAGE = {
     default: DEFAULT_USAGE,
     apply: `pr-shepherd apply
 
-Apply a review mutation, select changed files for authorization diagnostics, or append a PR journal item.
+Apply review mutations, mark selected changed files as viewed, or append a PR journal item.
 
 Usage:
   pr-shepherd apply review [PR] [review-flags]
@@ -39,8 +39,7 @@ At least one action flag is required.
 --help, -h                      Print this help and exit before GitHub I/O.`,
     "apply files": `pr-shepherd apply files
 
-Select changed files and report that viewed-state authorization cannot be verified.
-No file viewed-state mutation is attempted.
+Mark selected changed files as viewed.
 
 Usage:
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
@@ -179,8 +178,7 @@ Exit codes:
   See docs/exit-codes.md for the full sysexits.h table.`,
     "mark-files-as-viewed": `pr-shepherd mark-files-as-viewed
 
-Deprecated compatibility alias for selection-only file-view authorization diagnostics.
-No file viewed-state mutation is attempted.
+Deprecated compatibility alias for marking selected PR files as viewed.
 
 Usage:
   pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]

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

@@ -1 +1 @@
-export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          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  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\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 journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\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:
   [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          Select changed files; no viewed-state mutation is attempted.
+  apply files          Mark selected changed files as viewed.
   apply journal        Append a list item to the Shepherd Journal details block of a PR body.
   journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.
   build-suggestion-patches

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, select changed files for authorization diagnostics, or append a PR journal item.
+Apply review mutations, mark selected changed files as viewed, or append a PR journal item.
 
 Usage:
   pr-shepherd apply review [PR] [review-flags]
@@ -36,8 +36,7 @@ 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
 
-Select changed files and report that viewed-state authorization cannot be verified.
-No file viewed-state mutation is attempted.
+Mark selected changed files as viewed.
 
 Usage:
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
@@ -176,8 +175,7 @@ Exit codes:
   See docs/exit-codes.md for the full sysexits.h table.`;
     readonly "mark-files-as-viewed": `pr-shepherd mark-files-as-viewed
 
-Deprecated compatibility alias for selection-only file-view authorization diagnostics.
-No file viewed-state mutation is attempted.
+Deprecated compatibility alias for marking selected PR files as viewed.
 
 Usage:
   pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]
@@ -260,7 +258,7 @@ On POSIX, the final body-file path entry must be a readable regular file in a tr
 symlinks, FIFOs, devices, and unreadable paths exit 66. Unsupported platforms fail closed with exit 66.
 --help, -h                      Print this help and exit before any I/O.`;
     readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
-    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          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  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\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 journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\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/mark-files-as-viewed-formatter.mjs

@@ -3,12 +3,11 @@ export function formatMarkFilesAsViewedResult(result) {
     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.");
-    }
+    lines.push(`pullRequestId: ${result.pullRequestId}`);
+    appendPathSection(lines, "Requested exact paths", result.requestedPaths);
+    if (result.testSelector)
+        appendTextSection(lines, "Selectors", ["--tests"]);
+    appendTextSection(lines, "Match selectors", result.matchPatterns.map((pattern) => `--match ${pattern}`));
     appendPathSection(lines, "Matched files", result.matchedPaths);
     appendPathSection(lines, "Marked viewed", result.markedPaths);
     appendPathSection(lines, "Already viewed", result.alreadyViewedPaths);
@@ -22,9 +21,11 @@ export function formatMarkFilesAsViewedResult(result) {
             result.rateLimit.remaining !== undefined && result.rateLimit.limit !== undefined
                 ? `remaining ${result.rateLimit.remaining}/${result.rateLimit.limit}`
                 : null,
+            result.rateLimit.used !== undefined ? `used ${result.rateLimit.used}` : null,
             result.rateLimit.resetAt !== undefined
                 ? `reset at ${new Date(result.rateLimit.resetAt * 1000).toISOString()}`
                 : null,
+            result.rateLimit.resource !== undefined ? `resource ${result.rateLimit.resource}` : null,
         ]
             .filter(Boolean)
             .join(", ");

package/bin/commands/check.mjs

@@ -17,7 +17,7 @@ import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, }
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
-import { buildThreadMutationRouting } from "./iterate/thread-mutation-routing.mjs";
+import { buildThreadMutationRouting, canResolveOutdatedBotWithoutLocation, } from "./iterate/thread-mutation-routing.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -86,10 +86,11 @@ export async function runCheck(opts) {
     const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
     const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
     const repeatableThreadIds = new Set(visibleThreadCandidates
-        .filter((thread) => thread.path !== null &&
+        .filter((thread) => (thread.path !== null &&
         thread.line !== null &&
         (!replyThreadIds.has(thread.id) || thread.viewerCanReply === true) &&
-        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true))
+        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true)) ||
+        canResolveOutdatedBotWithoutLocation(thread, botUsernames))
         .map((thread) => thread.id));
     const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {

package/bin/commands/iterate/escalate.mjs

@@ -202,7 +202,7 @@ export function buildEscalateSuggestion(triggers, detail) {
         return "One or more failing checks have no autonomous follow-up available. Use the displayed conclusion, run or URL, and included evidence to handle them manually.";
     }
     if (triggers.includes("authorization-required")) {
-        return "GitHub did not confirm that the current viewer may perform the requested mark-ready or merge/enqueue operation. Ask a repository maintainer to perform that state change; Shepherd will not recommend a command that would be denied.";
+        return "GitHub did not confirm that the current viewer may perform the automatic mark-ready operation. Ask a repository maintainer to mark the pull request ready before resuming Shepherd.";
     }
     if (triggers.includes("merge-queue-removed")) {
         const reason = detail ? ` GitHub reason: ${detail}.` : "";

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

@@ -5,7 +5,7 @@ import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/ag
 import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
 import { buildResolveCommand } from "./classify.mjs";
-import { buildThreadMutationRouting } from "./thread-mutation-routing.mjs";
+import { buildThreadMutationRouting, canResolveOutdatedBotWithoutLocation, } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
@@ -157,7 +157,9 @@ export async function handleFixCode(ctx) {
         isConfiguredBotAuthor(review, botUsernames));
     const skippedDismissalIds = new Set(unauthorizedDismissals.map((review) => review.id));
     const changesRequestedReviewsForWork = actionableChangesRequestedReviews.filter((review) => !skippedDismissalIds.has(review.id));
-    const resolutionOnlyThreadsForWork = resolutionOnlyThreads.filter((thread) => !skippedThreadIds.has(thread.id) && thread.path !== null && thread.line !== null);
+    const resolutionOnlyThreadsForWork = resolutionOnlyThreads.filter((thread) => !skippedThreadIds.has(thread.id) &&
+        ((thread.path !== null && thread.line !== null) ||
+            canResolveOutdatedBotWithoutLocation(thread, botUsernames)));
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { behindBaseHint } = loadConfig().iterate;
@@ -209,15 +211,16 @@ export async function handleFixCode(ctx) {
     const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(retryableAgentThreads, resolutionOnlyThreadsForWork, allCommentIds, changesRequestedReviewsForWork, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
-    // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:
-    // resolution-only threads also need a known base in case the agent does push.
+    // prediction that the agent *will* push. Located resolution-only threads retain that guard;
+    // an outdated bot thread resolved only by ID has no code or push path.
+    const locatedResolutionOnlyThreadsForWork = resolutionOnlyThreadsForWork.filter((thread) => thread.path !== null && thread.line !== null);
     const pushIsPlausible = retryableActionableThreads.length > 0 ||
         failingAgentChecks.length > 0 ||
         annotatedExtra.length > 0 ||
         hasConflicts ||
         changesRequestedReviewsForWork.length > 0 ||
         actionableComments.length > 0 ||
-        resolutionOnlyThreadsForWork.length > 0;
+        locatedResolutionOnlyThreadsForWork.length > 0;
     if (baseLookup.isFallback && pushIsPlausible) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],

package/bin/commands/iterate/merge-state.mjs

@@ -7,45 +7,16 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
         return null;
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
-    // A merge queue is enrolled the same way auto-merge is granted: enabling
-    // auto-merge on a queue-required PR is what adds it to the queue, so
-    // viewerCanEnableAutoMerge authorizes both the plain-merge and enqueue paths.
-    if (report.viewerAuthorization?.viewerCanEnableAutoMerge === true) {
-        return {
-            ...base,
-            action: "merge",
-            merge: buildMergeCommandPlan({
-                pr: report.pr,
-                repo: report.repo,
-                nodeId: report.nodeId,
-                headSha: report.headSha ?? "unknown",
-                queue,
-            }),
-        };
-    }
-    const authorizationEscalateBase = {
-        triggers: ["authorization-required"],
-        unresolvedThreads: [],
-        ambiguousComments: [],
-        changesRequestedReviews: [],
-        authorization: [
-            {
-                action: "merge-or-enqueue",
-                targetIds: [report.nodeId],
-                reason: "denied-or-unverifiable",
-            },
-        ],
-        suggestion: buildEscalateSuggestion(["authorization-required"]),
-    };
     return {
         ...base,
-        action: "escalate",
-        escalate: {
-            ...authorizationEscalateBase,
-            humanMessage: buildEscalateHumanMessage(authorizationEscalateBase, report.pr, {
-                merge: true,
-            }),
-        },
+        action: "merge",
+        merge: buildMergeCommandPlan({
+            pr: report.pr,
+            repo: report.repo,
+            nodeId: report.nodeId,
+            headSha: report.headSha ?? "unknown",
+            queue,
+        }),
     };
 }
 export async function handleActiveMergeState(input) {

package/bin/commands/iterate/merge.mjs

@@ -38,6 +38,7 @@ export function buildMergeCommandPlan(input) {
     return {
         mode: "auto",
         command: { argv: [...base, "--auto", ...commandArgs] },
+        fallbackCommand: { argv: [...base, ...commandArgs] },
     };
 }
 export function renderMergeCommand(command) {

package/bin/commands/iterate/thread-mutation-routing.d.mts

@@ -6,4 +6,5 @@ export interface ThreadMutationRouting {
     standaloneResolveThreadIds: string[];
     resolveThreadIds: string[];
 }
+export declare function canResolveOutdatedBotWithoutLocation(thread: ReviewThread, botUsernames: NormalizedBotUsernames): boolean;
 export declare function buildThreadMutationRouting(threads: Array<AgentThread | ReviewThread>, botUsernames: NormalizedBotUsernames, ruleAutoResolveThreadIds: string[]): ThreadMutationRouting;

package/bin/commands/iterate/thread-mutation-routing.mjs

@@ -3,6 +3,13 @@ import { threadEndedByShepherd } from "../../comments/marker.mjs";
 function dedupeIds(ids) {
     return [...new Set(ids)];
 }
+export function canResolveOutdatedBotWithoutLocation(thread, botUsernames) {
+    return (!thread.isResolved &&
+        thread.isOutdated &&
+        (thread.path === null || thread.line === null) &&
+        isConfiguredBotAuthor(thread, botUsernames) &&
+        thread.viewerCanResolve === true);
+}
 export function buildThreadMutationRouting(threads, botUsernames, ruleAutoResolveThreadIds) {
     const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
     const replyThreadIds = dedupeIds(threads

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

@@ -13,6 +13,7 @@ export interface JournalResult {
     sectionExisted: boolean;
     dryRun: boolean;
     previewBody?: string;
+    /** @deprecated Explicit journal requests now rely on GitHub's mutation response. */
     authorizationSkipped?: "denied-or-unverifiable";
 }
 /** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */

package/bin/commands/journal/index.mjs

@@ -12,17 +12,8 @@ export async function runJournal(opts) {
     if (!prNumber) {
         throw new Error("PR number is required: no PR number provided and none found for current branch");
     }
-    const { nodeId, body, viewerCanUpdate } = await getPullRequestBody(prNumber, owner, name);
+    const { nodeId, body } = await getPullRequestBody(prNumber, owner, name);
     const { body: newBody, mutated, sectionExisted } = appendJournalItem(body, item);
-    if (mutated && !opts.dryRun && viewerCanUpdate !== true) {
-        return {
-            prNumber,
-            mutated: false,
-            sectionExisted,
-            dryRun: false,
-            authorizationSkipped: "denied-or-unverifiable",
-        };
-    }
     if (mutated && !opts.dryRun) {
         await updatePullRequestBody(nodeId, newBody);
     }

package/bin/commands/mark-files-as-viewed.d.mts

@@ -1,4 +1,4 @@
-import type { ResolveRateLimitStop } from "../comments/rate-limit.mts";
+import { type ResolveRateLimitStop } from "../comments/rate-limit.mts";
 import type { GlobalOptions } from "../types.mts";
 export interface MarkFilesAsViewedOptions extends GlobalOptions {
     prNumber?: number;
@@ -21,6 +21,7 @@ export interface MarkFilesAsViewedResult {
     errors: string[];
     rateLimit?: ResolveRateLimitStop;
     unmarkedPaths?: string[];
+    /** @deprecated Explicit file-view requests are attempted; GitHub authorizes the mutation. */
     authorizationSkipped?: "unverifiable";
 }
 /** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */

package/bin/commands/mark-files-as-viewed.mjs

@@ -1,6 +1,7 @@
 /* eslint-disable max-lines */
-import { graphql, getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
+import { graphql, graphqlWithRateLimit, getCurrentPrNumber, getRepoInfo, } from "../github/client.mjs";
 import { paginateForward } from "../github/pagination.mjs";
+import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "../comments/rate-limit.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr: Int!, $filesCursor: String) {
   _shepherdRateLimit: rateLimit {
@@ -29,6 +30,8 @@ const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr
   }
 }`;
 const TEST_FILE_RE = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[cm]?[jt]sx?$|_tests?\.rs$|(^|\/)tests?\.rs$/i;
+// Keep mutation batches small so rate-limit stops leave an ordered pending list.
+const MARK_FILES_CHUNK_SIZE = 10;
 /** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
 export async function runMarkFilesAsViewed(opts) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
@@ -58,12 +61,121 @@ export async function runMarkFilesAsViewed(opts) {
         missingPaths: selected.missingPaths,
         unmatchedSelectors: selected.unmatchedSelectors,
         errors: [],
-        ...(selected.pathsToMark.length > 0 && { authorizationSkipped: "unverifiable" }),
     };
-    // GitHub exposes no exact viewer capability for markFileAsViewed. Repository role and
-    // viewerCanEditFiles describe different operations, so this command fails closed.
+    await markFilesAsViewed(fetched.pullRequestId, selected.pathsToMark, result);
     return result;
 }
+async function markFilesAsViewed(pullRequestId, paths, result) {
+    for (let offset = 0; offset < paths.length; offset += MARK_FILES_CHUNK_SIZE) {
+        const chunk = paths.slice(offset, offset + MARK_FILES_CHUNK_SIZE);
+        // eslint-disable-next-line no-await-in-loop
+        const pendingPaths = await markFilesChunk(pullRequestId, chunk, result, offset + MARK_FILES_CHUNK_SIZE < paths.length);
+        if (pendingPaths === null)
+            continue;
+        const unmarkedPaths = [...pendingPaths, ...paths.slice(offset + chunk.length)];
+        if (unmarkedPaths.length > 0)
+            result.unmarkedPaths = unmarkedPaths;
+        return;
+    }
+}
+/** Returns pending paths when a rate limit stops further mutation batches. */
+async function markFilesChunk(pullRequestId, paths, result, hasPendingAfter) {
+    try {
+        const response = await graphqlWithRateLimit(buildMarkFilesMutation(pullRequestId, paths), {}, { allowPartialData: true });
+        const errors = (response.errors ?? []);
+        const rateLimit = rateLimitFromGraphQlResult(errors.map((error) => error.message), {
+            rateLimit: response.rateLimit,
+            retryAfterSeconds: response.retryAfterSeconds,
+            stopOnZeroRemaining: hasPendingAfter,
+        });
+        const classifiedErrors = classifyMarkFileErrors(errors, paths.length);
+        const pendingPaths = recordMarkFileResults(paths, response.data, errors, classifiedErrors, rateLimit, result);
+        return completeMarkFilesChunk(rateLimit, pendingPaths, result);
+    }
+    catch (error) {
+        return recordMarkFilesTransportError(error, paths, result);
+    }
+}
+function classifyMarkFileErrors(errors, pathCount) {
+    const aliasesWithNonRateErrors = new Set();
+    const aliasesWithRateLimitErrors = new Set();
+    const unscopedNonRateMessages = [];
+    for (const error of errors) {
+        const aliasIndex = markFileErrorAliasIndex(error);
+        if (aliasIndex === undefined || aliasIndex >= pathCount) {
+            if (!isRateLimitMessage(error.message))
+                unscopedNonRateMessages.push(error.message);
+            continue;
+        }
+        if (isRateLimitMessage(error.message))
+            aliasesWithRateLimitErrors.add(aliasIndex);
+        else
+            aliasesWithNonRateErrors.add(aliasIndex);
+    }
+    return { aliasesWithNonRateErrors, aliasesWithRateLimitErrors, unscopedNonRateMessages };
+}
+function recordMarkFileResults(paths, data, errors, classifiedErrors, rateLimit, result) {
+    const pendingPaths = [];
+    for (let index = 0; index < paths.length; index += 1) {
+        const path = paths[index];
+        if (data[`f${index}`] != null) {
+            result.markedPaths.push(path);
+            continue;
+        }
+        const messages = errorsForMarkFileAlias(errors, index);
+        const hasRateLimitError = classifiedErrors.aliasesWithRateLimitErrors.has(index);
+        const nonRateMessages = classifiedErrors.aliasesWithNonRateErrors.has(index)
+            ? messages.filter((message) => !isRateLimitMessage(message))
+            : classifiedErrors.unscopedNonRateMessages;
+        if (nonRateMessages.length > 0) {
+            for (const message of nonRateMessages)
+                result.errors.push(`${path}: ${message}`);
+        }
+        else if (!rateLimit) {
+            result.errors.push(`${path}: ${messages[0] ?? "mark returned null"}`);
+        }
+        if (rateLimit && (hasRateLimitError || nonRateMessages.length === 0))
+            pendingPaths.push(path);
+    }
+    return pendingPaths;
+}
+function completeMarkFilesChunk(rateLimit, pendingPaths, result) {
+    if (!rateLimit)
+        return null;
+    result.errors.push(`rate limit: ${rateLimit.message}`);
+    result.rateLimit = rateLimit;
+    return pendingPaths;
+}
+function recordMarkFilesTransportError(error, paths, result) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stop = rateLimitFromError(error, message);
+    if (stop) {
+        result.errors.push(`rate limit: ${stop.message}`);
+        result.rateLimit = stop;
+        return paths;
+    }
+    for (const path of paths)
+        result.errors.push(`${path}: ${message}`);
+    return null;
+}
+function buildMarkFilesMutation(pullRequestId, paths) {
+    const operations = paths.map((path, index) => `  f${index}: markFileAsViewed(input: { pullRequestId: ${JSON.stringify(pullRequestId)}, path: ${JSON.stringify(path)} }) { clientMutationId }`);
+    return `mutation MarkFilesAsViewed {\n${operations.join("\n")}\n}`;
+}
+function markFileErrorAliasIndex(error) {
+    if (!Array.isArray(error.path))
+        return undefined;
+    const alias = error.path.find((part) => typeof part === "string" && /^f\d+$/.test(part));
+    if (typeof alias !== "string")
+        return undefined;
+    const index = Number.parseInt(alias.slice(1), 10);
+    return Number.isNaN(index) ? undefined : index;
+}
+function errorsForMarkFileAlias(errors, index) {
+    return errors
+        .filter((error) => markFileErrorAliasIndex(error) === index)
+        .map((error) => error.message);
+}
 async function fetchPullRequestFiles(pr, repo) {
     const first = await graphql(FILES_QUERY, {
         owner: repo.owner,

package/bin/commands/resolve-mutate.mjs

@@ -27,45 +27,24 @@ export async function runResolveMutate(opts) {
     const humanReviewIds = new Set([...data.reviewSummaries, ...data.approvedReviews, ...data.changesRequestedReviews]
         .filter((r) => isHumanAuthor(r) && !isConfiguredBotAuthor(r, botUsernames))
         .map((r) => r.id));
-    const replyAuthorizedIds = new Set(data.reviewThreads
-        .filter((thread) => thread.viewerCanReply === true)
-        .map((thread) => thread.id));
-    const resolveAuthorizedIds = new Set(data.reviewThreads
-        .filter((thread) => thread.viewerCanResolve === true)
-        .map((thread) => thread.id));
-    const minimizeAuthorizedIds = new Set([
-        ...data.comments
-            .filter((comment) => comment.viewerCanMinimize === true)
-            .map((comment) => comment.id),
-        ...data.reviewSummaries
-            .filter((review) => review.viewerCanMinimize === true)
-            .map((review) => review.id),
-        ...data.approvedReviews
-            .filter((review) => review.viewerCanMinimize === true)
-            .map((review) => review.id),
-    ]);
-    const requestedReplyIds = new Set((opts.replyThreadIds ?? []).filter((id) => replyAuthorizedIds.has(id)));
+    // Iterate uses viewer capability fields while deciding which commands to
+    // print. Once a caller explicitly runs apply, GitHub's mutation response is
+    // authoritative and this path must not second-guess that intent.
+    const requestedReplyIds = new Set(opts.replyThreadIds ?? []);
     const allowedViewerHumanResolveIds = new Set(data.reviewThreads
         .filter((thread) => isViewerAuthoredHuman(thread, botUsernames) &&
         (requestedReplyIds.has(thread.id) || threadEndedByShepherd(thread)))
         .map((thread) => thread.id));
-    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => (!humanThreadIds.has(id) || allowedViewerHumanResolveIds.has(id)) &&
-        resolveAuthorizedIds.has(id));
+    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id) || allowedViewerHumanResolveIds.has(id));
     const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !allowedViewerHumanResolveIds.has(id));
-    const skippedUnauthorizedResolves = (opts.resolveThreadIds ?? []).filter((id) => (!humanThreadIds.has(id) || allowedViewerHumanResolveIds.has(id)) &&
-        !resolveAuthorizedIds.has(id));
-    const replyThreadIds = opts.replyThreadIds?.filter((id) => humanThreadIds.has(id) && replyAuthorizedIds.has(id));
+    const replyThreadIds = opts.replyThreadIds?.filter((id) => humanThreadIds.has(id));
     const skippedNonHumanReplies = (opts.replyThreadIds ?? []).filter((id) => !humanThreadIds.has(id));
-    const skippedUnauthorizedReplies = (opts.replyThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !replyAuthorizedIds.has(id));
-    const minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id) && minimizeAuthorizedIds.has(id));
+    const minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id));
     const skippedHumanMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => humanCommentIds.has(id) || humanReviewIds.has(id));
-    const skippedUnauthorizedMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id) && !minimizeAuthorizedIds.has(id));
-    const dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) &&
-        data.changesRequestedReviews.some((review) => review.id === id) &&
-        data.viewerAuthorization?.viewerCanAdminister === true);
+    const dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && data.changesRequestedReviews.some((review) => review.id === id));
     const skippedHumanDismissals = (opts.dismissReviewIds ?? []).filter((id) => humanReviewIds.has(id));
-    const skippedUnauthorizedDismissals = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && !dismissReviewIds.includes(id));
-    const hasAuthorizedMutation = resolveThreadIds.length > 0 ||
+    const skippedIneligibleDismissals = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && !dismissReviewIds.includes(id));
+    const hasMutation = resolveThreadIds.length > 0 ||
         (replyThreadIds?.length ?? 0) > 0 ||
         minimizeCommentIds.length > 0 ||
         dismissReviewIds.length > 0;
@@ -75,7 +54,7 @@ export async function runResolveMutate(opts) {
         minimizeCommentIds,
         dismissReviewIds,
         dismissMessage: opts.dismissMessage,
-        requireSha: hasAuthorizedMutation ? opts.requireSha : undefined,
+        requireSha: hasMutation ? opts.requireSha : undefined,
     });
     if (skippedHumanResolves.length > 0)
         result.skippedHumanResolves = skippedHumanResolves;
@@ -85,14 +64,12 @@ export async function runResolveMutate(opts) {
         result.skippedHumanDismissals = skippedHumanDismissals;
     if (skippedNonHumanReplies.length > 0)
         result.skippedNonHumanReplies = skippedNonHumanReplies;
-    if (skippedUnauthorizedReplies.length > 0)
-        result.skippedUnauthorizedReplies = skippedUnauthorizedReplies;
-    if (skippedUnauthorizedResolves.length > 0)
-        result.skippedUnauthorizedResolves = skippedUnauthorizedResolves;
-    if (skippedUnauthorizedMinimizes.length > 0)
-        result.skippedUnauthorizedMinimizes = skippedUnauthorizedMinimizes;
-    if (skippedUnauthorizedDismissals.length > 0)
-        result.skippedUnauthorizedDismissals = skippedUnauthorizedDismissals;
+    if (skippedIneligibleDismissals.length > 0) {
+        result.skippedDismissals = [
+            ...(result.skippedDismissals ?? []),
+            ...skippedIneligibleDismissals,
+        ];
+    }
     if (opts.dismissMessage) {
         const markedMessage = addPrShepherdMarker(opts.dismissMessage);
         await Promise.all(result.repliedThreads.map((id) => {

package/bin/comments/resolve.d.mts

@@ -12,9 +12,13 @@ export interface ResolveResult {
     skippedHumanMinimizes?: string[];
     skippedHumanDismissals?: string[];
     skippedNonHumanReplies?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedReplies?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedResolves?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedMinimizes?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedDismissals?: string[];
     rateLimit?: ResolveRateLimitStop;
     unrepliedThreads?: string[];

package/bin/comments/resolve.mjs

@@ -24,6 +24,12 @@ function isCommentedDismissError(message) {
 function dismissReviewNonDismissibleMessage(id) {
     return `Not dismissed: ${id} is a COMMENTED review. Use --minimize-comment-ids instead; --dismiss-review-ids is only for CHANGES_REQUESTED reviews.`;
 }
+function mutationErrorMessage(errors, alias) {
+    const messages = errors
+        .filter((error) => Array.isArray(error.path) && error.path.includes(alias))
+        .map((error) => error.message);
+    return messages.length > 0 ? messages.join("; ") : undefined;
+}
 export async function applyResolveOptions(pr, repo, opts) {
     const resolveThreadIds = dedupeIds(opts.resolveThreadIds ?? []);
     const replyThreadIds = dedupeIds(opts.replyThreadIds ?? []);
@@ -168,21 +174,21 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
         if (p?.comment?.id)
             result.repliedThreads.push(id);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${id}: reply returned null or comment not created`);
+            result.errors.push(`${id}: ${mutationErrorMessage(graphQlErrors, `p${i}`) ?? "reply returned null or comment not created"}`);
     }
     for (let i = 0; i < resolveIds.length; i++) {
         const r = data[`r${i}`];
         if (r?.thread?.isResolved === true)
             result.resolvedThreads.push(resolveIds[i]);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${resolveIds[i]}: resolve returned null or thread not resolved`);
+            result.errors.push(`${resolveIds[i]}: ${mutationErrorMessage(graphQlErrors, `r${i}`) ?? "resolve returned null or thread not resolved"}`);
     }
     for (let i = 0; i < minimizeIds.length; i++) {
         const m = data[`m${i}`];
         if (m?.minimizedComment?.isMinimized === true)
             result.minimizedComments.push(minimizeIds[i]);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${minimizeIds[i]}: minimize returned null or comment not minimized`);
+            result.errors.push(`${minimizeIds[i]}: ${mutationErrorMessage(graphQlErrors, `m${i}`) ?? "minimize returned null or comment not minimized"}`);
     }
     const singleDismiss = dismissIds.length === 1;
     const commentedDismissErrorIndexes = new Set();
@@ -204,7 +210,7 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
         else if (!suppressCurrentChunkErrors)
             result.errors.push(commentedDismissErrorIndexes.has(i) || (singleDismiss && hasUnmappedCommentedDismissError)
                 ? dismissReviewNonDismissibleMessage(dismissIds[i])
-                : `${dismissIds[i]}: dismiss returned null`);
+                : `${dismissIds[i]}: ${mutationErrorMessage(graphQlErrors, `d${i}`) ?? "dismiss returned null"}`);
     }
     if (rateLimitStop) {
         result.errors.push(`rate limit: ${rateLimitStop.message}`);

package/bin/github/client.d.mts

@@ -30,7 +30,6 @@ export declare function getPrHeadSha(pr: number, owner: string, name: string): P
 export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
     nodeId: string;
     body: string;
-    viewerCanUpdate?: boolean;
 }>;
 /** Overwrites the PR body. */
 export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;

package/bin/github/client.mjs

@@ -80,9 +80,6 @@ export async function getPullRequestBody(pr, owner, name) {
     return {
         nodeId: pullRequest.id,
         body: pullRequest.body ?? "",
-        ...(pullRequest.viewerCanUpdate !== undefined && {
-            viewerCanUpdate: pullRequest.viewerCanUpdate,
-        }),
     };
 }
 /** Overwrites the PR body. */

package/bin/github/gql/get-pr-body.gql

@@ -11,7 +11,6 @@ query GetPrBody($owner: String!, $repo: String!, $pr: Int!) {
     pullRequest(number: $pr) {
       id
       body
-      viewerCanUpdate
     }
   }
 }

package/bin/mcp/server.mjs

@@ -41,7 +41,7 @@ const reviewMutationsOperationSchema = z.object({
 const markFilesViewedOperationSchema = z.object({
     type: z.literal("mark_files_viewed"),
     files: z.array(z.string().min(1)).optional(),
-    tests: z.boolean().optional().describe("Select changed test files; no mutation occurs."),
+    tests: z.boolean().optional().describe("Select changed test files to mark as viewed."),
     matchPatterns: z.array(z.string().min(1)).optional(),
 });
 const appendJournalOperationSchema = z.object({
@@ -90,7 +90,7 @@ export function createPrShepherdMcpServer(options = {}) {
         },
     }, async (input) => runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), formatIterateResult));
     server.registerTool("apply", {
-        description: "Apply ordered authorized review and journal operations, or run selection-only file-view diagnostics, after prevalidation.",
+        description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
         inputSchema: applyInputSchema,
         annotations: {
             readOnlyHint: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.46.0",
+  "version": "0.46.2",
   "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.46.0",
+  "version": "0.46.2",
   "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.46.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.46.2", "pr-shepherd-mcp"]
     }
   }
 }

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

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

package/plugins/pr-shepherd/skills/mark-files-as-viewed/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mark-files-as-viewed
-description: "Select changed pull-request files and report viewed-state authorization diagnostics with pr-shepherd (MCP or CLI)."
+description: "Mark selected changed pull-request files as viewed with pr-shepherd (MCP or CLI)."
 user-invocable: true
 argument-hint: "[PR number or URL] [files|tests|--tests|--match REGEX]"
 allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob"]
@@ -8,7 +8,7 @@ allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob"]
 
 # mark-files-as-viewed
 
-Thin dispatcher for selection-only file-view authorization diagnostics. GitHub exposes no exact viewer capability for marking a PR file viewed, so this operation never recommends or attempts that mutation. Use the MCP server when it is available; otherwise use the CLI.
+Thin dispatcher for explicit file-view mutations. The operation attempts `markFileAsViewed` for selected files and surfaces GitHub's per-file results. Use the MCP server when it is available; otherwise use the CLI.
 
 ## Arguments: $ARGUMENTS
 

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -64,7 +64,7 @@ When several bullets share one runId (matrix jobs from the same run), the `rerun
 
 Applies to every `apply review:` / `resolve-only:` command the CLI prints. Covers only what stays safe if you run the printed command **unmodified** — `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution remains a separate CLI-printed step because the command is unsafe by default without those placeholders.
 
-The CLI only includes IDs whose per-object GitHub viewer capability authorizes the corresponding action, and `apply review` repeats that authorization check immediately before mutating. Do not reconstruct omitted review reply, thread resolution, or bot-review dismissal IDs and do not hand them off: denied or unverifiable review mutations are one-look skips that Shepherd suppresses until the item is edited. Threads without a path or line follow the same skip rule.
+The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Direct `apply review` honors those emitted IDs without a second authorization preflight and surfaces GitHub's per-operation result. Do not reconstruct omitted review reply, thread resolution, or bot-review dismissal IDs and do not hand them off: denied or unverifiable generated mutations are one-look skips that Shepherd suppresses until the item is edited. Active threads without a path or line follow the same skip rule; authorized outdated bot threads are emitted for resolution by thread ID even when GitHub clears their source line.
 
 - Run every generated `apply review:` / `resolve-only:` command even when no code change is warranted. The command records the agent's disposition of the included review items; skipping it leaves bot threads active and can eventually trigger `fix-thrash`.
 - Never add first-look-only or check-annotation IDs to `--reply-thread-ids`, `--resolve-thread-ids`, `--dismiss-review-ids`, or `--minimize-comment-ids` — those flags are pre-populated by the CLI.