pr-shepherd 0.45.0 → 0.46.1

package/bin/commands/iterate/merge-state.mjs

@@ -7,45 +7,16 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
         return null;
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
-    // A merge queue is enrolled the same way auto-merge is granted: enabling
-    // auto-merge on a queue-required PR is what adds it to the queue, so
-    // viewerCanEnableAutoMerge authorizes both the plain-merge and enqueue paths.
-    if (report.viewerAuthorization?.viewerCanEnableAutoMerge === true) {
-        return {
-            ...base,
-            action: "merge",
-            merge: buildMergeCommandPlan({
-                pr: report.pr,
-                repo: report.repo,
-                nodeId: report.nodeId,
-                headSha: report.headSha ?? "unknown",
-                queue,
-            }),
-        };
-    }
-    const authorizationEscalateBase = {
-        triggers: ["authorization-required"],
-        unresolvedThreads: [],
-        ambiguousComments: [],
-        changesRequestedReviews: [],
-        authorization: [
-            {
-                action: "merge-or-enqueue",
-                targetIds: [report.nodeId],
-                reason: "denied-or-unverifiable",
-            },
-        ],
-        suggestion: buildEscalateSuggestion(["authorization-required"]),
-    };
     return {
         ...base,
-        action: "escalate",
-        escalate: {
-            ...authorizationEscalateBase,
-            humanMessage: buildEscalateHumanMessage(authorizationEscalateBase, report.pr, {
-                merge: true,
-            }),
-        },
+        action: "merge",
+        merge: buildMergeCommandPlan({
+            pr: report.pr,
+            repo: report.repo,
+            nodeId: report.nodeId,
+            headSha: report.headSha ?? "unknown",
+            queue,
+        }),
     };
 }
 export async function handleActiveMergeState(input) {

package/bin/commands/iterate/merge.mjs

@@ -38,6 +38,7 @@ export function buildMergeCommandPlan(input) {
     return {
         mode: "auto",
         command: { argv: [...base, "--auto", ...commandArgs] },
+        fallbackCommand: { argv: [...base, ...commandArgs] },
     };
 }
 export function renderMergeCommand(command) {

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

@@ -2,4 +2,4 @@ import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, Fir
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean, pushAuthorized?: boolean): string[];
+isBehind?: boolean, viewerCanUpdate?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -11,8 +11,10 @@ export function renderResolveCommand(rc) {
     return renderShellCommand(parts);
 }
 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, pushAuthorized = false) {
+isBehind = false, viewerCanUpdate = false) {
     const instructions = [];
+    const locatedThreads = threads.filter((thread) => thread.path !== null && thread.line !== null);
+    const unlocatedThreads = threads.filter((thread) => thread.path === null || thread.line === null);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
     const hasNonConflictHints = threads.length > 0 ||
@@ -23,8 +25,10 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     // Start with interpretation. The agent decides what raw feedback warrants a code change.
     if (hasNonConflictHints) {
         const actionableSections = [];
-        if (threads.length > 0)
+        if (locatedThreads.length > 0)
             actionableSections.push("`## Review threads`");
+        if (unlocatedThreads.length > 0)
+            actionableSections.push("`## Unlocated review threads (logged once — no mutation)`");
         if (actionableComments.length > 0)
             actionableSections.push("`## Actionable comments`");
         if (failingChecks.length > 0)
@@ -53,17 +57,20 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = 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 (unlocatedThreads.length > 0) {
+        instructions.push("Acknowledge each item under `## Unlocated review threads (logged once — no mutation)`. Shepherd cannot route a code fix or review mutation without a path and line; the unchanged item will be skipped on later ticks.");
+    }
     // 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);
+    const hasSuggestions = locatedThreads.some((t) => t.suggestion);
     if (hasSuggestions)
         instructions.push(buildCommitSuggestionInstruction(prReference, "## Review threads"));
-    if (threads.length > 0 || actionableComments.length > 0) {
+    if (locatedThreads.length > 0 || actionableComments.length > 0) {
         // Actionable comments carry no file/line location (unlike threads), so "referenced above"
         // is only accurate when threads are present.
-        const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
+        const filesRef = locatedThreads.length > 0 ? "each file referenced above" : "the relevant files";
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
     }
     if (resolutionOnlyThreads.length > 0) {
@@ -81,14 +88,10 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts) {
-        instructions.push(pushAuthorized
-            ? `Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`
-            : `Commit any remaining conflict-resolution changes${mutationSuffix}.`);
+        instructions.push(`Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`);
     }
     else if (hasNonConflictHints) {
-        instructions.push(pushAuthorized
-            ? "If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps."
-            : "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.");
+        instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps.");
     }
     if (viewerCanUpdate &&
         (hasReviewMutations ||
@@ -100,7 +103,7 @@ isBehind = false, viewerCanUpdate = false, pushAuthorized = false) {
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
-    instructions.push(...buildResolveCommandInstruction(resolveCommand, pushAuthorized));
-    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha, pushAuthorized));
+    instructions.push(...buildResolveCommandInstruction(resolveCommand));
+    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
     return instructions;
 }

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

@@ -13,6 +13,7 @@ export interface JournalResult {
     sectionExisted: boolean;
     dryRun: boolean;
     previewBody?: string;
+    /** @deprecated Explicit journal requests now rely on GitHub's mutation response. */
     authorizationSkipped?: "denied-or-unverifiable";
 }
 /** @deprecated Hidden implementation for standalone `journal`; use `apply journal`. */

package/bin/commands/journal/index.mjs

@@ -12,17 +12,8 @@ export async function runJournal(opts) {
     if (!prNumber) {
         throw new Error("PR number is required: no PR number provided and none found for current branch");
     }
-    const { nodeId, body, viewerCanUpdate } = await getPullRequestBody(prNumber, owner, name);
+    const { nodeId, body } = 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[];
+    /** @deprecated Explicit file-view requests are attempted; GitHub authorizes the mutation. */
     authorizationSkipped?: "unverifiable";
 }
 /** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */

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

@@ -1,6 +1,7 @@
 /* eslint-disable max-lines */
-import { graphql, getCurrentPrNumber, getRepoInfo } from "../github/client.mjs";
+import { graphql, graphqlWithRateLimit, 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) {
   _shepherdRateLimit: rateLimit {
@@ -29,6 +30,8 @@ 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;
+// Keep mutation batches small so rate-limit stops leave an ordered pending list.
+const MARK_FILES_CHUNK_SIZE = 10;
 /** @deprecated Hidden implementation for `mark-files-as-viewed`; use `apply files`. */
 export async function runMarkFilesAsViewed(opts) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
@@ -58,12 +61,121 @@ export async function runMarkFilesAsViewed(opts) {
         missingPaths: selected.missingPaths,
         unmatchedSelectors: selected.unmatchedSelectors,
         errors: [],
-        ...(selected.pathsToMark.length > 0 && { authorizationSkipped: "unverifiable" }),
     };
-    // GitHub exposes no exact viewer capability for markFileAsViewed. Repository role and
-    // viewerCanEditFiles describe different operations, so this command fails closed.
+    await markFilesAsViewed(fetched.pullRequestId, selected.pathsToMark, result);
     return result;
 }
+async function markFilesAsViewed(pullRequestId, paths, result) {
+    for (let offset = 0; offset < paths.length; offset += MARK_FILES_CHUNK_SIZE) {
+        const chunk = paths.slice(offset, offset + MARK_FILES_CHUNK_SIZE);
+        // eslint-disable-next-line no-await-in-loop
+        const pendingPaths = await markFilesChunk(pullRequestId, chunk, result, offset + MARK_FILES_CHUNK_SIZE < paths.length);
+        if (pendingPaths === null)
+            continue;
+        const unmarkedPaths = [...pendingPaths, ...paths.slice(offset + chunk.length)];
+        if (unmarkedPaths.length > 0)
+            result.unmarkedPaths = unmarkedPaths;
+        return;
+    }
+}
+/** Returns pending paths when a rate limit stops further mutation batches. */
+async function markFilesChunk(pullRequestId, paths, result, hasPendingAfter) {
+    try {
+        const response = await graphqlWithRateLimit(buildMarkFilesMutation(pullRequestId, paths), {}, { allowPartialData: true });
+        const errors = (response.errors ?? []);
+        const rateLimit = rateLimitFromGraphQlResult(errors.map((error) => error.message), {
+            rateLimit: response.rateLimit,
+            retryAfterSeconds: response.retryAfterSeconds,
+            stopOnZeroRemaining: hasPendingAfter,
+        });
+        const classifiedErrors = classifyMarkFileErrors(errors, paths.length);
+        const pendingPaths = recordMarkFileResults(paths, response.data, errors, classifiedErrors, rateLimit, result);
+        return completeMarkFilesChunk(rateLimit, pendingPaths, result);
+    }
+    catch (error) {
+        return recordMarkFilesTransportError(error, paths, result);
+    }
+}
+function classifyMarkFileErrors(errors, pathCount) {
+    const aliasesWithNonRateErrors = new Set();
+    const aliasesWithRateLimitErrors = new Set();
+    const unscopedNonRateMessages = [];
+    for (const error of errors) {
+        const aliasIndex = markFileErrorAliasIndex(error);
+        if (aliasIndex === undefined || aliasIndex >= pathCount) {
+            if (!isRateLimitMessage(error.message))
+                unscopedNonRateMessages.push(error.message);
+            continue;
+        }
+        if (isRateLimitMessage(error.message))
+            aliasesWithRateLimitErrors.add(aliasIndex);
+        else
+            aliasesWithNonRateErrors.add(aliasIndex);
+    }
+    return { aliasesWithNonRateErrors, aliasesWithRateLimitErrors, unscopedNonRateMessages };
+}
+function recordMarkFileResults(paths, data, errors, classifiedErrors, rateLimit, result) {
+    const pendingPaths = [];
+    for (let index = 0; index < paths.length; index += 1) {
+        const path = paths[index];
+        if (data[`f${index}`] != null) {
+            result.markedPaths.push(path);
+            continue;
+        }
+        const messages = errorsForMarkFileAlias(errors, index);
+        const hasRateLimitError = classifiedErrors.aliasesWithRateLimitErrors.has(index);
+        const nonRateMessages = classifiedErrors.aliasesWithNonRateErrors.has(index)
+            ? messages.filter((message) => !isRateLimitMessage(message))
+            : classifiedErrors.unscopedNonRateMessages;
+        if (nonRateMessages.length > 0) {
+            for (const message of nonRateMessages)
+                result.errors.push(`${path}: ${message}`);
+        }
+        else if (!rateLimit) {
+            result.errors.push(`${path}: ${messages[0] ?? "mark returned null"}`);
+        }
+        if (rateLimit && (hasRateLimitError || nonRateMessages.length === 0))
+            pendingPaths.push(path);
+    }
+    return pendingPaths;
+}
+function completeMarkFilesChunk(rateLimit, pendingPaths, result) {
+    if (!rateLimit)
+        return null;
+    result.errors.push(`rate limit: ${rateLimit.message}`);
+    result.rateLimit = rateLimit;
+    return pendingPaths;
+}
+function recordMarkFilesTransportError(error, paths, result) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stop = rateLimitFromError(error, message);
+    if (stop) {
+        result.errors.push(`rate limit: ${stop.message}`);
+        result.rateLimit = stop;
+        return paths;
+    }
+    for (const path of paths)
+        result.errors.push(`${path}: ${message}`);
+    return null;
+}
+function buildMarkFilesMutation(pullRequestId, paths) {
+    const operations = paths.map((path, index) => `  f${index}: markFileAsViewed(input: { pullRequestId: ${JSON.stringify(pullRequestId)}, path: ${JSON.stringify(path)} }) { clientMutationId }`);
+    return `mutation MarkFilesAsViewed {\n${operations.join("\n")}\n}`;
+}
+function markFileErrorAliasIndex(error) {
+    if (!Array.isArray(error.path))
+        return undefined;
+    const alias = error.path.find((part) => typeof part === "string" && /^f\d+$/.test(part));
+    if (typeof alias !== "string")
+        return undefined;
+    const index = Number.parseInt(alias.slice(1), 10);
+    return Number.isNaN(index) ? undefined : index;
+}
+function errorsForMarkFileAlias(errors, index) {
+    return errors
+        .filter((error) => markFileErrorAliasIndex(error) === index)
+        .map((error) => error.message);
+}
 async function fetchPullRequestFiles(pr, repo) {
     const first = await graphql(FILES_QUERY, {
         owner: repo.owner,

package/bin/commands/poll.mjs

@@ -99,10 +99,7 @@ async function runPollCore(opts) {
             pendingQuotaWarning !== undefined &&
             !(lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) &&
             !(debounceUntil !== null && !pastDebounce)) {
-            const terminalOrHandoff = ["cancel", "escalate"].includes(lastResult.action) ||
-                (lastResult.action === "fix_code" &&
-                    lastResult.fix.instructions.some((instruction) => /stop polling|human direction/i.test(instruction)));
-            if (terminalOrHandoff) {
+            if (["cancel", "escalate"].includes(lastResult.action)) {
                 const { quotaWarning: _quotaWarning, ...withoutQuotaWarning } = lastResult;
                 lastResult = withoutQuotaWarning;
             }

package/bin/commands/resolve-mutate.mjs

@@ -27,45 +27,24 @@ 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 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)));
+    // Iterate uses viewer capability fields while deciding which commands to
+    // print. Once a caller explicitly runs apply, GitHub's mutation response is
+    // authoritative and this path must not second-guess that intent.
+    const requestedReplyIds = new Set(opts.replyThreadIds ?? []);
     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 resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id) || allowedViewerHumanResolveIds.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 replyThreadIds = opts.replyThreadIds?.filter((id) => humanThreadIds.has(id));
     const skippedNonHumanReplies = (opts.replyThreadIds ?? []).filter((id) => !humanThreadIds.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 minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id));
     const skippedHumanMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => humanCommentIds.has(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 dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && data.changesRequestedReviews.some((review) => review.id === id));
     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 ||
+    const skippedIneligibleDismissals = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && !dismissReviewIds.includes(id));
+    const hasMutation = resolveThreadIds.length > 0 ||
         (replyThreadIds?.length ?? 0) > 0 ||
         minimizeCommentIds.length > 0 ||
         dismissReviewIds.length > 0;
@@ -75,7 +54,7 @@ export async function runResolveMutate(opts) {
         minimizeCommentIds,
         dismissReviewIds,
         dismissMessage: opts.dismissMessage,
-        requireSha: hasAuthorizedMutation ? opts.requireSha : undefined,
+        requireSha: hasMutation ? opts.requireSha : undefined,
     });
     if (skippedHumanResolves.length > 0)
         result.skippedHumanResolves = skippedHumanResolves;
@@ -85,14 +64,12 @@ 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 (skippedIneligibleDismissals.length > 0) {
+        result.skippedDismissals = [
+            ...(result.skippedDismissals ?? []),
+            ...skippedIneligibleDismissals,
+        ];
+    }
     if (opts.dismissMessage) {
         const markedMessage = addPrShepherdMarker(opts.dismissMessage);
         await Promise.all(result.repliedThreads.map((id) => {

package/bin/comments/resolve.d.mts

@@ -12,9 +12,13 @@ export interface ResolveResult {
     skippedHumanMinimizes?: string[];
     skippedHumanDismissals?: string[];
     skippedNonHumanReplies?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedReplies?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedResolves?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedMinimizes?: string[];
+    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedDismissals?: string[];
     rateLimit?: ResolveRateLimitStop;
     unrepliedThreads?: string[];

package/bin/comments/resolve.mjs

@@ -24,6 +24,12 @@ function isCommentedDismissError(message) {
 function dismissReviewNonDismissibleMessage(id) {
     return `Not dismissed: ${id} is a COMMENTED review. Use --minimize-comment-ids instead; --dismiss-review-ids is only for CHANGES_REQUESTED reviews.`;
 }
+function mutationErrorMessage(errors, alias) {
+    const messages = errors
+        .filter((error) => Array.isArray(error.path) && error.path.includes(alias))
+        .map((error) => error.message);
+    return messages.length > 0 ? messages.join("; ") : undefined;
+}
 export async function applyResolveOptions(pr, repo, opts) {
     const resolveThreadIds = dedupeIds(opts.resolveThreadIds ?? []);
     const replyThreadIds = dedupeIds(opts.replyThreadIds ?? []);
@@ -168,21 +174,21 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
         if (p?.comment?.id)
             result.repliedThreads.push(id);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${id}: reply returned null or comment not created`);
+            result.errors.push(`${id}: ${mutationErrorMessage(graphQlErrors, `p${i}`) ?? "reply returned null or comment not created"}`);
     }
     for (let i = 0; i < resolveIds.length; i++) {
         const r = data[`r${i}`];
         if (r?.thread?.isResolved === true)
             result.resolvedThreads.push(resolveIds[i]);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${resolveIds[i]}: resolve returned null or thread not resolved`);
+            result.errors.push(`${resolveIds[i]}: ${mutationErrorMessage(graphQlErrors, `r${i}`) ?? "resolve returned null or thread not resolved"}`);
     }
     for (let i = 0; i < minimizeIds.length; i++) {
         const m = data[`m${i}`];
         if (m?.minimizedComment?.isMinimized === true)
             result.minimizedComments.push(minimizeIds[i]);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${minimizeIds[i]}: minimize returned null or comment not minimized`);
+            result.errors.push(`${minimizeIds[i]}: ${mutationErrorMessage(graphQlErrors, `m${i}`) ?? "minimize returned null or comment not minimized"}`);
     }
     const singleDismiss = dismissIds.length === 1;
     const commentedDismissErrorIndexes = new Set();
@@ -204,7 +210,7 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
         else if (!suppressCurrentChunkErrors)
             result.errors.push(commentedDismissErrorIndexes.has(i) || (singleDismiss && hasUnmappedCommentedDismissError)
                 ? dismissReviewNonDismissibleMessage(dismissIds[i])
-                : `${dismissIds[i]}: dismiss returned null`);
+                : `${dismissIds[i]}: ${mutationErrorMessage(graphQlErrors, `d${i}`) ?? "dismiss returned null"}`);
     }
     if (rateLimitStop) {
         result.errors.push(`rate limit: ${rateLimitStop.message}`);

package/bin/comments/review-visibility.d.mts

@@ -24,5 +24,5 @@ export declare function classifyReviewsForDisplay(reviews: Review[], seenMap: Ma
  *
  * Human-authored CR reviews continue to flow through the standard seen-gate.
  */
-export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames): ReviewVisibility;
+export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames, repeatBotReviews?: boolean): ReviewVisibility;
 export {};

package/bin/comments/review-visibility.mjs

@@ -31,7 +31,7 @@ export function classifyReviewsForDisplay(reviews, seenMap) {
  *
  * Human-authored CR reviews continue to flow through the standard seen-gate.
  */
-export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames) {
+export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames, repeatBotReviews = true) {
     const visible = [];
     const toMarkSeen = [];
     for (const review of reviews) {
@@ -39,7 +39,8 @@ export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botU
         const cls = classifyItem(review.id, review.body, seenMap);
         if (isBot) {
             if (cls === "unchanged") {
-                visible.push({ ...review, staleBotCr: true });
+                if (repeatBotReviews)
+                    visible.push({ ...review, staleBotCr: true });
             }
             else if (cls === "edited") {
                 visible.push({ ...review, edited: true });

package/bin/comments/thread-visibility.d.mts

@@ -7,5 +7,5 @@ interface ThreadVisibility {
     firstLookThreads: FirstLookThread[];
     toMarkSeen: ReviewThread[];
 }
-export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames): ThreadVisibility;
+export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames, repeatableThreadIds?: ReadonlySet<string>): ThreadVisibility;
 export {};

package/bin/comments/thread-visibility.mjs

@@ -19,14 +19,15 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
         return null;
     return { ...visible, firstLookStatus };
 }
-export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set()) {
+export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds) {
+    const shouldRepeat = (thread) => repeatableThreadIds?.has(thread.id) ?? true;
     const unresolvedThreads = threads.filter((t) => !t.isResolved);
     const activeThreads = unresolvedThreads
         .filter((t) => !t.isOutdated && !t.isMinimized)
         .flatMap((t) => {
         if (threadEndedByShepherd(t))
             return [];
-        if (isConfiguredBotAuthor(t, botUsernames))
+        if (isConfiguredBotAuthor(t, botUsernames) && shouldRepeat(t))
             return [t];
         const visible = classifyVisibleThread(t, seenMap);
         return visible ? [visible] : [];
@@ -40,7 +41,12 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
         }
         return t.isOutdated || t.isMinimized;
     })
-        .map((t) => classifyVisibleThread(t, seenMap) ?? t);
+        .flatMap((t) => {
+        const visible = classifyVisibleThread(t, seenMap);
+        if (visible)
+            return [visible];
+        return shouldRepeat(t) ? [t] : [];
+    });
     const firstLookThreads = [
         ...threads.flatMap((t) => {
             if (!t.isOutdated)

package/bin/github/client.d.mts

@@ -30,7 +30,6 @@ export declare function getPrHeadSha(pr: number, owner: string, name: string): P
 export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
     nodeId: string;
     body: string;
-    viewerCanUpdate?: boolean;
 }>;
 /** Overwrites the PR body. */
 export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;
@@ -38,7 +37,7 @@ export declare function updatePullRequestBody(pullRequestId: string, body: strin
  * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
  * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
- * READY handoff. The same response carries state so a concurrent merge or
+ * READY state. The same response carries state so a concurrent merge or
  * close can supersede the earlier GraphQL snapshot without another request.
  */
 export declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{

package/bin/github/client.mjs

@@ -80,9 +80,6 @@ export async function getPullRequestBody(pr, owner, name) {
     return {
         nodeId: pullRequest.id,
         body: pullRequest.body ?? "",
-        ...(pullRequest.viewerCanUpdate !== undefined && {
-            viewerCanUpdate: pullRequest.viewerCanUpdate,
-        }),
     };
 }
 /** Overwrites the PR body. */
@@ -93,7 +90,7 @@ export async function updatePullRequestBody(pullRequestId, body) {
  * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
  * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
- * READY handoff. The same response carries state so a concurrent merge or
+ * READY state. The same response carries state so a concurrent merge or
  * close can supersede the earlier GraphQL snapshot without another request.
  */
 export async function getMergeableState(pr, owner, repo) {

package/bin/github/gql/get-pr-body.gql

@@ -11,7 +11,6 @@ query GetPrBody($owner: String!, $repo: String!, $pr: Int!) {
     pullRequest(number: $pr) {
       id
       body
-      viewerCanUpdate
     }
   }
 }

package/bin/mcp/server.mjs

@@ -41,7 +41,7 @@ const reviewMutationsOperationSchema = z.object({
 const markFilesViewedOperationSchema = z.object({
     type: z.literal("mark_files_viewed"),
     files: z.array(z.string().min(1)).optional(),
-    tests: z.boolean().optional().describe("Select changed test files; no mutation occurs."),
+    tests: z.boolean().optional().describe("Select changed test files to mark as viewed."),
     matchPatterns: z.array(z.string().min(1)).optional(),
 });
 const appendJournalOperationSchema = z.object({
@@ -90,7 +90,7 @@ export function createPrShepherdMcpServer(options = {}) {
         },
     }, async (input) => runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), formatIterateResult));
     server.registerTool("apply", {
-        description: "Apply ordered authorized review and journal operations, or run selection-only file-view diagnostics, after prevalidation.",
+        description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
         inputSchema: applyInputSchema,
         annotations: {
             readOnlyHint: false,

package/bin/pr-reference.d.mts

@@ -15,6 +15,6 @@ export declare function parsePrReference(pr: number | string | undefined): Parse
 export declare function parseCliPrReference(value: string): ParsedPrReference | null;
 /** Converts a validated parsed reference into the command-layer target shape. */
 export declare function resolveParsedPrTarget(parsed: ParsedPrReference): ResolvedPrTarget;
-/** Canonical collision-safe PR reference for generated commands and handoffs. */
+/** Canonical collision-safe PR reference for generated commands and escalation messages. */
 export declare function formatPrUrl(repository: string, prNumber: number): string;
 export declare function isRepositoryQualifiedPrReference(pr: unknown): pr is string;