pr-shepherd 0.46.5 → 0.46.7

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

@@ -2,9 +2,34 @@ 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) {
+/** A stacked PR's merge is human-only: `gh pr merge` targets the PR's own base, which for a
+ * mid-stack layer is an unmerged parent branch, and auto-merge is unsupported on stacks. */
+function buildStackedEscalateResult(base, report, stack) {
+    const escalateBase = {
+        triggers: ["stacked-pr"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        stack,
+        suggestion: buildEscalateSuggestion(["stacked-pr"], String(report.pr)),
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalateBase,
+            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
+                merge: true,
+            }),
+        },
+    };
+}
+export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
     if (!enabled || !readyElapsed || report.mergeStatus.isDraft)
         return null;
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (stack)
+        return buildStackedEscalateResult(base, report, stack);
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
     return {
@@ -19,14 +44,55 @@ export function buildReadyMergeResult(enabled, readyElapsed, base, report) {
         }),
     };
 }
+/** Raw counts of non-CI actionable work held back for one queued-PR wait tick. Omitted (all zero) when empty. */
+function buildDeferredWork(input) {
+    const { report, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, minimizeApprovals, } = input;
+    // These buckets are not disjoint (e.g. an unresolved outdated thread is both
+    // `resolutionOnly` and `firstLook`; an eligible-to-minimize comment/summary is both
+    // `actionable`/`firstLook` and queued in `minimizeIds`/`reviewSummaryIds`) — dedupe by ID.
+    const threadIds = new Set([
+        ...report.threads.actionable.map((t) => t.id),
+        ...report.threads.resolutionOnly.map((t) => t.id),
+        ...report.threads.firstLook.map((t) => t.id),
+        ...(report.threads.ruleAutoResolveIds ?? []),
+    ]);
+    const commentIds = new Set([
+        ...report.comments.actionable.map((c) => c.id),
+        ...(report.comments.minimizeIds ?? []),
+        ...report.comments.firstLook.map((c) => c.id),
+    ]);
+    const reviewSummaryIdSet = new Set([
+        ...reviewSummaryIds,
+        ...firstLookSummaries.map((r) => r.id),
+        ...editedSummaries.map((r) => r.id),
+        ...(minimizeApprovals ? surfacedApprovals.map((r) => r.id) : []),
+    ]);
+    const deferredWork = {
+        threads: threadIds.size,
+        comments: commentIds.size,
+        changesRequestedReviews: report.changesRequestedReviews.length,
+        reviewSummaries: reviewSummaryIdSet.size,
+    };
+    const total = deferredWork.threads +
+        deferredWork.comments +
+        deferredWork.changesRequestedReviews +
+        deferredWork.reviewSummaries;
+    return total > 0 ? deferredWork : undefined;
+}
 export async function handleActiveMergeState(input) {
     const { enabled, active, base, report, stallKey } = input;
+    const inQueue = report.mergeQueue?.inQueue === true;
     if (enabled && active) {
         await clearStallState(stallKey);
+        // Only the queued case ever holds back non-CI actionable work (see the `deferWhileQueued`
+        // gate in index.mts, which requires `inQueue === true`); an ordinary active auto-merge
+        // request with no queue membership never defers anything, so it never carries counts here.
+        const deferredWork = inQueue ? buildDeferredWork(input) : undefined;
         return {
             ...base,
             action: "wait",
-            log: report.mergeQueue?.inQueue
+            ...(deferredWork && { deferredWork }),
+            log: inQueue
                 ? `WAIT: PR #${report.pr} is in the merge queue`
                 : `WAIT: PR #${report.pr} has auto-merge enabled`,
         };

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, 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
+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, hasExhaustedWorkflowRerun?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -3,6 +3,7 @@ import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintI
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
+import { partitionFixThreads, reviewSectionRefs } from "./fix-instruction-threads.mjs";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export function renderResolveCommand(rc) {
     const parts = [...rc.argv];
@@ -10,11 +11,10 @@ export function renderResolveCommand(rc) {
         parts.push("--require-sha", "$HEAD_SHA");
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+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, hasExhaustedWorkflowRerun = false) {
     const instructions = [];
-    const locatedThreads = threads.filter((thread) => thread.path !== null && thread.line !== null);
-    const unlocatedThreads = threads.filter((thread) => thread.path === null || thread.line === null);
+    const { locatedThreads, unlocatedMutatedThreads, unlocatedThreads } = partitionFixThreads(threads, resolveCommand, resolveOnlyCommand);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
     const repeatedWorkflowBranchRecoveryInstructions = buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, {
         isBehind,
@@ -29,20 +29,14 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
         actionableComments.length > 0;
     // Start with interpretation. The agent decides what raw feedback warrants a code change.
     if (hasNonConflictHints) {
-        const actionableSections = [];
-        if (locatedThreads.length > 0)
-            actionableSections.push("`## Review threads`");
-        if (unlocatedThreads.length > 0)
-            actionableSections.push("`## Unlocated review threads (logged once — no mutation)`");
-        if (actionableComments.length > 0)
-            actionableSections.push("`## Actionable comments`");
-        if (failingChecks.length > 0)
-            actionableSections.push("`## Failing checks`");
-        if (hasAnnotations) {
-            actionableSections.push("`## Check annotations`");
-        }
-        if (changesRequestedReviews.length > 0)
-            actionableSections.push("`## Changes-requested reviews`");
+        const actionableSections = reviewSectionRefs({
+            hasReviewThreads: locatedThreads.length > 0 || unlocatedMutatedThreads.length > 0,
+            hasUnlocatedSkipThreads: unlocatedThreads.length > 0,
+            hasActionableComments: actionableComments.length > 0,
+            hasFailingChecks: failingChecks.length > 0,
+            hasAnnotations,
+            hasChangesRequested: changesRequestedReviews.length > 0,
+        });
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
@@ -65,10 +59,6 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
     if (unlocatedThreads.length > 0) {
         instructions.push("Acknowledge each item under `## Unlocated review threads (logged once — no mutation)`. Shepherd cannot route a code fix or review mutation without a path and line; the unchanged item will be skipped on later ticks.");
     }
-    // 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 = locatedThreads.some((t) => t.suggestion);
     if (hasSuggestions)
         instructions.push(buildCommitSuggestionInstruction(prReference, "## Review threads"));
@@ -111,7 +101,6 @@ isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");
-    instructions.push(...buildResolveCommandInstruction(resolveCommand));
-    instructions.push(buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
+    instructions.push(...buildResolveCommandInstruction(resolveCommand), buildFixCompletionInstruction(failingChecks, hasConflicts, resolveCommand.requiresHeadSha));
     return instructions;
 }

package/bin/commands/iterate/thread-mutation-routing.d.mts

@@ -1,10 +1,18 @@
 import { type NormalizedBotUsernames } from "../../comments/authors.mts";
+import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mts";
+import type { ResolveOtherHumanThreads } from "../../config/load.mts";
 import type { AgentThread, ReviewThread } from "../../types.mts";
+export { shouldResolveOtherHumanThread };
+export type RoutableThread = AgentThread | ReviewThread;
 export interface ThreadMutationRouting {
     replyThreadIds: string[];
     pairedResolveThreadIds: string[];
     standaloneResolveThreadIds: string[];
     resolveThreadIds: string[];
 }
-export declare function canResolveOutdatedBotWithoutLocation(thread: ReviewThread, botUsernames: NormalizedBotUsernames): boolean;
-export declare function buildThreadMutationRouting(threads: Array<AgentThread | ReviewThread>, botUsernames: NormalizedBotUsernames, ruleAutoResolveThreadIds: string[]): ThreadMutationRouting;
+export declare function threadHasAuthorizedMutation(thread: {
+    id: string;
+    viewerCanReply?: boolean;
+    viewerCanResolve?: boolean;
+}, replyThreadIds: ReadonlySet<string>, resolveThreadIds: ReadonlySet<string>): boolean;
+export declare function buildThreadMutationRouting(threads: RoutableThread[], botUsernames: NormalizedBotUsernames, ruleAutoResolveThreadIds: string[], policy?: ResolveOtherHumanThreads): ThreadMutationRouting;

package/bin/commands/iterate/thread-mutation-routing.mjs

@@ -1,29 +1,41 @@
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "../../comments/authors.mjs";
 import { threadEndedByShepherd } from "../../comments/marker.mjs";
+import { shouldResolveOtherHumanThread } from "../../comments/thread-resolve-policy.mjs";
+export { shouldResolveOtherHumanThread };
 function dedupeIds(ids) {
     return [...new Set(ids)];
 }
-export function canResolveOutdatedBotWithoutLocation(thread, botUsernames) {
-    return (!thread.isResolved &&
-        thread.isOutdated &&
-        (thread.path === null || thread.line === null) &&
-        isConfiguredBotAuthor(thread, botUsernames) &&
-        thread.viewerCanResolve === true);
+function isOrdinaryHuman(thread, botUsernames) {
+    return isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
 }
-export function buildThreadMutationRouting(threads, botUsernames, ruleAutoResolveThreadIds) {
-    const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
-    const replyThreadIds = dedupeIds(threads
-        .filter((thread) => isOrdinaryHuman(thread) && !threadEndedByShepherd(thread))
-        .map((thread) => thread.id));
+function shouldPairResolve(thread, botUsernames, policy = "none") {
+    if (!isOrdinaryHuman(thread, botUsernames))
+        return true;
+    if (isViewerAuthoredHuman(thread, botUsernames))
+        return true;
+    return shouldResolveOtherHumanThread(thread, policy);
+}
+export function threadHasAuthorizedMutation(thread, replyThreadIds, resolveThreadIds) {
+    const inReply = replyThreadIds.has(thread.id);
+    const inResolve = resolveThreadIds.has(thread.id);
+    if (!inReply && !inResolve)
+        return false;
+    if (inReply && thread.viewerCanReply !== true)
+        return false;
+    if (inResolve && thread.viewerCanResolve !== true)
+        return false;
+    return true;
+}
+export function buildThreadMutationRouting(threads, botUsernames, ruleAutoResolveThreadIds, policy = "none") {
+    const replyThreadIds = dedupeIds(threads.filter((thread) => !threadEndedByShepherd(thread)).map((thread) => thread.id));
     const pairedResolveThreadIds = dedupeIds(threads
-        .filter((thread) => isViewerAuthoredHuman(thread, botUsernames) && !threadEndedByShepherd(thread))
+        .filter((thread) => shouldPairResolve(thread, botUsernames, policy) && !threadEndedByShepherd(thread))
         .map((thread) => thread.id));
     const pairedResolveIdSet = new Set(pairedResolveThreadIds);
     // Rule-matched threads bypass author routing; resolve-mutate retains the human-author guard.
     const standaloneResolveThreadIds = dedupeIds([
         ...threads
-            .filter((thread) => !isOrdinaryHuman(thread) ||
-            (isViewerAuthoredHuman(thread, botUsernames) && threadEndedByShepherd(thread)))
+            .filter((thread) => shouldPairResolve(thread, botUsernames, policy) && threadEndedByShepherd(thread))
             .map((thread) => thread.id),
         ...ruleAutoResolveThreadIds,
     ]).filter((id) => !pairedResolveIdSet.has(id));

package/bin/commands/resolve-mutate.mjs

@@ -3,6 +3,7 @@ import { applyResolveOptions } from "../comments/resolve.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, normalizeBotUsernames, } from "../comments/authors.mjs";
+import { shouldResolveOtherHumanThread } from "./iterate/thread-mutation-routing.mjs";
 import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { addPrShepherdMarker, threadEndedByShepherd } from "../comments/marker.mjs";
@@ -31,14 +32,24 @@ export async function runResolveMutate(opts) {
     // print. Once a caller explicitly runs apply, GitHub's mutation response is
     // authoritative and this path must not second-guess that intent.
     const requestedReplyIds = new Set(opts.replyThreadIds ?? []);
-    const allowedViewerHumanResolveIds = new Set(data.reviewThreads
-        .filter((thread) => isViewerAuthoredHuman(thread, botUsernames) &&
-        (requestedReplyIds.has(thread.id) || threadEndedByShepherd(thread)))
+    const policy = config.iterate?.resolveOtherHumanThreads ?? "none";
+    const allowedHumanResolveIds = new Set(data.reviewThreads
+        .filter((thread) => {
+        if (!humanThreadIds.has(thread.id))
+            return false;
+        const paired = requestedReplyIds.has(thread.id) || threadEndedByShepherd(thread);
+        if (!paired)
+            return false;
+        if (isViewerAuthoredHuman(thread, botUsernames))
+            return true;
+        return shouldResolveOtherHumanThread(thread, policy);
+    })
         .map((thread) => thread.id));
-    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id) || allowedViewerHumanResolveIds.has(id));
-    const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !allowedViewerHumanResolveIds.has(id));
-    const replyThreadIds = opts.replyThreadIds?.filter((id) => humanThreadIds.has(id));
-    const skippedNonHumanReplies = (opts.replyThreadIds ?? []).filter((id) => !humanThreadIds.has(id));
+    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id) || allowedHumanResolveIds.has(id));
+    const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !allowedHumanResolveIds.has(id));
+    const knownThreadIds = new Set(data.reviewThreads.map((thread) => thread.id));
+    const replyThreadIds = opts.replyThreadIds?.filter((id) => knownThreadIds.has(id));
+    const skippedNonHumanReplies = (opts.replyThreadIds ?? []).filter((id) => !knownThreadIds.has(id));
     const minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id));
     const skippedHumanMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => humanCommentIds.has(id) || humanReviewIds.has(id));
     const dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && data.changesRequestedReviews.some((review) => review.id === id));

package/bin/comments/thread-resolve-policy.d.mts

@@ -0,0 +1,6 @@
+import type { ResolveOtherHumanThreads } from "../config/load.mts";
+import type { AgentThread, ReviewThread } from "../types.mts";
+type OutdatableThread = AgentThread | ReviewThread;
+/** Other-human threads are resolved only when the iterate enum allows it. */
+export declare function shouldResolveOtherHumanThread(thread: OutdatableThread, policy: ResolveOtherHumanThreads): boolean;
+export {};

package/bin/comments/thread-resolve-policy.mjs

@@ -0,0 +1,9 @@
+function threadIsOutdated(thread) {
+    return "isOutdated" in thread && thread.isOutdated === true;
+}
+/** Other-human threads are resolved only when the iterate enum allows it. */
+export function shouldResolveOtherHumanThread(thread, policy) {
+    if (policy === "always")
+        return true;
+    return policy === "outdated" && threadIsOutdated(thread);
+}

package/bin/comments/thread-visibility.d.mts

@@ -1,5 +1,6 @@
 import { type SeenMarker } from "../state/seen-comments.mts";
 import { type NormalizedBotUsernames } from "./authors.mts";
+import type { ResolveOtherHumanThreads } from "../config/load.mts";
 import type { FirstLookThread, ReviewThread } from "../types.mts";
 interface ThreadVisibility {
     activeThreads: ReviewThread[];
@@ -7,5 +8,5 @@ interface ThreadVisibility {
     firstLookThreads: FirstLookThread[];
     toMarkSeen: ReviewThread[];
 }
-export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames, repeatableThreadIds?: ReadonlySet<string>): ThreadVisibility;
+export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames, repeatableThreadIds?: ReadonlySet<string>, resolveOtherHumanThreads?: ResolveOtherHumanThreads): ThreadVisibility;
 export {};

package/bin/comments/thread-visibility.mjs

@@ -2,6 +2,7 @@ import { classifyItem } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "./authors.mjs";
 import { threadEndedByShepherd } from "./marker.mjs";
+import { shouldResolveOtherHumanThread } from "./thread-resolve-policy.mjs";
 function withEdited(thread, edited) {
     return edited ? { ...thread, edited: true } : thread;
 }
@@ -19,15 +20,19 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
         return null;
     return { ...visible, firstLookStatus };
 }
-export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds) {
+export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds, resolveOtherHumanThreads = "none") {
     const shouldRepeat = (thread) => repeatableThreadIds?.has(thread.id) ?? true;
+    const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
     const unresolvedThreads = threads.filter((t) => !t.isResolved);
     const activeThreads = unresolvedThreads
         .filter((t) => !t.isOutdated && !t.isMinimized)
         .flatMap((t) => {
         if (threadEndedByShepherd(t))
             return [];
-        if (isConfiguredBotAuthor(t, botUsernames) && shouldRepeat(t))
+        const repeatAuthor = isConfiguredBotAuthor(t, botUsernames) ||
+            isViewerAuthoredHuman(t, botUsernames) ||
+            (isOrdinaryHuman(t) && resolveOtherHumanThreads === "always");
+        if (repeatAuthor && shouldRepeat(t))
             return [t];
         const visible = classifyVisibleThread(t, seenMap);
         return visible ? [visible] : [];
@@ -35,9 +40,11 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
     const resolutionOnlyThreads = unresolvedThreads
         .filter((t) => {
         const endedByShepherd = threadEndedByShepherd(t);
-        const ordinaryHuman = isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames);
-        if (endedByShepherd && ordinaryHuman) {
-            return isViewerAuthoredHuman(t, botUsernames);
+        if (endedByShepherd) {
+            if (!isOrdinaryHuman(t))
+                return true;
+            return (isViewerAuthoredHuman(t, botUsernames) ||
+                shouldResolveOtherHumanThread(t, resolveOtherHumanThreads));
         }
         return t.isOutdated || t.isMinimized;
     })

package/bin/config/load.d.mts

@@ -1,5 +1,7 @@
 declare const MINIMIZE_COMMENTS_POLICIES: readonly ["all", "bots", "users", "none"];
 export type MinimizeCommentsPolicy = (typeof MINIMIZE_COMMENTS_POLICIES)[number];
+declare const RESOLVE_OTHER_HUMAN_THREADS: readonly ["none", "outdated", "always"];
+export type ResolveOtherHumanThreads = (typeof RESOLVE_OTHER_HUMAN_THREADS)[number];
 export interface GraphqlQuotaWarningBand {
     remainingPercent: number;
     pollIntervalMinutes: number;
@@ -31,6 +33,12 @@ export interface PrShepherdConfig {
          * (default) omits the hint entirely; the CLI never prescribes rebase/merge mechanics itself.
          */
         behindBaseHint: string;
+        /**
+         * When to resolve other-human inline threads after Shepherd replies. Own and bot threads
+         * always reply-and-resolve. `none` (default) keeps other humans reply-only; `outdated`
+         * also resolves when GitHub reports `isOutdated`; `always` pairs reply-and-resolve.
+         */
+        resolveOtherHumanThreads: ResolveOtherHumanThreads;
     };
     watch: {
         readyDelayMinutes: number;
@@ -44,6 +52,8 @@ export interface PrShepherdConfig {
     };
     checks: {
         ciTriggerEvents: string[];
+        /** Regex patterns matched against each raw log line; matching lines are dropped from log excerpts. Empty by default — no lines are stripped unless configured. */
+        ignoreLogLines: string[];
     };
     mergeStatus: {
         blockingReviewerLogins: string[];
@@ -57,6 +67,14 @@ export interface PrShepherdConfig {
         autoMarkReady: boolean;
         /** Legacy-named patterns that keep matching Actions checks visible despite ignoreChecks. */
         neverCancelRuns: string[];
+        /**
+         * When `false` (default), `iterate --merge` defers non-CI actionable work
+         * (review threads, comments, changes-requested reviews, review summaries)
+         * while the PR sits in the merge queue, since a Shepherd-initiated push
+         * would eject it. When `true`, restores pre-existing behavior: actionable
+         * work is handled immediately regardless of queue membership.
+         */
+        workWhileQueued: boolean;
         /** @deprecated Accepted for compatibility, ignored by the loader. */
         autoResolveOutdated?: boolean;
         /** @deprecated Accepted for compatibility, ignored by the loader. */

package/bin/config/load.mjs

@@ -7,6 +7,7 @@ import builtins from "../config.json" with { type: "json" };
 import { getEffectiveCwd } from "../execution-context.mjs";
 import { findMergeStrategies } from "./merge-command-args.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
+const RESOLVE_OTHER_HUMAN_THREADS = ["none", "outdated", "always"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
 /**
  * Collect `.pr-shepherdrc.yml` files from `startDir` toward `$HOME` (closest first).
@@ -68,6 +69,13 @@ function parseMinimizeCommentsPolicy(value) {
         return value;
     throw new Error(`Invalid config: iterate.minimizeComments must be one of "all", "bots", "users", or "none", got ${JSON.stringify(value)}`);
 }
+function parseResolveOtherHumanThreads(value) {
+    if (typeof value === "string" &&
+        RESOLVE_OTHER_HUMAN_THREADS.includes(value)) {
+        return value;
+    }
+    throw new Error(`Invalid config: iterate.resolveOtherHumanThreads must be one of "none", "outdated", or "always", got ${JSON.stringify(value)}`);
+}
 function parseBotUsernames(value) {
     if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
         throw new Error(`Invalid config: botUsernames must be an array of strings`);
@@ -86,6 +94,20 @@ function parseNeverCancelRuns(value) {
     }
     return value;
 }
+function parseIgnoreLogLines(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid config: checks.ignoreLogLines must be an array of strings`);
+    }
+    for (const pattern of value) {
+        try {
+            new RegExp(pattern);
+        }
+        catch {
+            throw new Error(`Invalid config: checks.ignoreLogLines contains an invalid regular expression: ${pattern}`);
+        }
+    }
+    return value;
+}
 const SHEPHERD_OWNED_MERGE_FLAGS = [
     "--repo",
     "-R",
@@ -165,16 +187,18 @@ const KNOWN_NESTED_KEYS = {
         "minimizeApprovals",
         "minimizeComments",
         "behindBaseHint",
+        "resolveOtherHumanThreads",
     ]),
     watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
-    checks: new Set(["ciTriggerEvents"]),
+    checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),
     mergeStatus: new Set(["blockingReviewerLogins"]),
     merge: new Set(["commandArgs"]),
     actions: new Set([
         "autoMinimizeSuppressed",
         "autoMarkReady",
         "neverCancelRuns",
+        "workWhileQueued",
         "autoResolveOutdated",
         "commitSuggestions",
     ]),
@@ -261,6 +285,8 @@ export function loadConfig() {
             config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
         config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
+        config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
+        config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
         configCache.set(cwd, config);
         return config;
     }

package/bin/config.json

@@ -19,7 +19,8 @@
     "stallTimeoutMinutes": 60,
     "minimizeApprovals": false,
     "minimizeComments": "all",
-    "behindBaseHint": ""
+    "behindBaseHint": "",
+    "resolveOtherHumanThreads": "none"
   },
   "watch": {
     "readyDelayMinutes": 10,
@@ -36,7 +37,8 @@
     }
   },
   "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"]
+    "ciTriggerEvents": ["pull_request", "pull_request_target"],
+    "ignoreLogLines": []
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]
@@ -47,6 +49,7 @@
   "actions": {
     "autoMinimizeSuppressed": true,
     "autoMarkReady": true,
-    "neverCancelRuns": []
+    "neverCancelRuns": [],
+    "workWhileQueued": false
   }
 }

package/bin/mcp/server.mjs

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
 import { isRepositoryQualifiedPrReference } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
-import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
+import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
@@ -88,7 +88,13 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), formatIterateResult));
+    }, async (input) => {
+        // One options object feeds both channels so JSON and Markdown cannot drift.
+        const opts = {
+            readyDelaySuffix: input.readyDelaySeconds === undefined ? undefined : `${input.readyDelaySeconds}s`,
+        };
+        return runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), (result) => formatIterateResult(result, opts), (result) => projectIterateLean(result, opts));
+    });
     server.registerTool("apply", {
         description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
         inputSchema: applyInputSchema,
@@ -131,16 +137,22 @@ function readPackageVersion() {
     const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
     return packageJson.version;
 }
-function toolResult(result, text) {
+function toolResult(structured, text) {
     return {
         content: [{ type: "text", text }],
-        structuredContent: result,
+        structuredContent: structured,
     };
 }
-async function runTool(work, format) {
+/**
+ * `project` mirrors the CLI's `--format=json` treatment of the same result. Tools
+ * whose CLI JSON is the raw result object (apply, build_suggestion_patch(es) — see
+ * handlers.mts and cli-parser.mts, which JSON.stringify the result directly) omit
+ * `project` and return the result unchanged, matching their own CLI JSON output.
+ */
+async function runTool(work, format, project) {
     try {
         const result = await work();
-        return toolResult(result, format(result));
+        return toolResult(project ? project(result) : result, format(result));
     }
     catch (error) {
         return toolError(error);

package/bin/types/escalate.d.mts

@@ -1,7 +1,7 @@
 import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { CheckStatus, Review } from "./github.mts";
-import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed";
+import type { MergeQueueRemovalStatus, StackStatus } from "./merge-requirements.mts";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed" | "stacked-pr";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;
@@ -29,6 +29,7 @@ export interface EscalateDetails {
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;
+    stack?: StackStatus;
     authorization?: Array<{
         action: "mark-ready" | "merge-or-enqueue";
         targetIds: string[];

package/bin/types/iterate.d.mts

@@ -48,6 +48,7 @@ export interface IterateResultBase {
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
     log: string;
+    deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
 }
 export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
 interface IterateResultCancel extends IterateResultBase {
@@ -135,9 +136,18 @@ export interface IterateCommandOptions extends GlobalOptions {
     stallTimeoutSeconds?: number;
     /** Legacy per-invocation no-op retained for API compatibility. */
     neverCancelRuns?: string[];
+    /**
+     * Internal. `false` skips seen-marker writes (poll's discarded debounce ticks). Set
+     * only by `runPollCore`; excluded from the public `IterateInput` in api.mts.
+     */
     persistSeen?: boolean;
     /** Shepherd through readiness and emit the exact merge/queue command when ready. */
     merge?: boolean;
+    /**
+     * Internal. Defers attaching a quota warning until an until-terminal poll actually
+     * breaks. Set only by `runPollCore`; excluded from the public `IterateInput` in
+     * api.mts.
+     */
     deferQuotaWarning?: boolean;
 }
 export {};

package/bin/types/merge-queue.d.mts

@@ -11,3 +11,19 @@ export interface MergeQueueReport {
     /** The current PR head is not a parent of the removed synthetic queue commit. */
     headUpdatedAfterRemoval?: true;
 }
+/**
+ * Raw counts of actionable work held back while the PR sits in the merge queue
+ * (`actions.workWhileQueued` is `false`, the default) — a Shepherd-initiated push
+ * or mutation right now would eject the PR. Omitted entirely once every count is
+ * zero. Not emitted for checks/annotations/conflicts: those always surface via
+ * `fix_code` immediately regardless of queue membership.
+ */
+export interface IterateDeferredWork {
+    /** Unique review threads across actionable, resolution-only, first-look, and rule-auto-resolve. */
+    threads: number;
+    /** Unique PR comments across actionable, minimize-queued, and first-look. */
+    comments: number;
+    changesRequestedReviews: number;
+    /** Unique review summaries across the minimize queue, first-look, edited, and (if opted in) surfaced approvals. */
+    reviewSummaries: number;
+}