pr-shepherd 0.42.0 → 0.44.0

package/bin/cli/mutate-formatter.mjs

@@ -34,6 +34,10 @@ export function formatMutateResult(result) {
     pushIds(lines, "Skipped human minimizes", result.skippedHumanMinimizes);
     pushIds(lines, "Skipped human review dismissals", result.skippedHumanDismissals);
     pushIds(lines, "Skipped non-human/unknown thread replies", result.skippedNonHumanReplies);
+    pushIds(lines, "Authorization denied/unverifiable for thread replies", result.skippedUnauthorizedReplies);
+    pushIds(lines, "Authorization denied/unverifiable for thread resolves", result.skippedUnauthorizedResolves);
+    pushIds(lines, "Authorization denied/unverifiable for minimizes", result.skippedUnauthorizedMinimizes);
+    pushIds(lines, "Authorization denied/unverifiable for review dismissals", result.skippedUnauthorizedDismissals);
     const rateLimit = formatRateLimit(result);
     if (rateLimit)
         lines.push(rateLimit);

package/bin/cli/poll-handler.mjs

@@ -36,6 +36,7 @@ export async function handlePoll(args) {
         stallTimeoutSeconds: flags.stallTimeoutSeconds,
         noAutoMarkReady: flags.noAutoMarkReady,
         noAutoCancelActionable: flags.noAutoCancelActionable,
+        merge: flags.merge,
         intervalSeconds,
         timeoutSeconds,
         debounceSeconds,

package/bin/cli/runner.mjs

@@ -8,11 +8,12 @@ export function renderShellCommand(argv) {
 function renderShellArg(arg) {
     if (/^\$[A-Z_][A-Z0-9_]*$/.test(arg))
         return `"${arg}"`;
+    const assignment = /^([A-Za-z_][A-Za-z0-9_]*)=(\$[A-Z_][A-Z0-9_]*)$/.exec(arg);
+    if (assignment)
+        return `${assignment[1]}="${assignment[2]}"`;
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg))
         return arg;
     if (!/["$`\\]/.test(arg))
         return `"${arg}"`;
-    if (!arg.includes("'"))
-        return `'${arg}'`;
-    throw new Error(`Unexpected character in shell arg: ${JSON.stringify(arg)}`);
+    return `'${arg.replaceAll("'", `'"'"'`)}'`;
 }

package/bin/commands/check-terminal-report.mjs

@@ -2,6 +2,7 @@ export function buildTerminalReport(prNumber, repo, batchData, mergeStatus, stat
     return {
         pr: prNumber,
         nodeId: batchData.nodeId,
+        headSha: batchData.headRefOid,
         repo: `${repo.owner}/${repo.name}`,
         status,
         baseBranch: batchData.baseRefName,

package/bin/commands/check.mjs

@@ -22,7 +22,7 @@ import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
 export async function runCheck(opts) {
-    const repo = await getRepoInfo();
+    const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
@@ -42,7 +42,22 @@ export async function runCheck(opts) {
         ? []
         : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
-    const classifiedChecks = classifyChecks(allChecks);
+    const classifiedPrChecks = classifyChecks(allChecks);
+    const latestRemoval = batchData.latestMergeQueueRemoval;
+    const headUpdatedAfterRemoval = Boolean(latestRemoval &&
+        latestRemoval.beforeCommitParentOids &&
+        !latestRemoval.beforeCommitParentOids.includes(batchData.headRefOid));
+    const queueRawChecks = batchData.isInMergeQueue
+        ? (batchData.mergeQueueChecks ?? [])
+        : latestRemoval && !headUpdatedAfterRemoval
+            ? (batchData.removedMergeQueueChecks ?? [])
+            : [];
+    // Keep supersession grouping commit-local, but accept merge_group only for the
+    // synthetic queue-commit source.
+    const classifiedQueueChecks = classifyChecks(queueRawChecks, {
+        additionalRelevantEvents: ["merge_group"],
+    });
+    const classifiedChecks = [...classifiedPrChecks, ...classifiedQueueChecks];
     const verdict = getCiVerdict(classifiedChecks);
     const passing = classifiedChecks.filter((c) => c.category === "passed");
     const failing = classifiedChecks.filter((c) => c.category === "failing");
@@ -60,8 +75,10 @@ export async function runCheck(opts) {
     const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber);
     const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
-    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
-    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id)), seenMap, botUsernames);
+    const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize !== true));
+    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
+    const deniedRuleAutoResolveThreadIds = new Set(partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve !== true));
+    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id)), seenMap, botUsernames);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -72,7 +89,9 @@ export async function runCheck(opts) {
     const firstLookSummaries = [];
     const editedSummaries = [];
     const seenSummaries = [];
-    const unseenReviewSummaries = batchData.reviewSummaries.filter((r) => !partition.suppressedReviewSummaryIds.has(r.id));
+    const deniedRuleAutoResolveReviewSummaryIds = new Set(partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize !== true));
+    const unseenReviewSummaries = batchData.reviewSummaries.filter((r) => !partition.suppressedReviewSummaryIds.has(r.id) ||
+        deniedRuleAutoResolveReviewSummaryIds.has(r.id));
     for (const r of unseenReviewSummaries) {
         const cls = classifyItem(r.id, r.body, seenMap);
         if (cls === "new")
@@ -108,7 +127,8 @@ export async function runCheck(opts) {
                 .filter((t) => partition.suppressedThreadIds.has(t.id))
                 .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
             ...batchData.reviewSummaries
-                .filter((r) => partition.suppressedReviewSummaryIds.has(r.id))
+                .filter((r) => partition.suppressedReviewSummaryIds.has(r.id) &&
+                !deniedRuleAutoResolveReviewSummaryIds.has(r.id))
                 .map((r) => markSeen(stateKey, r.id, r.body)),
             ...batchData.changesRequestedReviews
                 .filter((r) => partition.suppressedChangesRequestedIds.has(r.id))
@@ -116,7 +136,17 @@ export async function runCheck(opts) {
         ]);
         await markReviewInlineThreadMarkers(stateKey, batchData.reviewThreads);
     }
-    const { threadIds: ruleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(partition, opts.autoMinimizeSuppressed);
+    const authorizedPartition = {
+        ...partition,
+        ruleAutoResolveThreadIds: partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve === true),
+        ruleAutoResolveCommentIds: partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize === true),
+        ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
+    };
+    const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(authorizedPartition, opts.autoMinimizeSuppressed);
+    const ruleAutoResolveThreadIds = [
+        ...authorizedRuleAutoResolveThreadIds,
+        ...deniedRuleAutoResolveThreadIds,
+    ];
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
     const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
     const approvedReviews = approvedReviewVisibility.visible;
@@ -131,10 +161,19 @@ export async function runCheck(opts) {
         }
     }
     const blockedByFilteredCheck = isBlockedByFilteredCheck(mergeStatus, verdict);
+    const queueCommit = batchData.isInMergeQueue
+        ? batchData.mergeQueueEntry?.headCommitOid
+        : batchData.latestMergeQueueRemoval?.beforeCommitOid;
+    const hasQueueState = Boolean(batchData.isMergeQueueEnabled ||
+        batchData.isInMergeQueue ||
+        batchData.autoMergeRequest ||
+        batchData.latestMergeQueueRemoval);
     return {
         pr: prNumber,
         nodeId: batchData.nodeId,
+        headSha: batchData.headRefOid,
         repo: `${repo.owner}/${repo.name}`,
+        ...(batchData.viewerAuthorization && { viewerAuthorization: batchData.viewerAuthorization }),
         status,
         baseBranch: batchData.baseRefName,
         mergeStatus,
@@ -175,6 +214,24 @@ export async function runCheck(opts) {
             : undefined),
         branchProtection: batchData.branchProtection,
         activity: batchData.activity,
+        ...(hasQueueState && {
+            mergeQueue: {
+                enabled: Boolean(batchData.isMergeQueueEnabled),
+                inQueue: Boolean(batchData.isInMergeQueue),
+                ...(batchData.autoMergeRequest && { autoMergeRequest: batchData.autoMergeRequest }),
+                ...(batchData.mergeQueueEntry && { entry: batchData.mergeQueueEntry }),
+                ...(batchData.latestMergeQueueRemoval && {
+                    latestRemoval: batchData.latestMergeQueueRemoval,
+                }),
+                ...(queueCommit && { checkCommitOid: queueCommit }),
+                ...((batchData.isInMergeQueue
+                    ? batchData.mergeQueueChecksIncomplete
+                    : batchData.removedMergeQueueChecksIncomplete) && {
+                    checksIncomplete: true,
+                }),
+                ...(headUpdatedAfterRemoval && { headUpdatedAfterRemoval: true }),
+            },
+        }),
     };
 }
 async function remainingRuleAutoResolveIds(partition, autoMinimizeSuppressed = false) {

package/bin/commands/commit-suggestion-instruction.d.mts

@@ -8,4 +8,4 @@
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.
  */
-export declare function buildCommitSuggestionInstruction(prNumber: number, sectionName: string): string;
+export declare function buildCommitSuggestionInstruction(prReference: string | number, sectionName: string): string;

package/bin/commands/commit-suggestion-instruction.mjs

@@ -9,10 +9,10 @@ import { buildPrShepherdCommand } from "../cli/runner.mjs";
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.
  */
-export function buildCommitSuggestionInstruction(prNumber, sectionName) {
+export function buildCommitSuggestionInstruction(prReference, sectionName) {
     const command = buildPrShepherdCommand([
         "build-suggestion-patches",
-        String(prNumber),
+        String(prReference),
         "--thread-id",
         "<id>",
         "--message",

package/bin/commands/commit-suggestion.mjs

@@ -1,9 +1,11 @@
 import { buildSingularInstructions } from "./suggestion-patch-item.mjs";
 import { runSuggestionPatches } from "./suggestion-patches.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
 /** @deprecated Use runSuggestionPatches. */
 export async function runCommitSuggestion(opts) {
     const result = await runSuggestionPatches({
         prNumber: opts.prNumber,
+        targetRepository: opts.targetRepository,
         format: opts.format,
         verbose: opts.verbose,
         suggestions: [
@@ -19,6 +21,6 @@ export async function runCommitSuggestion(opts) {
         ...patch,
         pr: result.pr,
         repo: result.repo,
-        postActionInstructions: buildSingularInstructions(patch, result.pr),
+        postActionInstructions: buildSingularInstructions(patch, formatPrUrl(result.repo, result.pr)),
     };
 }

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

@@ -0,0 +1,5 @@
+import type { IterateResultBase, ShepherdReport } from "../../types.mts";
+export declare function buildIterateBase(report: ShepherdReport, readyState: {
+    shouldCancel: boolean;
+    remainingSeconds: number;
+}): IterateResultBase;

package/bin/commands/iterate/base.mjs

@@ -0,0 +1,25 @@
+import { buildActiveChecks, buildRelevantChecks, buildSummary, buildSuppressedCheckFields, } from "./helpers.mjs";
+export function buildIterateBase(report, readyState) {
+    return {
+        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,
+        mergeQueue: report.mergeQueue,
+    };
+}

package/bin/commands/iterate/check-instructions.d.mts

@@ -17,11 +17,9 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
  *
  * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
  *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * - Self-reply exclusion: a human thread whose latest visible comment is already Shepherd's
- *   own prior reply still has its ID in `--reply-thread-ids` by default. Running the
- *   printed command as-is replies to Shepherd's own reply, which can re-surface the thread
- *   and produce a self-perpetuating reply loop — worse than a rejected mutation, and not
- *   something a caller can discover by inspecting the command alone.
+ * Marker-based self-reply routing is already reflected in the generated IDs. The instruction
+ * below makes that behavior explicit so an authenticated viewer's unmarked human feedback is
+ * not mistaken for an automated reply merely because the GitHub login matches.
  *
  * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
  * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
@@ -30,18 +28,6 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
  * without it, nothing in CLI output tells the agent that playbook exists.
  */
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
-/**
- * Build the CI-triage instruction. The per-conclusion rerun policy (GitHub Actions log
- * excerpts, `gh run view`/`gh run rerun` rules for CANCELLED/STARTUP_FAILURE/external
- * failures) is invariant text keyed on the `[conclusion: …]` tags already rendered in
- * `## Failing checks` — it lives in the pr-shepherd skill's "CI failure triage" playbook
- * instead of being re-emitted every tick. This supersedes the "CI budget rules" example in
- * CLAUDE.md's "Keep skills and loop prompts minimal" section (see that section's amendment
- * note). The `(no runId)` case stays here because it flips `buildFixCompletionInstruction`
- * to a human-handoff terminal state — that trigger, unlike the others, is CLI-decided. The
- * CLI sentence does not claim every failure has a log excerpt to read (only GitHub Actions
- * checks with a runId do — CANCELLED, STARTUP_FAILURE, and external checks may not); that
- * per-kind detail is exactly what the skill playbook table disambiguates.
- */
+/** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
-export declare function buildFixCompletionInstruction(checks: AgentCheck[]): string;
+export declare function buildFixCompletionInstruction(checks: AgentCheck[], requiresRemoteUpdateAuthorization?: boolean, hasShaGatedReviewMutations?: boolean): string;

package/bin/commands/iterate/check-instructions.mjs

@@ -18,7 +18,7 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
     const trimmedHint = typeof hint === "string" ? hint.trim() : "";
     if (!isBehind || trimmedHint === "")
         return [];
-    return [`The branch is behind \`origin/${baseBranch}\`. ${trimmedHint} before pushing.`];
+    return [`The branch is behind PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
 /**
  * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
@@ -26,11 +26,9 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
  *
  * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
  *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
- * - Self-reply exclusion: a human thread whose latest visible comment is already Shepherd's
- *   own prior reply still has its ID in `--reply-thread-ids` by default. Running the
- *   printed command as-is replies to Shepherd's own reply, which can re-surface the thread
- *   and produce a self-perpetuating reply loop — worse than a rejected mutation, and not
- *   something a caller can discover by inspecting the command alone.
+ * Marker-based self-reply routing is already reflected in the generated IDs. The instruction
+ * below makes that behavior explicit so an authenticated viewer's unmarked human feedback is
+ * not mistaken for an automated reply merely because the GitHub login matches.
  *
  * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
  * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
@@ -43,10 +41,10 @@ export function buildResolveCommandInstruction(resolveCommand) {
         return [];
     const instructions = [];
     if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
-        instructions.push("Before `apply review:`, remove any `--reply-thread-ids` entry whose latest visible comment is your own Shepherd reply. Do not reply to yourself.");
+        instructions.push("Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an established Shepherd reply; a marked viewer-authored human thread is emitted resolve-only, not for another reply.");
     }
     if (resolveCommand.requiresHeadSha) {
-        instructions.push("Replace `$HEAD_SHA` with the pushed commit SHA, or `$(git rev-parse HEAD)` if you did not push.");
+        instructions.push("If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, do not run this command until an authorized push updates the remote PR head; then replace `$HEAD_SHA` with that pushed commit SHA.");
     }
     if (resolveCommand.requiresDismissMessage) {
         instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
@@ -54,19 +52,7 @@ export function buildResolveCommandInstruction(resolveCommand) {
     instructions.push('Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.');
     return instructions;
 }
-/**
- * Build the CI-triage instruction. The per-conclusion rerun policy (GitHub Actions log
- * excerpts, `gh run view`/`gh run rerun` rules for CANCELLED/STARTUP_FAILURE/external
- * failures) is invariant text keyed on the `[conclusion: …]` tags already rendered in
- * `## Failing checks` — it lives in the pr-shepherd skill's "CI failure triage" playbook
- * instead of being re-emitted every tick. This supersedes the "CI budget rules" example in
- * CLAUDE.md's "Keep skills and loop prompts minimal" section (see that section's amendment
- * note). The `(no runId)` case stays here because it flips `buildFixCompletionInstruction`
- * to a human-handoff terminal state — that trigger, unlike the others, is CLI-decided. The
- * CLI sentence does not claim every failure has a log excerpt to read (only GitHub Actions
- * checks with a runId do — CANCELLED, STARTUP_FAILURE, and external checks may not); that
- * per-kind detail is exactly what the skill playbook table disambiguates.
- */
+/** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
 export function buildFailingCheckInstructions(checks) {
     if (checks.length === 0)
         return [];
@@ -74,17 +60,30 @@ export function buildFailingCheckInstructions(checks) {
     const hasTriageable = checks.some((c) => c.runId || c.detailsUrl);
     const instructions = [];
     if (hasTriageable) {
-        instructions.push('Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for `gh run view` / `gh run rerun` rules.');
+        instructions.push('Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.');
     }
     if (hasBare) {
         instructions.push("For each `(no runId)` failure, escalate to a human because no log or URL is available.");
     }
     return instructions;
 }
-export function buildFixCompletionInstruction(checks) {
-    const requiresHumanHandoff = checks.some((check) => !check.runId && !check.detailsUrl);
-    if (requiresHumanHandoff) {
+export function buildFixCompletionInstruction(checks, requiresRemoteUpdateAuthorization = false, hasShaGatedReviewMutations = false) {
+    if (requiresRemoteUpdateAuthorization) {
+        return "`[FIX_CODE]` requires a human handoff for an authorized push after conflict resolution. Shepherd cannot verify the Git credential's push authorization. Stop polling after committing, and resume only after the remote PR head changes.";
+    }
+    const hasUninspectableFailure = checks.some((check) => !check.runId && !check.detailsUrl);
+    const hasCiAuthorizationHandoff = checks.some((check) => check.conclusion === "CANCELLED" ||
+        check.conclusion === "STARTUP_FAILURE" ||
+        (check.runId === null && Boolean(check.detailsUrl)) ||
+        (check.runId !== null && !check.logExcerpt?.trim()));
+    if (hasUninspectableFailure) {
         return "`[FIX_CODE]` requires a human handoff for an uninspectable failing check. Stop polling after escalating, and resume only after human direction.";
     }
+    if (hasCiAuthorizationHandoff) {
+        return "`[FIX_CODE]` requires a human handoff for a failing check with no authorized follow-up action. Stop polling after escalating, and resume only after human direction.";
+    }
+    if (hasShaGatedReviewMutations) {
+        return "`[FIX_CODE]` is conditional: if you changed code, stop after committing and resume only after an authorized push changes the remote PR head; if you did not change code, complete the authorized review mutations and iterate again with the same options.";
+    }
     return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.";
 }

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

@@ -1,4 +1,4 @@
-import type { AgentThread, Review, ResolveCommand, AgentCheck, ReviewThread } from "../../types.mts";
+import type { AgentThread, Review, ResolveCommand, AgentCheck, ReviewThread, ViewerAuthorization } from "../../types.mts";
 import { type NormalizedBotUsernames } from "../../comments/authors.mts";
 import type { MinimizeCommentsPolicy } from "../../config/load.mts";
 export declare function classifyReviewSummaries(summaries: {
@@ -12,7 +12,7 @@ export declare function classifyReviewSummaries(summaries: {
     editedSummaries: Review[];
     surfacedApprovals: Review[];
 };
-export declare function buildResolveCommand(threads: AgentThread[], resolutionOnlyThreads: ReviewThread[], allCommentIds: string[], reviews: Review[], checks: AgentCheck[], prNumber: number, botUsernames?: NormalizedBotUsernames, ruleAutoResolveThreadIds?: string[]): {
+export declare function buildResolveCommand(threads: AgentThread[], resolutionOnlyThreads: ReviewThread[], allCommentIds: string[], reviews: Review[], checks: AgentCheck[], prReference: string | number, botUsernames?: NormalizedBotUsernames, ruleAutoResolveThreadIds?: string[], viewerAuthorization?: ViewerAuthorization, authorizationThreads?: ReviewThread[]): {
     resolveCommand: ResolveCommand;
     resolveOnlyCommand?: ResolveCommand;
 };

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,6 +26,8 @@ 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): string;
+export declare function buildEscalateHumanMessage(escalate: Omit<EscalateDetails, "humanMessage">, pr: string | number, opts?: {
+    merge?: boolean;
+}): string;
 export declare function buildEscalateSuggestion(triggers: EscalateTrigger[], detail?: string): string;
 export {};

package/bin/commands/iterate/escalate.mjs

@@ -59,7 +59,7 @@ export function validateBaseBranch(raw) {
     }
     return { branch: trimmed, isFallback: false };
 }
-export function buildEscalateHumanMessage(escalate, pr) {
+export function buildEscalateHumanMessage(escalate, pr, opts) {
     const lines = [];
     lines.push("⚠️ /pr-shepherd:pr-shepherd paused — manual intervention required");
     lines.push("");
@@ -109,6 +109,26 @@ export function buildEscalateHumanMessage(escalate, pr) {
             lines.push("");
         }
     }
+    if (escalate.mergeQueueRemoval) {
+        const removal = escalate.mergeQueueRemoval;
+        lines.push("");
+        lines.push("## Merge queue removal");
+        lines.push("");
+        lines.push(`- reason: \`${removal.reason ?? "not provided"}\``);
+        if (removal.actor)
+            lines.push(`- actor: \`@${removal.actor}\``);
+        lines.push(`- createdAtUnix: \`${removal.createdAtUnix}\``);
+        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");
@@ -120,10 +140,17 @@ export function buildEscalateHumanMessage(escalate, pr) {
     lines.push("");
     lines.push("---");
     lines.push("");
-    lines.push(`After completing manual fixes (and pushing if required), rerun \`/pr-shepherd:pr-shepherd ${pr}\` to resume.`);
+    lines.push(`After completing manual fixes (and pushing if required), rerun \`/pr-shepherd:pr-shepherd ${pr}${opts?.merge ? " --merge" : ""}\` to resume.`);
     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.`;
+    }
     if (triggers.includes("stall-timeout")) {
         const duration = detail ?? "60 minutes";
         return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;