pr-shepherd 1.1.0 → 1.1.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/checks/classify.d.mts

@@ -7,7 +7,9 @@
  *      to PR readiness.
  *   2. Drop checks with `conclusion == SKIPPED` or `conclusion == NEUTRAL` from the
  *      pass/fail tally. Report them as "skipped" for transparency but don't block on them.
- *   3. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer
+ *   3. A check that is not `COMPLETED` while its check suite is `COMPLETED` is stuck and
+ *      classifies as `failing`.
+ *   4. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer
  *      run of the same workflow exists on the same commit and event, or when an
  *      exact matching check from a lower-ID run started and succeeded later.
  *      GitHub can start jobs out of workflow-run creation order.

package/bin/checks/classify.mjs

@@ -7,7 +7,9 @@
  *      to PR readiness.
  *   2. Drop checks with `conclusion == SKIPPED` or `conclusion == NEUTRAL` from the
  *      pass/fail tally. Report them as "skipped" for transparency but don't block on them.
- *   3. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer
+ *   3. A check that is not `COMPLETED` while its check suite is `COMPLETED` is stuck and
+ *      classifies as `failing`.
+ *   4. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer
  *      run of the same workflow exists on the same commit and event, or when an
  *      exact matching check from a lower-ID run started and succeeded later.
  *      GitHub can start jobs out of workflow-run creation order.
@@ -76,6 +78,11 @@ function classify(check, relevantEvents) {
     const { status, conclusion } = check;
     // Not yet finished.
     if (status !== "COMPLETED") {
+        // The enclosing suite finished while this run did not: nothing will update it again, so
+        // waiting would only end in the stall timeout. Surface it as failing work (rerun the
+        // workflow) with the raw status and suite status shown.
+        if (check.suiteStatus === "COMPLETED")
+            return { ...check, category: "failing" };
         return { ...check, category: "in_progress" };
     }
     // Skipped / neutral — report but don't block.

package/bin/cli/triage-formatter.mjs

@@ -74,7 +74,11 @@ export function formatTriageResult(header, result, opts = {}) {
                 : ch.detailsUrl
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
-            const conclusionTag = ch.conclusion !== null ? ` [conclusion: ${ch.conclusion}]` : "";
+            const conclusionTag = ch.status !== undefined
+                ? ` [status: ${ch.status}, suite: ${ch.suiteStatus}]`
+                : ch.conclusion !== null
+                    ? ` [conclusion: ${ch.conclusion}]`
+                    : "";
             const attemptTag = ch.runAttempt !== undefined ? ` [attempt: ${ch.runAttempt}]` : "";
             const scopeTag = ch.scope
                 ? ` [scope: ${ch.scope}${ch.commitOid ? `, commit: ${ch.commitOid}` : ""}]`

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

@@ -14,14 +14,12 @@ export declare function hasCheckDrivenActionableWork(checks: {
     passing: ClassifiedCheck[];
     skipped: ClassifiedCheck[];
     filtered: ClassifiedCheck[];
-    ignored?: TriagedCheck[];
 }, mergeStatusValue: string): boolean;
 export declare function attachAndMergeCheckAnnotations(buckets: {
     passing: ClassifiedCheck[];
     failing: TriagedCheck[];
     skipped: ClassifiedCheck[];
     filtered: ClassifiedCheck[];
-    ignored: ClassifiedCheck[];
 }, seenMap: Map<string, {
     seenAt: number;
 }>, prNumber: number, cacheOpts?: AnnotationCacheOptions): Promise<{
@@ -29,6 +27,5 @@ export declare function attachAndMergeCheckAnnotations(buckets: {
     failing: TriagedCheck[];
     skipped: ClassifiedCheck[];
     filtered: ClassifiedCheck[];
-    ignored: ClassifiedCheck[];
 }>;
 export declare function annotationMarkerBody(a: CheckAnnotation): string;

package/bin/commands/check-annotations.mjs

@@ -12,7 +12,6 @@ export function checksWithActionableAnnotations(report) {
         ...report.checks.passing,
         ...report.checks.skipped,
         ...report.checks.filtered,
-        ...(report.checks.ignored ?? []),
     ].filter(hasActionableAnnotation);
 }
 /**
@@ -25,13 +24,7 @@ export function checksWithActionableAnnotations(report) {
  */
 export function hasCheckDrivenActionableWork(checks, mergeStatusValue) {
     return (checks.failing.length > 0 ||
-        [
-            ...checks.failing,
-            ...checks.passing,
-            ...checks.skipped,
-            ...checks.filtered,
-            ...(checks.ignored ?? []),
-        ].some(hasActionableAnnotation) ||
+        [...checks.failing, ...checks.passing, ...checks.skipped, ...checks.filtered].some(hasActionableAnnotation) ||
         mergeStatusValue === "CONFLICTS");
 }
 export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber, cacheOpts) {
@@ -40,7 +33,6 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
         ...buckets.passing,
         ...buckets.skipped,
         ...buckets.filtered,
-        ...buckets.ignored,
     ].filter(shouldFetchCheckAnnotations);
     const expectedCounts = new Map(candidates.flatMap((c) => c.id != null && c.annotationCount ? [[c.id, c.annotationCount]] : []));
     const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts && { ...cacheOpts, expectedCounts });
@@ -57,7 +49,6 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
         failing: apply(buckets.failing),
         skipped: apply(buckets.skipped),
         filtered: apply(buckets.filtered),
-        ignored: apply(buckets.ignored),
     };
 }
 async function attachUnseenCheckAnnotations(checks, seenMap, prNumber, cacheOpts) {

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

@@ -1,3 +1,8 @@
 import type { MergeStatusResult, ShepherdStatus } from "../types.mts";
 import type { CiVerdict } from "../checks/classify.mts";
-export declare function computeStatus(verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, mergeStatus: MergeStatusResult, changesRequestedReviews: number, hasUnreportedRequired?: boolean): ShepherdStatus;
+/**
+ * `awaitingChecks` is true when required checks have not reported, or when the PR has no relevant
+ * check yet while a relevant Actions workflow suite is still running: the suite exists before
+ * its check runs, so a CLEAN or DRAFT merge state is not yet proof that CI passed.
+ */
+export declare function computeStatus(verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, mergeStatus: MergeStatusResult, changesRequestedReviews: number, awaitingChecks?: boolean): ShepherdStatus;

package/bin/commands/check-status.mjs

@@ -1,4 +1,9 @@
-export function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews, hasUnreportedRequired = false) {
+/**
+ * `awaitingChecks` is true when required checks have not reported, or when the PR has no relevant
+ * check yet while a relevant Actions workflow suite is still running: the suite exists before
+ * its check runs, so a CLEAN or DRAFT merge state is not yet proof that CI passed.
+ */
+export function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews, awaitingChecks = false) {
     // Merge conflicts are always terminal regardless of CI state.
     if (mergeStatus.status === "CONFLICTS")
         return "FAILING";
@@ -26,7 +31,7 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
         changesRequestedReviews === 0 &&
         (mergeStatus.status === "BLOCKED" || mergeStatus.status === "UNSTABLE") &&
         !mergeStatus.blockingBotReviewInProgress &&
-        !hasUnreportedRequired) {
+        !awaitingChecks) {
         return "READY";
     }
     if (mergeStatus.status === "BLOCKED" ||
@@ -40,9 +45,9 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
     // DRAFT is treated the same as CLEAN for readiness — marking the PR ready resolves it.
     if ((mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT") &&
         verdict.allPassed &&
-        !hasUnreportedRequired)
+        !awaitingChecks)
         return "READY";
-    if (hasUnreportedRequired && (mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT"))
+    if (awaitingChecks && (mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT"))
         return "PENDING";
     return "UNKNOWN";
 }

package/bin/commands/check-unreported.mjs

@@ -110,7 +110,7 @@ function reportChecks(report) {
         ...report.checks.inProgress,
         ...report.checks.skipped,
         ...report.checks.filtered,
-        ...(report.checks.ignored ?? []),
+        ...(report.checks.ignoredNames ?? []).map((name) => ({ name })),
         ...(report.checks.supersededNames ?? []).map((name) => ({ name })),
     ];
 }

package/bin/commands/check.mjs

@@ -186,7 +186,6 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
-    const ignored = classifiedChecks.filter((c) => c.category === "ignored");
     const triagedBase = failing.length > 0 && !opts.skipTriage
         ? await triageFailingChecks(failing, repo, stateKey, triageBudget, classifiedChecks.filter((c) => c.category !== "failing"))
         : failing;
@@ -199,8 +198,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const ruleSet = await loadClassifyRules(getEffectiveCwd(), config.standardRules);
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
-    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber, { stateKey, headSha: batchData.headRefOid });
-    const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
+    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered }, seenMap, prNumber, { stateKey, headSha: batchData.headRefOid });
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
     const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => !canGenerateItemMutation(id, batchData.comments.find((comment) => comment.id === id)?.body ?? "", batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize, "minimize")));
     const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate["minimize-comments"], botUsernames, new Set(batchData.comments
@@ -261,7 +259,9 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             canGenerateItemMutation(review.id, review.body, batchData.viewerAuthorization?.viewerCanAdminister, "dismiss") ||
             visibleChangesRequestedIds.has(review.id));
     }).length;
-    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount, unreported.hasUnreportedRequired);
+    const awaitingChecks = unreported.hasUnreportedRequired ||
+        (!verdict.hasChecks && unreported.actionsWorkflowInProgress === true);
+    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount, awaitingChecks);
     status = enforceTransportReadiness(status, batchData);
     // Resolve any pending mergeability refresh (and the resulting MERGED/CLOSED short-circuit)
     // before deciding what to persist below — deferWhileQueued must see the same final,
@@ -269,7 +269,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     // 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, unreported.hasUnreportedRequired);
+        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount, awaitingChecks);
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
@@ -299,7 +299,6 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             passing: merged.passing,
             skipped: merged.skipped,
             filtered: merged.filtered,
-            ignored: merged.ignored,
         }, mergeStatus.status);
     // A deferred tick shows no review items, so it is never capped; its seen markers stay unwritten.
     const { buckets: budgeted, rollup: reviewItems, heldThreadReviewIds, } = applyReviewOutputBudget({
@@ -312,12 +311,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         editedComments,
     }, deferWhileQueued ? 0 : (opts.reviewOutputMaxChars ?? 0));
     if (opts.persistSeen !== false) {
-        const successfulAnnotations = [
-            ...merged.passing,
-            ...merged.skipped,
-            ...merged.filtered,
-            ...merged.ignored,
-        ]
+        const successfulAnnotations = [...merged.passing, ...merged.skipped, ...merged.filtered]
             .filter((check) => check.conclusion === "SUCCESS")
             .flatMap((check) => check.annotations ?? []);
         const deferredMarkSeen = deferWhileQueued
@@ -408,7 +402,6 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             inProgress: inProgress,
             skipped: merged.skipped,
             filtered: merged.filtered,
-            ...(ignoredAnnotated.length > 0 && { ignored: ignoredAnnotated }),
             filteredNames: verdict.filteredNames,
             blockedByFilteredCheck,
             ...(verdict.ignoredNames.length > 0 && {

package/bin/commands/iterate/conflicting-head-ci.d.mts

@@ -12,7 +12,7 @@ export declare function countReportedChecks(checks: {
     inProgress: readonly unknown[];
     skipped: readonly unknown[];
     filtered: readonly unknown[];
-    ignored?: readonly unknown[];
+    ignoredNames?: readonly unknown[];
 }): number;
 /** Place the missing-CI note with the conflict step, ahead of later repair lines. */
 export declare function insertConflictingHeadCiNote(instructions: string[], note: string | undefined): void;

package/bin/commands/iterate/conflicting-head-ci.mjs

@@ -18,7 +18,7 @@ export function countReportedChecks(checks) {
         checks.inProgress.length +
         checks.skipped.length +
         checks.filtered.length +
-        (checks.ignored?.length ?? 0));
+        (checks.ignoredNames?.length ?? 0));
 }
 /** Place the missing-CI note with the conflict step, ahead of later repair lines. */
 export function insertConflictingHeadCiNote(instructions, note) {

package/bin/commands/iterate/escalate.mjs

@@ -43,10 +43,12 @@ function renderEscalateAnnotation(annotation) {
 function renderEscalateCheck(check) {
     const workflowPrefix = check.workflowName ? `${check.workflowName} › ` : "";
     const jobLabel = check.jobName ?? check.name;
-    const conclusion = check.conclusion ?? "UNKNOWN";
+    const conclusionTag = check.status !== undefined
+        ? `[status: ${check.status}, suite: ${check.suiteStatus}]`
+        : `[conclusion: ${check.conclusion ?? "UNKNOWN"}]`;
     const attempt = check.runAttempt !== undefined ? ` [attempt: ${check.runAttempt}]` : "";
     const lines = [
-        `- ${renderCheckTarget(check)} — \`${workflowPrefix}${jobLabel}\` [conclusion: ${conclusion}]${attempt}${renderCheckScope(check)}`,
+        `- ${renderCheckTarget(check)} — \`${workflowPrefix}${jobLabel}\` ${conclusionTag}${attempt}${renderCheckScope(check)}`,
     ];
     if (check.failedStep)
         lines.push(`  > failed step: ${check.failedStep}`);

package/bin/commands/poll-summary-explicit-instructions.d.mts

@@ -3,4 +3,4 @@ import type { PollSummaryResult } from "../types.mts";
 export declare function isHandedOffSelection(result: PollSummaryResult): boolean;
 /** A final full-review probe can finish this selection without another aggregate read. */
 export declare function onlyDraftVerificationSelection(result: PollSummaryResult): boolean;
-export declare function explicitInstructions(result: PollSummaryResult): string[];
+export declare function explicitInstructions(result: PollSummaryResult, rerunCommand?: string): string[];

package/bin/commands/poll-summary-explicit-instructions.mjs

@@ -12,7 +12,10 @@ export function onlyDraftVerificationSelection(result) {
             item.action === "escalate" ||
             isDraftReadinessVerification(item)));
 }
-export function explicitInstructions(result) {
+/** Rerunning is mandatory while any selected row is non-terminal; a finished one-PR poll is not the end. */
+const KEEP_WATCHING = "Do not end the turn while any selected row is non-terminal: a one-PR poll returning `CANCEL` or `ESCALATE` finishes only that row, and rows that are `CANCEL`, `ESCALATE`, or handed off do not count.";
+export function explicitInstructions(result, rerunCommand) {
+    const again = rerunCommand ? `\`${rerunCommand}\`` : "this aggregate command";
     if (result.reason === "all_terminal")
         return [
             result.prs.some((item) => item.reasons.includes("draft-auto-mark-ready-disabled"))
@@ -21,27 +24,26 @@ export function explicitInstructions(result) {
         ];
     if (result.quotaWarning && result.reason !== "actionable") {
         return [
-            buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
+            buildQuotaAwareContinuation(result.quotaWarning, `1. This aggregate selection is non-terminal. Run ${again} again at the cadence below. ${KEEP_WATCHING} Before continuing,`),
         ];
     }
     if (result.reason === "waiting" || result.reason === "timeout") {
-        return ["1. Run this aggregate command again when the caller is ready to recheck."];
+        return [`1. Run ${again} again when the caller is ready to recheck. ${KEEP_WATCHING}`];
     }
     const instructions = [
         "1. Choose each non-WAIT, non-CANCEL row that can proceed independently and run or delegate its exact `pollCommand`.",
         "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
-        "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
+        `3. Run ${again} again after selected work completes; one row's \`ESCALATE\` does not stop work on other rows. ${KEEP_WATCHING}`,
     ];
     if (onlyDraftVerificationSelection(result)) {
-        instructions[2] =
-            "3. If every draft verification probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, stop this selection and report any `ESCALATE` rows; leave the drafts unchanged. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow the probes' instructions and rerun this aggregate selector when that work completes.";
+        instructions[2] = `3. If every draft verification probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop this selection and report any \`ESCALATE\` rows; leave the drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow the probes' instructions and rerun ${again} when that work completes.`;
     }
     else if (isHandedOffSelection(result)) {
         instructions[2] =
             "3. Stop after reporting each `ESCALATE` handoff; every selected row is `CANCEL` or `ESCALATE`, so do not run this aggregate poll again.";
     }
     else if (result.quotaWarning) {
-        instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, "3. After selected work completes,");
+        instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, `3. After selected work completes, run ${again} again at the cadence below; one row's \`ESCALATE\` does not stop work on other rows. ${KEEP_WATCHING}`);
     }
     return instructions;
 }

package/bin/commands/poll-summary-instructions.d.mts

@@ -1,8 +1,8 @@
 import type { PollSummaryItem, PollSummaryResult } from "../types.mts";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
-export declare function withPollSummaryInstructions(result: PollSummaryResult, mergeRequested: boolean): PollSummaryResult;
+export declare function withPollSummaryInstructions(result: PollSummaryResult, mergeRequested: boolean, rerunCommand?: string): PollSummaryResult;
 /** The projected summary, plus the idle layers when the stack plan can only wait on them. */
-export declare function planPollSummary(result: PollSummaryResult, mergeRequested: boolean): {
+export declare function planPollSummary(result: PollSummaryResult, mergeRequested: boolean, rerunCommand?: string): {
     result: PollSummaryResult;
     idle?: PollSummaryItem[];
 };

package/bin/commands/poll-summary-instructions.mjs

@@ -2,15 +2,15 @@
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
 import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planPrefixDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
-import { appendStackRerunInstruction, onlyDraftReadinessVerification, splitStackWork, } from "./stack-work.mjs";
+import { appendStackRerunInstruction, onlyDraftReadinessVerification, splitStackWork, stackRerunTarget, } from "./stack-work.mjs";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
-export function withPollSummaryInstructions(result, mergeRequested) {
-    return planPollSummary(result, mergeRequested).result;
+export function withPollSummaryInstructions(result, mergeRequested, rerunCommand) {
+    return planPollSummary(result, mergeRequested, rerunCommand).result;
 }
 /** The projected summary, plus the idle layers when the stack plan can only wait on them. */
-export function planPollSummary(result, mergeRequested) {
+export function planPollSummary(result, mergeRequested, rerunCommand) {
     if (result.selection.kind !== "stack") {
-        return { result: { ...result, instructions: explicitInstructions(result) } };
+        return { result: { ...result, instructions: explicitInstructions(result, rerunCommand) } };
     }
     const prs = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
     const staleChildren = new Set(result.stackAncestry?.map((gap) => gap.childPr) ?? []);
@@ -60,7 +60,7 @@ export function planPollSummary(result, mergeRequested) {
             return layer;
         }),
     };
-    const planned = planStack(projected, mergeRequested);
+    const planned = planStack(projected, mergeRequested, rerunCommand);
     const instructions = [...planned.instructions];
     if (result.quotaWarning && planned.action === "shepherd") {
         instructions.push(buildQuotaAwareContinuation(result.quotaWarning, `${instructions.length + 1}. After completing the stack action,`));
@@ -82,7 +82,8 @@ export function planPollSummary(result, mergeRequested) {
         ...(planned.idle && { idle: planned.idle }),
     };
 }
-function planStack(result, mergeRequested) {
+function planStack(result, mergeRequested, rerunCommand) {
+    const again = stackRerunTarget(rerunCommand);
     const open = result.prs.filter((item) => item.state === "OPEN");
     const gaps = result.stackAncestry ?? [];
     const staleChildren = new Set(gaps.map((gap) => gap.childPr));
@@ -93,7 +94,7 @@ function planStack(result, mergeRequested) {
     const agentWork = runnableCandidates.length > 0;
     // Only owned work defers a human handoff: rerunning cannot advance another author's layer.
     const ownedWork = runnableCandidates.some((item) => item.owned);
-    const drain = planPrefixDrain(result, mergeRequested);
+    const drain = planPrefixDrain(result, mergeRequested, rerunCommand);
     if (drain)
         return drain;
     const handoffs = findHumanHandoffs(result);
@@ -108,9 +109,9 @@ function planStack(result, mergeRequested) {
         if (ownedWork) {
             const rerun = onlyDraftReadinessVerification(work.sessions, work.idle) &&
                 work.sessions.every((item) => item.owned)
-                ? "If every listed one-PR probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, report the human handoff above and stop this `stack` command. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same `stack` command when that work completes."
-                : "After the listed one-PR sessions, rerun this same `stack` command. Stop for the human handoff only when no autonomous shepherding remains.";
-            appendStackRerunInstruction(instructions, runnableCandidates, rerun);
+                ? `If every listed one-PR probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, report the human handoff above and stop this \`stack\` command. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun ${again} when that work completes.`
+                : `After the listed one-PR sessions, rerun ${again}. Stop for the human handoff only when no autonomous shepherding remains.`;
+            appendStackRerunInstruction(instructions, runnableCandidates, rerun, false);
         }
         return { action: stop ? "escalate" : "shepherd", stackMergeable: false, instructions };
     }
@@ -129,7 +130,7 @@ function planStack(result, mergeRequested) {
                 instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. ${ownedWork ? "After autonomous shepherding, ask" : "Stop and ask"} for direction.`);
             }
             if (ownedWork) {
-                appendStackRerunInstruction(instructions, runnableCandidates, "After the listed one-PR sessions, rerun this same `stack` command. Stop for the human handoff only when no autonomous shepherding remains.");
+                appendStackRerunInstruction(instructions, runnableCandidates, `After the listed one-PR sessions, rerun ${again}. Stop for the human handoff only when no autonomous shepherding remains.`, false);
             }
             return { action: ownedWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
         }
@@ -149,10 +150,10 @@ function planStack(result, mergeRequested) {
         appendAutonomousInstructions(instructions, work.sessions);
         if (onlyDraftReadinessVerification(work.sessions, work.idle) &&
             work.sessions.every((item) => item.owned)) {
-            instructions.push(`${instructions.length + 1}. If every listed one-PR probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop shepherding this stack and leave those drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same \`stack\` command when that work completes.`);
+            instructions.push(`${instructions.length + 1}. If every listed one-PR probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop shepherding this stack and leave those drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun ${again} when that work completes.`);
             return { action: "shepherd", stackMergeable: false, instructions };
         }
-        const action = appendStackRerunInstruction(instructions, work.sessions, "After the selected one-PR sessions, rerun this same `stack` command.");
+        const action = appendStackRerunInstruction(instructions, work.sessions, `After the selected one-PR sessions, rerun ${again}.`);
         return { action, stackMergeable: false, instructions };
     }
     if (open.some((item) => item.isInMergeQueue)) {
@@ -176,7 +177,7 @@ function planStack(result, mergeRequested) {
         const instructions = [];
         const sessions = open.filter((item) => item.action !== "cancel");
         appendAutonomousInstructions(instructions, sessions);
-        const action = appendStackRerunInstruction(instructions, sessions, "After the selected one-PR sessions, rerun this same `stack` command.");
+        const action = appendStackRerunInstruction(instructions, sessions, `After the selected one-PR sessions, rerun ${again}.`);
         return { action, stackMergeable, instructions };
     }
     return retargetWaitPlan(open[0]);

package/bin/commands/poll-summary.mjs

@@ -4,6 +4,7 @@ import { ShepherdError } from "../exit-codes.mjs";
 import { getRepoInfo } from "../github/client.mjs";
 import { getGithubTransport } from "../github/transport.mjs";
 import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
+import { aggregateRerunCommand } from "../github/poll-summary-command.mjs";
 import { fetchPollSummary } from "../github/poll-summary.mjs";
 import { writeStackHandoffs } from "../github/stack-handoff.mjs";
 import { sleep } from "../util/sleep.mjs";
@@ -19,7 +20,7 @@ export function runPollSummary(opts) {
     return withApiTelemetryScope(async () => {
         const tick = await readPollSummaryTick(opts);
         await handOffRoutedLayers(tick);
-        return attachUsage(tick.result, opts.merge);
+        return attachUsage(tick.result, opts);
     });
 }
 export function runAggregatePoll(opts) {
@@ -60,7 +61,7 @@ async function readPollSummaryTick(opts) {
         prs: fetched.prs,
         ...(fetched.stackAncestry?.length && { stackAncestry: fetched.stackAncestry }),
         ...(fetched.allowedMergeMethods && { allowedMergeMethods: fetched.allowedMergeMethods }),
-    }, opts.merge === true);
+    }, opts.merge === true, aggregateRerunCommand(`${repo.owner}/${repo.name}`, fetched.selection, opts));
     const result = await applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate["stall-timeout-minutes"] * 60);
     return { result, repo, ...(fetched.handoffSource && { handoffSource: fetched.handoffSource }) };
 }
@@ -104,7 +105,7 @@ async function runAggregatePollCore(opts) {
                         stackMergeable: true,
                         instructions: ["1. Stop — every stack layer is merged."],
                         ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                    }, opts.merge);
+                    }, opts);
                 }
                 return attachUsage({
                     ...explicit,
@@ -116,7 +117,7 @@ async function runAggregatePollCore(opts) {
                         `1. Native stack #${last.selection.stackNumber} disappeared before every tracked layer merged. Stop and ask the stack owner to reconcile the remaining PRs; do not claim the stack is complete.`,
                     ],
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                }, opts.merge);
+                }, opts);
             }
             const early = await rateLimitRetry.wait(error, {
                 untilTerminal: opts.untilTerminal === true,
@@ -127,7 +128,7 @@ async function runAggregatePollCore(opts) {
                 onAllTerminal: (pulls) => aggregateCancelFromPulls(last, opts.targetRepository, pulls),
             });
             if (early) {
-                return presentProbedCancel(pendingQuotaWarning ? { ...early, quotaWarning: pendingQuotaWarning } : early, opts.merge);
+                return presentProbedCancel(pendingQuotaWarning ? { ...early, quotaWarning: pendingQuotaWarning } : early, opts);
             }
             continue;
         }
@@ -148,14 +149,14 @@ async function runAggregatePollCore(opts) {
                 ...last,
                 reason: "all_terminal",
                 ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-            }, opts.merge);
+            }, opts);
         }
         if (immediate) {
             return attachUsage({
                 ...last,
                 reason: "actionable",
                 ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-            }, opts.merge);
+            }, opts);
         }
         if (hasFix) {
             if (debounceMs === 0 || Date.now() >= (debounceUntil ??= Date.now() + debounceMs)) {
@@ -164,13 +165,13 @@ async function runAggregatePollCore(opts) {
                     ...last,
                     reason: "actionable",
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                }, opts.merge);
+                }, opts);
             }
         }
         else {
             debounceUntil = null;
             if (opts.untilTerminal && pendingQuotaWarning) {
-                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning }, opts.merge);
+                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning }, opts);
             }
         }
         const elapsedMs = Date.now() - start;
@@ -180,7 +181,7 @@ async function runAggregatePollCore(opts) {
         if (!opts.untilTerminal && debounceUntil === null) {
             const remainingMs = timeoutMs - elapsedMs;
             if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
-                return attachUsage({ ...last, reason: "timeout" }, opts.merge);
+                return attachUsage({ ...last, reason: "timeout" }, opts);
             }
         }
         const statusSignature = summaryStatusSignature(last);
@@ -199,15 +200,15 @@ function writeAggregateRuleAutoResolve(result) {
         if (item.ruleAutoResolve?.summary)
             process.stderr.write(`#${item.pr} ${item.ruleAutoResolve.summary}\n`);
 }
-function presentProbedCancel(result, merge) {
+function presentProbedCancel(result, opts) {
     // The stack planner already cancels an all-merged stack and escalates a
     // closed-unmerged layer. Do not rewrite that into a successful stop.
-    return attachUsage({ ...result, reason: "all_terminal" }, merge);
+    return attachUsage({ ...result, reason: "all_terminal" }, opts);
 }
 function isMissingStack(error) {
     return (error instanceof ShepherdError && error.message.includes("not part of a native GitHub stack"));
 }
-function attachUsage(result, mergeRequested) {
+function attachUsage(result, opts) {
     const apiUsage = summarizeApiTelemetry();
     const enriched = apiUsage ? { ...result, apiUsage } : result;
     // A disappeared native stack is an aggregate-level terminal handoff. Keep
@@ -216,5 +217,5 @@ function attachUsage(result, mergeRequested) {
     if (enriched.selection.kind === "stack" && enriched.nextAction === "escalate") {
         return enriched;
     }
-    return withPollSummaryInstructions(enriched, mergeRequested === true);
+    return withPollSummaryInstructions(enriched, opts.merge === true, aggregateRerunCommand(enriched.repo, enriched.selection, opts));
 }

package/bin/commands/ready-mergeability.d.mts

@@ -10,6 +10,6 @@ export declare function refreshUnknownMergeability(prNumber: number, repo: RepoI
     batchData: BatchPrData;
     didRefresh: boolean;
 }>;
-export declare function refreshReadyMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData, verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, changesRequestedCount: number, hasUnreportedRequired?: boolean): Promise<ReadyMergeabilityRefresh>;
+export declare function refreshReadyMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData, verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, changesRequestedCount: number, awaitingChecks?: boolean): Promise<ReadyMergeabilityRefresh>;
 export declare function isBlockedByFilteredCheck(mergeStatus: MergeStatusResult, verdict: CiVerdict): boolean;
 export {};

package/bin/commands/ready-mergeability.mjs

@@ -8,10 +8,10 @@ export async function refreshUnknownMergeability(prNumber, repo, batchData) {
     }
     return { batchData: await readMergeability(prNumber, repo, batchData), didRefresh: true };
 }
-export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments, changesRequestedCount, hasUnreportedRequired = false) {
+export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments, changesRequestedCount, awaitingChecks = false) {
     const refreshedBatchData = await readMergeability(prNumber, repo, batchData);
     const mergeStatus = deriveMergeStatus(refreshedBatchData);
-    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedCount, hasUnreportedRequired);
+    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedCount, awaitingChecks);
     return { batchData: refreshedBatchData, mergeStatus, status };
 }
 export function isBlockedByFilteredCheck(mergeStatus, verdict) {

package/bin/commands/stack-drain.d.mts

@@ -8,7 +8,7 @@ export interface StackPlan {
     idle?: PollSummaryItem[];
     instructions: string[];
 }
-export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
+export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean, rerunCommand?: string): StackPlan | undefined;
 /**
  * A merge-requested, fully ready stack whose bottom open layer still targets
  * the merged layer below it until GitHub retargets it onto the stack base.

package/bin/commands/stack-drain.mjs

@@ -2,7 +2,7 @@ import { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-hando
 export { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-handoffs.mjs";
 import { stackMergeFlag } from "./stack-merge-flag.mjs";
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
-import { splitStackWork } from "./stack-work.mjs";
+import { splitStackWork, stackRerunTarget } from "./stack-work.mjs";
 import { getGithubTransport } from "../github/transport.mjs";
 import { buildMergeCommandPlan, renderMergeCommand } from "./iterate/merge.mjs";
 function readyPrefixTop(result) {
@@ -28,7 +28,7 @@ function readyPrefixTop(result) {
     }
     return top;
 }
-export function planPrefixDrain(result, mergeRequested) {
+export function planPrefixDrain(result, mergeRequested, rerunCommand) {
     if (!mergeRequested)
         return undefined;
     const top = readyPrefixTop(result);
@@ -92,7 +92,7 @@ export function planPrefixDrain(result, mergeRequested) {
     const handoffs = findHumanHandoffs(result);
     if (handoffs)
         appendHumanHandoffInstructions(instructions, handoffs, false);
-    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun this same \`stack --merge\` command; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
+    instructions.push(`${instructions.length + 1}. After the merge attempt, rerun ${rerunCommand ? stackRerunTarget(rerunCommand) : "this same `stack --merge` command"}; GitHub retargets the next layer onto \`${top.stack.baseRefName}\`. Shepherd any layer that GitHub rejects or ejects.`);
     return {
         action: "merge",
         stackMergeable: gaps.length === 0 && open.every(isStackLayerReady),