pr-shepherd 1.0.0 → 1.1.1

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.0.0",
+  "version": "1.1.1",
   "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/poll-summary-formatter.mjs

@@ -3,6 +3,7 @@ import { withPollSummaryInstructions } from "../commands/poll-summary-instructio
 import { formatStackOverview, projectStackOverview } from "./stack-overview.mjs";
 import { formatTransportEvidence } from "./transport-formatter.mjs";
 import { formatNextCheckLines } from "./next-check-format.mjs";
+import { formatRuleAutoResolveLines } from "./rule-auto-resolve-lines.mjs";
 export function formatPollSummaryResult(result) {
     if (result.selection.kind === "stack")
         return formatStackOverview(projectStackOverview(result));
@@ -69,12 +70,14 @@ function formatItem(item) {
         ...(review
             ? [`  - review: ${formatCounts(review, review.incomplete ? ", incomplete" : "")}`]
             : []),
+        ...formatRuleAutoResolveLines(item.ruleAutoResolve),
         ...(item.queueRemoval
             ? [
                 `  - queue removal: reason \`${item.queueRemoval.reason ?? "UNKNOWN"}\` · at \`${item.queueRemoval.createdAtUnix}\`${item.queueRemoval.actor ? ` · actor \`@${item.queueRemoval.actor}\`` : ""}${item.queueRemoval.beforeCommitOid ? ` · commit \`${item.queueRemoval.beforeCommitOid}\`` : ""}${item.queueRemoval.beforeCommitParentOids?.length ? ` · parents \`${item.queueRemoval.beforeCommitParentOids.join(",")}\`` : ""}`,
             ]
             : []),
         `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
+        ...(item.error ? [`  - error: ${item.error.replace(/\s*[\r\n]+\s*/g, " ")}`] : []),
         ...(item.transport ? [`  - transport \`${item.transport}\``] : []),
         ...(item.transportUnavailable ?? []).map(({ field, reason }) => `  - unavailable \`${field}\`: ${reason}`),
         ...(item.pollCommand

package/bin/cli/rule-auto-resolve-lines.d.mts

@@ -0,0 +1,3 @@
+import type { PollSummaryRuleAutoResolve } from "../types.mts";
+/** Row lines for an aggregate row or stack layer: the one-PR `## Classification auto-resolve` content. */
+export declare function formatRuleAutoResolveLines(event: PollSummaryRuleAutoResolve | undefined): string[];

package/bin/cli/rule-auto-resolve-lines.mjs

@@ -0,0 +1,12 @@
+/** Row lines for an aggregate row or stack layer: the one-PR `## Classification auto-resolve` content. */
+export function formatRuleAutoResolveLines(event) {
+    if (!event)
+        return [];
+    const link = (kind, id, url) => `    - ${kind} \`${id}\`${url ? ` ${url}` : ""}`;
+    return [
+        `  - classification auto-resolve: ${event.summary}`,
+        ...(event.threads ?? []).map((thread) => link("thread", thread.id, thread.url)),
+        ...(event.minimized ?? []).map((item) => link(item.kind, item.id, item.url)),
+        ...(event.errors ?? []).map((error) => `    - ${error}`),
+    ];
+}

package/bin/cli/stack-layer-view.d.mts

@@ -1,4 +1,4 @@
-import type { PollSummaryItem } from "../types.mts";
+import type { PollSummaryItem, PollSummaryRuleAutoResolve } from "../types.mts";
 /** One lean stack row shared by Markdown, JSON, and MCP. */
 export interface StackLayerView {
     transport?: "rest";
@@ -26,6 +26,7 @@ export interface StackLayerView {
     actionable?: number;
     checksIncomplete?: true;
     reviewIncomplete?: true;
+    ruleAutoResolve?: PollSummaryRuleAutoResolve;
     queueRemoval?: {
         reason: string | null;
         actor?: string;

package/bin/cli/stack-overview.mjs

@@ -3,6 +3,7 @@ import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { formatTransportEvidence } from "./transport-formatter.mjs";
 import { formatNextCheckLines } from "./next-check-format.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
+import { formatRuleAutoResolveLines } from "./rule-auto-resolve-lines.mjs";
 /** Lean stack payload shared by Markdown, JSON, and MCP. */
 export function projectStackOverview(result) {
     const selection = result.selection;
@@ -59,6 +60,7 @@ function projectLayer(item, stale) {
             (item.review?.actionable ?? 0) > 0 && { actionable: item.review?.actionable }),
         ...(item.checks?.incomplete && { checksIncomplete: true }),
         ...(item.review?.incomplete && { reviewIncomplete: true }),
+        ...(item.ruleAutoResolve && { ruleAutoResolve: item.ruleAutoResolve }),
         ...(removal && {
             queueRemoval: {
                 reason: removal.reason,
@@ -156,6 +158,7 @@ function formatLayerLines(layer, index, overview) {
     return [
         `- ${layer.url === formatPrUrl(overview.repo, layer.pr) ? `PR #${layer.pr}: ${layer.title}` : `[PR #${layer.pr}: ${layer.title}](${layer.url})`}${facts.length > 0 ? ` — ${facts.join(" · ")}` : ""}`,
         `  - ${details.join(" · ")}`,
+        ...formatRuleAutoResolveLines(layer.ruleAutoResolve),
         ...(layer.transport ? [`  - transport \`${layer.transport}\``] : []),
         ...(layer.transportUnavailable ?? []).map(({ field, reason }) => `  - unavailable \`${field}\`: ${reason}`),
     ];

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

@@ -0,0 +1,8 @@
+import type { BatchPartition } from "../classify/apply.mts";
+import type { PrActivitySummary } from "../types.mts";
+/**
+ * Drop rule-suppressed items from the activity digest, matching what `check` hides from the
+ * agent. IDs whose automatic minimize/resolve was denied stay visible: `check` surfaces those
+ * once so the caller can act. `reviewRoundCount` is raw review history and stays unchanged.
+ */
+export declare function filterSuppressedActivity(activity: PrActivitySummary | undefined, partition: BatchPartition, denied: Iterable<string>): PrActivitySummary | undefined;

package/bin/commands/check-activity.mjs

@@ -0,0 +1,26 @@
+/**
+ * Drop rule-suppressed items from the activity digest, matching what `check` hides from the
+ * agent. IDs whose automatic minimize/resolve was denied stay visible: `check` surfaces those
+ * once so the caller can act. `reviewRoundCount` is raw review history and stays unchanged.
+ */
+export function filterSuppressedActivity(activity, partition, denied) {
+    if (!activity)
+        return activity;
+    const deniedIds = new Set(denied);
+    const hidden = (id, suppressed) => suppressed.has(id) && !deniedIds.has(id);
+    const reviewItemsSinceLatestCommit = activity.reviewItemsSinceLatestCommit.filter((item) => {
+        switch (item.kind) {
+            case "pr-comment":
+                return !hidden(item.id, partition.suppressedCommentIds);
+            case "review-thread-comment":
+                return !item.threadId || !hidden(item.threadId, partition.suppressedThreadIds);
+            case "review-summary":
+                return !hidden(item.id, partition.suppressedReviewSummaryIds);
+            case "changes-requested-review":
+                return !partition.suppressedChangesRequestedIds.has(item.id);
+            default:
+                return true;
+        }
+    });
+    return { ...activity, reviewItemsSinceLatestCommit };
+}

package/bin/commands/check-annotations.mjs

@@ -42,7 +42,8 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
         ...buckets.filtered,
         ...buckets.ignored,
     ].filter(shouldFetchCheckAnnotations);
-    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts);
+    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 });
     const byId = new Map(annotated.flatMap((c) => (c.id != null ? [[c.id, c]] : [])));
     const apply = (list) => list.map((c) => {
         const next = (c.id == null ? undefined : byId.get(c.id)) ?? c;

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-wait-detectors.mjs

@@ -30,6 +30,17 @@ function detectorsCover(stored) {
  * Read the PR's REST change detectors: the pull, the head's check runs, check suites and
  * statuses, the three feedback lists, and the base branch. Every read is conditional, so an
  * unchanged resource answers a free 304.
+ *
+ * The feedback lists are deliberately not rule-aware (#635 gap 7). An edited bot comment, even
+ * a rule-suppressed or minimized one, answers 200 and wakes the tick. The wake costs one
+ * charged list read plus one `BatchPr` first page (a complete fingerprint needs no more),
+ * the same point a fingerprint hit spends. Once the digest is re-recorded, a later eligible
+ * tick can replay for free again, but only if every detector answers 304 with that digest and
+ * the stored snapshot is within `poll.reconcile-seconds`; otherwise it goes to `BatchPr`. Being
+ * rule-aware would need the loaded rules, a persisted set of hidden comment ids (REST has no
+ * `isMinimized`), and a content digest in place of the ETag. That is more code, and more risk
+ * of sleeping through a real change (a rule-suppressed comment edited so it no longer matches,
+ * an edited minimized human comment, which `check` surfaces), than the one point it saves.
  */
 async function readDetectors(prNumber, repo, report) {
     const prefix = restRepoPath(repo);

package/bin/commands/check.mjs

@@ -33,6 +33,7 @@ import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./iterate/thread-mutation-routing.mjs";
 import { loadClassifyRules } from "../classify/loader.mjs";
+import { filterSuppressedActivity } from "./check-activity.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
@@ -260,7 +261,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,
@@ -268,7 +271,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;
@@ -449,7 +452,11 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         ...(batchData.allowedMergeMethods && {
             allowedMergeMethods: batchData.allowedMergeMethods,
         }),
-        activity: batchData.activity,
+        activity: filterSuppressedActivity(batchData.activity, partition, [
+            ...deniedRuleAutoResolveCommentIds,
+            ...deniedRuleAutoResolveThreadIds,
+            ...deniedRuleAutoResolveReviewSummaryIds,
+        ]),
         ...(hasQueueState && {
             mergeQueue: {
                 enabled: Boolean(batchData.isMergeQueueEnabled),

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

@@ -1,2 +1,8 @@
 import type { PollSummaryResult } from "../types.mts";
+/**
+ * Decision-relevant state only. Raw review totals and the ignored, skipped, filtered, and
+ * superseded check counts move when rules suppress a bot notice or a bot reposts a status
+ * check, which would reprint quiet polls and keep an idle stack from reaching `stall-timeout`.
+ * Post-rule `actionable` and the check transitions that drive routing stay in.
+ */
 export declare function summaryStatusSignature(result: PollSummaryResult): string;

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

@@ -1,3 +1,9 @@
+/**
+ * Decision-relevant state only. Raw review totals and the ignored, skipped, filtered, and
+ * superseded check counts move when rules suppress a bot notice or a bot reposts a status
+ * check, which would reprint quiet polls and keep an idle stack from reaching `stall-timeout`.
+ * Post-rule `actionable` and the check transitions that drive routing stay in.
+ */
 export function summaryStatusSignature(result) {
     return JSON.stringify({
         nextAction: result.nextAction,
@@ -9,8 +15,19 @@ export function summaryStatusSignature(result) {
             mergeable: item.mergeable,
             mergeStateStatus: item.mergeStateStatus,
             reviewDecision: item.reviewDecision,
-            checks: item.checks,
-            review: item.review,
+            checks: item.checks && {
+                passing: item.checks.passing,
+                failing: item.checks.failing,
+                inProgress: item.checks.inProgress,
+                incomplete: item.checks.incomplete,
+                annotated: item.checks.annotated,
+                unreportedRequired: item.checks.unreportedRequired,
+                actionsWorkflowInProgress: item.checks.actionsWorkflowInProgress,
+            },
+            review: item.review && {
+                actionable: item.review.actionable,
+                incomplete: item.review.incomplete,
+            },
         })),
     });
 }