pr-shepherd 0.43.0 → 0.44.1

package/bin/threads/transcript.mjs

@@ -6,6 +6,7 @@ export function threadComments(thread) {
             author: c.author,
             authorType: c.authorType ?? "Unknown",
             ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
+            ...(c.viewerDidAuthor === true && { viewerDidAuthor: true }),
             body: c.body,
             url: c.url,
             createdAtUnix: c.createdAtUnix ?? 0,
@@ -20,6 +21,7 @@ export function threadComments(thread) {
             ...(thread.authorAssociation !== undefined && {
                 authorAssociation: thread.authorAssociation,
             }),
+            ...(thread.viewerDidAuthor === true && { viewerDidAuthor: true }),
             body: thread.body,
             url: thread.url ?? "",
             createdAtUnix: thread.createdAtUnix ?? 0,

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

@@ -4,6 +4,7 @@ export interface AgentThreadComment {
     author: string;
     authorType?: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     url: string;
 }

package/bin/types/escalate.d.mts

@@ -1,7 +1,7 @@
 import type { AgentComment, AgentThread } from "./report.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "bot-cr-not-dismissed" | "merge-queue-removed";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;
@@ -27,4 +27,9 @@ export interface EscalateDetails {
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;
+    authorization?: Array<{
+        action: "reply-thread" | "resolve-thread" | "dismiss-review" | "mark-ready" | "merge-or-enqueue";
+        targetIds: string[];
+        reason: "denied-or-unverifiable";
+    }>;
 }

package/bin/types/github.d.mts

@@ -7,6 +7,17 @@ export type MergeableState = "CONFLICTING" | "MERGEABLE" | "UNKNOWN";
 export type MergeStateStatus = "BEHIND" | "BLOCKED" | "CLEAN" | "DIRTY" | "DRAFT" | "HAS_HOOKS" | "UNKNOWN" | "UNSTABLE";
 export type ReviewDecision = "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | null;
 export type AuthorType = "User" | "Bot" | "Unknown";
+type RepositoryPermission = "NONE" | "READ" | "TRIAGE" | "WRITE" | "MAINTAIN" | "ADMIN";
+/** Raw GitHub viewer fields used to gate remote actions. */
+export interface ViewerAuthorization {
+    repositoryPermission: RepositoryPermission | null;
+    viewerCanAdminister: boolean;
+    viewerDidAuthor: boolean;
+    viewerCanUpdate: boolean;
+    viewerCanEnableAutoMerge: boolean;
+    viewerCanEditFiles: boolean;
+    headRepositoryPermission: RepositoryPermission | null;
+}
 /** Raw relationship between a comment author and the repository, as reported by GitHub. */
 export type CommentAuthorAssociation = "COLLABORATOR" | "CONTRIBUTOR" | "FIRST_TIMER" | "FIRST_TIME_CONTRIBUTOR" | "MANNEQUIN" | "MEMBER" | "NONE" | "OWNER";
 export interface CheckRun {
@@ -40,6 +51,8 @@ export interface ReviewThread {
     isResolved: boolean;
     isOutdated: boolean;
     isMinimized: boolean;
+    viewerCanReply?: boolean;
+    viewerCanResolve?: boolean;
     path: string | null;
     line: number | null;
     /** Start of the comment's line range. Null for single-line comments (use `line` for both). */
@@ -49,6 +62,7 @@ export interface ReviewThread {
     author: string;
     authorType: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     url: string;
     createdAtUnix?: number;
@@ -70,6 +84,7 @@ export interface SuggestionBlock {
 export interface PrComment {
     id: string;
     isMinimized: boolean;
+    viewerCanMinimize?: boolean;
     author: string;
     authorType: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
@@ -82,6 +97,8 @@ export interface Review {
     author: string;
     authorType: AuthorType;
     authorAssociation?: CommentAuthorAssociation;
+    /** Present for minimizable COMMENTED/APPROVED reviews; false for non-minimizable review rows. */
+    viewerCanMinimize?: boolean;
     body: string;
     createdAtUnix?: number;
     edited?: boolean;
@@ -123,6 +140,7 @@ export interface BatchPrData extends BatchPrMergeFields {
     headRefName: string;
     /** `"owner/name"` of the head repository; null when the fork has been deleted. */
     headRepoWithOwner: string | null;
+    viewerAuthorization?: ViewerAuthorization;
     baseRefName: string;
     reviewRequests: Array<{
         login: string;
@@ -144,3 +162,4 @@ export interface BatchPrData extends BatchPrMergeFields {
     branchProtection: BranchProtection | null;
     activity?: PrActivitySummary;
 }
+export {};

package/bin/types/iterate.d.mts

@@ -59,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[];
@@ -69,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[];
@@ -90,13 +90,13 @@ 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;
@@ -127,10 +127,11 @@ export type IterateResult = IterateResultWait | IterateResultCancel | IterateRes
 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. */

package/bin/types/report.d.mts

@@ -1,4 +1,4 @@
-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";
@@ -24,6 +24,8 @@ export interface ShepherdReport {
     /** 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;
@@ -87,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;
@@ -94,6 +100,7 @@ export interface AgentThread {
     author: string;
     authorType?: AuthorType;
     authorAssociation?: import("./github.mts").CommentAuthorAssociation;
+    viewerDidAuthor?: true;
     body: string;
     url: string;
     comments?: AgentThreadComment[];
@@ -103,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;
@@ -160,6 +169,10 @@ export interface RelevantCheck {
 }
 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/package.json

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.43.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.44.1", "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

@@ -14,7 +14,7 @@ Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only wh
 
 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 forward `--merge` when supplied; 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, plus `merge: true` when `--merge` was supplied, 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;
-}