pr-shepherd 0.56.6 → 0.57.0

package/bin/comments/resolve.mjs

@@ -1,9 +1,18 @@
 /* eslint-disable max-lines */
 import { graphqlWithRateLimit } from "../github/client.mjs";
 import { addPrShepherdMarker } from "./marker.mjs";
+import { findExistingReplies } from "./existing-reply-scan.mjs";
 import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "./rate-limit.mjs";
 import { setPendingOps } from "./pending-ops.mjs";
 import { waitForSha } from "./sha-poll.mjs";
+import { githubOperation, getGithubTransport } from "../github/transport.mjs";
+import { resolveGraphqlThreadId } from "../github/rest-identities.mjs";
+import { applyRestReviewChunk, isAmbiguousMutationError } from "./rest-review-mutations.mjs";
+import { assertReplyOutcomeKnown, rememberUncertainReplies, trackAdoptedReplyThreads, } from "./uncertain-replies.mjs";
+import { isRestSessionRefusal } from "../github/rest-session-refusal.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { readReplyRecoveryEvidence } from "../github/reply-recovery-read.mjs";
+import { GitHubRequestError, isRetryableGraphQlInternal, } from "../github/errors.mjs";
 const COMMENTED_DISMISS_ERROR_PATTERNS = [
     /can\s*not\s+dismiss[\s\S]*?commented pull request review/i,
 ];
@@ -30,7 +39,15 @@ function mutationErrorMessage(errors, alias) {
         .map((error) => error.message);
     return messages.length > 0 ? messages.join("; ") : undefined;
 }
-export async function applyResolveOptions(pr, repo, opts) {
+function uncertainReplyIds(ids, confirmed, errors) {
+    return ids.filter((id, index) => {
+        if (confirmed.includes(id))
+            return false;
+        const applicable = errors.filter((error) => error.path === undefined || (Array.isArray(error.path) && error.path[0] === `p${index}`));
+        return applicable.length === 0 || isRetryableGraphQlInternal(applicable);
+    });
+}
+export async function applyResolveOptions(pr, repo, opts, preflight) {
     const resolveThreadIds = dedupeIds(opts.resolveThreadIds ?? []);
     const replyThreadIds = dedupeIds(opts.replyThreadIds ?? []);
     const minimizeCommentIds = opts.minimizeCommentIds ?? [];
@@ -45,12 +62,30 @@ export async function applyResolveOptions(pr, repo, opts) {
     if ((dismissReviewIds.length > 0 || replyThreadIds.length > 0) && !opts.dismissMessage) {
         throw new Error("--message is required when replying to threads or dismissing reviews");
     }
-    if (opts.requireSha) {
+    // A preflight that already saw the required head stands in for the first poll; its
+    // recovery evidence is used only when no poll wait separated it from the mutation.
+    const headConfirmed = !opts.requireSha || preflight?.headSha === opts.requireSha;
+    const preloadedEvidence = headConfirmed ? preflight?.evidence : undefined;
+    if (opts.requireSha && !headConfirmed) {
         // Verify GitHub received the commit before resolving — prevents auto-merge
         // before reviewers see the fix.
         await waitForSha(pr, repo, opts.requireSha);
     }
-    await bulkApply(replyThreadIds, resolveThreadIds, minimizeCommentIds, dismissReviewIds, opts.dismissMessage ?? "", result);
+    const known = await assertReplyOutcomeKnown({ repo, pr }, replyThreadIds, opts.dismissMessage ?? "");
+    const adopted = [
+        ...known,
+        ...(opts.adoptExistingReplies
+            ? await findExistingReplies({ repo, pr }, replyThreadIds.filter((id) => !known.includes(id)), opts.dismissMessage ?? "", preloadedEvidence)
+            : []),
+    ];
+    result.repliedThreads.push(...adopted);
+    trackAdoptedReplyThreads(result, adopted);
+    await bulkApply(replyThreadIds.filter((id) => !adopted.includes(id)), resolveThreadIds, minimizeCommentIds, dismissReviewIds, opts.dismissMessage ?? "", result, { repo, pr }, preloadedEvidence);
+    if (result.sessionRefusal)
+        result.instructions = [
+            "Restore GitHub access for this session using the proxy instructions above.",
+            "Retry only the pending IDs listed above.",
+        ];
     return result;
 }
 /** @deprecated Compatibility alias; use `autoResolveThreads`. */
@@ -68,6 +103,8 @@ export async function autoResolveThreads(threadIds) {
         errors: [],
     };
     await bulkApply([], threadIds, [], [], "", result);
+    if (result.sessionRefusal)
+        throw new ShepherdError(result.sessionRefusal, EXIT.NOPERM);
     return { resolved: result.resolvedThreads, errors: result.errors };
 }
 export async function autoMinimizeComments(minimizeIds) {
@@ -81,6 +118,8 @@ export async function autoMinimizeComments(minimizeIds) {
         errors: [],
     };
     await bulkApply([], [], minimizeIds, [], "", result);
+    if (result.sessionRefusal)
+        throw new ShepherdError(result.sessionRefusal, EXIT.NOPERM);
     return { minimized: result.minimizedComments, errors: result.errors };
 }
 // Keep mutation batches small so rate-limit stops leave a precise pending list.
@@ -102,7 +141,7 @@ function buildBulkMutation(replyIds, resolveIds, minimizeIds, dismissIds, dismis
     }
     return `mutation BulkApply {\n${ops.join("\n")}\n}`;
 }
-async function bulkApply(replyIds, resolveIds, minimizeIds, dismissIds, dismissMessage, result) {
+async function bulkApply(replyIds, resolveIds, minimizeIds, dismissIds, dismissMessage, result, context, firstChunkEvidence) {
     const allOps = [
         ...replyIds.map((id) => ({ kind: "p", id })),
         ...resolveIds.map((id) => ({ kind: "r", id })),
@@ -112,34 +151,76 @@ async function bulkApply(replyIds, resolveIds, minimizeIds, dismissIds, dismissM
     for (let i = 0; i < allOps.length; i += BULK_CHUNK_SIZE) {
         const chunk = allOps.slice(i, i + BULK_CHUNK_SIZE);
         // eslint-disable-next-line no-await-in-loop
-        const stopped = await bulkApplyChunk(chunk.filter((o) => o.kind === "r").map((o) => o.id), chunk.filter((o) => o.kind === "p").map((o) => o.id), chunk.filter((o) => o.kind === "m").map((o) => o.id), chunk.filter((o) => o.kind === "d").map((o) => o.id), dismissMessage, result, i + BULK_CHUNK_SIZE < allOps.length);
+        const stopped = await bulkApplyChunk(chunk.filter((o) => o.kind === "r").map((o) => o.id), chunk.filter((o) => o.kind === "p").map((o) => o.id), chunk.filter((o) => o.kind === "m").map((o) => o.id), chunk.filter((o) => o.kind === "d").map((o) => o.id), dismissMessage, result, i + BULK_CHUNK_SIZE < allOps.length, context, i === 0 ? firstChunkEvidence : undefined);
         if (stopped) {
             setPendingOps(result, allOps.slice(i));
             return;
         }
     }
 }
-async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dismissMessage, result, hasPendingAfter) {
-    const doc = buildBulkMutation(replyIds, resolveIds, minimizeIds, dismissIds, dismissMessage);
+async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dismissMessage, result, hasPendingAfter, context, preloadedEvidence) {
     let data = {};
     let graphQlErrors = [];
     let rateLimitStop;
     let suppressCurrentChunkErrors = false;
+    let restStopped = false;
+    let graphqlMutationAttempted = false;
+    let replyEvidence = new Map();
+    if (context && replyIds.length && getGithubTransport() === "graphql") {
+        // Evidence is all-or-nothing per batch, as the standalone read is.
+        if (replyIds.every((id) => preloadedEvidence?.has(id)))
+            replyEvidence = new Map(replyIds.map((id) => [id, preloadedEvidence.get(id)]));
+        else
+            try {
+                replyEvidence = await readReplyRecoveryEvidence(context.repo, context.pr, replyIds);
+            }
+            catch {
+                /* Preserve explicit mutation eligibility when recovery evidence is unavailable. */
+            }
+    }
     try {
-        const resp = await graphqlWithRateLimit(doc, {}, {
-            allowPartialData: true,
-        });
+        const resp = await githubOperation("BulkApply", async () => {
+            const [graphqlReplies, graphqlResolves] = await Promise.all([
+                Promise.all(replyIds.map(resolveGraphqlThreadId)),
+                Promise.all(resolveIds.map(resolveGraphqlThreadId)),
+            ]);
+            graphqlMutationAttempted = true;
+            return graphqlWithRateLimit(buildBulkMutation(graphqlReplies, graphqlResolves, minimizeIds, dismissIds, dismissMessage), {}, { allowPartialData: true });
+        }, () => applyRestReviewChunk({
+            ...context,
+            replyIds,
+            resolveIds,
+            minimizeIds,
+            dismissIds,
+            message: dismissMessage,
+        }), { mutation: true });
+        if ("restStopped" in resp)
+            restStopped = resp.restStopped === true;
+        if ("sessionRefusal" in resp && typeof resp.sessionRefusal === "string")
+            result.sessionRefusal = resp.sessionRefusal;
         data = resp.data;
         graphQlErrors = (resp.errors ?? []);
         const graphQlErrorMessages = graphQlErrors.map((e) => e.message);
-        suppressCurrentChunkErrors = graphQlErrorMessages.some(isRateLimitMessage);
+        suppressCurrentChunkErrors = restStopped || graphQlErrorMessages.some(isRateLimitMessage);
         rateLimitStop = rateLimitFromGraphQlResult(graphQlErrorMessages, {
             rateLimit: resp.rateLimit,
-            retryAfterSeconds: resp.retryAfterSeconds,
+            retryAfterSeconds: "retryAfterSeconds" in resp ? resp.retryAfterSeconds : undefined,
             stopOnZeroRemaining: hasPendingAfter,
         });
     }
     catch (err) {
+        if (isRestSessionRefusal(err))
+            throw err;
+        const uncertainIds = err instanceof GitHubRequestError && err.status === 200
+            ? uncertainReplyIds(replyIds, [], err.graphqlErrors ?? [])
+            : replyIds;
+        const ambiguous = isAmbiguousMutationError(err) ||
+            (graphqlMutationAttempted &&
+                err instanceof GitHubRequestError &&
+                (isRetryableGraphQlInternal(err.graphqlErrors) ||
+                    (err.status === 200 && (!err.graphqlErrors?.length || uncertainIds.length > 0))));
+        if (context && graphqlMutationAttempted && ambiguous)
+            await rememberUncertainReplies(context, uncertainIds, dismissMessage, replyEvidence);
         const msg = err instanceof Error ? err.message : String(err);
         const stop = rateLimitFromError(err, msg);
         if (stop) {
@@ -155,7 +236,7 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
             result.errors.push(`${id}: ${msg}`);
         for (const id of dismissIds)
             result.errors.push(`${id}: ${msg}`);
-        return false;
+        return ambiguous;
     }
     for (let i = 0; i < replyIds.length; i++) {
         const id = replyIds[i];
@@ -164,21 +245,21 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
         const p = data[`p${i}`];
         if (p?.comment?.id)
             result.repliedThreads.push(id);
-        else if (!suppressCurrentChunkErrors)
+        else if (!suppressCurrentChunkErrors || mutationErrorMessage(graphQlErrors, `p${i}`))
             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)
+        else if (!suppressCurrentChunkErrors || mutationErrorMessage(graphQlErrors, `r${i}`))
             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)
+        else if (!suppressCurrentChunkErrors || mutationErrorMessage(graphQlErrors, `m${i}`))
             result.errors.push(`${minimizeIds[i]}: ${mutationErrorMessage(graphQlErrors, `m${i}`) ?? "minimize returned null or comment not minimized"}`);
     }
     const singleDismiss = dismissIds.length === 1;
@@ -198,17 +279,26 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
         const d = data[`d${i}`];
         if (d?.pullRequestReview != null)
             result.dismissedReviews.push(dismissIds[i]);
-        else if (!suppressCurrentChunkErrors)
+        else if (!suppressCurrentChunkErrors || mutationErrorMessage(graphQlErrors, `d${i}`))
             result.errors.push(commentedDismissErrorIndexes.has(i) || (singleDismiss && hasUnmappedCommentedDismissError)
                 ? dismissReviewNonDismissibleMessage(dismissIds[i])
                 : `${dismissIds[i]}: ${mutationErrorMessage(graphQlErrors, `d${i}`) ?? "dismiss returned null"}`);
     }
+    const internalFailure = graphqlMutationAttempted && isRetryableGraphQlInternal(graphQlErrors);
+    const uncertainIds = graphqlMutationAttempted
+        ? uncertainReplyIds(replyIds, result.repliedThreads, graphQlErrors)
+        : [];
+    if (context && uncertainIds.length) {
+        await rememberUncertainReplies(context, uncertainIds, dismissMessage, replyEvidence);
+    }
     if (rateLimitStop) {
         result.errors.push(`rate limit: ${rateLimitStop.message}`);
         result.rateLimit = rateLimitStop;
         return true;
     }
-    return false;
+    if (result.sessionRefusal)
+        return true;
+    return restStopped || internalFailure || uncertainIds.length > 0;
 }
 function dismissErrorAliasIndex(error) {
     if (!Array.isArray(error.path))

package/bin/comments/rest-reply.d.mts

@@ -0,0 +1,9 @@
+import type { RateLimitInfo } from "../github/http-utils.mts";
+import type { RepoInfo } from "../github/client.mts";
+interface ReplyResult {
+    id: string;
+    rateLimit?: RateLimitInfo;
+}
+export declare function isAmbiguousMutationError(error: unknown): boolean;
+export declare function replyToThread(repo: RepoInfo, pr: number, root: string, body: string): Promise<ReplyResult>;
+export {};

package/bin/comments/rest-reply.mjs

@@ -0,0 +1,95 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "../state/base.mjs";
+import { rest, restWithRateLimit } from "../github/http.mjs";
+import { GitHubRequestError } from "../github/errors.mjs";
+import { isTransportError } from "../github/http-utils.mjs";
+import { readRestPages, restRepoPath } from "../github/rest-reader-core.mjs";
+import { isRestSessionRefusal } from "../github/rest-session-refusal.mjs";
+export function isAmbiguousMutationError(error) {
+    return isTransportError(error) || (error instanceof GitHubRequestError && error.status >= 500);
+}
+function replyPath(repo, pr, root, body) {
+    const hash = createHash("sha256").update(`${root}\n${body}`).digest("hex");
+    return resolvePrStatePath({ owner: repo.owner, repo: repo.name, pr }, "pending-replies", `${hash}.json`);
+}
+async function readComments(repo, pr) {
+    return readRestPages(`${restRepoPath(repo)}/pulls/${pr}/comments`);
+}
+async function findPendingReply(repo, pr, pending) {
+    if (!pending.viewer)
+        return undefined;
+    const existing = new Set(pending.beforeIds);
+    const response = await readComments(repo, pr);
+    const matches = response.nodes.filter((comment) => String(comment.in_reply_to_id) === pending.root &&
+        comment.body === pending.body &&
+        comment.user?.login === pending.viewer &&
+        !existing.has(comment.id));
+    return matches.length === 1
+        ? { id: String(matches[0].id), rateLimit: response.rateLimit }
+        : undefined;
+}
+export async function replyToThread(repo, pr, root, body) {
+    const path = replyPath(repo, pr, root, body);
+    let pending;
+    try {
+        pending = JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw new Error("Cannot read pending REST reply; cannot safely retry", { cause: error });
+    }
+    if (pending) {
+        if (pending.root !== root || pending.body !== body || !Array.isArray(pending.beforeIds))
+            throw new Error("Invalid pending REST reply; cannot safely retry");
+        const id = await findPendingReply(repo, pr, pending);
+        if (!id)
+            throw new Error("Previous reply outcome is uncertain; refresh the thread before retrying, no duplicate reply was sent");
+        await unlink(path);
+        return id;
+    }
+    // These reads provide the exact author and pre-write IDs needed after a lost response.
+    let viewer;
+    try {
+        viewer = (await rest("GET", "/user")).login;
+    }
+    catch (error) {
+        if (isRestSessionRefusal(error))
+            throw error;
+        if (!(error instanceof GitHubRequestError) || ![403, 404].includes(error.status))
+            throw error;
+    }
+    const comments = await readComments(repo, pr);
+    pending = {
+        root,
+        body,
+        ...(viewer && { viewer }),
+        beforeIds: comments.nodes.map((comment) => comment.id),
+    };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(pending), { flag: "wx" });
+    try {
+        const result = await restWithRateLimit("POST", `${restRepoPath(repo)}/pulls/${pr}/comments/${root}/replies`, { body });
+        if (!Number.isSafeInteger(result.data?.id) || result.data.id <= 0)
+            throw new Error("Reply returned no valid comment ID; outcome is uncertain");
+        await unlink(path);
+        return { id: String(result.data.id), rateLimit: result.rateLimit };
+    }
+    catch (error) {
+        if (isAmbiguousMutationError(error)) {
+            try {
+                const id = await findPendingReply(repo, pr, pending);
+                if (id) {
+                    await unlink(path);
+                    return id;
+                }
+            }
+            catch { }
+        }
+        else if (error instanceof GitHubRequestError && error.status >= 400 && error.status < 500) {
+            await unlink(path);
+        }
+        throw error;
+    }
+}

package/bin/comments/rest-review-mutations.d.mts

@@ -0,0 +1,22 @@
+import type { RepoInfo } from "../github/client.mts";
+import type { RateLimitInfo } from "../github/http-utils.mts";
+export declare function applyRestReviewChunk(input: {
+    repo?: RepoInfo;
+    pr?: number;
+    replyIds: string[];
+    resolveIds: string[];
+    minimizeIds: string[];
+    dismissIds: string[];
+    message: string;
+}): Promise<{
+    data: Record<string, unknown>;
+    errors: Array<{
+        message: string;
+        path: string[];
+    }>;
+    rateLimit?: RateLimitInfo;
+    retryAfterSeconds?: number;
+    restStopped?: true;
+    sessionRefusal?: string;
+}>;
+export { isAmbiguousMutationError } from "./rest-reply.mts";

package/bin/comments/rest-review-mutations.mjs

@@ -0,0 +1,125 @@
+import { replyToThread, isAmbiguousMutationError } from "./rest-reply.mjs";
+import { restWithRateLimit } from "../github/http.mjs";
+import { GitHubRequestError } from "../github/errors.mjs";
+import { isCcrTransport } from "../github/transport.mjs";
+import { UnsupportedRestOperationError } from "../github/unsupported-rest.mjs";
+import { resolveRestIdentity, resolveRestThreadRoot } from "../github/rest-identities.mjs";
+import { readRestPages, restRepoPath } from "../github/rest-reader-core.mjs";
+import { addPrShepherdMarker } from "./marker.mjs";
+import { rateLimitFromError } from "./rate-limit.mjs";
+import { markMutationDenied } from "../state/seen-comments.mjs";
+import { readRestFeedback } from "../github/rest-feedback-read.mjs";
+import { threadTranscriptBody } from "../threads/transcript.mjs";
+import { isRestSessionRefusal } from "../github/rest-session-refusal.mjs";
+async function reviewNumericId(repo, pr, id) {
+    if (/^[1-9][0-9]*$/.test(id))
+        return id;
+    try {
+        const entry = await resolveRestIdentity(id, "review");
+        if (entry.pr === pr &&
+            entry.repo.owner.toLowerCase() === repo.owner.toLowerCase() &&
+            entry.repo.name.toLowerCase() === repo.name.toLowerCase())
+            return entry.numericId;
+    }
+    catch { }
+    const reviews = (await readRestPages(`${restRepoPath(repo)}/pulls/${pr}/reviews`)).nodes;
+    const target = reviews.find((review) => review.node_id === id);
+    if (!target)
+        throw new Error(`Cannot address review ${id} through REST in ${repo.owner}/${repo.name}#${pr}`);
+    return String(target.id);
+}
+async function rememberDenied(input, id, kind) {
+    let key;
+    try {
+        const identity = input.repo && input.pr !== undefined ? undefined : await resolveRestIdentity(id);
+        const repo = input.repo ?? identity.repo;
+        const pr = input.pr ?? identity.pr;
+        key = { owner: repo.owner, repo: repo.name, pr };
+        const feedback = await readRestFeedback(pr, repo);
+        const root = kind === "dismiss" ? undefined : await resolveRestThreadRoot(repo, pr, id);
+        const body = kind === "dismiss"
+            ? feedback.reviews.find((review) => review.node_id === id || String(review.id) === id)?.body
+            : feedback.threads.find((thread) => thread.id === id || thread.id === `rest-thread-${root}`);
+        if (body !== undefined && body !== null)
+            await markMutationDenied(key, id, typeof body === "string" ? body : threadTranscriptBody(body));
+    }
+    catch {
+        // Generated mutations already surfaced this revision; a failed refresh must not retry it.
+        if (key)
+            await markMutationDenied(key, id);
+    }
+}
+export async function applyRestReviewChunk(input) {
+    const result = { data: {}, errors: [] };
+    const ops = [
+        ...input.replyIds.map((id, index) => ({ id, alias: `p${index}`, kind: "reply" })),
+        ...input.resolveIds.map((id, index) => ({ id, alias: `r${index}`, kind: "resolve" })),
+        ...input.minimizeIds.map((id, index) => ({ id, alias: `m${index}`, kind: "minimize" })),
+        ...input.dismissIds.map((id, index) => ({ id, alias: `d${index}`, kind: "dismiss" })),
+    ];
+    for (const op of ops) {
+        try {
+            if (op.kind === "minimize")
+                throw new UnsupportedRestOperationError("minimizeComment");
+            let repo = input.repo;
+            let pr = input.pr;
+            if (!repo || pr === undefined) {
+                const identity = await resolveRestIdentity(op.id, op.kind === "dismiss" ? "review" : "thread");
+                repo = identity.repo;
+                pr = identity.pr;
+            }
+            const prefix = `${restRepoPath(repo)}/pulls/${pr}`;
+            if (op.kind === "reply") {
+                const root = await resolveRestThreadRoot(repo, pr, op.id);
+                const response = await replyToThread(repo, pr, root, addPrShepherdMarker(input.message));
+                result.rateLimit = response.rateLimit;
+                result.data[op.alias] = { comment: { id: response.id } };
+            }
+            else if (op.kind === "resolve") {
+                if (!isCcrTransport())
+                    throw new UnsupportedRestOperationError("resolveReviewThread", "thread resolution requires the cloud CCR proxy");
+                const root = await resolveRestThreadRoot(repo, pr, op.id);
+                const response = await restWithRateLimit("POST", `${prefix}/ccr/comments/${root}/resolve`);
+                result.rateLimit = response.rateLimit;
+                if (response.data?.resolved !== true)
+                    throw new Error("CCR resolve did not confirm the thread was resolved");
+                result.data[op.alias] = { thread: { isResolved: true } };
+            }
+            else {
+                const review = await reviewNumericId(repo, pr, op.id);
+                const response = await restWithRateLimit("PUT", `${prefix}/reviews/${review}/dismissals`, { message: input.message });
+                result.rateLimit = response.rateLimit;
+                if (response.data?.state !== "DISMISSED")
+                    throw new Error("Review dismissal did not confirm DISMISSED state");
+                result.data[op.alias] = { pullRequestReview: { state: "DISMISSED" } };
+            }
+            if (result.rateLimit?.remaining === 0) {
+                result.errors.push({ message: "GitHub REST core rate limit remaining is 0", path: [] });
+                result.restStopped = true;
+                break;
+            }
+        }
+        catch (error) {
+            if (isRestSessionRefusal(error)) {
+                result.sessionRefusal = error.message;
+                result.restStopped = true;
+                break;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            result.errors.push({ message, path: [op.alias] });
+            const stop = rateLimitFromError(error, message);
+            if (!stop && error instanceof GitHubRequestError && [403, 404].includes(error.status))
+                await rememberDenied(input, op.id, op.kind);
+            if (error instanceof GitHubRequestError) {
+                result.rateLimit = error.rateLimit;
+                result.retryAfterSeconds = error.retryAfterSeconds;
+            }
+            if (stop || isAmbiguousMutationError(error) || message.includes("outcome is uncertain")) {
+                result.restStopped = true;
+                break;
+            }
+        }
+    }
+    return result;
+}
+export { isAmbiguousMutationError } from "./rest-reply.mjs";

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, repeatBotReviews?: boolean): ReviewVisibility;
+export declare function classifyChangesRequestedReviewsForDisplay(reviews: Review[], seenMap: Map<string, SeenMarker>, botUsernames: NormalizedBotUsernames, repeatBotReviews?: boolean, deniedDismissalIds?: ReadonlySet<string>): 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, repeatBotReviews = true) {
+export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botUsernames, repeatBotReviews = true, deniedDismissalIds = new Set()) {
     const visible = [];
     const toMarkSeen = [];
     for (const review of reviews) {
@@ -39,8 +39,9 @@ export function classifyChangesRequestedReviewsForDisplay(reviews, seenMap, botU
         const cls = classifyItem(review.id, review.body, seenMap);
         if (isBot) {
             if (cls === "unchanged") {
-                if (repeatBotReviews)
+                if (repeatBotReviews && !deniedDismissalIds.has(review.id)) {
                     visible.push({ ...review, staleBotCr: true });
+                }
             }
             else if (cls === "edited") {
                 visible.push({ ...review, edited: true });

package/bin/comments/sha-poll.mjs

@@ -3,11 +3,12 @@ import { loadConfig } from "../config/load.mjs";
 import { sleep } from "../util/sleep.mjs";
 export async function waitForSha(pr, repo, expectedSha) {
     const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
+    let lastSha;
     for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
         try {
             // eslint-disable-next-line no-await-in-loop
-            const currentSha = await getPrHeadSha(pr, repo.owner, repo.name);
-            if (currentSha === expectedSha)
+            lastSha = await getPrHeadSha(pr, repo.owner, repo.name);
+            if (lastSha === expectedSha)
                 return;
         }
         catch (err) {
@@ -19,5 +20,8 @@ export async function waitForSha(pr, repo, expectedSha) {
             await sleep(SHA_POLL_INTERVAL_MS);
         }
     }
-    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
+    // Iterate prints a `--require-sha` that reads the current checkout's HEAD. Name that cause,
+    // so a run from another checkout can recover from this error alone.
+    const current = lastSha ? ` (currently ${lastSha})` : "";
+    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly. If this command ran outside the PR head checkout, rerun it with \`--require-sha\` set to the PR head SHA you pushed${current}.`);
 }

package/bin/comments/thread-visibility.mjs

@@ -23,9 +23,10 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
 export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds, resolveOtherHumanThreads = "none") {
     const shouldRepeat = (thread) => repeatableThreadIds?.has(thread.id) ?? true;
     const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
-    const unresolvedThreads = threads.filter((t) => !t.isResolved);
+    const unknownStatusThreads = threads.filter((thread) => thread.isResolved === undefined || thread.isOutdated === undefined);
+    const unresolvedThreads = threads.filter((thread) => thread.isResolved === false && thread.isOutdated !== undefined);
     const activeThreads = unresolvedThreads
-        .filter((t) => !t.isOutdated && !t.isMinimized)
+        .filter((t) => t.isOutdated === false && t.isMinimized !== true)
         .flatMap((t) => {
         if (threadEndedByShepherd(t))
             return [];
@@ -56,23 +57,27 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
     });
     const firstLookThreads = [
         ...threads.flatMap((t) => {
-            if (!t.isOutdated)
+            if (t.isOutdated !== true || t.isResolved === undefined)
                 return [];
             const visible = classifyFirstLookThread(t, seenMap, "outdated");
             return visible ? [visible] : [];
         }),
         ...threads.flatMap((t) => {
-            if (!t.isResolved || t.isOutdated)
+            if (t.isResolved !== true || t.isOutdated !== false)
                 return [];
             const visible = classifyFirstLookThread(t, seenMap, "resolved");
             return visible ? [visible] : [];
         }),
         ...threads.flatMap((t) => {
-            if (!t.isMinimized || t.isResolved || t.isOutdated)
+            if (!t.isMinimized || t.isResolved !== false || t.isOutdated !== false)
                 return [];
             const visible = classifyFirstLookThread(t, seenMap, "minimized");
             return visible ? [visible] : [];
         }),
+        ...unknownStatusThreads.flatMap((thread) => {
+            const visible = classifyFirstLookThread(thread, seenMap, "unknown");
+            return visible ? [visible] : [];
+        }),
     ];
     const seenMarkerIds = new Set();
     const toMarkSeen = [...activeThreads, ...resolutionOnlyThreads, ...firstLookThreads].filter((thread) => {

package/bin/comments/uncertain-replies.d.mts

@@ -0,0 +1,11 @@
+import type { RepoInfo } from "../github/client.mts";
+import { type ReplyEvidence } from "../github/reply-recovery-read.mts";
+interface ReplyContext {
+    repo: RepoInfo;
+    pr: number;
+}
+export declare function trackAdoptedReplyThreads(result: object, ids: readonly string[]): void;
+export declare function adoptedReplyThreads(result: object): readonly string[];
+export declare function assertReplyOutcomeKnown(context: ReplyContext, ids: string[], message: string): Promise<string[]>;
+export declare function rememberUncertainReplies(context: ReplyContext, ids: string[], message: string, evidence?: Map<string, ReplyEvidence>): Promise<void>;
+export {};