pr-shepherd 0.42.0 → 0.44.0

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/poll.mjs

@@ -112,7 +112,9 @@ export async function runPoll(opts) {
             await sleep(intervalMs);
             continue;
         }
-        if (untilTerminal && lastResult.action === "mark_ready" && !pastDebounce) {
+        if ((untilTerminal || iterateOpts.merge) &&
+            lastResult.action === "mark_ready" &&
+            !pastDebounce) {
             debounceUntil = null;
             await sleep(intervalMs);
             continue;

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

@@ -43,10 +43,14 @@ interface PrShepherdConfig {
     mergeStatus: {
         blockingReviewerLogins: string[];
     };
+    merge?: {
+        /** Options added to ordinary `gh pr merge` commands. Queue commands never use these. */
+        commandArgs: string[];
+    };
     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;

package/bin/config/load.mjs

@@ -5,6 +5,7 @@ import { homedir } from "node:os";
 import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
 import { getEffectiveCwd } from "../execution-context.mjs";
+import { findMergeStrategies } from "./merge-command-args.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
 /**
@@ -85,6 +86,35 @@ function parseNeverCancelRuns(value) {
     }
     return value;
 }
+const SHEPHERD_OWNED_MERGE_FLAGS = [
+    "--repo",
+    "-R",
+    "--auto",
+    "--disable-auto",
+    "--match-head-commit",
+    "--admin",
+    "--body-file",
+    "-F",
+    "--help",
+    "-h",
+];
+function parseMergeCommandArgs(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error("Invalid config: merge.commandArgs must be an array of strings");
+    }
+    for (const arg of value) {
+        if (SHEPHERD_OWNED_MERGE_FLAGS.some((flag) => arg === flag ||
+            arg.startsWith(`${flag}=`) ||
+            (flag.startsWith("-") && !flag.startsWith("--") && arg.startsWith(flag)))) {
+            throw new Error(`Invalid config: merge.commandArgs cannot include Shepherd-owned ${arg}`);
+        }
+    }
+    const strategies = findMergeStrategies(value);
+    if (strategies.length > 1) {
+        throw new Error(`Invalid config: merge.commandArgs includes multiple merge strategies: ${strategies.join(", ")}`);
+    }
+    return strategies.length === 0 ? [...value, "--merge"] : [...value];
+}
 const KNOWN_CONFIG_KEYS = new Set([
     "classify",
     "botUsernames",
@@ -94,6 +124,7 @@ const KNOWN_CONFIG_KEYS = new Set([
     "resolve",
     "checks",
     "mergeStatus",
+    "merge",
     "actions",
 ]);
 const KNOWN_NESTED_KEYS = {
@@ -108,6 +139,7 @@ const KNOWN_NESTED_KEYS = {
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents"]),
     mergeStatus: new Set(["blockingReviewerLogins"]),
+    merge: new Set(["commandArgs"]),
     actions: new Set([
         "autoMinimizeSuppressed",
         "autoMarkReady",
@@ -194,6 +226,8 @@ export function loadConfig() {
         config.botUsernames = parseBotUsernames(config.botUsernames);
         config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
         config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
+        if (config.merge)
+            config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;

package/bin/config/merge-command-args.d.mts

@@ -0,0 +1,2 @@
+/** Return active merge strategies while validating compound strategy syntax. */
+export declare function findMergeStrategies(args: string[]): string[];