pr-shepherd 0.43.0 → 0.44.0

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  --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    Do not cancel in-progress runs before actionable fixes.\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 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-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

@@ -36,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
@@ -55,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}`;
     }
@@ -81,10 +81,10 @@ 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(" · ");
     }

package/bin/cli/iterate-lean.mjs

@@ -168,6 +168,10 @@ export function projectIterateLean(result, opts) {
                     ...(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,
                 },

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);

package/bin/cli/mutate-formatter.mjs

@@ -34,6 +34,10 @@ export function formatMutateResult(result) {
     pushIds(lines, "Skipped human minimizes", result.skippedHumanMinimizes);
     pushIds(lines, "Skipped human review dismissals", result.skippedHumanDismissals);
     pushIds(lines, "Skipped non-human/unknown thread replies", result.skippedNonHumanReplies);
+    pushIds(lines, "Authorization denied/unverifiable for thread replies", result.skippedUnauthorizedReplies);
+    pushIds(lines, "Authorization denied/unverifiable for thread resolves", result.skippedUnauthorizedResolves);
+    pushIds(lines, "Authorization denied/unverifiable for minimizes", result.skippedUnauthorizedMinimizes);
+    pushIds(lines, "Authorization denied/unverifiable for review dismissals", result.skippedUnauthorizedDismissals);
     const rateLimit = formatRateLimit(result);
     if (rateLimit)
         lines.push(rateLimit);

package/bin/commands/check.mjs

@@ -22,7 +22,7 @@ import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
 export async function runCheck(opts) {
-    const repo = await getRepoInfo();
+    const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
@@ -75,8 +75,10 @@ export async function runCheck(opts) {
     const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber);
     const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
-    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
-    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id)), seenMap, botUsernames);
+    const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize !== true));
+    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
+    const deniedRuleAutoResolveThreadIds = new Set(partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve !== true));
+    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id)), seenMap, botUsernames);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -87,7 +89,9 @@ export async function runCheck(opts) {
     const firstLookSummaries = [];
     const editedSummaries = [];
     const seenSummaries = [];
-    const unseenReviewSummaries = batchData.reviewSummaries.filter((r) => !partition.suppressedReviewSummaryIds.has(r.id));
+    const deniedRuleAutoResolveReviewSummaryIds = new Set(partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize !== true));
+    const unseenReviewSummaries = batchData.reviewSummaries.filter((r) => !partition.suppressedReviewSummaryIds.has(r.id) ||
+        deniedRuleAutoResolveReviewSummaryIds.has(r.id));
     for (const r of unseenReviewSummaries) {
         const cls = classifyItem(r.id, r.body, seenMap);
         if (cls === "new")
@@ -123,7 +127,8 @@ export async function runCheck(opts) {
                 .filter((t) => partition.suppressedThreadIds.has(t.id))
                 .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
             ...batchData.reviewSummaries
-                .filter((r) => partition.suppressedReviewSummaryIds.has(r.id))
+                .filter((r) => partition.suppressedReviewSummaryIds.has(r.id) &&
+                !deniedRuleAutoResolveReviewSummaryIds.has(r.id))
                 .map((r) => markSeen(stateKey, r.id, r.body)),
             ...batchData.changesRequestedReviews
                 .filter((r) => partition.suppressedChangesRequestedIds.has(r.id))
@@ -131,7 +136,17 @@ export async function runCheck(opts) {
         ]);
         await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
     }
-    const { threadIds: ruleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(partition, opts.autoMinimizeSuppressed);
+    const authorizedPartition = {
+        ...partition,
+        ruleAutoResolveThreadIds: partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve === true),
+        ruleAutoResolveCommentIds: partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize === true),
+        ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
+    };
+    const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(authorizedPartition, opts.autoMinimizeSuppressed);
+    const ruleAutoResolveThreadIds = [
+        ...authorizedRuleAutoResolveThreadIds,
+        ...deniedRuleAutoResolveThreadIds,
+    ];
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
     const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
     const approvedReviews = approvedReviewVisibility.visible;
@@ -158,6 +173,7 @@ export async function runCheck(opts) {
         nodeId: batchData.nodeId,
         headSha: batchData.headRefOid,
         repo: `${repo.owner}/${repo.name}`,
+        ...(batchData.viewerAuthorization && { viewerAuthorization: batchData.viewerAuthorization }),
         status,
         baseBranch: batchData.baseRefName,
         mergeStatus,

package/bin/commands/commit-suggestion-instruction.d.mts

@@ -8,4 +8,4 @@
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.
  */
-export declare function buildCommitSuggestionInstruction(prNumber: number, sectionName: string): string;
+export declare function buildCommitSuggestionInstruction(prReference: string | number, sectionName: string): string;

package/bin/commands/commit-suggestion-instruction.mjs

@@ -9,10 +9,10 @@ import { buildPrShepherdCommand } from "../cli/runner.mjs";
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.
  */
-export function buildCommitSuggestionInstruction(prNumber, sectionName) {
+export function buildCommitSuggestionInstruction(prReference, sectionName) {
     const command = buildPrShepherdCommand([
         "build-suggestion-patches",
-        String(prNumber),
+        String(prReference),
         "--thread-id",
         "<id>",
         "--message",

package/bin/commands/commit-suggestion.mjs

@@ -1,9 +1,11 @@
 import { buildSingularInstructions } from "./suggestion-patch-item.mjs";
 import { runSuggestionPatches } from "./suggestion-patches.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
 /** @deprecated Use runSuggestionPatches. */
 export async function runCommitSuggestion(opts) {
     const result = await runSuggestionPatches({
         prNumber: opts.prNumber,
+        targetRepository: opts.targetRepository,
         format: opts.format,
         verbose: opts.verbose,
         suggestions: [
@@ -19,6 +21,6 @@ export async function runCommitSuggestion(opts) {
         ...patch,
         pr: result.pr,
         repo: result.repo,
-        postActionInstructions: buildSingularInstructions(patch, result.pr),
+        postActionInstructions: buildSingularInstructions(patch, formatPrUrl(result.repo, result.pr)),
     };
 }

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

@@ -17,11 +17,9 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
  *
  * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
  *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * - Self-reply exclusion: a human thread whose latest visible comment is already Shepherd's
- *   own prior reply still has its ID in `--reply-thread-ids` by default. Running the
- *   printed command as-is replies to Shepherd's own reply, which can re-surface the thread
- *   and produce a self-perpetuating reply loop — worse than a rejected mutation, and not
- *   something a caller can discover by inspecting the command alone.
+ * Marker-based self-reply routing is already reflected in the generated IDs. The instruction
+ * below makes that behavior explicit so an authenticated viewer's unmarked human feedback is
+ * not mistaken for an automated reply merely because the GitHub login matches.
  *
  * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
  * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
@@ -30,18 +28,6 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
  * without it, nothing in CLI output tells the agent that playbook exists.
  */
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
-/**
- * Build the CI-triage instruction. The per-conclusion rerun policy (GitHub Actions log
- * excerpts, `gh run view`/`gh run rerun` rules for CANCELLED/STARTUP_FAILURE/external
- * failures) is invariant text keyed on the `[conclusion: …]` tags already rendered in
- * `## Failing checks` — it lives in the pr-shepherd skill's "CI failure triage" playbook
- * instead of being re-emitted every tick. This supersedes the "CI budget rules" example in
- * CLAUDE.md's "Keep skills and loop prompts minimal" section (see that section's amendment
- * note). The `(no runId)` case stays here because it flips `buildFixCompletionInstruction`
- * to a human-handoff terminal state — that trigger, unlike the others, is CLI-decided. The
- * CLI sentence does not claim every failure has a log excerpt to read (only GitHub Actions
- * checks with a runId do — CANCELLED, STARTUP_FAILURE, and external checks may not); that
- * per-kind detail is exactly what the skill playbook table disambiguates.
- */
+/** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
-export declare function buildFixCompletionInstruction(checks: AgentCheck[]): string;
+export declare function buildFixCompletionInstruction(checks: AgentCheck[], requiresRemoteUpdateAuthorization?: boolean, hasShaGatedReviewMutations?: boolean): string;

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

@@ -18,7 +18,7 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
     const trimmedHint = typeof hint === "string" ? hint.trim() : "";
     if (!isBehind || trimmedHint === "")
         return [];
-    return [`The branch is behind \`origin/${baseBranch}\`. ${trimmedHint} before pushing.`];
+    return [`The branch is behind PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
 /**
  * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
@@ -26,11 +26,9 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
  *
  * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
  *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * - Self-reply exclusion: a human thread whose latest visible comment is already Shepherd's
- *   own prior reply still has its ID in `--reply-thread-ids` by default. Running the
- *   printed command as-is replies to Shepherd's own reply, which can re-surface the thread
- *   and produce a self-perpetuating reply loop — worse than a rejected mutation, and not
- *   something a caller can discover by inspecting the command alone.
+ * Marker-based self-reply routing is already reflected in the generated IDs. The instruction
+ * below makes that behavior explicit so an authenticated viewer's unmarked human feedback is
+ * not mistaken for an automated reply merely because the GitHub login matches.
  *
  * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
  * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
@@ -43,10 +41,10 @@ export function buildResolveCommandInstruction(resolveCommand) {
         return [];
     const instructions = [];
     if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
-        instructions.push("Before `apply review:`, remove any `--reply-thread-ids` entry whose latest visible comment is your own Shepherd reply. Do not reply to yourself.");
+        instructions.push("Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an established Shepherd reply; a marked viewer-authored human thread is emitted resolve-only, not for another reply.");
     }
     if (resolveCommand.requiresHeadSha) {
-        instructions.push("Replace `$HEAD_SHA` with the pushed commit SHA, or `$(git rev-parse HEAD)` if you did not push.");
+        instructions.push("If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, do not run this command until an authorized push updates the remote PR head; then replace `$HEAD_SHA` with that pushed commit SHA.");
     }
     if (resolveCommand.requiresDismissMessage) {
         instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
@@ -54,19 +52,7 @@ export function buildResolveCommandInstruction(resolveCommand) {
     instructions.push('Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.');
     return instructions;
 }
-/**
- * Build the CI-triage instruction. The per-conclusion rerun policy (GitHub Actions log
- * excerpts, `gh run view`/`gh run rerun` rules for CANCELLED/STARTUP_FAILURE/external
- * failures) is invariant text keyed on the `[conclusion: …]` tags already rendered in
- * `## Failing checks` — it lives in the pr-shepherd skill's "CI failure triage" playbook
- * instead of being re-emitted every tick. This supersedes the "CI budget rules" example in
- * CLAUDE.md's "Keep skills and loop prompts minimal" section (see that section's amendment
- * note). The `(no runId)` case stays here because it flips `buildFixCompletionInstruction`
- * to a human-handoff terminal state — that trigger, unlike the others, is CLI-decided. The
- * CLI sentence does not claim every failure has a log excerpt to read (only GitHub Actions
- * checks with a runId do — CANCELLED, STARTUP_FAILURE, and external checks may not); that
- * per-kind detail is exactly what the skill playbook table disambiguates.
- */
+/** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export function buildFailingCheckInstructions(checks) {
     if (checks.length === 0)
         return [];
@@ -74,17 +60,30 @@ export function buildFailingCheckInstructions(checks) {
     const hasTriageable = checks.some((c) => c.runId || c.detailsUrl);
     const instructions = [];
     if (hasTriageable) {
-        instructions.push('Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for `gh run view` / `gh run rerun` rules.');
+        instructions.push('Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.');
     }
     if (hasBare) {
         instructions.push("For each `(no runId)` failure, escalate to a human because no log or URL is available.");
     }
     return instructions;
 }
-export function buildFixCompletionInstruction(checks) {
-    const requiresHumanHandoff = checks.some((check) => !check.runId && !check.detailsUrl);
-    if (requiresHumanHandoff) {
+export function buildFixCompletionInstruction(checks, requiresRemoteUpdateAuthorization = false, hasShaGatedReviewMutations = false) {
+    if (requiresRemoteUpdateAuthorization) {
+        return "`[FIX_CODE]` requires a human handoff for an authorized push after conflict resolution. Shepherd cannot verify the Git credential's push authorization. Stop polling after committing, and resume only after the remote PR head changes.";
+    }
+    const hasUninspectableFailure = checks.some((check) => !check.runId && !check.detailsUrl);
+    const hasCiAuthorizationHandoff = checks.some((check) => check.conclusion === "CANCELLED" ||
+        check.conclusion === "STARTUP_FAILURE" ||
+        (check.runId === null && Boolean(check.detailsUrl)) ||
+        (check.runId !== null && !check.logExcerpt?.trim()));
+    if (hasUninspectableFailure) {
         return "`[FIX_CODE]` requires a human handoff for an uninspectable failing check. Stop polling after escalating, and resume only after human direction.";
     }
+    if (hasCiAuthorizationHandoff) {
+        return "`[FIX_CODE]` requires a human handoff for a failing check with no authorized follow-up action. Stop polling after escalating, and resume only after human direction.";
+    }
+    if (hasShaGatedReviewMutations) {
+        return "`[FIX_CODE]` is conditional: if you changed code, stop after committing and resume only after an authorized push changes the remote PR head; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
+    }
     return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.";
 }

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

@@ -1,4 +1,4 @@
-import type { AgentThread, Review, ResolveCommand, AgentCheck, ReviewThread } from "../../types.mts";
+import type { AgentThread, Review, ResolveCommand, AgentCheck, ReviewThread, ViewerAuthorization } from "../../types.mts";
 import { type NormalizedBotUsernames } from "../../comments/authors.mts";
 import type { MinimizeCommentsPolicy } from "../../config/load.mts";
 export declare function classifyReviewSummaries(summaries: {
@@ -12,7 +12,7 @@ export declare function classifyReviewSummaries(summaries: {
     editedSummaries: Review[];
     surfacedApprovals: Review[];
 };
-export declare function buildResolveCommand(threads: AgentThread[], resolutionOnlyThreads: ReviewThread[], allCommentIds: string[], reviews: Review[], checks: AgentCheck[], prNumber: number, botUsernames?: NormalizedBotUsernames, ruleAutoResolveThreadIds?: string[]): {
+export declare function buildResolveCommand(threads: AgentThread[], resolutionOnlyThreads: ReviewThread[], allCommentIds: string[], reviews: Review[], checks: AgentCheck[], prReference: string | number, botUsernames?: NormalizedBotUsernames, ruleAutoResolveThreadIds?: string[], viewerAuthorization?: ViewerAuthorization, authorizationThreads?: ReviewThread[]): {
     resolveCommand: ResolveCommand;
     resolveOnlyCommand?: ResolveCommand;
 };