pr-shepherd 0.42.0 → 0.44.0

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

@@ -5,13 +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 { formatPrUrl } from "../../pr-reference.mjs";
 function nextFixAttempts(stored, headSha, threads) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
@@ -29,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));
@@ -55,7 +120,7 @@ export async function handleFixCode(ctx) {
             action: "escalate",
             escalate: {
                 ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+                humanMessage: buildEscalateHumanMessage(escalateBase, prReference),
             },
         };
     }
@@ -74,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;
@@ -102,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:
@@ -141,13 +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 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,

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,
@@ -65,6 +63,8 @@ export function buildRelevantChecks(report) {
                 runId: c.runId,
                 detailsUrl: c.detailsUrl || null,
                 ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
+                ...(c.scope !== undefined && { scope: c.scope }),
+                ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
                 summary: c.summary,
             },
         ];
@@ -85,6 +85,8 @@ export function buildRelevantChecks(report) {
                 ...(c.summary !== undefined && { summary: c.summary }),
                 ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
                 ...(c.annotations !== undefined && { annotations: c.annotations }),
+                ...(c.scope !== undefined && { scope: c.scope }),
+                ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
             },
         ];
     });
@@ -98,23 +100,10 @@ export function buildActiveChecks(report) {
         detailsUrl: c.detailsUrl || null,
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.summary !== undefined && { summary: c.summary }),
+        ...(c.scope !== undefined && { scope: c.scope }),
+        ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
     }));
 }
-// Best-effort: cancelling a completed run is a no-op, not an error.
-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);
-        // GitHub returns 409 when the run reached a terminal state — expected, not worth logging.
-        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,11 +1,9 @@
 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, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
+import { getCurrentHeadSha, buildWaitLog, buildTerminalCancelResult, blockedCancelNote, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
@@ -13,6 +11,9 @@ import { handleFixCode } from "./fix-code.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 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);
@@ -74,40 +75,12 @@ export async function runIterate(opts) {
         report.mergeStatus.status === "CONFLICTS" ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
-        editedSummaries.length > 0;
-    const isCleanReadyHandoff = report.status === "READY" && !hasActionableWork;
+        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);
-    const base = {
-        pr: report.pr,
-        repo: report.repo,
-        status: report.status,
-        state: report.mergeStatus.state,
-        mergeStateStatus: report.mergeStatus.mergeStateStatus,
-        mergeStatus: report.mergeStatus.status,
-        reviewDecision: report.mergeStatus.reviewDecision,
-        blockingBotReviewInProgress: report.mergeStatus.blockingBotReviewInProgress,
-        isDraft: report.mergeStatus.isDraft,
-        shouldCancel: readyState.shouldCancel,
-        remainingSeconds: readyState.remainingSeconds,
-        summary: buildSummary(report),
-        baseBranch: report.baseBranch,
-        branchProtection: report.branchProtection,
-        mergeRequirements: report.mergeStatus.mergeRequirements,
-        checks: buildRelevantChecks(report),
-        inProgressChecks: buildActiveChecks(report),
-        ...buildSuppressedCheckFields(report),
-        activity: report.activity,
-    };
-    if (readyState.shouldCancel) {
-        await clearStallState(stallKey);
-        const cancelNote = blockedCancelNote(base);
-        return {
-            ...base,
-            action: "cancel",
-            reason: "ready-delay-elapsed",
-            log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
-        };
-    }
+    const base = buildIterateBase(report, readyState);
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     if (hasActionableWork) {
         return handleFixCode({
@@ -128,17 +101,32 @@ export async function runIterate(opts) {
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
+    const mergeStateResult = await handleActiveMergeState({
+        enabled: opts.merge,
+        active: activeMerge,
+        base,
+        report,
+        stallKey,
+    });
+    if (mergeStateResult)
+        return mergeStateResult;
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
-        !report.mergeStatus.blockingBotReviewInProgress &&
-        !readyState.shouldCancel;
-    if (canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady) {
-        await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
+        !report.mergeStatus.blockingBotReviewInProgress;
+    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);
+        if (mergeResult)
+            return mergeResult;
+        const cancelNote = blockedCancelNote(base);
         return {
             ...base,
-            action: "mark_ready",
-            markedReady: true,
-            log: `MARKED READY: PR #${report.pr} converted from draft to ready for review`,
+            action: "cancel",
+            reason: "ready-delay-elapsed",
+            log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
         };
     }
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, { ...base, action: "wait", log: buildWaitLog(base) }, report, reviewSummaryIds);

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.d.mts

@@ -0,0 +1,15 @@
+import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+type StallKey = {
+    owner: string;
+    repo: string;
+    pr: number;
+};
+export declare function buildReadyMergeResult(enabled: boolean | undefined, readyElapsed: boolean, base: IterateResultBase, report: ShepherdReport): IterateResult | null;
+export declare function handleActiveMergeState(input: {
+    enabled: boolean | undefined;
+    active: boolean;
+    base: IterateResultBase;
+    report: ShepherdReport;
+    stallKey: StallKey;
+}): Promise<IterateResult | null>;
+export {};

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

@@ -0,0 +1,82 @@
+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: "escalate",
+        escalate: {
+            ...authorizationEscalateBase,
+            humanMessage: buildEscalateHumanMessage(authorizationEscalateBase, report.pr, {
+                merge: true,
+            }),
+        },
+    };
+}
+export async function handleActiveMergeState(input) {
+    const { enabled, active, base, report, stallKey } = input;
+    if (enabled && active) {
+        await clearStallState(stallKey);
+        return {
+            ...base,
+            action: "wait",
+            log: report.mergeQueue?.inQueue
+                ? `WAIT: PR #${report.pr} is in the merge queue`
+                : `WAIT: PR #${report.pr} has auto-merge enabled`,
+        };
+    }
+    const removal = report.mergeQueue?.latestRemoval;
+    if (!enabled || !removal || report.mergeQueue?.headUpdatedAfterRemoval)
+        return null;
+    await clearStallState(stallKey);
+    const escalateBase = {
+        triggers: ["merge-queue-removed"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        mergeQueueRemoval: removal,
+        suggestion: buildEscalateSuggestion(["merge-queue-removed"], removal.reason ?? "GitHub did not provide a reason"),
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalateBase,
+            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
+                merge: true,
+            }),
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { MergeCommandPlan } from "../../types.mts";
+interface MergePlanInput {
+    pr: number;
+    repo: string;
+    nodeId: string;
+    headSha: string;
+    queue: boolean;
+}
+export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan;
+export declare function renderMergeCommand(command: {
+    argv: string[];
+}): string;
+export {};

package/bin/commands/iterate/merge.mjs

@@ -0,0 +1,45 @@
+import { loadConfig } from "../../config/load.mjs";
+import { findMergeStrategies } from "../../config/merge-command-args.mjs";
+import { renderShellCommand } from "../../cli/runner.mjs";
+const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
+export function buildMergeCommandPlan(input) {
+    const base = [
+        "gh",
+        "pr",
+        "merge",
+        String(input.pr),
+        "--repo",
+        input.repo,
+        "--match-head-commit",
+        input.headSha,
+    ];
+    if (input.queue) {
+        return {
+            mode: "queue",
+            command: { argv: base },
+            queueApiFallbackCommand: {
+                argv: [
+                    "gh",
+                    "api",
+                    "graphql",
+                    "-f",
+                    `query=${ENQUEUE_MUTATION}`,
+                    "-f",
+                    `pullRequestId=${input.nodeId}`,
+                    "-f",
+                    `expectedHeadOid=${input.headSha}`,
+                ],
+            },
+        };
+    }
+    const configuredArgs = loadConfig().merge?.commandArgs ?? [];
+    const hasStrategy = findMergeStrategies(configuredArgs).length > 0;
+    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, "--merge"];
+    return {
+        mode: "auto",
+        command: { argv: [...base, "--auto", ...commandArgs] },
+    };
+}
+export function renderMergeCommand(command) {
+    return renderShellCommand(command.argv);
+}

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[];

package/bin/commands/iterate/render.mjs

@@ -10,8 +10,8 @@ export function renderResolveCommand(rc) {
         parts.push("--require-sha", "$HEAD_SHA");
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+isBehind = false, viewerCanUpdate = false) {
     const instructions = [];
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
@@ -38,13 +38,13 @@ isBehind = false) {
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
     if (hasConflicts) {
-        instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing and pushing.");
+        instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing.");
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
         instructions.push("Review every item under `## First-look items` before acting.");
     }
-    if (firstLookSummaries.length > 0)
+    if (firstLookSummaries.length > 0 && viewerCanUpdate)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
     const editedTotal = editedSummaries.length +
         actionableComments.filter((c) => c.edited).length +
@@ -53,15 +53,13 @@ isBehind = false) {
     if (editedTotal > 0) {
         instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
     }
-    if (inProgressRunIds.length > 0) {
-        instructions.push("If you will push, first cancel every ID under `## In-progress runs` with `gh run cancel <id>` (ignore errors for runs that already finished). If you will not push, leave them alone.");
-    }
-    if (cancelledCount > 0) {
-        instructions.push("Do not cancel the IDs under `## Cancelled runs` again. The CLI already cancelled them.");
-    }
+    // GitHub exposes no exact viewer capability for workflow-run cancellation, so the
+    // informational run lists never produce a cancellation recommendation.
+    void inProgressRunIds;
+    void cancelledCount;
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions)
-        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads"));
+        instructions.push(buildCommitSuggestionInstruction(prReference, "## Review threads"));
     if (threads.length > 0 || actionableComments.length > 0) {
         // Actionable comments carry no file/line location (unlike threads), so "referenced above"
         // is only accurate when threads are present.
@@ -83,21 +81,22 @@ isBehind = false) {
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     if (hasConflicts) {
-        instructions.push(`Commit any remaining changes and push the conflict resolution${mutationSuffix}.`);
+        instructions.push(`Commit any remaining conflict-resolution changes${mutationSuffix}.`);
     }
     else if (hasNonConflictHints) {
-        instructions.push(`If you changed code, commit any remaining changes and push${mutationSuffix}. Otherwise, do not commit or push.`);
+        instructions.push("If you changed code, commit any remaining changes, then stop and hand off for a push whose authorization is established outside Shepherd; do not run the remaining review mutations or iterate until the remote PR head changes. Shepherd cannot verify the Git credential's push authorization. If you did not change code, do not commit and continue with the remaining steps.");
     }
-    if (hasReviewMutations ||
-        hasNonConflictHints ||
-        firstLookTotal > 0 ||
-        firstLookSummaries.length > 0 ||
-        editedTotal > 0) {
-        instructions.push(buildShepherdJournalInstruction(prNumber));
+    if (viewerCanUpdate &&
+        (hasReviewMutations ||
+            hasNonConflictHints ||
+            firstLookTotal > 0 ||
+            firstLookSummaries.length > 0 ||
+            editedTotal > 0)) {
+        instructions.push(buildShepherdJournalInstruction(prReference));
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
     instructions.push(...buildResolveCommandInstruction(resolveCommand));
-    instructions.push(buildFixCompletionInstruction(failingChecks));
+    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
     return instructions;
 }