pr-shepherd 1.1.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.1.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/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-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.mjs

@@ -261,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,
@@ -269,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;

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),

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

@@ -17,8 +17,11 @@ export declare function onlyDraftReadinessVerification(sessions: PollSummaryItem
  * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
+/** The literal stack command to rerun, or the generic name when the caller's command is unknown. */
+export declare function stackRerunTarget(command?: string): string;
 /**
  * The closing step after routed sessions: rerun the stack command, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
+ * `keepWatching` is false when a human handoff may end the run before every layer is terminal.
  */
-export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string): "shepherd" | "escalate";
+export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string, keepWatching?: boolean): "shepherd" | "escalate";

package/bin/commands/stack-work.mjs

@@ -35,12 +35,20 @@ function isProbed(item) {
 function onlyUnownedWork(layers) {
     return layers.length > 0 && layers.every((item) => !item.owned);
 }
+/** The turn must outlive every non-terminal layer; a one-PR session ending does not end the stack. */
+const STACK_KEEP_WATCHING = "Keep watching until every layer is terminal.";
+/** The literal stack command to rerun, or the generic name when the caller's command is unknown. */
+export function stackRerunTarget(command) {
+    return command ? `\`${command}\`` : "this same `stack` command";
+}
 /**
  * The closing step after routed sessions: rerun the stack command, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
+ * `keepWatching` is false when a human handoff may end the run before every layer is terminal.
  */
-export function appendStackRerunInstruction(instructions, layers, rerun) {
+export function appendStackRerunInstruction(instructions, layers, rerun, keepWatching = true) {
     const stop = onlyUnownedWork(layers);
-    instructions.push(`${instructions.length + 1}. ${stop ? "No owned layer needs a session. Report this overview and stop." : rerun}`);
+    const step = keepWatching ? `${rerun} ${STACK_KEEP_WATCHING}` : rerun;
+    instructions.push(`${instructions.length + 1}. ${stop ? "No owned layer needs a session. Report this overview and stop." : step}`);
     return stop ? "escalate" : "shepherd";
 }

package/bin/commands/tick.mjs

@@ -86,6 +86,7 @@ async function withAggregateNextCheck(result, opts) {
 function withoutPollingCadence(step) {
     return step
         .replace(/ Recheck(?: them)? at the configured polling cadence\./g, "")
+        .replace(/Do not end the turn while any selected row is non-terminal: /g, "Keep watching every non-terminal selected row through the wake-up below: ")
         .replace("rerun that command at the configured cadence to resume its UUID", "rerun that command after the wake-up below to resume its UUID");
 }
 function aggregateNextCheck(result, stallDeadlineSeconds) {

package/bin/github/batch-parser-helpers.mjs

@@ -28,6 +28,7 @@ export function mapCheckRunNode(node) {
     const summary = extractCheckRunSummary(node.title, node.summary);
     const rawCreatedAt = node.checkSuite?.workflowRun?.createdAt ?? node.checkSuite?.createdAt;
     const rawUpdatedAt = node.checkSuite?.workflowRun?.updatedAt ?? node.checkSuite?.updatedAt;
+    const suiteStatus = node.checkSuite?.status || undefined;
     const createdAtUnix = rawCreatedAt ? parseCreatedAt(rawCreatedAt) : undefined;
     const startedAtUnix = node.startedAt ? parseCreatedAt(node.startedAt) : undefined;
     const completedAtUnix = node.completedAt ? parseCreatedAt(node.completedAt) : undefined;
@@ -43,6 +44,7 @@ export function mapCheckRunNode(node) {
         runId,
         ...(workflowName !== undefined && { workflowName }),
         ...(workflowId !== undefined && { workflowId }),
+        ...(suiteStatus !== undefined && { suiteStatus }),
         ...(createdAtUnix !== undefined && { createdAtUnix }),
         ...(startedAtUnix !== undefined && { startedAtUnix }),
         ...(completedAtUnix !== undefined && { completedAtUnix }),

package/bin/github/batch-raw-types.d.mts

@@ -234,6 +234,7 @@ export type RawContextNode = {
         }>;
     };
     checkSuite: {
+        status?: string | null;
         createdAt?: string;
         updatedAt?: string;
         workflowRun: {

package/bin/github/github-fetch.d.mts

@@ -1,2 +1,6 @@
-/** Attach proxy routing to GitHub requests without changing the host's dispatcher. */
-export declare function githubFetch(input: string | URL, init?: RequestInit): Promise<Response>;
+/**
+ * Attach proxy routing to GitHub requests without changing the host's dispatcher.
+ * The request, including reading its body, is bounded by `timeoutMs`; a stall
+ * rejects with an ETIMEDOUT error that the transport retry treats as transient.
+ */
+export declare function githubFetch(input: string | URL, init?: RequestInit, timeoutMs?: number): Promise<Response>;

package/bin/github/github-fetch.mjs

@@ -1,5 +1,7 @@
 import { createRequire } from "node:module";
 import { createCapturedProxyAgent } from "./captured-proxy-agent.mjs";
+import { GITHUB_API_TIMEOUT_MS } from "./github-timeouts.mjs";
+import { redactUrl } from "./http-utils.mjs";
 import { loadUndiciKeepingLegacyDispatcher } from "./legacy-dispatcher.mjs";
 const require = createRequire(import.meta.url);
 let proxyAgent;
@@ -9,8 +11,41 @@ function loadUndici() {
     undiciModule ??= loadUndiciKeepingLegacyDispatcher(() => require("undici"));
     return undiciModule;
 }
-/** Attach proxy routing to GitHub requests without changing the host's dispatcher. */
-export async function githubFetch(input, init) {
+/**
+ * Attach proxy routing to GitHub requests without changing the host's dispatcher.
+ * The request, including reading its body, is bounded by `timeoutMs`; a stall
+ * rejects with an ETIMEDOUT error that the transport retry treats as transient.
+ */
+export async function githubFetch(input, init, timeoutMs = GITHUB_API_TIMEOUT_MS) {
+    const deadline = AbortSignal.timeout(timeoutMs);
+    const signal = init?.signal ? AbortSignal.any([init.signal, deadline]) : deadline;
+    try {
+        return await bufferBody(await routedFetch(input, { ...init, signal }));
+    }
+    catch (err) {
+        if (deadline.aborted && !init?.signal?.aborted) {
+            const method = init?.method ?? "GET";
+            throw Object.assign(new Error(`GitHub request timed out after ${timeoutMs / 1000}s: ${method} ${redactUrl(String(input))}`, { cause: err }), { code: "ETIMEDOUT" });
+        }
+        throw err;
+    }
+}
+/**
+ * Read a streamed body inside the deadline and the callers' transport retry, so a
+ * body that stalls after the headers is retried like a stalled request. Callers
+ * read every body in full anyway.
+ */
+async function bufferBody(response) {
+    if (typeof response.body?.getReader !== "function")
+        return response;
+    const bytes = await response.arrayBuffer();
+    return new Response(bytes.byteLength > 0 ? bytes : null, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+async function routedFetch(input, init) {
     const httpProxy = process.env["http_proxy"] ?? process.env["HTTP_PROXY"] ?? "";
     const httpsProxy = process.env["https_proxy"] ?? process.env["HTTPS_PROXY"] ?? "";
     if (!httpProxy && !httpsProxy)

package/bin/github/github-timeouts.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Deadline for one GitHub REST or GraphQL request, headers and body included.
+ * Without it a half-open connection waits for undici's 300s headers/body
+ * defaults (10s for connect) and the tick prints nothing meanwhile.
+ */
+export declare const GITHUB_API_TIMEOUT_MS = 60000;
+/** Deadline for Actions log downloads, which can be several megabytes. */
+export declare const GITHUB_LOG_TIMEOUT_MS = 180000;

package/bin/github/github-timeouts.mjs

@@ -0,0 +1,8 @@
+/**
+ * Deadline for one GitHub REST or GraphQL request, headers and body included.
+ * Without it a half-open connection waits for undici's 300s headers/body
+ * defaults (10s for connect) and the tick prints nothing meanwhile.
+ */
+export const GITHUB_API_TIMEOUT_MS = 60_000;
+/** Deadline for Actions log downloads, which can be several megabytes. */
+export const GITHUB_LOG_TIMEOUT_MS = 180_000;

package/bin/github/gql/batch-pr-page.gql

@@ -196,6 +196,7 @@ query BatchPrPage(
                       }
                     }
                     checkSuite {
+                      status
                       createdAt
                       updatedAt
                       workflowRun {

package/bin/github/gql/batch-pr.gql

@@ -356,6 +356,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
                       }
                     }
                     checkSuite {
+                      status
                       createdAt
                       updatedAt
                       workflowRun {

package/bin/github/gql/commit-check-contexts.gql

@@ -53,6 +53,7 @@ query CommitCheckContexts($owner: String!, $repo: String!, $oid: String!, $curso
                   }
                 }
                 checkSuite {
+                  status
                   createdAt
                   updatedAt
                   workflowRun {

package/bin/github/gql/poll-summary-check-contexts.gql

@@ -15,6 +15,7 @@ fragment PollSummaryCheckContexts on StatusCheckRollupContextConnection {
       startedAt
       completedAt
       checkSuite {
+        status
         createdAt
         updatedAt
         workflowRun {

package/bin/github/http-utils.mjs

@@ -15,6 +15,9 @@ const TRANSPORT_ERROR_CODES = new Set([
 export function isTransportError(err) {
     if (!(err instanceof Error))
         return false;
+    // The request deadline aborts a stalled body read with a TimeoutError.
+    if (err.name === "TimeoutError")
+        return true;
     const code = err.code;
     if (code && TRANSPORT_ERROR_CODES.has(code))
         return true;

package/bin/github/poll-summary-checks.mjs

@@ -93,6 +93,7 @@ function checkRuns(rollup, scope) {
             ...(run?.workflow?.databaseId != null && {
                 workflowId: String(run.workflow.databaseId),
             }),
+            ...(context.checkSuite?.status && { suiteStatus: context.checkSuite.status }),
             ...(context.startedAt && { startedAtUnix: parseCreatedAt(context.startedAt) }),
             ...(context.completedAt && { completedAtUnix: parseCreatedAt(context.completedAt) }),
             ...(scope && { scope }),

package/bin/github/poll-summary-command.d.mts

@@ -1,2 +1,8 @@
-import type { PollSummaryCommandOptions, PollSummaryItem } from "../types.mts";
+import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection } from "../types.mts";
 export declare function pollCommandFields(repo: string, pr: number, isDraft: boolean, opts: PollSummaryCommandOptions): Pick<PollSummaryItem, "pollCommand" | "pollProbe">;
+/**
+ * The literal command that re-runs this aggregate selection with the options the caller used.
+ * Intervals and timeouts are omitted: they are loop cadence, not selection. Options equal to the
+ * configured defaults are omitted too, since the parser fills them from config.
+ */
+export declare function aggregateRerunCommand(repo: string, selection: PollSummarySelection, opts: PollSummaryCommandOptions): string;

package/bin/github/poll-summary-command.mjs

@@ -24,3 +24,32 @@ export function pollCommandFields(repo, pr, isDraft, opts) {
     const pollCommand = buildPrShepherdCommand(args).text;
     return boundedDraft ? { pollCommand, pollProbe: true } : { pollCommand };
 }
+/**
+ * The literal command that re-runs this aggregate selection with the options the caller used.
+ * Intervals and timeouts are omitted: they are loop cadence, not selection. Options equal to the
+ * configured defaults are omitted too, since the parser fills them from config.
+ */
+export function aggregateRerunCommand(repo, selection, opts) {
+    const args = selection.kind === "stack"
+        ? ["stack", formatPrUrl(repo, selection.anchor), opts.tick ? "--once" : "--until-terminal"]
+        : [
+            ...(opts.tick ? ["iterate"] : []),
+            ...selection.requested.map((pr) => formatPrUrl(repo, pr)),
+            ...(opts.tick ? [] : ["--until-terminal"]),
+        ];
+    if (opts.merge)
+        args.push("--merge");
+    // The parser always fills these from config, so a default value adds nothing to the command.
+    const iterate = loadConfig().iterate;
+    if (opts.readyDelaySeconds !== undefined &&
+        opts.readyDelaySeconds !== iterate["ready-delay-minutes"] * 60)
+        args.push("--ready-delay", `${opts.readyDelaySeconds}s`);
+    if (opts.stallTimeoutSeconds !== undefined &&
+        opts.stallTimeoutSeconds !== iterate["stall-timeout-minutes"] * 60)
+        args.push("--stall-timeout", `${opts.stallTimeoutSeconds}s`);
+    if (opts.instructions)
+        args.push("--instructions", opts.instructions);
+    if (opts.noAutoMarkReady)
+        args.push("--no-auto-mark-ready");
+    return buildPrShepherdCommand(args).text;
+}

package/bin/github/poll-summary-projector.mjs

@@ -12,7 +12,7 @@ import { isCurrentSummaryReady } from "./poll-summary-readiness.mjs";
 import { applyOpenCheckBlockers } from "./poll-summary-check-blockers.mjs";
 import { normalizePollSummaryState, routePollSummary } from "./poll-summary-route.mjs";
 import { hydrateReadyAnnotationProbe, readyFingerprint } from "./poll-summary-annotation-probe.mjs";
-import { applyUnreportedRequiredChecks, summaryRequiredContexts, } from "./poll-summary-unreported.mjs";
+import { applyPendingWorkflowSuites, applyUnreportedRequiredChecks, summaryRequiredContexts, } from "./poll-summary-unreported.mjs";
 import { aliasThreadSeenMarkers } from "./rest-identities.mjs";
 import { restQueueRequirement } from "./poll-summary-rest-queue.mjs";
 import { detectBlockingReviewer } from "./poll-summary-blocking-reviewer.mjs";
@@ -25,6 +25,7 @@ applyRuleAutoResolve = false) {
     const required = summaryRequiredContexts(raw, mergeTargetContexts);
     const checks = summarizePollSummaryChecks(raw, required);
     applyUnreportedRequiredChecks(raw, checks, required);
+    applyPendingWorkflowSuites(raw, checks);
     const { review, ruleAutoResolve } = await evaluatePollSummaryReview(raw, seen, viewerCanAdminister, applyRuleAutoResolve && normalizePollSummaryState(raw.state) === "OPEN"
         ? { owner: repo.owner, repo: repo.name, pr: raw.number }
         : undefined);

package/bin/github/poll-summary-raw.d.mts

@@ -46,6 +46,7 @@ type RawCheckContext = {
         totalCount: number;
     };
     checkSuite: {
+        status?: string | null;
         createdAt?: string | null;
         updatedAt?: string | null;
         workflowRun: {

package/bin/github/poll-summary-readiness.mjs

@@ -1,6 +1,7 @@
 import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
 import { parseBranchRules } from "./batch-parsers-rules.mjs";
 import { rulesComplete } from "./fingerprint-fields.mjs";
+import { hasNoRelevantChecks } from "./poll-summary-unreported.mjs";
 import { isKnownMergeStateStatus, transportReadinessGaps } from "./transport-evidence.mjs";
 /**
  * Fresh compact evidence required before a READY receipt can be used.
@@ -42,5 +43,6 @@ export function isCurrentSummaryReady(raw, checks, review, options = {}) {
         (sourceChecks.failing ?? 0) === 0 &&
         (sourceChecks.inProgress ?? 0) === 0 &&
         (checks.unreportedRequired?.length ?? 0) === 0 &&
+        !(checks.actionsWorkflowInProgress === true && hasNoRelevantChecks(checks)) &&
         (review.actionable ?? 0) === 0);
 }

package/bin/github/poll-summary-route.mjs

@@ -1,4 +1,5 @@
 import { loadConfig } from "../config/load.mjs";
+import { hasNoRelevantChecks } from "./poll-summary-unreported.mjs";
 import { isKnownMergeStateStatus, transportReadinessGaps } from "./transport-evidence.mjs";
 import { canGenerateGithubMutation } from "./mutation-policy.mjs";
 import { getGithubTransport, isCcrTransport } from "./transport.mjs";
@@ -25,6 +26,7 @@ export function routePollSummary(raw, checks, review, opts) {
         return { action: "triage", reasons: ["unreported-required-checks"] };
     }
     if ((checks.inProgress ?? 0) > 0 ||
+        (checks.actionsWorkflowInProgress === true && hasNoRelevantChecks(checks)) ||
         !isKnownMergeStateStatus(raw.mergeStateStatus) ||
         raw.mergeable === "UNKNOWN" ||
         raw.mergeStateStatus === "UNKNOWN")

package/bin/github/poll-summary-unreported.d.mts

@@ -7,3 +7,10 @@ export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[],
 export declare function summaryRequiredContexts(raw: RawSummaryPr, mergeTargetContexts: readonly string[] | undefined): string[];
 /** Record missing required contexts. A running Actions workflow does not clear the names. */
 export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, required: readonly string[]): void;
+/** No relevant check yet. A skipped, filtered, ignored or superseded check is not relevant. */
+export declare function hasNoRelevantChecks(checks: PollSummaryChecks): boolean;
+/**
+ * Flag a running Actions workflow suite when the head has no relevant check yet. Suites exist
+ * before their check runs, so CLEAN with no checks is not proof that CI passed.
+ */
+export declare function applyPendingWorkflowSuites(raw: RawSummaryPr, checks: PollSummaryChecks): void;

package/bin/github/poll-summary-unreported.mjs

@@ -37,6 +37,22 @@ export function applyUnreportedRequiredChecks(raw, checks, required) {
         checks.actionsWorkflowInProgress = true;
     }
 }
+/** No relevant check yet. A skipped, filtered, ignored or superseded check is not relevant. */
+export function hasNoRelevantChecks(checks) {
+    return (checks.passing ?? 0) + (checks.failing ?? 0) + (checks.inProgress ?? 0) === 0;
+}
+/**
+ * Flag a running Actions workflow suite when the head has no relevant check yet. Suites exist
+ * before their check runs, so CLEAN with no checks is not proof that CI passed.
+ */
+export function applyPendingWorkflowSuites(raw, checks) {
+    if (checks.actionsWorkflowInProgress === true || !hasNoRelevantChecks(checks))
+        return;
+    const suites = raw.commits.nodes[0]?.commit.checkSuites?.nodes ?? [];
+    if (actionsWorkflowInProgress(suites, new Set(loadConfig().checks["ci-trigger-events"]))) {
+        checks.actionsWorkflowInProgress = true;
+    }
+}
 function reportedNames(raw) {
     const names = new Set();
     const rollups = [

package/bin/github/rest-check-read.mjs

@@ -3,8 +3,9 @@ import { recordRestIdentity } from "./rest-identities.mjs";
 import { readRest as rest } from "./rest-reader-core.mjs";
 export async function readRestCommitChecks(oid, repo, pr = 0) {
     const prefix = restRepoPath(repo);
-    const checks = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
+    // Suites first: a COMPLETED suite read before the runs means a run still not COMPLETED is stuck.
     const suites = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-suites`, (body) => restCollection(body, "check_suites"));
+    const checks = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
     const statuses = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/statuses`);
     const workflowRuns = await readRestPages(`${prefix}/actions/runs?head_sha=${encodeURIComponent(oid)}`, (body) => restCollection(body, "workflow_runs"));
     for (const suite of suites.nodes) {
@@ -64,6 +65,7 @@ export async function readRestCommitChecks(oid, repo, pr = 0) {
             annotations: { totalCount: check.output.annotations_count, nodes: [] },
             checkSuite: suite
                 ? {
+                    status: suite.status.toUpperCase(),
                     createdAt: suite.created_at,
                     updatedAt: suite.updated_at,
                     workflowRun: run

package/bin/github/rest-text.mjs

@@ -2,6 +2,7 @@ import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { githubFetch } from "./github-fetch.mjs";
+import { GITHUB_LOG_TIMEOUT_MS } from "./github-timeouts.mjs";
 import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody, } from "./http-utils.mjs";
@@ -19,7 +20,7 @@ export async function restText(path, onRateLimit) {
         const auth = await makeAuthHeaders();
         authSource = auth.source;
         credentialFingerprint = auth.fingerprint;
-        return githubFetch(url, { method: "GET", headers: auth.headers, redirect: "manual" });
+        return githubFetch(url, { method: "GET", headers: auth.headers, redirect: "manual" }, GITHUB_LOG_TIMEOUT_MS);
     }, t0, (response, durationMs) => recordIntermediateResponse({
         n,
         kind: "restText",
@@ -105,7 +106,7 @@ async function followRestTextRedirect(res, entry) {
     const logUrl = redactUrl(location);
     appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
     const t1 = performance.now();
-    const redirectRes = await githubFetch(location);
+    const redirectRes = await githubFetch(location, undefined, GITHUB_LOG_TIMEOUT_MS);
     appendEntry(formatResponseEntry({
         n: n2,
         kind: "restText",

package/bin/github/stack-handoff-page.mjs

@@ -90,6 +90,7 @@ export function batchResponseFromSummary(layer, source, runs) {
             ...(run.annotations && { annotations: run.annotations }),
             checkSuite: suite
                 ? {
+                    ...(suite.status && { status: suite.status }),
                     ...(suite.createdAt && { createdAt: suite.createdAt }),
                     ...(suite.updatedAt && { updatedAt: suite.updatedAt }),
                     workflowRun: workflowRun

package/bin/reporters/agent.mjs

@@ -59,6 +59,8 @@ export function toAgentCheck(c) {
         runId: c.runId,
         detailsUrl: c.detailsUrl,
         conclusion: c.conclusion,
+        ...(c.status !== "COMPLETED" &&
+            c.suiteStatus !== undefined && { status: c.status, suiteStatus: c.suiteStatus }),
         ...(c.runAttempt !== undefined && c.runAttempt > 1 && { runAttempt: c.runAttempt }),
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.jobName !== undefined && { jobName: c.jobName }),

package/bin/types/github.d.mts

@@ -57,6 +57,12 @@ export interface CheckRun {
     summary?: string;
     /** Workflow display name for GitHub Actions check runs, when GraphQL exposes it. */
     workflowName?: string;
+    /**
+     * Raw status of the check suite this run belongs to. Absent when GitHub did not report one
+     * (status contexts, synthetic checks, or a transport that cannot read it). A `COMPLETED`
+     * suite with a run that is not `COMPLETED` is a stuck check.
+     */
+    suiteStatus?: string;
     workflowId?: string;
     /** True when GraphQL reported at least one CheckRun annotation. Omitted when false. */
     hasAnnotations?: boolean;

package/bin/types/report.d.mts

@@ -1,4 +1,4 @@
-import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, ViewerAuthorization, CheckConclusion, SuggestionBlock } from "./github.mts";
+import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, ViewerAuthorization, CheckConclusion, CheckStatus, SuggestionBlock } from "./github.mts";
 import type { ClassifiedCheck, RelatedFailedJob, TriagedCheck } from "./check-classification.mts";
 import type { AgentThreadComment } from "./agent-thread.mts";
 import type { CheckAnnotation } from "./check-annotations.mts";
@@ -196,6 +196,10 @@ export interface AgentCheck {
     detailsUrl: string | null;
     /** Raw GitHub check conclusion; may be null for some completed checks from upstream data. */
     conclusion: CheckConclusion;
+    /** Raw check status, present only for a stuck check: not `COMPLETED` while its suite is. */
+    status?: CheckStatus;
+    /** Raw check-suite status (`COMPLETED`), present only with `status` for a stuck check. */
+    suiteStatus?: string;
     /** Workflow display name (e.g. `"CI"`). Populated on a best-effort basis when available from the jobs API. */
     workflowName?: string;
     /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from check name for matrix builds. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.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.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@1.1.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@1.1.1", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@1.1.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@1.1.1", "pr-shepherd-mcp"]
   }
 }

package/plugins/pr-shepherd/skills/pr-shepherd/references/ci-failure-triage.md

@@ -13,6 +13,7 @@ Apply when a step says `Playbook: "CI failure triage"`. Use the excerpts and tag
 - Actions failure with a run id: read the excerpt. Fix a real test or build failure in code and never rerun it, even with a printed `rerun:`. Run a printed `rerun:` only for a transient cause; without one, finish the other work. Then iterate without waiting.
 - An empty excerpt is not evidence of a transient failure. A gate-job excerpt naming failed jobs (for example `test-playwright: failure`) is test-failure evidence even without a stack trace: read the `Other failed jobs in this run` tails first, and only when a named job's tail is absent or truncated run `gh run view <runId> --log-failed -R <owner/repo>`. Rerun only when those logs show a transient cause.
 - `CANCELLED` or `STARTUP_FAILURE` (no excerpt): run a printed `rerun:`, else finish the other work; iterate without waiting.
+- `[status: …, suite: COMPLETED]` (stuck run): the workflow finished but this check never completed, so there is nothing to fix in code. Run a printed `rerun:`, else finish the other work; iterate without waiting.
 - `ACTION_REQUIRED`: finish the other work and iterate. Shepherd escalates if manual approval is still required.
 - `external` with a URL: inspect the provider or reproduce locally, fix, and iterate. The URL alone is not `[ESCALATE]`.
 - `(no runId)` without a URL: keep the metadata. Shepherd escalates when nothing else remains.