pr-shepherd 0.43.0 → 0.44.0

package/bin/commands/iterate/render.mjs

@@ -10,8 +10,8 @@ export function renderResolveCommand(rc) {
         parts.push("--require-sha", "$HEAD_SHA");
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+isBehind = false, viewerCanUpdate = false) {
     const instructions = [];
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
@@ -38,13 +38,13 @@ isBehind = false) {
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
     if (hasConflicts) {
-        instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing and pushing.");
+        instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing.");
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
         instructions.push("Review every item under `## First-look items` before acting.");
     }
-    if (firstLookSummaries.length > 0)
+    if (firstLookSummaries.length > 0 && viewerCanUpdate)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
     const editedTotal = editedSummaries.length +
         actionableComments.filter((c) => c.edited).length +
@@ -53,15 +53,13 @@ isBehind = false) {
     if (editedTotal > 0) {
         instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
     }
-    if (inProgressRunIds.length > 0) {
-        instructions.push("If you will push, first cancel every ID under `## In-progress runs` with `gh run cancel <id>` (ignore errors for runs that already finished). If you will not push, leave them alone.");
-    }
-    if (cancelledCount > 0) {
-        instructions.push("Do not cancel the IDs under `## Cancelled runs` again. The CLI already cancelled them.");
-    }
+    // GitHub exposes no exact viewer capability for workflow-run cancellation, so the
+    // informational run lists never produce a cancellation recommendation.
+    void inProgressRunIds;
+    void cancelledCount;
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions)
-        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads"));
+        instructions.push(buildCommitSuggestionInstruction(prReference, "## Review threads"));
     if (threads.length > 0 || actionableComments.length > 0) {
         // Actionable comments carry no file/line location (unlike threads), so "referenced above"
         // is only accurate when threads are present.
@@ -83,21 +81,22 @@ isBehind = false) {
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts) {
-        instructions.push(`Commit any remaining changes and push the conflict resolution${mutationSuffix}.`);
+        instructions.push(`Commit any remaining conflict-resolution changes${mutationSuffix}.`);
     }
     else if (hasNonConflictHints) {
-        instructions.push(`If you changed code, commit any remaining changes and push${mutationSuffix}. Otherwise, do not commit or push.`);
+        instructions.push("If you changed code, commit any remaining changes, then stop and hand off for a push whose authorization is established outside Shepherd; do not run the remaining review mutations or iterate until the remote PR head changes. Shepherd cannot verify the Git credential's push authorization. If you did not change code, do not commit and continue with the remaining steps.");
     }
-    if (hasReviewMutations ||
-        hasNonConflictHints ||
-        firstLookTotal > 0 ||
-        firstLookSummaries.length > 0 ||
-        editedTotal > 0) {
-        instructions.push(buildShepherdJournalInstruction(prNumber));
+    if (viewerCanUpdate &&
+        (hasReviewMutations ||
+            hasNonConflictHints ||
+            firstLookTotal > 0 ||
+            firstLookSummaries.length > 0 ||
+            editedTotal > 0)) {
+        instructions.push(buildShepherdJournalInstruction(prReference));
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
     instructions.push(...buildResolveCommandInstruction(resolveCommand));
-    instructions.push(buildFixCompletionInstruction(failingChecks));
+    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
     return instructions;
 }

package/bin/commands/iterate/stall.mjs

@@ -2,6 +2,7 @@ import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
 import { checksWithActionableAnnotations } from "../check-annotations.mjs";
+import { formatPrUrl } from "../../pr-reference.mjs";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
@@ -36,6 +37,7 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
     });
 }
 export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {
+    const prReference = formatPrUrl(report.repo, prNumber);
     const nowSeconds = Math.floor(Date.now() / 1000);
     const stalledChecks = findCiStartStalledChecks(report.checks.inProgress, nowSeconds, {
         stallTimeoutSeconds,
@@ -56,7 +58,7 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
             action: "escalate",
             escalate: {
                 ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+                humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
             },
         };
     }
@@ -86,7 +88,7 @@ export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, ba
                 action: "escalate",
                 escalate: {
                     ...escalateBase,
-                    humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+                    humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
                 },
             };
         }

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

@@ -0,0 +1,9 @@
+import { type NormalizedBotUsernames } from "../../comments/authors.mts";
+import type { AgentThread, ReviewThread } from "../../types.mts";
+export interface ThreadMutationRouting {
+    replyThreadIds: string[];
+    pairedResolveThreadIds: string[];
+    standaloneResolveThreadIds: string[];
+    resolveThreadIds: string[];
+}
+export declare function buildThreadMutationRouting(threads: Array<AgentThread | ReviewThread>, botUsernames: NormalizedBotUsernames, ruleAutoResolveThreadIds: string[]): ThreadMutationRouting;

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

@@ -0,0 +1,29 @@
+import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "../../comments/authors.mjs";
+import { threadEndedByShepherd } from "../../comments/marker.mjs";
+function dedupeIds(ids) {
+    return [...new Set(ids)];
+}
+export function buildThreadMutationRouting(threads, botUsernames, ruleAutoResolveThreadIds) {
+    const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
+    const replyThreadIds = dedupeIds(threads
+        .filter((thread) => isOrdinaryHuman(thread) && !threadEndedByShepherd(thread))
+        .map((thread) => thread.id));
+    const pairedResolveThreadIds = dedupeIds(threads
+        .filter((thread) => isViewerAuthoredHuman(thread, botUsernames) && !threadEndedByShepherd(thread))
+        .map((thread) => thread.id));
+    const pairedResolveIdSet = new Set(pairedResolveThreadIds);
+    // Rule-matched threads bypass author routing; resolve-mutate retains the human-author guard.
+    const standaloneResolveThreadIds = dedupeIds([
+        ...threads
+            .filter((thread) => !isOrdinaryHuman(thread) ||
+            (isViewerAuthoredHuman(thread, botUsernames) && threadEndedByShepherd(thread)))
+            .map((thread) => thread.id),
+        ...ruleAutoResolveThreadIds,
+    ]).filter((id) => !pairedResolveIdSet.has(id));
+    return {
+        replyThreadIds,
+        pairedResolveThreadIds,
+        standaloneResolveThreadIds,
+        resolveThreadIds: dedupeIds([...pairedResolveThreadIds, ...standaloneResolveThreadIds]),
+    };
+}

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

@@ -1,5 +1,9 @@
 export interface RunJournalOptions {
     prNumber: number | undefined;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
     rawItem: string;
     dryRun: boolean;
 }
@@ -9,6 +13,7 @@ export interface JournalResult {
     sectionExisted: boolean;
     dryRun: boolean;
     previewBody?: string;
+    authorizationSkipped?: "denied-or-unverifiable";
 }
 /** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */
 export declare function runJournal(opts: RunJournalOptions): Promise<JournalResult>;

package/bin/commands/journal/index.mjs

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

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

@@ -1,4 +1,4 @@
-import { type ResolveRateLimitStop } from "../comments/rate-limit.mts";
+import type { ResolveRateLimitStop } from "../comments/rate-limit.mts";
 import type { GlobalOptions } from "../types.mts";
 export interface MarkFilesAsViewedOptions extends GlobalOptions {
     prNumber?: number;
@@ -21,6 +21,7 @@ export interface MarkFilesAsViewedResult {
     errors: string[];
     rateLimit?: ResolveRateLimitStop;
     unmarkedPaths?: string[];
+    authorizationSkipped?: "unverifiable";
 }
 /** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
 export declare function runMarkFilesAsViewed(opts: MarkFilesAsViewedOptions): Promise<MarkFilesAsViewedResult>;

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

@@ -1,7 +1,6 @@
 /* eslint-disable max-lines */
-import { graphql, graphqlWithRateLimit, getCurrentPrNumber, getRepoInfo, } from "../github/client.mjs";
+import { graphql, getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
 import { paginateForward } from "../github/pagination.mjs";
-import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "../comments/rate-limit.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr: Int!, $filesCursor: String) {
   repository(owner: $owner, name: $repo) {
@@ -22,10 +21,9 @@ const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr
   }
 }`;
 const TEST_FILE_RE = /(^|\/)(tests?|__tests__|spec)(\/|$)|\.(test|spec)\.[cm]?[jt]sx?$|_tests?\.rs$|(^|\/)tests?\.rs$/i;
-const BULK_CHUNK_SIZE = 10;
 /** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
 export async function runMarkFilesAsViewed(opts) {
-    const repo = await getRepoInfo();
+    const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (!prNumber) {
         throw new ShepherdError("No PR number provided and no current branch PR found", EXIT.UNAVAILABLE);
@@ -52,8 +50,10 @@ export async function runMarkFilesAsViewed(opts) {
         missingPaths: selected.missingPaths,
         unmatchedSelectors: selected.unmatchedSelectors,
         errors: [],
+        ...(selected.pathsToMark.length > 0 && { authorizationSkipped: "unverifiable" }),
     };
-    await bulkMarkFilesAsViewed(fetched.pullRequestId, selected.pathsToMark, result);
+    // GitHub exposes no exact viewer capability for markFileAsViewed. Repository role and
+    // viewerCanEditFiles describe different operations, so this command fails closed.
     return result;
 }
 async function fetchPullRequestFiles(pr, repo) {
@@ -132,90 +132,3 @@ function selectChangedFiles(changedFiles, opts) {
     const pathsToMark = matchedPaths.filter((path) => !alreadyViewedSet.has(path));
     return { matchedPaths, alreadyViewedPaths, missingPaths, unmatchedSelectors, pathsToMark };
 }
-function buildBulkMutation(paths) {
-    const ops = paths.map((path, i) => `  m${i}: markFileAsViewed(input: { pullRequestId: $pullRequestId, path: ${JSON.stringify(path)} }) { pullRequest { id } }`);
-    return `mutation BulkMarkFilesAsViewed($pullRequestId: ID!) {\n${ops.join("\n")}\n}`;
-}
-async function bulkMarkFilesAsViewed(pullRequestId, paths, result) {
-    for (let i = 0; i < paths.length; i += BULK_CHUNK_SIZE) {
-        const chunk = paths.slice(i, i + BULK_CHUNK_SIZE);
-        // eslint-disable-next-line no-await-in-loop
-        const stopped = await bulkMarkFilesAsViewedChunk(pullRequestId, chunk, result, i + BULK_CHUNK_SIZE < paths.length);
-        if (stopped) {
-            const markedSet = new Set(result.markedPaths);
-            result.unmarkedPaths = paths.slice(i).filter((path) => !markedSet.has(path));
-            return;
-        }
-    }
-}
-async function bulkMarkFilesAsViewedChunk(pullRequestId, paths, result, hasPendingAfter) {
-    if (paths.length === 0)
-        return false;
-    let data = {};
-    let graphQlErrors = [];
-    let suppressCurrentChunkErrors = false;
-    let rateLimitStop;
-    try {
-        const resp = await graphqlWithRateLimit(buildBulkMutation(paths), { pullRequestId }, { allowPartialData: true });
-        data = resp.data;
-        graphQlErrors = (resp.errors ?? []);
-        const messages = graphQlErrors.map((e) => e.message);
-        suppressCurrentChunkErrors = messages.some(isRateLimitMessage);
-        rateLimitStop = rateLimitFromGraphQlResult(messages, {
-            rateLimit: resp.rateLimit,
-            retryAfterSeconds: resp.retryAfterSeconds,
-            stopOnZeroRemaining: hasPendingAfter,
-        });
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        const stop = rateLimitFromError(err, msg);
-        if (stop) {
-            result.errors.push(`rate limit: ${stop.message}`);
-            result.rateLimit = stop;
-            return true;
-        }
-        for (const path of paths)
-            result.errors.push(`${path}: ${msg}`);
-        return false;
-    }
-    const errorMessagesByAlias = mapAliasErrors(graphQlErrors);
-    for (let i = 0; i < paths.length; i += 1) {
-        const alias = `m${i}`;
-        const m = data[alias];
-        if (m?.pullRequest?.id === pullRequestId) {
-            result.markedPaths.push(paths[i]);
-        }
-        else if (!suppressCurrentChunkErrors) {
-            result.errors.push(`${paths[i]}: ${errorMessagesByAlias.get(alias) ?? "mark returned null"}`);
-        }
-    }
-    if (rateLimitStop) {
-        result.errors.push(`rate limit: ${rateLimitStop.message}`);
-        result.rateLimit = rateLimitStop;
-        return true;
-    }
-    return false;
-}
-function mapAliasErrors(errors) {
-    const out = new Map();
-    for (const error of errors) {
-        if (!Array.isArray(error.path))
-            continue;
-        const alias = error.path.find((part) => typeof part === "string" && isMarkAlias(part));
-        if (typeof alias === "string")
-            out.set(alias, error.message);
-    }
-    return out;
-}
-function isMarkAlias(value) {
-    if (!value.startsWith("m"))
-        return false;
-    if (value.length === 1)
-        return false;
-    for (const char of value.slice(1)) {
-        if (char < "0" || char > "9")
-            return false;
-    }
-    return true;
-}

package/bin/commands/resolve-mutate.mjs

@@ -2,14 +2,14 @@ import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { applyResolveOptions } from "../comments/resolve.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
 import { loadConfig } from "../config/load.mjs";
-import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
+import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, normalizeBotUsernames, } from "../comments/authors.mjs";
 import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
-import { addPrShepherdMarker } from "../comments/marker.mjs";
+import { addPrShepherdMarker, threadEndedByShepherd } from "../comments/marker.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 /** @deprecated Hidden implementation for `resolve`; use `apply review`. */
 export async function runResolveMutate(opts) {
-    const repo = await getRepoInfo();
+    const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
@@ -27,21 +27,55 @@ export async function runResolveMutate(opts) {
     const humanReviewIds = new Set([...data.reviewSummaries, ...data.approvedReviews, ...data.changesRequestedReviews]
         .filter((r) => isHumanAuthor(r) && !isConfiguredBotAuthor(r, botUsernames))
         .map((r) => r.id));
-    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id));
-    const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id));
-    const replyThreadIds = opts.replyThreadIds?.filter((id) => humanThreadIds.has(id));
+    const replyAuthorizedIds = new Set(data.reviewThreads
+        .filter((thread) => thread.viewerCanReply === true)
+        .map((thread) => thread.id));
+    const resolveAuthorizedIds = new Set(data.reviewThreads
+        .filter((thread) => thread.viewerCanResolve === true)
+        .map((thread) => thread.id));
+    const minimizeAuthorizedIds = new Set([
+        ...data.comments
+            .filter((comment) => comment.viewerCanMinimize === true)
+            .map((comment) => comment.id),
+        ...data.reviewSummaries
+            .filter((review) => review.viewerCanMinimize === true)
+            .map((review) => review.id),
+        ...data.approvedReviews
+            .filter((review) => review.viewerCanMinimize === true)
+            .map((review) => review.id),
+    ]);
+    const requestedReplyIds = new Set((opts.replyThreadIds ?? []).filter((id) => replyAuthorizedIds.has(id)));
+    const allowedViewerHumanResolveIds = new Set(data.reviewThreads
+        .filter((thread) => isViewerAuthoredHuman(thread, botUsernames) &&
+        (requestedReplyIds.has(thread.id) || threadEndedByShepherd(thread)))
+        .map((thread) => thread.id));
+    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => (!humanThreadIds.has(id) || allowedViewerHumanResolveIds.has(id)) &&
+        resolveAuthorizedIds.has(id));
+    const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !allowedViewerHumanResolveIds.has(id));
+    const skippedUnauthorizedResolves = (opts.resolveThreadIds ?? []).filter((id) => (!humanThreadIds.has(id) || allowedViewerHumanResolveIds.has(id)) &&
+        !resolveAuthorizedIds.has(id));
+    const replyThreadIds = opts.replyThreadIds?.filter((id) => humanThreadIds.has(id) && replyAuthorizedIds.has(id));
     const skippedNonHumanReplies = (opts.replyThreadIds ?? []).filter((id) => !humanThreadIds.has(id));
-    const minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id));
+    const skippedUnauthorizedReplies = (opts.replyThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !replyAuthorizedIds.has(id));
+    const minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id) && minimizeAuthorizedIds.has(id));
     const skippedHumanMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => humanCommentIds.has(id) || humanReviewIds.has(id));
-    const dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id));
+    const skippedUnauthorizedMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id) && !minimizeAuthorizedIds.has(id));
+    const dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) &&
+        data.changesRequestedReviews.some((review) => review.id === id) &&
+        data.viewerAuthorization?.viewerCanAdminister === true);
     const skippedHumanDismissals = (opts.dismissReviewIds ?? []).filter((id) => humanReviewIds.has(id));
+    const skippedUnauthorizedDismissals = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && !dismissReviewIds.includes(id));
+    const hasAuthorizedMutation = resolveThreadIds.length > 0 ||
+        (replyThreadIds?.length ?? 0) > 0 ||
+        minimizeCommentIds.length > 0 ||
+        dismissReviewIds.length > 0;
     const result = await applyResolveOptions(prNumber, repo, {
         resolveThreadIds,
         replyThreadIds,
         minimizeCommentIds,
         dismissReviewIds,
         dismissMessage: opts.dismissMessage,
-        requireSha: opts.requireSha,
+        requireSha: hasAuthorizedMutation ? opts.requireSha : undefined,
     });
     if (skippedHumanResolves.length > 0)
         result.skippedHumanResolves = skippedHumanResolves;
@@ -51,6 +85,14 @@ export async function runResolveMutate(opts) {
         result.skippedHumanDismissals = skippedHumanDismissals;
     if (skippedNonHumanReplies.length > 0)
         result.skippedNonHumanReplies = skippedNonHumanReplies;
+    if (skippedUnauthorizedReplies.length > 0)
+        result.skippedUnauthorizedReplies = skippedUnauthorizedReplies;
+    if (skippedUnauthorizedResolves.length > 0)
+        result.skippedUnauthorizedResolves = skippedUnauthorizedResolves;
+    if (skippedUnauthorizedMinimizes.length > 0)
+        result.skippedUnauthorizedMinimizes = skippedUnauthorizedMinimizes;
+    if (skippedUnauthorizedDismissals.length > 0)
+        result.skippedUnauthorizedDismissals = skippedUnauthorizedDismissals;
     if (opts.dismissMessage) {
         const markedMessage = addPrShepherdMarker(opts.dismissMessage);
         await Promise.all(result.repliedThreads.map((id) => {

package/bin/commands/shepherd-journal.d.mts

@@ -11,4 +11,4 @@ export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body un
  * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
  * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
  */
-export declare function buildShepherdJournalInstruction(prNumber: number): string;
+export declare function buildShepherdJournalInstruction(prReference: string | number): string;

package/bin/commands/shepherd-journal.mjs

@@ -11,6 +11,6 @@ export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `##
  * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
  * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
  */
-export function buildShepherdJournalInstruction(prNumber) {
-    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`. See "Shepherd Journal" in the pr-shepherd skill for citation conventions.`;
+export function buildShepherdJournalInstruction(prReference) {
+    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prReference} '- <decision>'\`. See "Shepherd Journal" in the pr-shepherd skill for citation conventions.`;
 }

package/bin/commands/suggestion-patch-item.d.mts

@@ -10,6 +10,6 @@ export declare function buildSuggestionPatchItem({ thread, request, originalCont
     request: SuggestionPatchRequest;
     originalContent: string;
 }): SuggestionPatchResult;
-export declare function buildSingularInstructions(patch: SuggestionPatchResult, prNumber: number): string[];
+export declare function buildSingularInstructions(patch: SuggestionPatchResult, prReference: string | number): string[];
 export declare function buildCommitCommand(patch: SuggestionPatchResult): string;
 export declare function quotePath(path: string): string;

package/bin/commands/suggestion-patch-item.mjs

@@ -1,7 +1,6 @@
 import { relative, resolve } from "node:path";
 import { getEffectiveCwd } from "../execution-context.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
 import { getUnsafeSuggestionRangeReason } from "../suggestions/range.mjs";
@@ -62,23 +61,16 @@ export function buildSuggestionPatchItem({ thread, request, originalContent, })
         filesToStage: [thread.path],
     };
 }
-export function buildSingularInstructions(patch, prNumber) {
+export function buildSingularInstructions(patch, prReference) {
     const range = patch.startLine === patch.endLine
         ? `line ${patch.startLine}`
         : `lines ${patch.startLine}–${patch.endLine}`;
-    const resolveCommand = buildPrShepherdCommand([
-        "apply",
-        "review",
-        String(prNumber),
-        "--resolve-thread-ids",
-        patch.threadId,
-    ]).text;
     return [
         `Apply the patch to \`${patch.path}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
         `Stage the file: \`git add -- ${quotePath(patch.path)}\``,
         `Commit: \`${buildCommitCommand(patch)}\``,
-        `Resolve the thread on GitHub: \`${resolveCommand}\``,
-        `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
+        `Use the originating iterate output for any authorization-checked GitHub review action for thread \`${patch.threadId}\` on ${String(prReference)}.`,
+        "Shepherd cannot verify authorization for the Git credential that would push this branch, so this output does not recommend a push.",
     ];
 }
 export function buildCommitCommand(patch) {

package/bin/commands/suggestion-patches.mjs

@@ -5,7 +5,7 @@ import { buildCommitCommand, buildSuggestionPatchItem, quotePath, validateSugges
 import { checkPatchesApply, getLocalHeadSha, getPathsStatus, isAncestor, readPrHeadFile, } from "./suggestion-patch-git.mjs";
 export async function runSuggestionPatches(opts) {
     validateRequests(opts.suggestions);
-    const repo = await getRepoInfo();
+    const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
@@ -96,8 +96,8 @@ function buildBatchInstructions(patches) {
     ]);
     return [
         ...patchInstructions,
-        "Push once after every patch is committed: `git push` (or `git push --force-with-lease` after rebasing).",
-        `Then continue with the originating iterate output's \`apply review\` instructions for thread IDs: ${patches.map((patch) => patch.threadId).join(", ")}.`,
+        "Shepherd cannot verify authorization for the Git credential that would push this branch, so this output does not recommend a push.",
+        `Continue only with authorization-checked \`apply review\` instructions from the originating iterate output for thread IDs: ${patches.map((patch) => patch.threadId).join(", ")}.`,
     ];
 }
 function errorMessage(error) {

package/bin/comments/authors.d.mts

@@ -12,3 +12,9 @@ export declare function isConfiguredBotAuthor(author: {
     login?: string;
     authorType?: AuthorType;
 }, botUsernames?: NormalizedBotUsernames): boolean;
+export declare function isViewerAuthoredHuman(author: {
+    author?: string;
+    login?: string;
+    authorType?: AuthorType;
+    viewerDidAuthor?: true;
+}, botUsernames?: NormalizedBotUsernames): boolean;

package/bin/comments/authors.mjs

@@ -30,3 +30,8 @@ export function isConfiguredBotAuthor(author, botUsernames = new Set()) {
         return false;
     return botUsernames.has(normalized);
 }
+export function isViewerAuthoredHuman(author, botUsernames = new Set()) {
+    return (author.viewerDidAuthor === true &&
+        isHumanAuthor(author) &&
+        !isConfiguredBotAuthor(author, botUsernames));
+}

package/bin/comments/marker.d.mts

@@ -1,2 +1,7 @@
-export declare function hasPrShepherdMarker(body: string): boolean;
 export declare function addPrShepherdMarker(body: string): string;
+export declare function threadEndedByShepherd(thread: {
+    body: string;
+    comments?: readonly {
+        body: string;
+    }[];
+}): boolean;

package/bin/comments/marker.mjs

@@ -1,7 +1,14 @@
 const PR_SHEPHERD_MARKER = "<!-- pr-shepherd -->";
-export function hasPrShepherdMarker(body) {
+function hasPrShepherdMarker(body) {
     return body.startsWith(PR_SHEPHERD_MARKER);
 }
 export function addPrShepherdMarker(body) {
     return `${PR_SHEPHERD_MARKER}\n${body}`;
 }
+export function threadEndedByShepherd(thread) {
+    const comments = thread.comments;
+    if (comments && comments.length > 0) {
+        return hasPrShepherdMarker(comments[comments.length - 1].body);
+    }
+    return hasPrShepherdMarker(thread.body);
+}

package/bin/comments/resolve.d.mts

@@ -12,6 +12,10 @@ export interface ResolveResult {
     skippedHumanMinimizes?: string[];
     skippedHumanDismissals?: string[];
     skippedNonHumanReplies?: string[];
+    skippedUnauthorizedReplies?: string[];
+    skippedUnauthorizedResolves?: string[];
+    skippedUnauthorizedMinimizes?: string[];
+    skippedUnauthorizedDismissals?: string[];
     rateLimit?: ResolveRateLimitStop;
     unrepliedThreads?: string[];
     unresolvedThreads?: string[];

package/bin/comments/thread-visibility.mjs

@@ -1,14 +1,7 @@
 import { classifyItem } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
-import { isConfiguredBotAuthor } from "./authors.mjs";
-import { hasPrShepherdMarker } from "./marker.mjs";
-function threadEndedByShepherd(thread) {
-    const comments = thread.comments;
-    if (comments && comments.length > 0) {
-        return hasPrShepherdMarker(comments[comments.length - 1].body);
-    }
-    return hasPrShepherdMarker(thread.body);
-}
+import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "./authors.mjs";
+import { threadEndedByShepherd } from "./marker.mjs";
 function withEdited(thread, edited) {
     return edited ? { ...thread, edited: true } : thread;
 }
@@ -39,7 +32,14 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
         return visible ? [visible] : [];
     });
     const resolutionOnlyThreads = unresolvedThreads
-        .filter((t) => t.isOutdated || t.isMinimized)
+        .filter((t) => {
+        const endedByShepherd = threadEndedByShepherd(t);
+        const ordinaryHuman = isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames);
+        if (endedByShepherd && ordinaryHuman) {
+            return isViewerAuthoredHuman(t, botUsernames);
+        }
+        return t.isOutdated || t.isMinimized;
+    })
         .map((t) => classifyVisibleThread(t, seenMap) ?? t);
     const firstLookThreads = [
         ...threads.flatMap((t) => {

package/bin/comments/visible-comments.mjs

@@ -5,7 +5,8 @@ export function classifyVisibleComments(comments, seenMap, minimizeComments, bot
     const minimizeIds = [];
     const toMarkSeen = [];
     for (const c of comments.filter((comment) => !comment.isMinimized)) {
-        if (shouldMinimizeAuthor(c.authorType, minimizeComments, c.author, botUsernames)) {
+        if (c.viewerCanMinimize === true &&
+            shouldMinimizeAuthor(c.authorType, minimizeComments, c.author, botUsernames)) {
             actionable.push(c);
             minimizeIds.push(c.id);
             toMarkSeen.push(c); // prevents re-surfacing as first-look after GitHub marks it minimized

package/bin/config/load.d.mts

@@ -50,7 +50,7 @@ interface PrShepherdConfig {
     actions: {
         autoMinimizeSuppressed: boolean;
         autoMarkReady: boolean;
-        /** Case-insensitive glob patterns for workflow/check names Shepherd must not cancel. */
+        /** Legacy-named patterns that keep matching Actions checks visible despite ignoreChecks. */
         neverCancelRuns: string[];
         /** @deprecated Accepted for compatibility, ignored by the loader. */
         autoResolveOutdated?: boolean;