pr-shepherd 0.46.5 → 0.46.7

package/bin/cli/list-formatters.d.mts

@@ -35,9 +35,10 @@ export declare function renderThreadBullet(t: ThreadBulletInput, opts?: {
     renderSuggestion?: boolean;
     noBody?: boolean;
     suppressEditedMarker?: boolean;
+    verbose?: boolean;
 }): string;
-export declare function renderThreadConversation(t: ThreadBulletInput): string;
-export declare function blockquote(body: string): string;
+export declare function renderThreadConversation(t: ThreadBulletInput, verbose?: boolean): string;
+export declare function blockquote(body: string, maxChars?: number, url?: string): string;
 export declare function renderCommentBullet(c: {
     id: string;
     url?: string;
@@ -74,5 +75,5 @@ export declare function renderReviewListSection(heading: string, items: {
  * Threads that also appear in resolutionOnlyIds have their body suppressed
  * (already shown in `## Review threads to resolve`).
  */
-export declare function buildFirstLookBullets(firstLookThreads: FirstLookThread[], resolutionOnlyIds: Set<string>, firstLookComments: FirstLookComment[]): string[];
+export declare function buildFirstLookBullets(firstLookThreads: FirstLookThread[], resolutionOnlyIds: Set<string>, firstLookComments: FirstLookComment[], verbose?: boolean): string[];
 export {};

package/bin/cli/list-formatters.mjs

@@ -1,5 +1,6 @@
 import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
 import { threadComments } from "../threads/transcript.mjs";
+import { truncateBody, BODY_TRUNCATE_MAX_CHARS, NESTED_BODY_TRUNCATE_MAX_CHARS, } from "./body-truncate.mjs";
 const BODY_PREVIEW_MAX = 100;
 export function renderAuthor(author, authorType, authorAssociation, viewerDidAuthor) {
     return [`@${author}`, authorType, authorAssociation, viewerDidAuthor ? "viewer-authored" : null]
@@ -41,48 +42,54 @@ export function renderThreadBullet(t, opts = {}) {
     }
     const parts = [bulletLine];
     if (!opts.noBody) {
-        parts.push(renderThreadCommentBullets(t));
+        parts.push(renderThreadCommentBullets(t, opts.verbose));
     }
     if (t.suggestion && opts.renderSuggestion) {
         parts.push(renderSuggestionBlock(t.suggestion));
     }
     return parts.join("\n");
 }
-export function renderThreadConversation(t) {
-    if (!t.comments || t.comments.length === 0)
-        return blockquote(t.body);
+export function renderThreadConversation(t, verbose = false) {
+    const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
+    if (!t.comments || t.comments.length === 0) {
+        return blockquote(t.body, topCap, t.url);
+    }
+    const nestedCap = verbose ? undefined : NESTED_BODY_TRUNCATE_MAX_CHARS;
     return threadComments(t)
-        .map((c) => {
+        .map((c, i) => {
         const heading = c.id
             ? c.url
                 ? `#### [commentId=${c.id}](${c.url}) (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`
                 : `#### \`commentId=${c.id}\` (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`
             : `#### (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`;
-        return `${heading}\n\n${blockquote(c.body)}`;
+        return `${heading}\n\n${blockquote(c.body, i === 0 ? topCap : nestedCap, c.url)}`;
     })
         .join("\n\n");
 }
-export function blockquote(body) {
-    return body
+export function blockquote(body, maxChars, url) {
+    const text = maxChars === undefined ? body : truncateBody(body, maxChars, url);
+    return text
         .replace(/\r\n/g, "\n")
         .split("\n")
         .map((line) => (line === "" ? ">" : `> ${line}`))
         .join("\n");
 }
-function renderThreadCommentBullets(t) {
+function renderThreadCommentBullets(t, verbose = false) {
+    const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
+    const nestedCap = verbose ? undefined : NESTED_BODY_TRUNCATE_MAX_CHARS;
     return threadComments(t)
-        .map((c) => {
+        .map((c, i) => {
         const link = c.url ? ` [↗](${c.url})` : "";
         const id = c.id ? `\`commentId=${c.id}\`` : "comment";
         return [
             `  - ${id}${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation, c.viewerDidAuthor)})`,
-            indentBlockquote(c.body, "    "),
+            indentBlockquote(c.body, "    ", i === 0 ? topCap : nestedCap, c.url),
         ].join("\n");
     })
         .join("\n");
 }
-function indentBlockquote(body, indent) {
-    return blockquote(body)
+function indentBlockquote(body, indent, maxChars, url) {
+    return blockquote(body, maxChars, url)
         .split("\n")
         .map((line) => `${indent}${line}`)
         .join("\n");
@@ -118,13 +125,14 @@ export function renderReviewListSection(heading, items) {
  * Threads that also appear in resolutionOnlyIds have their body suppressed
  * (already shown in `## Review threads to resolve`).
  */
-export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, firstLookComments) {
+export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, firstLookComments, verbose = false) {
     const bullets = [];
     for (const t of firstLookThreads) {
         bullets.push(renderThreadBullet(t, {
             statusTag: renderFirstLookStatusTag(t),
             noBody: resolutionOnlyIds.has(t.id),
             suppressEditedMarker: true,
+            verbose,
         }));
     }
     for (const c of firstLookComments) {

package/bin/commands/check-annotations.d.mts

@@ -1,6 +1,21 @@
 import { type AnnotationCacheOptions } from "../github/check-annotations.mts";
 import type { CheckAnnotation, ClassifiedCheck, ShepherdReport, TriagedCheck } from "../types.mts";
 export declare function checksWithActionableAnnotations(report: ShepherdReport): TriagedCheck[];
+/**
+ * True when GitHub itself is already acting on this PR regardless of Shepherd (a failing
+ * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
+ * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
+ * the seen-marker suppression gate there can't drift from the actual iterate dispatch
+ * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * seen markers must not be suppressed just because the PR happens to be queued).
+ */
+export declare function hasCheckDrivenActionableWork(checks: {
+    failing: TriagedCheck[];
+    passing: ClassifiedCheck[];
+    skipped: ClassifiedCheck[];
+    filtered: ClassifiedCheck[];
+    ignored?: TriagedCheck[];
+}, mergeStatusValue: string): boolean;
 export declare function attachAndMergeCheckAnnotations(buckets: {
     passing: ClassifiedCheck[];
     failing: TriagedCheck[];

package/bin/commands/check-annotations.mjs

@@ -2,6 +2,9 @@ import { fetchCheckRunAnnotations, } from "../github/check-annotations.mjs";
 function shouldFetchCheckAnnotations(check) {
     return check.id != null && check.status === "COMPLETED" && check.hasAnnotations === true;
 }
+function hasActionableAnnotation(check) {
+    return check.conclusion !== "SUCCESS" && (check.annotations?.length ?? 0) > 0;
+}
 export function checksWithActionableAnnotations(report) {
     return [
         ...report.checks.failing,
@@ -9,7 +12,26 @@ export function checksWithActionableAnnotations(report) {
         ...report.checks.skipped,
         ...report.checks.filtered,
         ...(report.checks.ignored ?? []),
-    ].filter((c) => c.conclusion !== "SUCCESS" && (c.annotations?.length ?? 0) > 0);
+    ].filter(hasActionableAnnotation);
+}
+/**
+ * True when GitHub itself is already acting on this PR regardless of Shepherd (a failing
+ * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
+ * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
+ * the seen-marker suppression gate there can't drift from the actual iterate dispatch
+ * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * seen markers must not be suppressed just because the PR happens to be queued).
+ */
+export function hasCheckDrivenActionableWork(checks, mergeStatusValue) {
+    return (checks.failing.length > 0 ||
+        [
+            ...checks.failing,
+            ...checks.passing,
+            ...checks.skipped,
+            ...checks.filtered,
+            ...(checks.ignored ?? []),
+        ].some(hasActionableAnnotation) ||
+        mergeStatusValue === "CONFLICTS");
 }
 export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber, cacheOpts) {
     const candidates = [

package/bin/commands/check.d.mts

@@ -4,4 +4,5 @@ export declare function runCheck(opts: GlobalOptions & {
     autoMinimizeSuppressed?: boolean;
     skipTriage?: boolean;
     persistSeen?: boolean;
+    merge?: boolean;
 }): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -7,7 +7,7 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { annotationMarkerBody, attachAndMergeCheckAnnotations } from "./check-annotations.mjs";
+import { annotationMarkerBody, attachAndMergeCheckAnnotations, hasCheckDrivenActionableWork, } from "./check-annotations.mjs";
 import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
@@ -17,7 +17,7 @@ import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, }
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
-import { buildThreadMutationRouting, canResolveOutdatedBotWithoutLocation, } from "./iterate/thread-mutation-routing.mjs";
+import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./iterate/thread-mutation-routing.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -47,9 +47,16 @@ export async function runCheck(opts) {
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedPrChecks = classifyChecks(allChecks);
     const latestRemoval = batchData.latestMergeQueueRemoval;
+    // `timelineItems(last: 1, ...)` returns the single most recent removal regardless of age, so
+    // a PR removed from the queue once, long ago, and never re-added keeps returning that same
+    // historical event forever. When GitHub omits the removed queue commit for that old event
+    // (e.g. after the synthetic commit is garbage collected), freshness is unverifiable — treat
+    // it as stale/updated rather than as still current, so Shepherd doesn't escalate
+    // `merge-queue-removed` permanently on data it can no longer check. The raw removal fields
+    // still render in the merge-queue header regardless of this flag.
     const headUpdatedAfterRemoval = Boolean(latestRemoval &&
-        latestRemoval.beforeCommitParentOids &&
-        !latestRemoval.beforeCommitParentOids.includes(batchData.headRefOid));
+        (!latestRemoval.beforeCommitParentOids ||
+            !latestRemoval.beforeCommitParentOids.includes(batchData.headRefOid)));
     const queueRawChecks = batchData.isInMergeQueue
         ? (batchData.mergeQueueChecks ?? [])
         : latestRemoval && !headUpdatedAfterRemoval
@@ -83,17 +90,14 @@ export async function runCheck(opts) {
     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 visibleThreadCandidates = batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id));
-    const threadMutationRouting = buildThreadMutationRouting(visibleThreadCandidates, botUsernames, partition.ruleAutoResolveThreadIds);
+    const resolveOtherHumanThreads = config.iterate.resolveOtherHumanThreads ?? "none";
+    const threadMutationRouting = buildThreadMutationRouting(visibleThreadCandidates, botUsernames, partition.ruleAutoResolveThreadIds, resolveOtherHumanThreads);
     const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
     const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
     const repeatableThreadIds = new Set(visibleThreadCandidates
-        .filter((thread) => (thread.path !== null &&
-        thread.line !== null &&
-        (!replyThreadIds.has(thread.id) || thread.viewerCanReply === true) &&
-        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true)) ||
-        canResolveOutdatedBotWithoutLocation(thread, botUsernames))
+        .filter((thread) => threadHasAuthorizedMutation(thread, replyThreadIds, resolveThreadIds))
         .map((thread) => thread.id));
-    const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds);
+    const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds, resolveOtherHumanThreads);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -118,6 +122,51 @@ export async function runCheck(opts) {
     }
     const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames, batchData.viewerAuthorization?.viewerCanAdminister === true);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
+    const changesRequestedReviews = changesRequestedReviewVisibility.visible;
+    const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
+    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((review) => {
+        if (partition.suppressedChangesRequestedIds.has(review.id))
+            return false;
+        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
+        return (!isBot ||
+            batchData.viewerAuthorization?.viewerCanAdminister === true ||
+            visibleChangesRequestedIds.has(review.id));
+    }).length;
+    const approvedReviews = approvedReviewVisibility.visible;
+    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
+    // Resolve any pending mergeability refresh (and the resulting MERGED/CLOSED short-circuit)
+    // before deciding what to persist below — deferWhileQueued must see the same final,
+    // possibly-refreshed mergeStatus that commands/iterate/index.mts acts on, not the pre-refresh
+    // snapshot. A conflict newly discovered by this REST read is exactly the kind of check-driven
+    // signal that keeps a queued PR out of the deferral path.
+    if (status === "READY" && !didRefreshMergeability) {
+        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount);
+        batchData = refreshed.batchData;
+        mergeStatus = refreshed.mergeStatus;
+        status = refreshed.status;
+        if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
+            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        }
+    }
+    // Mirrors the deferral gate in commands/iterate/index.mts exactly (via the shared
+    // hasCheckDrivenActionableWork helper, so the two can't drift): when this tick's non-CI
+    // actionable work (threads/comments/review summaries/changes-requested) will be held back
+    // because the PR is queued, none of it was actually shown to the agent this tick —
+    // persisting seen markers for it now would make it silently vanish from every later tick
+    // once it's no longer "new" or "edited", even after the PR leaves the queue. A queued PR
+    // that also has check-driven work (failing checks, actionable annotations, conflicts) is
+    // NOT deferred — index.mts still renders these items via fix_code — so this must stay false
+    // in that case too, or their seen markers would be suppressed while actually being shown.
+    const deferWhileQueued = opts.merge === true &&
+        batchData.isInMergeQueue === true &&
+        config.actions.workWhileQueued !== true &&
+        !hasCheckDrivenActionableWork({
+            failing: merged.failing,
+            passing: merged.passing,
+            skipped: merged.skipped,
+            filtered: merged.filtered,
+            ignored: merged.ignored,
+        }, mergeStatus.status);
     if (opts.persistSeen !== false) {
         const successfulAnnotations = [
             ...merged.passing,
@@ -127,19 +176,24 @@ export async function runCheck(opts) {
         ]
             .filter((check) => check.conclusion === "SUCCESS")
             .flatMap((check) => check.annotations ?? []);
+        const deferredMarkSeen = deferWhileQueued
+            ? []
+            : [
+                ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+                ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
+                ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
+                ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
+                ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+                ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ];
         await Promise.allSettled([
             ...successfulAnnotations.map((a) => markSeen(stateKey, a.id, annotationMarkerBody(a))),
-            ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
-            ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-            ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
-            ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
-            ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-            ...approvedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
+            ...deferredMarkSeen,
             ...batchData.comments
-                .filter((c) => partition.suppressedCommentIds.has(c.id))
+                .filter((c) => partition.suppressedCommentIds.has(c.id) && !deniedRuleAutoResolveCommentIds.has(c.id))
                 .map((c) => markSeen(stateKey, c.id, c.body)),
             ...batchData.reviewThreads
-                .filter((t) => partition.suppressedThreadIds.has(t.id))
+                .filter((t) => partition.suppressedThreadIds.has(t.id) && !deniedRuleAutoResolveThreadIds.has(t.id))
                 .map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
             ...batchData.reviewSummaries
                 .filter((r) => partition.suppressedReviewSummaryIds.has(r.id) &&
@@ -163,27 +217,6 @@ export async function runCheck(opts) {
         ...authorizedRuleAutoResolveThreadIds,
         ...[...deniedRuleAutoResolveThreadIds].filter((id) => visibleMutationThreadIds.has(id)),
     ];
-    const changesRequestedReviews = changesRequestedReviewVisibility.visible;
-    const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
-    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((review) => {
-        if (partition.suppressedChangesRequestedIds.has(review.id))
-            return false;
-        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
-        return (!isBot ||
-            batchData.viewerAuthorization?.viewerCanAdminister === true ||
-            visibleChangesRequestedIds.has(review.id));
-    }).length;
-    const approvedReviews = approvedReviewVisibility.visible;
-    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
-    if (status === "READY" && !didRefreshMergeability) {
-        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount);
-        batchData = refreshed.batchData;
-        mergeStatus = refreshed.mergeStatus;
-        status = refreshed.status;
-        if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
-            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
-        }
-    }
     const blockedByFilteredCheck = isBlockedByFilteredCheck(mergeStatus, verdict);
     const queueCommit = batchData.isInMergeQueue
         ? batchData.mergeQueueEntry?.headCommitOid

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

@@ -58,7 +58,7 @@ export function buildResolveCommandInstruction(resolveCommand) {
         return [];
     const instructions = [];
     if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
-        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.");
+        instructions.push("Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an established Shepherd reply; a marked thread that is still being resolved is emitted resolve-only, not for another reply.");
     }
     if (resolveCommand.requiresHeadSha) {
         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, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA.");

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

@@ -1,6 +1,6 @@
 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";
+import type { MinimizeCommentsPolicy, ResolveOtherHumanThreads } from "../../config/load.mts";
 export declare function classifyReviewSummaries(summaries: {
     firstLook: Review[];
     seen: Review[];
@@ -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[], prReference: string | number, botUsernames?: NormalizedBotUsernames, ruleAutoResolveThreadIds?: string[], viewerAuthorization?: ViewerAuthorization, authorizationThreads?: ReviewThread[]): {
+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[], resolveOtherHumanThreads?: ResolveOtherHumanThreads): {
     resolveCommand: ResolveCommand;
     resolveOnlyCommand?: ResolveCommand;
 };

package/bin/commands/iterate/classify.mjs

@@ -58,9 +58,9 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prReference, botUsernames = new Set(), ruleAutoResolveThreadIds = [], viewerAuthorization, authorizationThreads = []) {
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prReference, botUsernames = new Set(), ruleAutoResolveThreadIds = [], viewerAuthorization, authorizationThreads = [], resolveOtherHumanThreads = "none") {
     const allThreads = [...threads, ...resolutionOnlyThreads];
-    const routed = buildThreadMutationRouting(allThreads, botUsernames, ruleAutoResolveThreadIds);
+    const routed = buildThreadMutationRouting(allThreads, botUsernames, ruleAutoResolveThreadIds, resolveOtherHumanThreads);
     const canReply = new Set(authorizationThreads
         .filter((thread) => thread.viewerCanReply === true)
         .map((thread) => thread.id));

package/bin/commands/iterate/escalate.mjs

@@ -1,4 +1,5 @@
 import { loadConfig } from "../../config/load.mjs";
+import { inlineCode } from "../../util/markdown.mjs";
 function renderEscalateAuthor(item) {
     return [`@${item.author}`, item.authorType, item.authorAssociation].filter(Boolean).join(" · ");
 }
@@ -176,6 +177,10 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
         if (removal.beforeCommitOid)
             lines.push(`- queue commit: \`${removal.beforeCommitOid}\``);
     }
+    if (escalate.stack) {
+        const s = escalate.stack;
+        lines.push("", "## GitHub stack", "", `- layer: \`${s.position}\` of \`${s.size}\` in stack \`${s.number}\``, `- stack base: ${inlineCode(s.baseRefName)}`);
+    }
     if (escalate.authorization && escalate.authorization.length > 0) {
         lines.push("");
         lines.push("## Authorization");
@@ -199,6 +204,10 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
+    if (triggers.includes("stacked-pr")) {
+        const selector = detail ?? "<pr>";
+        return `This PR belongs to a GitHub stack, so Shepherd will not emit a merge command. \`gh pr merge\` targets the PR's own base branch — for a mid-stack layer that is the unmerged parent branch, not the stack's base — and auto-merge is unsupported on stacked PRs. Merge from the GitHub stack UI, or run \`gh stack merge --squash ${selector}\` (requires the \`github/gh-stack\` extension — run \`gh extension install github/gh-stack\` first if it's not installed), which lands this PR and every unmerged layer below it.`;
+    }
     if (triggers.includes("check-follow-up-unavailable")) {
         return "One or more failing checks have no autonomous follow-up available. Use the displayed conclusion, run or URL, and included evidence to handle them manually.";
     }

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

@@ -5,7 +5,7 @@ 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, canResolveOutdatedBotWithoutLocation, } from "./thread-mutation-routing.mjs";
+import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thread-mutation-routing.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
@@ -55,9 +55,8 @@ export async function handleFixCode(ctx) {
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
     const allThreads = [...report.threads.actionable, ...report.threads.resolutionOnly];
     const ruleAutoResolveIds = new Set(ruleAutoResolveThreadIds ?? []);
-    const routedThreadMutations = buildThreadMutationRouting(allThreads, botUsernames, [
-        ...ruleAutoResolveIds,
-    ]);
+    const resolveOtherHumanThreads = loadConfig().iterate.resolveOtherHumanThreads ?? "none";
+    const routedThreadMutations = buildThreadMutationRouting(allThreads, botUsernames, [...ruleAutoResolveIds], resolveOtherHumanThreads);
     const replyIdSet = new Set(routedThreadMutations.replyThreadIds);
     const resolveIdSet = new Set(routedThreadMutations.resolveThreadIds);
     const unauthorizedReplies = allThreads.filter((thread) => replyIdSet.has(thread.id) && thread.viewerCanReply !== true);
@@ -65,7 +64,10 @@ export async function handleFixCode(ctx) {
     const unauthorizedDismissals = report.changesRequestedReviews.filter((review) => (!isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames)) &&
         report.viewerAuthorization?.viewerCanAdminister !== true);
     const skippedThreadIds = new Set([...unauthorizedReplies, ...unauthorizedResolves].map((thread) => thread.id));
-    const retryableActionableThreads = report.threads.actionable.filter((thread) => !skippedThreadIds.has(thread.id) && thread.path !== null && thread.line !== null);
+    const mutationActionableThreads = report.threads.actionable.filter((thread) => !skippedThreadIds.has(thread.id) &&
+        ((thread.path !== null && thread.line !== null) ||
+            threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
+    const retryableActionableThreads = mutationActionableThreads.filter((thread) => thread.path !== null && thread.line !== null);
     const protectedRuns = [];
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, retryableActionableThreads);
@@ -168,7 +170,7 @@ export async function handleFixCode(ctx) {
     const changesRequestedReviewsForWork = actionableChangesRequestedReviews.filter((review) => !skippedDismissalIds.has(review.id));
     const resolutionOnlyThreadsForWork = resolutionOnlyThreads.filter((thread) => !skippedThreadIds.has(thread.id) &&
         ((thread.path !== null && thread.line !== null) ||
-            canResolveOutdatedBotWithoutLocation(thread, botUsernames)));
+            threadHasAuthorizedMutation(thread, replyIdSet, resolveIdSet)));
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
     const { behindBaseHint } = loadConfig().iterate;
@@ -223,9 +225,9 @@ export async function handleFixCode(ctx) {
     }
     // Push access to the PR head branch is a usage precondition. Build review mutations for
     // conflict ticks normally so the caller can push and complete the same fix_code cycle.
-    const retryableActionableIds = new Set(retryableActionableThreads.map((thread) => thread.id));
-    const retryableAgentThreads = threads.filter((thread) => retryableActionableIds.has(thread.id));
-    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(retryableAgentThreads, resolutionOnlyThreadsForWork, allCommentIds, changesRequestedReviewsForWork, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads);
+    const mutationActionableIds = new Set(mutationActionableThreads.map((thread) => thread.id));
+    const mutationAgentThreads = threads.filter((thread) => mutationActionableIds.has(thread.id));
+    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(mutationAgentThreads, resolutionOnlyThreadsForWork, allCommentIds, changesRequestedReviewsForWork, failingAgentChecks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
     // 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. Located resolution-only threads retain that guard;

package/bin/commands/iterate/fix-instruction-threads.d.mts

@@ -0,0 +1,14 @@
+import type { AgentThread, ResolveCommand } from "../../types.mts";
+export declare function partitionFixThreads(threads: AgentThread[], resolveCommand: ResolveCommand, resolveOnlyCommand?: ResolveCommand): {
+    locatedThreads: AgentThread[];
+    unlocatedMutatedThreads: AgentThread[];
+    unlocatedThreads: AgentThread[];
+};
+export declare function reviewSectionRefs(input: {
+    hasReviewThreads: boolean;
+    hasUnlocatedSkipThreads: boolean;
+    hasActionableComments: boolean;
+    hasFailingChecks: boolean;
+    hasAnnotations: boolean;
+    hasChangesRequested: boolean;
+}): string[];

package/bin/commands/iterate/fix-instruction-threads.mjs

@@ -0,0 +1,32 @@
+function mutatedThreadIdSet(resolveCommand, resolveOnlyCommand) {
+    return new Set([
+        ...(resolveCommand.replyThreadIds ?? []),
+        ...(resolveCommand.resolveThreadIds ?? []),
+        ...(resolveOnlyCommand?.replyThreadIds ?? []),
+        ...(resolveOnlyCommand?.resolveThreadIds ?? []),
+    ]);
+}
+export function partitionFixThreads(threads, resolveCommand, resolveOnlyCommand) {
+    const mutatedThreadIds = mutatedThreadIdSet(resolveCommand, resolveOnlyCommand);
+    return {
+        locatedThreads: threads.filter((thread) => thread.path !== null && thread.line !== null),
+        unlocatedMutatedThreads: threads.filter((thread) => (thread.path === null || thread.line === null) && mutatedThreadIds.has(thread.id)),
+        unlocatedThreads: threads.filter((thread) => (thread.path === null || thread.line === null) && !mutatedThreadIds.has(thread.id)),
+    };
+}
+export function reviewSectionRefs(input) {
+    const sections = [];
+    if (input.hasReviewThreads)
+        sections.push("`## Review threads`");
+    if (input.hasUnlocatedSkipThreads)
+        sections.push("`## Unlocated review threads (logged once — no mutation)`");
+    if (input.hasActionableComments)
+        sections.push("`## Actionable comments`");
+    if (input.hasFailingChecks)
+        sections.push("`## Failing checks`");
+    if (input.hasAnnotations)
+        sections.push("`## Check annotations`");
+    if (input.hasChangesRequested)
+        sections.push("`## Changes-requested reviews`");
+    return sections;
+}

package/bin/commands/iterate/index.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { runCheck } from "../check.mjs";
 import { updateReadyDelay } from "../ready-delay.mjs";
 import { getCurrentPrNumber } from "../../github/client.mjs";
@@ -10,8 +11,8 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 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 { hasCheckDrivenActionableWork } from "../check-annotations.mjs";
+import { buildReadyMergeOutcome, handleActiveMergeState } from "./merge-state.mjs";
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
 import { withIterateApiUsage } from "./run.mjs";
@@ -73,9 +74,7 @@ async function runIterateCore(opts) {
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.comments.firstLook.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
-        report.checks.failing.length > 0 ||
-        checksWithActionableAnnotations(report).length > 0 ||
-        report.mergeStatus.status === "CONFLICTS" ||
+        hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status) ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0 ||
@@ -85,7 +84,16 @@ async function runIterateCore(opts) {
     const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName);
     const base = buildIterateBase(report, readyState);
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
-    if (hasActionableWork) {
+    // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
+    // GitHub itself is already acting on — the queue will eject the PR for these regardless of
+    // what Shepherd does, so they always surface immediately. Only review threads/comments/
+    // changes-requested reviews/review summaries — the categories that would otherwise cause a
+    // Shepherd-initiated push while the PR sits safely in the queue — are eligible for deferral.
+    const checkDrivenActionableWork = hasCheckDrivenActionableWork(report.checks, report.mergeStatus.status);
+    const deferWhileQueued = opts.merge === true &&
+        report.mergeQueue?.inQueue === true &&
+        config.actions.workWhileQueued !== true;
+    if (hasActionableWork && !(deferWhileQueued && !checkDrivenActionableWork)) {
         return handleFixCode({
             base,
             report,
@@ -110,6 +118,11 @@ async function runIterateCore(opts) {
         base,
         report,
         stallKey,
+        reviewSummaryIds,
+        firstLookSummaries,
+        editedSummaries,
+        surfacedApprovals,
+        minimizeApprovals: config.iterate.minimizeApprovals,
     });
     if (mergeStateResult)
         return mergeStateResult;
@@ -121,7 +134,7 @@ async function runIterateCore(opts) {
         return markReadyResult;
     if (readyState.shouldCancel) {
         await clearStallState(stallKey);
-        const mergeResult = buildReadyMergeResult(opts.merge, true, base, report);
+        const mergeResult = buildReadyMergeOutcome(opts.merge, true, base, report);
         if (mergeResult)
             return mergeResult;
         const cancelNote = blockedCancelNote(base);

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

@@ -1,15 +1,20 @@
-import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+import type { IterateResult, IterateResultBase, Review, 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 buildReadyMergeOutcome(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;
+    reviewSummaryIds: string[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    surfacedApprovals: Review[];
+    minimizeApprovals: boolean;
 }): Promise<IterateResult | null>;
 export {};