pr-shepherd 0.56.5 → 0.57.0

package/bin/commands/stack-work.mjs

@@ -1,3 +1,5 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
 /**
  * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
  * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
@@ -30,9 +32,39 @@ export function splitStackWork(candidates, staleChildren) {
  */
 export function appendMarkReadyInstructions(instructions, layers) {
     for (const item of layers) {
+        if (!item.owned) {
+            instructions.push(`${instructions.length + 1}. PR #${item.pr} is not owned. Leave its draft state unchanged.`);
+            continue;
+        }
+        if (item.transport === "rest") {
+            const command = buildPrShepherdCommand([
+                "iterate",
+                formatPrUrl(item.repo, item.pr),
+                "--transport",
+                "rest",
+            ]).text;
+            instructions.push(`${instructions.length + 1}. Run \`${item.pollCommand}\` first for PR #${item.pr}. If it returns \`[WAIT]\` saying the draft is held only because automatic mark-ready is disabled, run \`${command}\` to authorize the CCR ready transition; otherwise follow the probe's instructions.`);
+            continue;
+        }
         instructions.push(`${instructions.length + 1}. Automatic mark-ready is disabled, so marking PR #${item.pr} ready for review is your step. Run \`${item.pollCommand}\` first. If it returns \`[WAIT]\` saying PR #${item.pr} stays in draft because ${AUTO_MARK_READY_DISABLED_HOLD}, run \`gh pr ready ${item.pr} -R ${item.repo}\`; otherwise complete its instructions and leave PR #${item.pr} in draft this round.`);
     }
 }
 function isProbed(item) {
     return item.pollProbe === true && item.pollCommand !== undefined;
 }
+/**
+ * Work exists, but every routed layer belongs to another author: rerunning the stack selector
+ * cannot change anything, so the caller reports the overview and stops instead.
+ */
+function onlyUnownedWork(layers) {
+    return layers.length > 0 && layers.every((item) => !item.owned);
+}
+/**
+ * The closing step after routed sessions: rerun the selector, or stop when nothing is owned.
+ * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
+ */
+export function appendStackRerunInstruction(instructions, layers, rerun) {
+    const stop = onlyUnownedWork(layers);
+    instructions.push(`${instructions.length + 1}. ${stop ? "No owned layer needs a session. Report this overview and stop." : rerun}`);
+    return stop ? "escalate" : "shepherd";
+}

package/bin/comments/existing-reply-scan.d.mts

@@ -0,0 +1,17 @@
+import type { RepoInfo } from "../github/client.mts";
+import { type ReplyEvidence } from "../github/reply-recovery-read.mts";
+/**
+ * Threads whose last comment is already this exact Shepherd reply from the authenticated viewer.
+ *
+ * A cloud session can lose its state directory between ticks, taking the uncertain-reply
+ * records with it. With no local record to consult, GitHub is the only evidence of whether a
+ * reply already landed, so the `apply review` commands Shepherd generates in durable-state
+ * sessions opt in (`--adopt-existing-replies`) to checking it before posting. Direct apply
+ * requests never run this scan. A failed read never blocks the reply: it only means this
+ * safeguard had nothing to say. A batch fully covered by `preloaded` evidence (the
+ * apply-review preflight, read with no wait since) skips its read.
+ */
+export declare function findExistingReplies(context: {
+    repo: RepoInfo;
+    pr: number;
+}, ids: readonly string[], message: string, preloaded?: Map<string, ReplyEvidence>): Promise<string[]>;

package/bin/comments/existing-reply-scan.mjs

@@ -0,0 +1,41 @@
+import { readReplyRecoveryEvidence } from "../github/reply-recovery-read.mjs";
+import { addPrShepherdMarker } from "./marker.mjs";
+const BATCH = 10;
+/**
+ * Threads whose last comment is already this exact Shepherd reply from the authenticated viewer.
+ *
+ * A cloud session can lose its state directory between ticks, taking the uncertain-reply
+ * records with it. With no local record to consult, GitHub is the only evidence of whether a
+ * reply already landed, so the `apply review` commands Shepherd generates in durable-state
+ * sessions opt in (`--adopt-existing-replies`) to checking it before posting. Direct apply
+ * requests never run this scan. A failed read never blocks the reply: it only means this
+ * safeguard had nothing to say. A batch fully covered by `preloaded` evidence (the
+ * apply-review preflight, read with no wait since) skips its read.
+ */
+export async function findExistingReplies(context, ids, message, preloaded) {
+    if (ids.length === 0)
+        return [];
+    const marked = addPrShepherdMarker(message);
+    const found = [];
+    for (let offset = 0; offset < ids.length; offset += BATCH) {
+        const batch = ids.slice(offset, offset + BATCH);
+        try {
+            const evidence = batch.every((id) => preloaded?.has(id))
+                ? preloaded
+                : await readReplyRecoveryEvidence(context.repo, context.pr, batch);
+            for (const id of batch) {
+                const item = evidence.get(id);
+                const last = item?.comments.at(-1);
+                if (item &&
+                    last?.body === marked &&
+                    last.author?.toLowerCase() === item.viewer.toLowerCase()) {
+                    found.push(id);
+                }
+            }
+        }
+        catch {
+            /* Evidence is advisory here; the normal reply path still runs. */
+        }
+    }
+    return found;
+}

package/bin/comments/rate-limit.mjs

@@ -17,7 +17,7 @@ export function rateLimitFromGraphQlResult(messages, meta) {
     if (message)
         return buildRateLimitStop(message, meta);
     if (meta.stopOnZeroRemaining === true && meta.rateLimit?.remaining === 0) {
-        return buildRateLimitStop("GitHub GraphQL rate limit remaining is 0", meta);
+        return buildRateLimitStop(`GitHub ${meta.rateLimit?.resource === "core" ? "REST core" : "GraphQL"} rate limit remaining is 0`, meta);
     }
     return undefined;
 }
@@ -47,5 +47,5 @@ function finiteNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
 export function isRateLimitMessage(message) {
-    return /rate limit|rate-limit|secondary limit|secondary rate/i.test(message);
+    return /rate limit|rate-limit|secondary limit|secondary rate|abuse detection/i.test(message);
 }

package/bin/comments/resolve.d.mts

@@ -1,6 +1,7 @@
 import { type RepoInfo } from "../github/client.mts";
 import type { ResolveOptions } from "../types.mts";
 import { type ResolveRateLimitStop } from "./rate-limit.mts";
+import { type ReplyEvidence } from "../github/reply-recovery-read.mts";
 export interface ResolveResult {
     repliedThreads: string[];
     resolvedThreads: string[];
@@ -26,12 +27,17 @@ export interface ResolveResult {
     /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedDismissals?: string[];
     rateLimit?: ResolveRateLimitStop;
+    sessionRefusal?: string;
+    instructions?: string[];
     unrepliedThreads?: string[];
     unresolvedThreads?: string[];
     unminimizedComments?: string[];
     undismissedReviews?: string[];
 }
-export declare function applyResolveOptions(pr: number, repo: RepoInfo, opts: ResolveOptions): Promise<ResolveResult>;
+export declare function applyResolveOptions(pr: number, repo: RepoInfo, opts: ResolveOptions, preflight?: {
+    headSha?: string;
+    evidence: Map<string, ReplyEvidence>;
+}): Promise<ResolveResult>;
 /** @deprecated Compatibility alias; use `autoResolveThreads`. */
 export declare function autoResolveOutdated(threadIds: string[]): Promise<{
     resolved: string[];

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