pr-shepherd 1.1.0 → 1.1.2

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

@@ -4,7 +4,7 @@ import type { RawSummaryPr } from "./poll-summary-raw.mts";
 type Routed = Pick<PollSummaryItem, "action" | "reasons">;
 /**
  * The one-PR check treats unseen annotations on any non-SUCCESS check (failing, skipped,
- * filtered, ignored or neutral) as actionable work. The compact summary only has annotation
+ * filtered or neutral) as actionable work; `checks.ignore` checks never gate, annotations included. The compact summary only has annotation
  * totals, and only for a row that otherwise claims readiness, so it loads them then and reads
  * the annotations of just the non-SUCCESS checks that have any. A row with unseen annotations,
  * or whose annotations cannot be read, goes to its one-PR `pollCommand` instead of

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

@@ -11,7 +11,7 @@ const READY_CLAIMS = new Set([
 ]);
 /**
  * The one-PR check treats unseen annotations on any non-SUCCESS check (failing, skipped,
- * filtered, ignored or neutral) as actionable work. The compact summary only has annotation
+ * filtered or neutral) as actionable work; `checks.ignore` checks never gate, annotations included. The compact summary only has annotation
  * totals, and only for a row that otherwise claims readiness, so it loads them then and reads
  * the annotations of just the non-SUCCESS checks that have any. A row with unseen annotations,
  * or whose annotations cannot be read, goes to its one-PR `pollCommand` instead of
@@ -44,7 +44,7 @@ function nonSuccessCheckTotals(raw, required, totalsKnown) {
     for (const check of classifiedSummaryChecks(raw, required)) {
         if (check.scope || check.id == null || !head.has(check.id))
             continue;
-        if (check.category === "in_progress" || check.category === "superseded")
+        if (["in_progress", "superseded", "ignored"].includes(check.category))
             continue;
         if (check.status !== "COMPLETED" || check.conclusion === "SUCCESS")
             continue;

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";
@@ -69,8 +69,6 @@ export interface ShepherdReport {
         skipped: ClassifiedCheck[];
         /** Checks filtered out because they were triggered by a non-PR event (push, schedule, etc.). */
         filtered: ClassifiedCheck[];
-        /** Ignored checks with unseen annotations; omitted when empty. */
-        ignored?: ClassifiedCheck[];
         filteredNames: string[];
         blockedByFilteredCheck: boolean;
         ignoredNames?: string[];
@@ -196,6 +194,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.2",
   "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.2",
   "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.2",
   "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.2", "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.2", "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.