pr-shepherd 0.43.0 → 0.44.0

package/bin/commands/iterate/classify.mjs

@@ -1,6 +1,7 @@
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { shouldMinimizeAuthor } from "../../comments/minimize-policy.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, } from "../../comments/authors.mjs";
+import { buildThreadMutationRouting } from "./thread-mutation-routing.mjs";
 function dedupeIds(ids) {
     const seen = new Set();
     const out = [];
@@ -14,7 +15,8 @@ function dedupeIds(ids) {
 }
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all", botUsernames = new Set(), unresolvedThreads = [], ruleAutoResolveIds = []) {
     const blockedReviewIds = new Set(unresolvedThreads.flatMap((t) => (t.reviewId !== undefined ? [t.reviewId] : [])));
-    const eligible = (r) => shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames) &&
+    const eligible = (r) => r.viewerCanMinimize === true &&
+        shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames) &&
         !blockedReviewIds.has(r.id);
     // First-look summaries still need one tick to surface their body to the agent,
     // so their minimize IDs ride in the agent-facing apply command. Seen summaries
@@ -34,7 +36,8 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
     if (minimizeApprovals) {
         const surfacedApprovals = [];
         for (const r of approvals) {
-            if (shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
+            if (r.viewerCanMinimize === true &&
+                shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
                 minimizeIds.push(r.id);
             else
                 surfacedApprovals.push(r);
@@ -55,35 +58,45 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber, botUsernames = new Set(), ruleAutoResolveThreadIds = []) {
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prReference, botUsernames = new Set(), ruleAutoResolveThreadIds = [], viewerAuthorization, authorizationThreads = []) {
     const allThreads = [...threads, ...resolutionOnlyThreads];
-    const replyThreadIds = dedupeIds(allThreads
-        .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
-        .map((t) => t.id));
-    // Rule-matched threads bypass the author check (human-author guard still applies in resolve-mutate).
-    const resolveThreadIds = dedupeIds([
-        ...allThreads
-            .filter((t) => !isHumanAuthor(t) || isConfiguredBotAuthor(t, botUsernames))
-            .map((t) => t.id),
-        ...ruleAutoResolveThreadIds,
-    ]);
+    const routed = buildThreadMutationRouting(allThreads, botUsernames, ruleAutoResolveThreadIds);
+    const canReply = new Set(authorizationThreads
+        .filter((thread) => thread.viewerCanReply === true)
+        .map((thread) => thread.id));
+    const canResolve = new Set(authorizationThreads
+        .filter((thread) => thread.viewerCanResolve === true)
+        .map((thread) => thread.id));
+    const replyThreadIds = routed.replyThreadIds.filter((id) => canReply.has(id));
+    // Viewer-authored human resolves stay paired with an authorized reply. Marker-ended
+    // viewer-authored retries and bot/non-human resolves need only resolve authorization.
+    const pairedResolveThreadIds = routed.pairedResolveThreadIds.filter((id) => canReply.has(id) && canResolve.has(id));
+    const standaloneResolveThreadIds = routed.standaloneResolveThreadIds.filter((id) => canResolve.has(id));
+    const resolveThreadIds = dedupeIds([...pairedResolveThreadIds, ...standaloneResolveThreadIds]);
     // Bot/non-human CHANGES_REQUESTED reviews are auto-dismissed after the agent pushes a fix.
     // Human reviews are left for the reviewer to re-review or dismiss themselves.
-    const dismissReviewIds = dedupeIds(reviews
-        .filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames))
-        .map((r) => r.id));
+    const dismissReviewIds = dedupeIds(viewerAuthorization?.viewerCanAdminister === true
+        ? reviews
+            .filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames))
+            .map((r) => r.id)
+        : []);
     const hasReply = replyThreadIds.length > 0;
     const hasDismiss = dismissReviewIds.length > 0;
     // Mutations that require --message: replies (to human threads) and dismissals (of bot CR reviews).
     const hasMessageMutations = hasReply || hasDismiss;
     const hasResolveOrMinimize = resolveThreadIds.length > 0 || allCommentIds.length > 0;
-    if (hasMessageMutations && hasResolveOrMinimize) {
-        // Split: message-bearing mutations (replies + dismissals) ride in resolveArgv;
-        // resolve/minimize mutations go in resolveOnlyArgv so they can run without SHA or message.
-        const resolveArgv = buildPrShepherdCommand(["apply", "review", String(prNumber)]).argv;
+    const hasStandaloneResolveOrMinimize = standaloneResolveThreadIds.length > 0 || allCommentIds.length > 0;
+    if (hasMessageMutations && hasStandaloneResolveOrMinimize) {
+        // Split: message-bearing mutations plus their paired viewer-authored resolves ride in
+        // resolveArgv; standalone resolve/minimize mutations go in resolveOnlyArgv so they can
+        // run without SHA or message.
+        const resolveArgv = buildPrShepherdCommand(["apply", "review", String(prReference)]).argv;
         if (replyThreadIds.length > 0) {
             resolveArgv.push("--reply-thread-ids", replyThreadIds.join(","));
         }
+        if (pairedResolveThreadIds.length > 0) {
+            resolveArgv.push("--resolve-thread-ids", pairedResolveThreadIds.join(","));
+        }
         resolveArgv.push("--message", "$DISMISS_MESSAGE");
         if (hasDismiss) {
             resolveArgv.push("--dismiss-review-ids", dismissReviewIds.join(","));
@@ -96,12 +109,15 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
             requiresHeadSha,
             requiresDismissMessage: true,
             ...(replyThreadIds.length > 0 ? { replyThreadIds } : undefined),
+            ...(pairedResolveThreadIds.length > 0
+                ? { resolveThreadIds: pairedResolveThreadIds }
+                : undefined),
             ...(hasDismiss ? { dismissReviewIds } : undefined),
             hasMutations: true,
         };
-        const resolveOnlyArgv = buildPrShepherdCommand(["apply", "review", String(prNumber)]).argv;
-        if (resolveThreadIds.length > 0) {
-            resolveOnlyArgv.push("--resolve-thread-ids", resolveThreadIds.join(","));
+        const resolveOnlyArgv = buildPrShepherdCommand(["apply", "review", String(prReference)]).argv;
+        if (standaloneResolveThreadIds.length > 0) {
+            resolveOnlyArgv.push("--resolve-thread-ids", standaloneResolveThreadIds.join(","));
         }
         if (allCommentIds.length > 0) {
             resolveOnlyArgv.push("--minimize-comment-ids", allCommentIds.join(","));
@@ -110,13 +126,15 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
             argv: resolveOnlyArgv,
             requiresHeadSha: false,
             requiresDismissMessage: false,
-            ...(resolveThreadIds.length > 0 ? { resolveThreadIds } : undefined),
+            ...(standaloneResolveThreadIds.length > 0
+                ? { resolveThreadIds: standaloneResolveThreadIds }
+                : undefined),
             hasMutations: true,
         };
         return { resolveCommand, resolveOnlyCommand };
     }
     // Single command: all mutations combined (or only one category present).
-    const argv = buildPrShepherdCommand(["apply", "review", String(prNumber)]).argv;
+    const argv = buildPrShepherdCommand(["apply", "review", String(prReference)]).argv;
     if (replyThreadIds.length > 0) {
         argv.push("--reply-thread-ids", replyThreadIds.join(","));
         argv.push("--message", "$DISMISS_MESSAGE");

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

@@ -26,7 +26,7 @@ interface BaseBranchLookup {
  */
 export declare function formatDurationApprox(seconds: number): string;
 export declare function validateBaseBranch(raw: string): BaseBranchLookup;
-export declare function buildEscalateHumanMessage(escalate: Omit<EscalateDetails, "humanMessage">, pr: number, opts?: {
+export declare function buildEscalateHumanMessage(escalate: Omit<EscalateDetails, "humanMessage">, pr: string | number, opts?: {
     merge?: boolean;
 }): string;
 export declare function buildEscalateSuggestion(triggers: EscalateTrigger[], detail?: string): string;

package/bin/commands/iterate/escalate.mjs

@@ -121,6 +121,14 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
         if (removal.beforeCommitOid)
             lines.push(`- queue commit: \`${removal.beforeCommitOid}\``);
     }
+    if (escalate.authorization && escalate.authorization.length > 0) {
+        lines.push("");
+        lines.push("## Authorization");
+        lines.push("");
+        for (const item of escalate.authorization) {
+            lines.push(`- ${item.action}: ${item.targetIds.map((id) => `\`${id}\``).join(", ")} — GitHub denied the action or did not expose a confirming capability`);
+        }
+    }
     if (escalate.thrashHistory && escalate.thrashHistory.length > 0) {
         lines.push("");
         lines.push("## Fix attempts");
@@ -136,6 +144,9 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
+    if (triggers.includes("authorization-required")) {
+        return "GitHub did not confirm that the current viewer may perform one or more required actions. Ask a repository maintainer to handle the listed items; Shepherd will not recommend commands that would be denied.";
+    }
     if (triggers.includes("merge-queue-removed")) {
         const reason = detail ? ` GitHub reason: ${detail}.` : "";
         return `The PR left the merge queue without an actionable check failure.${reason} Confirm the removal was not intentional before adding it again.`;

package/bin/commands/iterate/fix-code.mjs

@@ -5,14 +5,14 @@ import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/ag
 import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
 import { buildResolveCommand } from "./classify.mjs";
+import { buildThreadMutationRouting } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
-import { tryCancelRun, buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./helpers.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { buildMergeCommandPlan } from "./merge.mjs";
+import { formatPrUrl } from "../../pr-reference.mjs";
 function nextFixAttempts(stored, headSha, threads) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
@@ -30,9 +30,73 @@ function nextFixAttempts(stored, headSha, threads) {
 }
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
+    const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
-    const { protectedRunIds, protectedRuns } = buildRunProtection([...failingChecks, ...report.checks.inProgress], opts.neverCancelRuns);
+    const allThreads = [...report.threads.actionable, ...report.threads.resolutionOnly];
+    const ruleAutoResolveIds = new Set(ruleAutoResolveThreadIds ?? []);
+    const routedThreadMutations = buildThreadMutationRouting(allThreads, botUsernames, [
+        ...ruleAutoResolveIds,
+    ]);
+    const replyIdSet = new Set(routedThreadMutations.replyThreadIds);
+    const resolveIdSet = new Set(routedThreadMutations.resolveThreadIds);
+    const unauthorizedReplies = allThreads.filter((thread) => report.viewerAuthorization !== undefined &&
+        replyIdSet.has(thread.id) &&
+        thread.viewerCanReply !== true);
+    const unauthorizedResolves = allThreads.filter((thread) => report.viewerAuthorization !== undefined &&
+        resolveIdSet.has(thread.id) &&
+        thread.viewerCanResolve !== true);
+    const unauthorizedDismissals = report.changesRequestedReviews.filter((review) => report.viewerAuthorization !== undefined &&
+        (!isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames)) &&
+        report.viewerAuthorization?.viewerCanAdminister !== true);
+    const authorization = [
+        ...(unauthorizedReplies.length > 0
+            ? [
+                {
+                    action: "reply-thread",
+                    targetIds: unauthorizedReplies.map((thread) => thread.id),
+                    reason: "denied-or-unverifiable",
+                },
+            ]
+            : []),
+        ...(unauthorizedResolves.length > 0
+            ? [
+                {
+                    action: "resolve-thread",
+                    targetIds: unauthorizedResolves.map((thread) => thread.id),
+                    reason: "denied-or-unverifiable",
+                },
+            ]
+            : []),
+        ...(unauthorizedDismissals.length > 0
+            ? [
+                {
+                    action: "dismiss-review",
+                    targetIds: unauthorizedDismissals.map((review) => review.id),
+                    reason: "denied-or-unverifiable",
+                },
+            ]
+            : []),
+    ];
+    if (authorization.length > 0) {
+        const authorizationEscalateBase = {
+            triggers: ["authorization-required"],
+            unresolvedThreads: allThreads.map(toAgentThread),
+            ambiguousComments: report.comments.actionable.map(toAgentComment),
+            changesRequestedReviews: report.changesRequestedReviews,
+            authorization,
+            suggestion: buildEscalateSuggestion(["authorization-required"]),
+        };
+        return {
+            ...base,
+            action: "escalate",
+            escalate: {
+                ...authorizationEscalateBase,
+                humanMessage: buildEscalateHumanMessage(authorizationEscalateBase, prReference),
+            },
+        };
+    }
+    const protectedRuns = [];
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);
     const botCrReviews = report.changesRequestedReviews.filter((r) => !isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames));
@@ -56,7 +120,7 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+                humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
             },
         };
     }
@@ -75,18 +139,14 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+                humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
             },
         };
     }
     await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts, threadBodyHashes });
-    let cancelled = [];
-    if (!opts.noAutoCancelActionable) {
-        const runIds = buildAutoCancelRunIdsWithOptions(report, { protectedRunIds });
-        const results = await Promise.all(runIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
-        cancelled = results.filter((id) => id !== null);
-    }
-    const cancelledSet = new Set(cancelled);
+    // GitHub does not expose a per-run viewer capability for cancellation. Fail closed:
+    // do not issue or recommend an Actions mutation based only on repository role.
+    const cancelled = [];
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
     const resolutionOnlyThreads = report.threads.resolutionOnly;
@@ -103,21 +163,15 @@ export async function handleFixCode(ctx) {
     // Only surface in-progress runs when a push is plausible — resolution-only and
     // summary-only iterations have no path to a push, so listing runs would prompt
     // unnecessary cancellation.
-    const pushLikely = threads.length > 0 ||
-        failingAgentChecks.length > 0 ||
-        annotatedExtra.length > 0 ||
-        hasConflicts ||
-        changesRequestedReviews.length > 0 ||
-        actionableComments.length > 0;
-    const inProgressRunIds = pushLikely
-        ? buildInProgressRunIds(report, cancelledSet, {
-            suppressProtectedFreshReruns: false,
-            protectedRunIds,
-        })
-        : [];
+    const inProgressRunIds = [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, failingAgentChecks, prNumber, botUsernames, ruleAutoResolveThreadIds);
+    // Conflict resolution necessarily changes the branch head, but Shepherd cannot verify
+    // authorization for the local Git credential that would publish it. Defer review mutations
+    // until an authorized push updates the PR and a fresh iteration can rebuild SHA-safe commands.
+    const { resolveCommand, resolveOnlyCommand } = hasConflicts
+        ? buildResolveCommand([], [], [], [], [], prReference, botUsernames, [], undefined, [])
+        : buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
     // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:
@@ -142,27 +196,13 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...fallbackEscalateBase,
-                humanMessage: buildEscalateHumanMessage(fallbackEscalateBase, prNumber),
+                humanMessage: buildEscalateHumanMessage(fallbackEscalateBase, prReference),
             },
         };
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind);
-    const hasMergeGroupFailure = failingChecks.some((check) => check.scope === "merge_group");
-    const needsRequeue = Boolean(hasMergeGroupFailure || report.mergeQueue?.inQueue || report.mergeQueue?.latestRemoval);
-    const requeue = opts.merge && needsRequeue
-        ? buildMergeCommandPlan({
-            pr: report.pr,
-            repo: report.repo,
-            nodeId: report.nodeId,
-            headSha: "$HEAD_SHA",
-            queue: true,
-        })
-        : undefined;
-    if (requeue) {
-        instructions.splice(Math.max(0, instructions.length - 1), 0, "After all fixes and review mutations, replace `$HEAD_SHA` in the requeue commands with the full pushed PR-head SHA (or `$(git rev-parse HEAD)`). If GitHub no longer reports the PR in the merge queue, run the `requeue:` command shown above; if the gh CLI reports that auto-merge is disabled, run `requeue API fallback:` instead.");
-    }
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true);
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
@@ -184,7 +224,6 @@ export async function handleFixCode(ctx) {
             firstLookComments,
             inProgressRunIds,
             protectedRuns,
-            ...(requeue && { requeue }),
         },
         cancelled,
     };

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

@@ -1,5 +1,4 @@
 import type { ActiveCheck, IterateResult, IterateResultBase, IterateResultSummary, RelevantCheck, ShepherdReport } from "../../types.mts";
-export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mts";
 export declare function buildSummary(report: ShepherdReport): IterateResultSummary;
 /** Non-blocking check-name lists (ignored/superseded), omitted from the result when empty. */
 export declare function buildSuppressedCheckFields(report: ShepherdReport): Pick<IterateResultBase, "ignoredNames" | "supersededNames">;
@@ -8,7 +7,6 @@ export declare function buildTerminalCancelResult(report: ShepherdReport): Itera
 /** Build completed, non-skipped checks relevant to PR readiness. */
 export declare function buildRelevantChecks(report: ShepherdReport): RelevantCheck[];
 export declare function buildActiveChecks(report: ShepherdReport): ActiveCheck[];
-export declare function tryCancelRun(runId: string, owner: string, repo: string): Promise<string | null>;
 export declare function getCurrentHeadSha(): Promise<string | null>;
 export declare function buildWaitLog(base: IterateResultBase): string;
 export declare function blockedCancelNote(base: IterateResultBase): string;

package/bin/commands/iterate/helpers.mjs

@@ -1,10 +1,8 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
-import { rest } from "../../github/http.mjs";
 import { getExecutionCwd } from "../../execution-context.mjs";
 import { blockedReasonFromRequirements } from "../../merge-status/requirements-format.mjs";
 const execFile = promisify(execFileCb);
-export { buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./reruns.mjs";
 export function buildSummary(report) {
     return {
         passing: report.checks.passing.length,
@@ -106,19 +104,6 @@ export function buildActiveChecks(report) {
         ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
     }));
 }
-export async function tryCancelRun(runId, owner, repo) {
-    try {
-        await rest("POST", `/repos/${owner}/${repo}/actions/runs/${runId}/cancel`);
-        return runId;
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (/409|already completed|cannot cancel a workflow run that is completed/i.test(msg))
-            return null;
-        process.stderr.write(`pr-shepherd: cancel run ${runId} failed (ignored): ${msg}\n`);
-        return null;
-    }
-}
 export async function getCurrentHeadSha() {
     try {
         const { stdout } = await execFile("git", ["rev-parse", "HEAD"], {

package/bin/commands/iterate/index.mjs

@@ -1,8 +1,6 @@
 import { runCheck } from "../check.mjs";
 import { updateReadyDelay } from "../ready-delay.mjs";
 import { getCurrentPrNumber } from "../../github/client.mjs";
-import { graphql } from "../../github/http.mjs";
-import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { EXIT, ShepherdError } from "../../exit-codes.mjs";
 import { getCurrentHeadSha, buildWaitLog, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
@@ -15,6 +13,7 @@ import { autoMinimizeComments } from "../../comments/resolve.mjs";
 import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { buildReadyMergeResult, handleActiveMergeState } from "./merge-state.mjs";
 import { buildIterateBase } from "./base.mjs";
+import { markReadyIfAuthorized } from "./mark-ready.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
@@ -76,7 +75,8 @@ export async function runIterate(opts) {
         report.mergeStatus.status === "CONFLICTS" ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
-        editedSummaries.length > 0;
+        editedSummaries.length > 0 ||
+        (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
     const activeMerge = Boolean(opts.merge && (report.mergeQueue?.inQueue || report.mergeQueue?.autoMergeRequest));
     const isCleanReadyHandoff = report.status === "READY" && !hasActionableWork && !activeMerge;
     const readyState = await updateReadyDelay(report.pr, isCleanReadyHandoff, readyDelaySeconds, repoOwner, repoName);
@@ -113,15 +113,9 @@ export async function runIterate(opts) {
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
-    if (canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady) {
-        await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
-        return {
-            ...base,
-            action: "mark_ready",
-            markedReady: true,
-            log: `MARKED READY: PR #${report.pr} converted from draft to ready for review`,
-        };
-    }
+    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady, base, report);
+    if (markReadyResult)
+        return markReadyResult;
     if (readyState.shouldCancel) {
         await clearStallState(stallKey);
         const mergeResult = buildReadyMergeResult(opts.merge, true, base, report);

package/bin/commands/iterate/mark-ready.d.mts

@@ -0,0 +1,2 @@
+import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+export declare function markReadyIfAuthorized(enabled: boolean, base: IterateResultBase, report: ShepherdReport): Promise<IterateResult | null>;

package/bin/commands/iterate/mark-ready.mjs

@@ -0,0 +1,38 @@
+import { graphql } from "../../github/http.mjs";
+import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
+import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
+export async function markReadyIfAuthorized(enabled, base, report) {
+    if (!enabled)
+        return null;
+    if (report.viewerAuthorization?.viewerCanUpdate === true) {
+        await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
+        return {
+            ...base,
+            action: "mark_ready",
+            markedReady: true,
+            log: `MARKED READY: PR #${report.pr} converted from draft to ready for review`,
+        };
+    }
+    const escalation = {
+        triggers: ["authorization-required"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        authorization: [
+            {
+                action: "mark-ready",
+                targetIds: [report.nodeId],
+                reason: "denied-or-unverifiable",
+            },
+        ],
+        suggestion: buildEscalateSuggestion(["authorization-required"]),
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalation,
+            humanMessage: buildEscalateHumanMessage(escalation, report.pr),
+        },
+    };
+}

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

@@ -1,21 +1,48 @@
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
 import { buildMergeCommandPlan } from "./merge.mjs";
+import { formatPrUrl } from "../../pr-reference.mjs";
 export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
     if (!enabled || !readyElapsed || report.mergeStatus.isDraft)
         return null;
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
+    if (!queue && report.viewerAuthorization?.viewerCanEnableAutoMerge === true) {
+        return {
+            ...base,
+            action: "merge",
+            merge: buildMergeCommandPlan({
+                pr: report.pr,
+                repo: report.repo,
+                nodeId: report.nodeId,
+                headSha: report.headSha ?? "unknown",
+                queue: false,
+            }),
+        };
+    }
+    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: "merge",
-        merge: buildMergeCommandPlan({
-            pr: report.pr,
-            repo: report.repo,
-            nodeId: report.nodeId,
-            headSha: report.headSha ?? "unknown",
-            queue,
-        }),
+        action: "escalate",
+        escalate: {
+            ...authorizationEscalateBase,
+            humanMessage: buildEscalateHumanMessage(authorizationEscalateBase, report.pr, {
+                merge: true,
+            }),
+        },
     };
 }
 export async function handleActiveMergeState(input) {
@@ -47,7 +74,9 @@ export async function handleActiveMergeState(input) {
         action: "escalate",
         escalate: {
             ...escalateBase,
-            humanMessage: buildEscalateHumanMessage(escalateBase, report.pr, { merge: true }),
+            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
+                merge: true,
+            }),
         },
     };
 }

package/bin/commands/iterate/merge.mjs

@@ -38,7 +38,6 @@ 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

@@ -1,5 +1,5 @@
 import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, FirstLookThread, FirstLookComment, ReviewThread } from "../../types.mts";
 /** 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, prNumber: 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): 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): string[];