pr-shepherd 0.43.0 → 0.44.0

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.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.43.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.43.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.43.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

@@ -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;
-}