pr-shepherd 0.42.0 → 0.44.0

package/bin/types/github.mjs

@@ -1,4 +1 @@
-// GitHub primitives, check runs, review threads, and batch PR data types.
-// Check classification types (CheckCategory/ClassifiedCheck/TriagedCheck) live in
-// check-classification.mts to stay under the file-length cap.
 export {};

package/bin/types/iterate.d.mts

@@ -1,37 +1,11 @@
 import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
-import type { BranchProtection, CheckStatus, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
+import type { BranchProtection, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
 import type { MergeRequirements } from "./merge-requirements.mts";
+import type { EscalateDetails } from "./escalate.mts";
+import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
-export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "cancel" | "escalate";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "bot-cr-not-dismissed";
-export interface AgentStalledCheck {
-    name: string;
-    status: CheckStatus;
-    source: "check_run" | "status_context" | "startup_failure";
-    runId: string | null;
-    detailsUrl: string | null;
-    createdAtUnix?: number;
-    startedAtUnix?: number;
-    updatedAtUnix?: number;
-    ageSeconds: number;
-    summary?: string;
-}
-export interface EscalateDetails {
-    triggers: EscalateTrigger[];
-    unresolvedThreads: AgentThread[];
-    ambiguousComments: AgentComment[];
-    changesRequestedReviews: Review[];
-    /** Pending/unstarted CI checks that exceeded the stall timeout. */
-    stalledChecks?: AgentStalledCheck[];
-    /** Populated when fix-thrash triggered — threads that have been attempted too many times. */
-    thrashHistory?: Array<{
-        threadId: string;
-        attempts: number;
-    }>;
-    suggestion: string;
-    humanMessage: string;
-}
+export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
 export interface IterateResultSummary {
     passing: number;
     skipped: number;
@@ -66,6 +40,7 @@ export interface IterateResultBase {
     ignoredNames?: string[];
     supersededNames?: string[];
     activity?: PrActivitySummary;
+    mergeQueue?: import("./merge-queue.mts").MergeQueueReport;
 }
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
@@ -84,9 +59,9 @@ export interface ResolveCommand {
     requiresHeadSha: boolean;
     /** Whether the model must substitute $DISMISS_MESSAGE with a specific description of the fix. */
     requiresDismissMessage: boolean;
-    /** Thread IDs that should receive a reply instead of a resolve mutation. */
+    /** Thread IDs that should receive a reply. Viewer-authored human IDs may also appear in resolveThreadIds. */
     replyThreadIds?: string[];
-    /** Thread IDs that should be resolved on GitHub. Human-authored IDs must not appear here. */
+    /** Thread IDs that should be resolved on GitHub. Human IDs are allowed only for authenticated-viewer reply+resolve pairs or marker-ended retries. */
     resolveThreadIds?: string[];
     /** Bot/non-human CHANGES_REQUESTED review IDs to dismiss. Human-authored IDs must not appear here. */
     dismissReviewIds?: string[];
@@ -94,8 +69,8 @@ export interface ResolveCommand {
     hasMutations: boolean;
 }
 /**
- * Default fix_code variant: agent applies edits locally, commits, pushes,
- * then runs the pre-built apply command. Emitted under `## Post-fix push`.
+ * Default fix_code variant: agent applies edits locally, commits when needed,
+ * then runs the pre-built apply command. Emitted under `## Post-fix actions`.
  */
 interface FixRebaseAndPush {
     threads: AgentThread[];
@@ -115,14 +90,16 @@ interface FixRebaseAndPush {
     changesRequestedReviews: Review[];
     /** Pre-built apply command. Run after committing and pushing. */
     resolveCommand: ResolveCommand;
-    /** When present, run this command first (no SHA substitution needed) to resolve bot threads and minimize comments, independent of any push. */
+    /** When present, run this command first (no SHA substitution needed) for standalone thread resolves and comment minimization, independent of any push. */
     resolveOnlyCommand?: ResolveCommand;
     /** Ordered steps for the model to follow. */
     instructions: string[];
-    /** Run IDs of in-progress GitHub Actions checks. The agent should cancel these before pushing new commits; if it decides not to push (e.g. resolve-only), it may skip cancellation. Empty when all in-progress runs are external status checks or already cancelled. */
+    /** Reserved compatibility field. Always empty because Shepherd cannot verify workflow-cancellation authorization. */
     inProgressRunIds: string[];
-    /** Workflow runs deliberately excluded from cancellation by actions.neverCancelRuns. */
+    /** Reserved compatibility field. Always empty because Shepherd never recommends workflow cancellation. */
     protectedRuns: ProtectedRun[];
+    /** Requeue command emitted after merge-group remediation. */
+    requeue?: MergeCommandPlan;
     /** First-look threads — previously hidden, surfaced for acknowledgment only. */
     firstLookThreads: FirstLookThread[];
     /** First-look comments — previously hidden, surfaced for acknowledgment only. */
@@ -138,19 +115,26 @@ interface IterateResultMarkReady extends IterateResultBase {
     markedReady: boolean;
     log: string;
 }
+export interface IterateResultMerge extends IterateResultBase {
+    action: "merge";
+    merge: MergeCommandPlan;
+}
 interface IterateResultEscalate extends IterateResultBase {
     action: "escalate";
     escalate: EscalateDetails;
 }
-export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultEscalate;
+export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultMerge | IterateResultEscalate;
 export interface IterateCommandOptions extends GlobalOptions {
     readyDelaySeconds?: number;
     noAutoMarkReady?: boolean;
+    /** Legacy no-op retained for API compatibility; workflow runs are never cancelled. */
     noAutoCancelActionable?: boolean;
     /** Override stall timeout seconds. Defaults to config.iterate.stallTimeoutMinutes * 60. */
     stallTimeoutSeconds?: number;
-    /** Case-insensitive workflow/check glob patterns Shepherd must not cancel. */
+    /** Legacy per-invocation no-op retained for API compatibility. */
     neverCancelRuns?: string[];
     persistSeen?: boolean;
+    /** Shepherd through readiness and emit the exact merge/queue command when ready. */
+    merge?: boolean;
 }
 export {};

package/bin/types/merge-action.d.mts

@@ -0,0 +1,12 @@
+interface ShellCommand {
+    argv: string[];
+}
+export interface MergeCommandPlan {
+    mode: "auto" | "queue";
+    command: ShellCommand;
+    /** Ordinary merge retry without `--auto`, used only when auto-merge is unavailable. */
+    fallbackCommand?: ShellCommand;
+    /** Direct enqueuePullRequest fallback for the known gh CLI queue limitation. */
+    queueApiFallbackCommand?: ShellCommand;
+}
+export {};

package/bin/types/merge-action.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/merge-queue.d.mts

@@ -0,0 +1,13 @@
+import type { AutoMergeRequestStatus, MergeQueueEntryStatus, MergeQueueRemovalStatus } from "./merge-requirements.mts";
+export interface MergeQueueReport {
+    enabled: boolean;
+    inQueue: boolean;
+    autoMergeRequest?: AutoMergeRequestStatus;
+    entry?: MergeQueueEntryStatus;
+    latestRemoval?: MergeQueueRemovalStatus;
+    checkCommitOid?: string;
+    /** GitHub reported more than the first 100 contexts on the queue commit. */
+    checksIncomplete?: true;
+    /** The current PR head is not a parent of the removed synthetic queue commit. */
+    headUpdatedAfterRemoval?: true;
+}

package/bin/types/merge-queue.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/merge-requirements.d.mts

@@ -17,6 +17,21 @@ export interface MergeQueueEntryStatus {
     position: number;
     state: string;
     estimatedTimeToMerge: number | null;
+    headCommitOid?: string;
+    enqueuedAtUnix?: number;
+    enqueuer?: string;
+}
+export interface AutoMergeRequestStatus {
+    enabledAtUnix: number;
+    mergeMethod: string;
+    enabledBy?: string;
+}
+export interface MergeQueueRemovalStatus {
+    reason: string | null;
+    actor?: string;
+    createdAtUnix: number;
+    beforeCommitOid?: string;
+    beforeCommitParentOids?: string[];
 }
 export interface StackStatus {
     number: number;
@@ -30,6 +45,8 @@ export interface BatchPrMergeFields {
     isInMergeQueue?: boolean;
     isMergeQueueEnabled?: boolean;
     mergeQueueEntry?: MergeQueueEntryStatus | null;
+    autoMergeRequest?: AutoMergeRequestStatus | null;
+    latestMergeQueueRemoval?: MergeQueueRemovalStatus | null;
     stack?: StackStatus | null;
 }
 /** Snapshot of "why can't I merge" requirements vs current PR state. */

package/bin/types/report.d.mts

@@ -1,8 +1,9 @@
-import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, CheckConclusion, SuggestionBlock } from "./github.mts";
+import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, ViewerAuthorization, CheckConclusion, SuggestionBlock } from "./github.mts";
 import type { ClassifiedCheck, TriagedCheck } from "./check-classification.mts";
 import type { AgentThreadComment } from "./agent-thread.mts";
 import type { CheckAnnotation } from "./check-annotations.mts";
 import type { PrActivitySummary } from "./activity.mts";
+import type { MergeQueueReport } from "./merge-queue.mts";
 export interface FirstLookThread extends ReviewThread {
     firstLookStatus: "outdated" | "resolved" | "minimized";
     autoResolved?: boolean;
@@ -20,7 +21,11 @@ export interface ShepherdReport {
     pr: number;
     /** GitHub node ID of the PR — used for mutations (e.g. markPullRequestReadyForReview). */
     nodeId: string;
+    /** GitHub PR head OID from the same batch used to decide the action. */
+    headSha?: string;
     repo: string;
+    /** Raw GitHub viewer fields used to decide which remote actions may be offered. */
+    viewerAuthorization?: ViewerAuthorization;
     status: ShepherdStatus;
     /** PR base branch from the GraphQL batch. */
     baseBranch: string;
@@ -71,6 +76,7 @@ export interface ShepherdReport {
     /** Branch protection rule for the PR's base branch. Null when no rule exists or the base ref is unavailable. */
     branchProtection: import("./github.mts").BranchProtection | null;
     activity?: PrActivitySummary;
+    mergeQueue?: MergeQueueReport;
 }
 export interface ResolveOptions {
     resolveThreadIds?: string[];
@@ -83,6 +89,10 @@ export interface ResolveOptions {
 }
 export interface AgentThread {
     id: string;
+    /** Raw GitHub capability; omitted only in legacy/incomplete snapshots. */
+    viewerCanReply?: boolean;
+    /** Raw GitHub capability; omitted only in legacy/incomplete snapshots. */
+    viewerCanResolve?: boolean;
     reviewId?: string;
     path: string | null;
     line: number | null;
@@ -90,6 +100,7 @@ export interface AgentThread {
     author: string;
     authorType?: AuthorType;
     authorAssociation?: import("./github.mts").CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     url: string;
     comments?: AgentThreadComment[];
@@ -99,6 +110,8 @@ export interface AgentThread {
 /** Comment shape emitted to the iterate agent — stripped of always-false flags. */
 export interface AgentComment {
     id: string;
+    /** Raw GitHub capability; omitted only in legacy/incomplete snapshots. */
+    viewerCanMinimize?: boolean;
     author: string;
     authorType?: AuthorType;
     authorAssociation?: import("./github.mts").CommentAuthorAssociation;
@@ -125,6 +138,8 @@ export interface AgentCheck {
     logExcerpt?: string;
     annotations?: CheckAnnotation[];
     annotationOnly?: true;
+    scope?: "merge_group";
+    commitOid?: string;
 }
 /**
  * A single CI check that is relevant to PR readiness — triggered by a PR event
@@ -149,9 +164,15 @@ export interface RelevantCheck {
     logExcerpt?: string;
     /** Marker-gated inline annotations from this check. */
     annotations?: CheckAnnotation[];
+    scope?: "merge_group";
+    commitOid?: string;
 }
 export interface GlobalOptions {
     prNumber?: number;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
     format: "text" | "json";
     verbose?: boolean;
 }

package/bin/types/review-thread.d.mts

@@ -6,6 +6,7 @@ export interface ReviewThreadComment {
     author: string;
     authorType: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     url: string;
     createdAtUnix: number;

package/bin/types/suggestion-patch.d.mts

@@ -18,7 +18,7 @@ export interface BuildSuggestionPatchesResult {
     repo: string;
     /** Suggestion patches in caller-supplied application order. */
     patches: SuggestionPatchResult[];
-    /** Steps for applying and committing every patch, then pushing once. */
+    /** Steps for applying and committing every patch; branch updates require separate authorization. */
     postActionInstructions: string[];
 }
 /** Compatibility result for the singular suggestion-patch adapter. */

package/bin/types.d.mts

@@ -9,3 +9,6 @@ export * from "./types/report.mts";
 export * from "./types/suggestion-patch.mts";
 export * from "./types/iterate.mts";
 export * from "./types/merge-requirements.mts";
+export * from "./types/merge-action.mts";
+export * from "./types/escalate.mts";
+export * from "./types/merge-queue.mts";

package/bin/types.mjs

@@ -9,3 +9,6 @@ export * from "./types/report.mjs";
 export * from "./types/suggestion-patch.mjs";
 export * from "./types/iterate.mjs";
 export * from "./types/merge-requirements.mjs";
+export * from "./types/merge-action.mjs";
+export * from "./types/escalate.mjs";
+export * from "./types/merge-queue.mjs";

package/bin/util/markdown.d.mts

@@ -1 +1,3 @@
 export declare function joinSections(sections: (string | null | undefined)[]): string;
+/** Wrap arbitrary text in a CommonMark code span without colliding with embedded backticks. */
+export declare function inlineCode(value: string): string;

package/bin/util/markdown.mjs

@@ -5,3 +5,10 @@ export function joinSections(sections) {
         .filter((s) => s !== "")
         .join("\n\n");
 }
+/** Wrap arbitrary text in a CommonMark code span without colliding with embedded backticks. */
+export function inlineCode(value) {
+    const longestRun = Math.max(0, ...Array.from(value.matchAll(/`+/g), (match) => match[0].length));
+    const delimiter = "`".repeat(longestRun + 1);
+    const padding = value.startsWith("`") || value.endsWith("`") ? " " : "";
+    return `${delimiter}${padding}${value}${padding}${delimiter}`;
+}

package/package.json

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

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

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

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

@@ -1,6 +1,6 @@
 ---
 name: mark-files-as-viewed
-description: "Mark changed pull-request files as viewed with pr-shepherd (MCP or CLI)."
+description: "Select changed pull-request files and report viewed-state authorization diagnostics 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,10 +8,10 @@ allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob"]
 
 # mark-files-as-viewed
 
-Thin dispatcher for marking PR files viewed. Use the MCP server when it is available; otherwise use the CLI.
+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.
 
 ## Arguments: $ARGUMENTS
 
 1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL. Treat standalone `tests` as `--tests`; preserve explicit paths and `--match <regex>` selectors.
 
-2. If the `apply` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `apply` with that qualified reference and one `mark_files_viewed` operation, then print the full result. If MCP is unavailable and the parsed PR is repository-qualified, run `gh repo view --json nameWithOwner --jq .nameWithOwner` and verify that repository matches the reference case-insensitively. Stop on a mismatch or failed lookup; the CLI does not validate the URL repository. Convert a verified `owner/repo#N` to `https://github.com/owner/repo/pull/N`, then run `pr-shepherd apply files` with the parsed PR and selectors and print the full result.
+2. If the `apply` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `apply` with that qualified reference and one `mark_files_viewed` operation, then print the full result. If MCP is unavailable, convert a supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N` and otherwise pass the parsed PR unchanged to `pr-shepherd apply files` with the selectors, then print the full result. A qualified reference may target a fork or upstream repository; the current checkout remains the local git/config/rules context.

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

@@ -2,7 +2,7 @@
 name: pr-shepherd
 description: 'Iterate a GitHub pull request with pr-shepherd (MCP or CLI). Use for requests like "use pr-shepherd", "iterate PR #123", or "run pr-shepherd until this PR is ready".'
 user-invocable: true
-argument-hint: "[PR number or URL]"
+argument-hint: "[PR number or URL] [--merge]"
 allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
 ---
 
@@ -12,9 +12,9 @@ Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only wh
 
 ## Arguments: $ARGUMENTS
 
-1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR.
+1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL and an optional `--merge` flag from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
 
-2. Before passing a supplied GitHub PR URL or `owner/repo#N` to the CLI, run `gh repo view --json nameWithOwner --jq .nameWithOwner` and verify that repository matches the reference case-insensitively. Stop on a mismatch or failed lookup; the CLI does not validate the URL repository. Convert a verified `owner/repo#N` to `https://github.com/owner/repo/pull/N`, then run the poll command `pr-shepherd` with the optional PR argument and print its full result. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference and print its full result.
+2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the poll command `pr-shepherd` with the optional PR argument and forward `--merge` when supplied. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference, plus `merge: true` when `--merge` was supplied, and print its full result.
 
 3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
 
@@ -28,11 +28,11 @@ mechanics every tick. Apply the referenced playbook in full whenever a step poin
 ### Suggestion patches
 
 - Run one plural `build-suggestion-patches` command with a repeated `--thread-id … --message … [--description …]` group for every marked thread in displayed order.
-- The CLI only builds patches. Apply, stage, and commit the returned patches in order, then push once.
+- The CLI only builds patches. Apply, stage, and commit the returned patches in order. Push only when authorization has been established outside Shepherd; GitHub viewer fields cannot verify the local Git credential.
 - The command builds from the fetched PR head and accepts a clean local descendant only when the complete ordered patch stream passes `git apply --check`.
 - If the command refuses because a suggestion is unsafe or no longer applies, inspect the current source, the displayed replacement block, and reviewer intent before editing manually. Do not apply a stale numeric range blindly or retry unchanged input.
 - A returned patch was checked against the then-current worktree. If it later fails, re-inspect the worktree because it changed after validation.
-- Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.
+- Keep the generated thread IDs and flag placement unchanged. Viewer-authored human feedback may intentionally appear in both reply and resolve flags; unmarked other-human feedback remains reply-only. Marker-ended other-human feedback is already acknowledged and has no generated mutation.
 
 ### CI failure triage
 
@@ -40,18 +40,20 @@ Match each failure's `[conclusion: …]` tag under `## Failing checks` to a rule
 
 More specific rows win over the general "GitHub Actions failure" row — check conclusion first.
 
-| Tag / kind                                                               | Do                                                                                                                                                                                                                                                                               |
-| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If missing or insufficient, run a bounded command such as `gh run view <runId> --log-failed \| tail -n 200` — the unbounded form can dump excessive log output into context. Open the run URL only if that still lacks detail. |
-| Transient infrastructure failure                                         | Rerun with `gh run rerun <runId> --failed`.                                                                                                                                                                                                                                      |
-| Real test or build failure                                               | Apply a code fix — do not rerun.                                                                                                                                                                                                                                                 |
-| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered for this conclusion. Run `gh run rerun <runId>` unless this tick will push new commits. Not resolved by a rerun classification — `## Cancelled runs` is a different section.                                                                          |
-| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered for this conclusion. Inspect with `gh run view <runId>`, rerun with `gh run rerun <runId>` if warranted.                                                                                                                                              |
-| `external` (no run ID, has a URL)                                        | Open its URL and inspect it.                                                                                                                                                                                                                                                     |
+| Tag / kind                                                               | Do                                                                                                                                                                                                |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If it is missing or insufficient, hand off the displayed run ID/URL; Shepherd cannot verify authorization for another Actions read or mutation. |
+| Transient infrastructure failure                                         | Record the diagnosis. Shepherd does not recommend a rerun because GitHub exposes no exact viewer capability for that workflow-run action.                                                         |
+| Real test or build failure                                               | Apply a code fix — do not rerun.                                                                                                                                                                  |
+| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered. Hand off the displayed metadata; Shepherd cannot verify authorization for another Actions read or mutation.                                                           |
+| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered. Hand off the displayed metadata; Shepherd cannot verify authorization for another Actions read or mutation.                                                           |
+| `external` (no run ID, has a URL)                                        | Preserve the URL in the handoff. Shepherd does not recommend opening it because it cannot verify the current viewer's access to the external system.                                              |
 
 ### Review-mutation mechanics
 
-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 and the self-reply exclusion rule are separate CLI-printed steps, not covered here, because the printed command is unsafe by default without them.
+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.
 
 - 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.
@@ -59,7 +61,7 @@ Applies to every `apply review:` / `resolve-only:` command the CLI prints. Cover
 
 ### Review-mutation routing
 
-For threads under both `## Review threads` and `## Review threads to resolve`, evaluate every thread before running mutations. Keep bot and non-human IDs in `--resolve-thread-ids`, including when the feedback is advisory, already satisfied, or otherwise warrants no code change. Human-authored IDs use `--reply-thread-ids`; Shepherd replies instead of resolving them. Never move a human-authored ID to `--resolve-thread-ids`. Use the commands as generated — do not move an ID between flags.
+For threads under both `## Review threads` and `## Review threads to resolve`, evaluate every thread before running mutations. Keep bot and non-human IDs in `--resolve-thread-ids`, including when the feedback is advisory, already satisfied, or otherwise warrants no code change. Unmarked other-human inline-thread IDs use `--reply-thread-ids` only. When the original human inline comment has `viewerDidAuthor: true` and its latest comment is unmarked, keep that same ID in both `--reply-thread-ids` and `--resolve-thread-ids`: the reply runs before the resolve. When the latest comment begins `<!-- pr-shepherd -->`, it is an established Shepherd reply—not merely a same-account comment. A marker-ended viewer-authored thread may be resolve-only for retry; a marker-ended other-human thread is already acknowledged and has no generated mutation. Do not add an unmarked human ID to `--resolve-thread-ids` without its paired generated reply, and do not move IDs between flags.
 
 ### Shepherd Journal
 

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

@@ -1,20 +0,0 @@
-import type { ShepherdReport } from "../../types.mts";
-import type { ProtectedRun } from "../../types/protected-run.mts";
-type FailingCheck = ShepherdReport["checks"]["failing"][number];
-type InProgressCheck = ShepherdReport["checks"]["inProgress"][number];
-type CancellableCheck = FailingCheck | InProgressCheck;
-interface RunProtection {
-    protectedRunIds: Set<string>;
-    protectedRuns: ProtectedRun[];
-}
-interface BuildRunIdOptions {
-    protectedRunIds?: Set<string>;
-}
-export declare function buildAutoCancelRunIdsWithOptions(report: ShepherdReport, opts?: BuildRunIdOptions): string[];
-interface BuildInProgressRunIdOptions {
-    suppressProtectedFreshReruns?: boolean;
-    protectedRunIds?: Set<string>;
-}
-export declare function buildInProgressRunIds(report: ShepherdReport, cancelledSet: Set<string>, opts?: BuildInProgressRunIdOptions): string[];
-export declare function buildRunProtection(checks: CancellableCheck[], patterns?: string[]): RunProtection;
-export {};

package/bin/commands/iterate/reruns.mjs

@@ -1,105 +0,0 @@
-import picomatch from "picomatch";
-function matchesRerunCheck(failure, check) {
-    if (failure.runId !== null && check.runId !== null) {
-        return failure.runId === check.runId && failure.name === check.name;
-    }
-    return failure.runId === null && check.runId === null && failure.name === check.name;
-}
-function isProtectedByFreshRerun(failure, check) {
-    const attemptStartedAt = check.startedAtUnix ?? check.updatedAtUnix ?? check.createdAtUnix;
-    return (attemptStartedAt !== undefined &&
-        matchesRerunCheck(failure, check) &&
-        failure.completedAtUnix !== undefined &&
-        attemptStartedAt >= failure.completedAtUnix &&
-        (failure.startedAtUnix === undefined || failure.startedAtUnix < attemptStartedAt));
-}
-function hasProtectedFreshRerun(failure, checks) {
-    return checks.some((check) => isProtectedByFreshRerun(failure, check));
-}
-function isProtectedFreshRerun(check, failures) {
-    const matchingFailures = failures.filter((failure) => matchesRerunCheck(failure, check));
-    return (matchingFailures.length > 0 &&
-        matchingFailures.every((failure) => isProtectedByFreshRerun(failure, check)));
-}
-function protectedFreshRerunIds(report) {
-    return new Set(report.checks.inProgress
-        .filter((check) => isProtectedFreshRerun(check, report.checks.failing))
-        .map((check) => check.runId)
-        .filter((id) => id !== null));
-}
-export function buildAutoCancelRunIdsWithOptions(report, opts = {}) {
-    return [
-        ...new Set(report.checks.failing
-            .filter((check) => !hasProtectedFreshRerun(check, report.checks.inProgress))
-            .map((check) => check.runId)
-            .filter((id) => id !== null && !(opts.protectedRunIds?.has(id) ?? false))),
-    ];
-}
-export function buildInProgressRunIds(report, cancelledSet, opts = {}) {
-    const protectedRunIds = opts.suppressProtectedFreshReruns === false ? new Set() : protectedFreshRerunIds(report);
-    return [
-        ...new Set(report.checks.inProgress
-            .map((check) => check.runId)
-            .filter((id) => id !== null &&
-            !cancelledSet.has(id) &&
-            !protectedRunIds.has(id) &&
-            !(opts.protectedRunIds?.has(id) ?? false))),
-    ];
-}
-export function buildRunProtection(checks, patterns = []) {
-    if (patterns.length === 0)
-        return { protectedRunIds: new Set(), protectedRuns: [] };
-    const matchers = patterns.map((pattern) => ({
-        pattern,
-        isMatch: picomatch(pattern, { nocase: true }),
-    }));
-    const byRunId = new Map();
-    for (const check of checks) {
-        if (check.runId === null)
-            continue;
-        const match = findProtectionMatch(check, matchers);
-        if (match === null)
-            continue;
-        addProtectedRun(byRunId, check.runId, check, match);
-    }
-    const protectedRuns = [...byRunId.values()];
-    return {
-        protectedRunIds: new Set(protectedRuns.map((run) => run.runId)),
-        protectedRuns,
-    };
-}
-function addProtectedRun(byRunId, runId, check, matchedPattern) {
-    const existing = byRunId.get(runId);
-    if (existing) {
-        updateProtectedRun(existing, check);
-        return;
-    }
-    byRunId.set(runId, createProtectedRun(runId, check, matchedPattern));
-}
-function updateProtectedRun(run, check) {
-    if (!run.checkNames.includes(check.name))
-        run.checkNames.push(check.name);
-    if (run.workflowName === undefined && check.workflowName !== undefined) {
-        run.workflowName = check.workflowName;
-    }
-}
-function createProtectedRun(runId, check, matchedPattern) {
-    return {
-        runId,
-        matchedPattern,
-        checkNames: [check.name],
-        ...(check.workflowName !== undefined && { workflowName: check.workflowName }),
-    };
-}
-function findProtectionMatch(check, matchers) {
-    const candidates = [
-        check.workflowName,
-        "jobName" in check ? check.jobName : undefined,
-        check.name,
-    ].filter((value) => value !== undefined && value.trim() !== "");
-    for (const matcher of matchers) {
-        if (candidates.some((candidate) => matcher.isMatch(candidate)))
-            return matcher.pattern;
-    }
-    return null;
-}