pr-shepherd 0.54.1 → 0.55.1

package/bin/github/poll-summary-annotation-probe.d.mts

@@ -0,0 +1,19 @@
+import { type RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/**
+ * True when a ready layer's annotation probe failed or stopped short of every
+ * check page. Callers must not store or compare a fingerprint of that snapshot:
+ * it is missing annotation totals a later successful probe would include.
+ */
+export declare function annotationProbeUnavailable(pr: RawSummaryPr): boolean;
+/** Stored hash when the probe missed, so a later complete probe can still match. */
+export declare function readyFingerprint(raw: RawSummaryPr, stored: string | null): string | null;
+/**
+ * Annotation totals are omitted from the always-on summary. A layer that
+ * otherwise looks ready loads them once so a READY receipt still changes when
+ * a check gains an annotation.
+ */
+export declare function hydrateReadyAnnotationProbe(pr: RawSummaryPr, repo: RepoInfo, review: {
+    actionable?: number;
+    incomplete?: true;
+}): Promise<void>;

package/bin/github/poll-summary-annotation-probe.mjs

@@ -0,0 +1,88 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { isCurrentSummaryReady } from "./poll-summary-readiness.mjs";
+import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
+import { fingerprintRawSummaryPr } from "./poll-summary-fingerprint.mjs";
+import { POLL_SUMMARY_ANNOTATION_PROBE_QUERY } from "./queries.mjs";
+const PROBE_UNAVAILABLE = Symbol.for("prShepherd.annotationProbeUnavailable");
+/**
+ * True when a ready layer's annotation probe failed or stopped short of every
+ * check page. Callers must not store or compare a fingerprint of that snapshot:
+ * it is missing annotation totals a later successful probe would include.
+ */
+export function annotationProbeUnavailable(pr) {
+    return Boolean(pr[PROBE_UNAVAILABLE]);
+}
+/** Stored hash when the probe missed, so a later complete probe can still match. */
+export function readyFingerprint(raw, stored) {
+    if (annotationProbeUnavailable(raw))
+        return stored;
+    return fingerprintRawSummaryPr(raw);
+}
+/**
+ * Annotation totals are omitted from the always-on summary. A layer that
+ * otherwise looks ready loads them once so a READY receipt still changes when
+ * a check gains an annotation.
+ */
+export async function hydrateReadyAnnotationProbe(pr, repo, review) {
+    const checks = summarizePollSummaryChecks(pr);
+    if (!isCurrentSummaryReady(pr, checks, review))
+        return;
+    if (!(await hydrateCommitAnnotations(pr, repo))) {
+        pr[PROBE_UNAVAILABLE] = true;
+    }
+}
+async function hydrateCommitAnnotations(pr, repo) {
+    const commit = pr.commits.nodes[0]?.commit;
+    const nodes = commit?.statusCheckRollup?.contexts.nodes;
+    if (!commit || !nodes?.some((node) => node.__typename === "CheckRun" && node.id))
+        return true;
+    const pages = await collectProbePages(commit.oid, repo);
+    if (!pages)
+        return false;
+    const probed = new Map(pages.flatMap((node) => node.__typename === "CheckRun" && node.id ? [[node.id, node.annotations]] : []));
+    for (const node of nodes) {
+        if (node.__typename !== "CheckRun" || !node.id)
+            continue;
+        const annotations = probed.get(node.id);
+        if (annotations)
+            node.annotations = annotations;
+    }
+    return true;
+}
+/** Every check page, oldest last. Null when a page cannot be trusted. */
+async function collectProbePages(oid, repo) {
+    const pages = [];
+    let before = null;
+    const seen = new Set();
+    for (;;) {
+        const contexts = await fetchProbePage(oid, repo, before);
+        if (!contexts)
+            return null;
+        pages.push(...contexts.nodes);
+        const pageInfo = contexts.pageInfo;
+        if (!pageInfo?.hasPreviousPage)
+            return pages;
+        const cursor = pageInfo.startCursor;
+        if (!cursor || seen.has(cursor))
+            return null;
+        seen.add(cursor);
+        before = cursor;
+    }
+}
+async function fetchProbePage(oid, repo, before) {
+    try {
+        const { data } = await graphqlWithRateLimit(POLL_SUMMARY_ANNOTATION_PROBE_QUERY, {
+            owner: repo.owner,
+            repo: repo.name,
+            oid,
+            before,
+        });
+        const object = data.repository?.object;
+        if (object?.__typename !== "Commit" || object.oid !== oid)
+            return null;
+        return object.statusCheckRollup?.contexts ?? null;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -33,7 +33,7 @@ export function fingerprintRawSummaryPr(raw) {
             ...raw.commits,
             nodes: raw.commits.nodes.map((node) => ({
                 ...node,
-                commit: { ...node.commit, committedDate: undefined },
+                commit: { ...node.commit, committedDate: undefined, checkSuites: undefined },
             })),
         },
     };

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

@@ -1,4 +1,4 @@
 import type { PollSummaryCommandOptions, PollSummaryItem } from "../types.mts";
 import type { RepoInfo } from "./client.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
-export declare function summarizePollSummaryPr(raw: RawSummaryPr, repo: RepoInfo, opts: PollSummaryCommandOptions, viewerCanAdminister?: boolean): Promise<PollSummaryItem>;
+export declare function summarizePollSummaryPr(raw: RawSummaryPr, repo: RepoInfo, opts: PollSummaryCommandOptions, viewerCanAdminister?: boolean, mergeTargetContexts?: readonly string[], viewerLogin?: string | null): Promise<PollSummaryItem>;

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

@@ -6,15 +6,17 @@ import { loadSeenMap } from "../state/seen-comments.mjs";
 import { isReadyReceiptCurrent, readReadyReceipt } from "../state/ready-receipts.mjs";
 import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
 import { summarizePollSummaryReview } from "./poll-summary-review.mjs";
-import { fingerprintRawSummaryPr } from "./poll-summary-fingerprint.mjs";
 import { currentQueueRemovalEvent } from "./poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "./poll-summary-readiness.mjs";
 import { applyOpenCheckBlockers } from "./poll-summary-check-blockers.mjs";
 import { normalizePollSummaryState, routePollSummary } from "./poll-summary-route.mjs";
-export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdminister = false) {
+import { hydrateReadyAnnotationProbe, readyFingerprint } from "./poll-summary-annotation-probe.mjs";
+import { applyUnreportedRequiredChecks } from "./poll-summary-unreported.mjs";
+export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdminister = false, mergeTargetContexts, viewerLogin = null) {
     const repoName = `${repo.owner}/${repo.name}`;
     const seen = await loadSeenMap({ owner: repo.owner, repo: repo.name, pr: raw.number });
     const checks = summarizePollSummaryChecks(raw);
+    applyUnreportedRequiredChecks(raw, checks, mergeTargetContexts);
     const review = await summarizePollSummaryReview(raw, seen, viewerCanAdminister);
     const blockingReviewerInProgress = detectBlockingReviewer(raw);
     const removalEvent = currentQueueRemovalEvent(raw);
@@ -44,15 +46,17 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
             baseRefName: raw.stack.baseRefName,
         }
         : undefined;
-    const fingerprint = opts.stackPrNumber !== undefined ? fingerprintRawSummaryPr(raw) : null;
-    const receipt = fingerprint
-        ? await readReadyReceipt({ owner: repo.owner, repo: repo.name, pr: raw.number })
-        : null;
-    // A queued PR's target branch can advance as earlier queue entries merge.
-    // Keep the pre-enqueue base binding for the receipt comparison while the
-    // merge group itself supplies the current mergeability evidence.
+    if (opts.stackPrNumber !== undefined)
+        await hydrateReadyAnnotationProbe(raw, repo, review);
+    const receipt = opts.stackPrNumber === undefined
+        ? null
+        : await readReadyReceipt({ owner: repo.owner, repo: repo.name, pr: raw.number });
+    const fingerprint = opts.stackPrNumber === undefined
+        ? null
+        : readyFingerprint(raw, receipt?.readinessFingerprint ?? null);
+    // A queued PR's base can advance. Keep the receipt base while the probe is complete.
     const receiptFingerprint = raw.isInMergeQueue && receipt
-        ? fingerprintRawSummaryPr({ ...raw, baseRefOid: receipt.baseRefOid })
+        ? readyFingerprint({ ...raw, baseRefOid: receipt.baseRefOid }, receipt.readinessFingerprint)
         : fingerprint;
     const currentReady = isCurrentSummaryReady(raw, checks, review, {
         allowQueuedProgress: opts.stackPrNumber !== undefined && raw.isInMergeQueue,
@@ -78,6 +82,10 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
         repo: repoName,
         title: raw.title,
         url: raw.url || formatPrUrl(repoName, raw.number),
+        ...(raw.author?.login && { authorLogin: raw.author.login }),
+        ...(raw.author?.login &&
+            viewerLogin !== null &&
+            raw.author.login.toLowerCase() === viewerLogin.toLowerCase() && { owned: true }),
         action,
         reasons,
         state: normalizePollSummaryState(raw.state),
@@ -131,9 +139,8 @@ function pollCommandFields(repo, pr, isDraft, opts) {
         args.push("--merge");
     if (opts.readyDelaySeconds !== undefined)
         args.push("--ready-delay", `${opts.readyDelaySeconds}s`);
-    if (opts.stallTimeoutSeconds !== undefined) {
+    if (opts.stallTimeoutSeconds !== undefined)
         args.push("--stall-timeout", `${opts.stallTimeoutSeconds}s`);
-    }
     if (opts.noAutoMarkReady && !boundedDraft)
         args.push("--no-auto-mark-ready");
     const pollCommand = buildPrShepherdCommand(args).text;

package/bin/github/poll-summary-queue-removal.mjs

@@ -1,4 +1,4 @@
-import { queueRemovalAppliesToHead } from "./queue-removal-freshness.mjs";
+import { headPushUnixFromCheckNodes, queueRemovalAppliesToHead, } from "./queue-removal-freshness.mjs";
 import { parseCreatedAt } from "./batch-parser-helpers.mjs";
 /** Latest queue removal that still applies to this PR head, not an older attempt. */
 export function currentQueueRemovalEvent(raw) {
@@ -12,11 +12,15 @@ export function currentQueueRemovalEvent(raw) {
     if (addition && Date.parse(addition.createdAt) > removalTime)
         return null;
     const parents = removal.beforeCommit?.parents?.nodes.map((parent) => parent.oid);
-    const headCommittedAt = raw.commits?.nodes[0]?.commit.committedDate;
+    const headCommit = raw.commits?.nodes[0]?.commit;
+    const headPushedAtUnix = headPushUnixFromCheckNodes(headCommit?.statusCheckRollup?.contexts.nodes);
     if (!queueRemovalAppliesToHead({
         parentOids: parents,
         headOid: raw.headRefOid,
-        ...(headCommittedAt && { headCommittedAtUnix: parseCreatedAt(headCommittedAt) }),
+        ...(headCommit?.committedDate && {
+            headCommittedAtUnix: parseCreatedAt(headCommit.committedDate),
+        }),
+        ...(headPushedAtUnix !== undefined && { headPushedAtUnix }),
         removedAtUnix: Math.floor(removalTime / 1000),
     })) {
         return null;

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

@@ -1,3 +1,4 @@
+import type { RawBaseRef } from "./batch-raw-rules.mts";
 export interface RawAuthor {
     __typename?: string;
     login: string;
@@ -29,9 +30,11 @@ type RawCheckContext = {
         totalCount: number;
     };
     checkSuite: {
+        createdAt?: string | null;
         workflowRun: {
             databaseId?: string | number;
             event: string;
+            createdAt?: string | null;
             workflow?: {
                 name: string;
                 databaseId: string | number;
@@ -60,11 +63,23 @@ export interface RawSummaryCommit {
     oid: string;
     committedDate?: string;
     statusCheckRollup: RawCheckRollup | null;
+    checkSuites?: {
+        nodes: Array<{
+            status?: string | null;
+            conclusion: string | null;
+            workflowRun: {
+                event: string | null;
+            } | null;
+        }>;
+    } | null;
 }
 export interface RawSummaryPr {
     number: number;
     title: string;
     url: string;
+    author?: {
+        login: string;
+    } | null;
     state: string;
     updatedAt?: string;
     lifecycleEvents?: {
@@ -79,6 +94,7 @@ export interface RawSummaryPr {
     headRefOid: string;
     baseRefOid: string;
     baseRefName: string;
+    baseRef?: RawBaseRef | null;
     mergeable: string;
     mergeStateStatus: string;
     reviewDecision: string | null;

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

@@ -21,5 +21,6 @@ export function isCurrentSummaryReady(raw, checks, review, options = {}) {
         (checks.failing ?? 0) === 0 &&
         (sourceChecks.failing ?? 0) === 0 &&
         (sourceChecks.inProgress ?? 0) === 0 &&
+        (checks.unreportedRequired?.length ?? 0) === 0 &&
         (review.actionable ?? 0) === 0);
 }

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

@@ -16,6 +16,11 @@ export function routePollSummary(raw, checks, review, opts) {
         }
         return { action: "fix_code", reasons: ["review-work"] };
     }
+    if ((checks.unreportedRequired?.length ?? 0) > 0 &&
+        checks.actionsWorkflowInProgress !== true &&
+        (checks.inProgress ?? 0) === 0) {
+        return { action: "fix_code", reasons: ["unreported-required-checks"] };
+    }
     if ((checks.inProgress ?? 0) > 0 ||
         raw.mergeable === "UNKNOWN" ||
         raw.mergeStateStatus === "UNKNOWN" ||

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

@@ -0,0 +1,6 @@
+import type { PollSummaryChecks } from "../types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/** Required contexts from the open layer whose base is the stack trunk. */
+export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[]): string[] | undefined;
+/** Record missing required contexts. A running Actions workflow does not clear the names. */
+export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, mergeTargetContexts: readonly string[] | undefined): void;

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

@@ -0,0 +1,51 @@
+import { loadConfig } from "../config/load.mjs";
+import { actionsWorkflowInProgress, selectMergeTargetContexts, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+/** Required contexts from the open layer whose base is the stack trunk. */
+export function trunkRequiredContexts(ordered) {
+    const trunk = ordered.find((pr) => pr.stack)?.stack?.baseRefName;
+    if (!trunk)
+        return undefined;
+    const bottom = ordered.find((pr) => pr.state === "OPEN" && pr.baseRefName === trunk);
+    if (!bottom)
+        return undefined;
+    return parseBranchRules(bottom.baseRef).requiredStatusCheckContexts;
+}
+/** Record missing required contexts. A running Actions workflow does not clear the names. */
+export function applyUnreportedRequiredChecks(raw, checks, mergeTargetContexts) {
+    const trunk = raw.stack?.baseRefName;
+    const required = selectMergeTargetContexts({
+        localContexts: parseBranchRules(raw.baseRef).requiredStatusCheckContexts,
+        ...(mergeTargetContexts !== undefined && { trunkContexts: mergeTargetContexts }),
+        baseRefName: raw.baseRefName,
+        ...(trunk !== undefined && mergeTargetContexts !== undefined && { trunkRefName: trunk }),
+    });
+    const missing = unreportedRequiredContexts(required, reportedNames(raw));
+    if (missing.length === 0)
+        return;
+    checks.unreportedRequired = missing;
+    const suites = raw.commits.nodes[0]?.commit.checkSuites?.nodes ?? [];
+    if (actionsWorkflowInProgress(suites, new Set(loadConfig().checks.ciTriggerEvents))) {
+        checks.actionsWorkflowInProgress = true;
+    }
+}
+function reportedNames(raw) {
+    const names = new Set();
+    const rollups = [
+        raw.commits.nodes[0]?.commit.statusCheckRollup,
+        raw.mergeQueueEntry?.headCommit?.statusCheckRollup,
+    ];
+    for (const rollup of rollups) {
+        for (const node of rollup?.contexts.nodes ?? []) {
+            if (!node)
+                continue;
+            const name = node.__typename === "CheckRun" ? node.name : node.context;
+            if (typeof name !== "string")
+                continue;
+            const trimmed = name.trim();
+            if (trimmed)
+                names.add(trimmed);
+        }
+    }
+    return names;
+}

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

@@ -5,6 +5,7 @@ export interface FetchedPollSummary {
     selection: PollSummarySelection;
     prs: PollSummaryItem[];
     stackAncestry?: PollSummaryStackAncestry[];
+    allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
 }
 export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;
 /** Fresh, read-only snapshot used to bind a one-PR READY receipt to stack routing. */

package/bin/github/poll-summary.mjs

@@ -1,8 +1,9 @@
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
-import { missingRepositoryError } from "./errors.mjs";
+import { GitHubRequestError, isRetryableGraphQlResourceLimit, missingRepositoryError, } from "./errors.mjs";
 import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
+import { trunkRequiredContexts } from "./poll-summary-unreported.mjs";
 import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
 import { MAX_STACK_ENTRIES_PER_PAGE, readStack, readStackTopology, stackAncestryGaps, } from "./stack-read.mjs";
 const MAX_EXPLICIT_PRS_PER_QUERY = 50;
@@ -62,16 +63,40 @@ async function fetchExplicitChunk(prs, repo) {
 async function fetchStackSummary(opts, repo) {
     const anchor = opts.stackPrNumber;
     const topology = await readStackTopology(anchor, repo);
-    const { stackNumber, stackSize, viewerCanAdminister, ordered } = await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first: Math.min(topology.stackSize, MAX_STACK_ENTRIES_PER_PAGE) });
+    const { stackNumber, stackSize, viewerLogin, viewerCanAdminister, ordered, allowedMergeMethods } = await readStackSummary(anchor, repo, topology.stackSize);
     for (const pr of ordered)
         await hydratePollSummaryChecks(pr, repo);
     const stackAncestry = stackAncestryGaps(ordered);
+    const required = trunkRequiredContexts(ordered);
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
-        prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
+        prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin))),
         ...(stackAncestry.length > 0 && { stackAncestry }),
+        ...(allowedMergeMethods && { allowedMergeMethods }),
     };
 }
+/**
+ * A wide check matrix can blow GitHub's per-query resource limit on the full
+ * page. Halve `first` down to one entry and let `readStack` follow `after`.
+ * The shared summary fragment stays intact: one layer is the same shape as an
+ * explicit summary, and check hydration still completes windows past 100.
+ */
+async function readStackSummary(anchor, repo, stackSize) {
+    let first = Math.min(stackSize, MAX_STACK_ENTRIES_PER_PAGE);
+    for (;;) {
+        try {
+            return await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first });
+        }
+        catch (err) {
+            if (!(err instanceof GitHubRequestError) ||
+                !isRetryableGraphQlResourceLimit(err.graphqlErrors) ||
+                first <= 1) {
+                throw err;
+            }
+            first = Math.floor(first / 2);
+        }
+    }
+}
 function deduplicate(values) {
     return [...new Set(values)];
 }

package/bin/github/queries.d.mts

@@ -14,11 +14,20 @@ export declare const BATCH_PR_PAGE_QUERY: string;
 export declare const PR_FINGERPRINT_QUERY: string;
 /** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
 export declare const POLL_SUMMARY_FRAGMENT: string;
+/** Trunk branch rules plus how far `headRef` is behind that branch. */
+export declare const REF_RULES_QUERY: string;
+/** How far a non-stack head is behind its PR base. One compare, no rules payload. */
+export declare const BASE_BEHIND_QUERY: string;
 /**
  * Pages older status contexts for one commit with the same node selection as
  * the compact summary, so hydrated and first-page nodes fingerprint alike.
  */
 export declare const POLL_SUMMARY_CHECK_PAGE_QUERY: string;
+/**
+ * Annotation totals for one commit, used only when a summary layer otherwise
+ * looks ready. `$before` pages older than the newest 100 contexts.
+ */
+export declare const POLL_SUMMARY_ANNOTATION_PROBE_QUERY: string;
 /** Discovers and summarizes every entry in one native GitHub pull-request stack. */
 export declare const POLL_STACK_SUMMARY_QUERY: string;
 /** Reads only native-stack membership and the refs that link adjacent entries. */

package/bin/github/queries.mjs

@@ -9,7 +9,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
-const withSharedFragments = (query) => `${gql("pr-merge-policy.gql")}\n${gql("commit-check-suites.gql")}\n${query}`;
+const withSharedFragments = (query) => `${gql("ref-rules.gql")}\n${gql("pr-merge-policy.gql")}\n${gql("commit-check-suites.gql")}\n${query}`;
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 export const BATCH_PR_QUERY = withSharedFragments(gql("batch-pr.gql"));
 /** Slim @include follow-up for outstanding batch-query connections. */
@@ -18,12 +18,21 @@ export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
 export const PR_FINGERPRINT_QUERY = withSharedFragments(gql("pr-fingerprint.gql"));
 const POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT = gql("poll-summary-check-contexts.gql");
 /** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
-export const POLL_SUMMARY_FRAGMENT = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
+export const POLL_SUMMARY_FRAGMENT = `${gql("ref-rules.gql")}\n${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
+/** Trunk branch rules plus how far `headRef` is behind that branch. */
+export const REF_RULES_QUERY = `${gql("ref-rules.gql")}\n${gql("ref-rules-query.gql")}`;
+/** How far a non-stack head is behind its PR base. One compare, no rules payload. */
+export const BASE_BEHIND_QUERY = gql("base-behind.gql");
 /**
  * Pages older status contexts for one commit with the same node selection as
  * the compact summary, so hydrated and first-page nodes fingerprint alike.
  */
 export const POLL_SUMMARY_CHECK_PAGE_QUERY = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-check-page.gql")}`;
+/**
+ * Annotation totals for one commit, used only when a summary layer otherwise
+ * looks ready. `$before` pages older than the newest 100 contexts.
+ */
+export const POLL_SUMMARY_ANNOTATION_PROBE_QUERY = gql("poll-summary-annotation-probe.gql");
 /** Discovers and summarizes every entry in one native GitHub pull-request stack. */
 export const POLL_STACK_SUMMARY_QUERY = `${POLL_SUMMARY_FRAGMENT}\n${gql("poll-stack-summary.gql")}`;
 /** Reads only native-stack membership and the refs that link adjacent entries. */

package/bin/github/queue-removal-freshness.d.mts

@@ -1,16 +1,31 @@
+type PushCheckNode = {
+    __typename?: string;
+    checkSuite?: {
+        createdAt?: string | null;
+        workflowRun?: {
+            event?: string | null;
+            createdAt?: string | null;
+        } | null;
+    } | null;
+};
 /**
  * Whether a removed merge-queue commit still belongs to the current PR head.
  *
  * A merge-commit queue lists that head as a parent. Squash and rebase queues
- * build a one-parent commit on the base (or on the previous group commit), so
- * the PR head is not an ancestor. Missing parents are unverifiable: GitHub
- * keeps returning the latest removal after the synthetic commit is gone.
- * A one-parent removal is stale when the current head's committer time is
- * later than the removal, which is a push after the ejection.
+ * build a one-parent commit on the base, so parent identity cannot show a
+ * later push. Missing parents are unverifiable: GitHub keeps returning the
+ * latest removal after the synthetic commit is gone. A one-parent removal is
+ * stale once this head reached the PR after the removal. That time is the
+ * earliest pull_request check on the head, with the head's committer time as
+ * the fallback when no check time is available.
  */
 export declare function queueRemovalAppliesToHead(input: {
     parentOids: readonly string[] | null | undefined;
     headOid: string;
     headCommittedAtUnix?: number;
+    headPushedAtUnix?: number;
     removedAtUnix?: number;
 }): boolean;
+/** Earliest pull_request check-suite time on the head commit, when one exists. */
+export declare function headPushUnixFromCheckNodes(nodes: readonly (PushCheckNode | null)[] | null | undefined): number | undefined;
+export {};

package/bin/github/queue-removal-freshness.mjs

@@ -1,12 +1,15 @@
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
+const PULL_REQUEST_EVENTS = new Set(["pull_request", "pull_request_target"]);
 /**
  * Whether a removed merge-queue commit still belongs to the current PR head.
  *
  * A merge-commit queue lists that head as a parent. Squash and rebase queues
- * build a one-parent commit on the base (or on the previous group commit), so
- * the PR head is not an ancestor. Missing parents are unverifiable: GitHub
- * keeps returning the latest removal after the synthetic commit is gone.
- * A one-parent removal is stale when the current head's committer time is
- * later than the removal, which is a push after the ejection.
+ * build a one-parent commit on the base, so parent identity cannot show a
+ * later push. Missing parents are unverifiable: GitHub keeps returning the
+ * latest removal after the synthetic commit is gone. A one-parent removal is
+ * stale once this head reached the PR after the removal. That time is the
+ * earliest pull_request check on the head, with the head's committer time as
+ * the fallback when no check time is available.
  */
 export function queueRemovalAppliesToHead(input) {
     const parents = input.parentOids ?? [];
@@ -16,11 +19,35 @@ export function queueRemovalAppliesToHead(input) {
         return true;
     if (parents.length > 1)
         return false;
-    if (input.headCommittedAtUnix !== undefined &&
-        input.removedAtUnix !== undefined &&
-        input.removedAtUnix > 0 &&
-        input.headCommittedAtUnix > input.removedAtUnix) {
+    const removedAt = input.removedAtUnix;
+    if (removedAt === undefined || removedAt <= 0)
+        return true;
+    const pushedAt = input.headPushedAtUnix;
+    if (pushedAt !== undefined && pushedAt > 0)
+        return pushedAt <= removedAt;
+    const committedAt = input.headCommittedAtUnix;
+    if (committedAt !== undefined && committedAt > removedAt)
         return false;
-    }
     return true;
 }
+/** Earliest pull_request check-suite time on the head commit, when one exists. */
+export function headPushUnixFromCheckNodes(nodes) {
+    let earliest;
+    for (const node of nodes ?? []) {
+        if (node?.__typename !== "CheckRun")
+            continue;
+        const run = node.checkSuite?.workflowRun;
+        const event = run?.event;
+        if (event == null || !PULL_REQUEST_EVENTS.has(event))
+            continue;
+        const raw = node.checkSuite?.createdAt || run?.createdAt;
+        if (!raw)
+            continue;
+        const at = parseCreatedAt(raw);
+        if (at <= 0)
+            continue;
+        if (earliest === undefined || at < earliest)
+            earliest = at;
+    }
+    return earliest;
+}

package/bin/github/stack-read.d.mts

@@ -1,3 +1,4 @@
+import { type MergeMethod } from "../config/merge-method.mts";
 import type { PollSummaryStackAncestry } from "../types.mts";
 import { type RepoInfo } from "./client.mts";
 /** GitHub's `first` ceiling for one native-stack entries page. */
@@ -15,9 +16,12 @@ export interface StackMemberRefs {
 export interface StackRead<Pr extends StackMemberRefs> {
     stackNumber: number;
     stackSize: number;
+    viewerLogin: string | null;
     viewerCanAdminister: boolean;
     /** Every member, bottom-to-top, each observed in the same paged read. */
     ordered: Pr[];
+    /** Present when the query selected repository merge settings, including an empty list. */
+    allowedMergeMethods?: MergeMethod[];
 }
 /**
  * Page through one native stack and fail closed on anything short of the full

package/bin/github/stack-read.mjs

@@ -1,3 +1,4 @@
+import { readAllowedMergeMethods } from "../config/merge-method.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { missingRepositoryError } from "./errors.mjs";
@@ -15,13 +16,17 @@ export async function readStack(query, anchor, repo, variables = {}) {
     let stackNumber = 0;
     let stackSize = 0;
     let viewerCanAdminister = false;
+    let viewerLogin = null;
+    let allowedMergeMethods;
     const entries = [];
     do {
         const response = await graphqlWithRateLimit(query, { owner: repo.owner, repo: repo.name, anchor, after, ...variables });
+        viewerLogin = response.data.viewer?.login ?? viewerLogin;
         const repository = response.data.repository;
         if (!repository)
             throw missingRepositoryError(repo);
         viewerCanAdminister = repository.viewerCanAdminister;
+        allowedMergeMethods = readAllowedMergeMethods(repository) ?? allowedMergeMethods;
         if (!repository.pullRequest) {
             throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
         }
@@ -59,7 +64,14 @@ export async function readStack(query, anchor, repo, variables = {}) {
     const ordered = [...unique.values()]
         .sort((left, right) => left.position - right.position)
         .map((entry) => entry.pullRequest);
-    return { stackNumber, stackSize, viewerCanAdminister, ordered };
+    return {
+        stackNumber,
+        stackSize,
+        viewerLogin,
+        viewerCanAdminister,
+        ordered,
+        ...(allowedMergeMethods && { allowedMergeMethods }),
+    };
 }
 /** Membership and linking refs only — no per-PR CI or review hydration. */
 export function readStackTopology(anchor, repo) {

package/bin/mcp/server.mjs

@@ -7,6 +7,7 @@ import { isRepositoryQualifiedPrReference, normalizeRepositoryIdentity, parsePrR
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
 import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
 import { formatPollSummaryResult } from "../cli/poll-summary-formatter.mjs";
+import { projectStackOverview } from "../cli/stack-overview.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
@@ -104,7 +105,11 @@ export function createPrShepherdMcpServer(options = {}) {
         };
         return runTool(() => runIterateSelector(shepherd, requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
             ? formatPollSummaryResult(result)
-            : formatIterateResult(result, opts), (result) => isPollSummary(result) ? result : projectIterateLean(result, opts));
+            : formatIterateResult(result, opts), (result) => isPollSummary(result)
+            ? result.selection.kind === "stack"
+                ? projectStackOverview(result)
+                : result
+            : projectIterateLean(result, opts));
     });
     server.registerTool("apply", {
         description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",