pr-shepherd 0.52.0 → 0.53.0

package/bin/github/merge-queue-checks.mjs

@@ -1,4 +1,6 @@
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
 import { graphql } from "./client.mjs";
+import { queueRemovalAppliesToHead } from "./queue-removal-freshness.mjs";
 import { requireContextNodes } from "./batch-response.mjs";
 import { COMMIT_CHECK_CONTEXTS_QUERY } from "./queries.mjs";
 function omittedCursorError(oid) {
@@ -60,8 +62,15 @@ function currentRemovalCommit(raw) {
     if (addition && Date.parse(removal.createdAt) < Date.parse(addition.createdAt))
         return undefined;
     const parentOids = removal.beforeCommit.parents?.nodes.map((node) => node.oid);
-    if (!parentOids?.includes(raw.headRefOid))
+    const headCommittedAt = raw.commits?.nodes[0]?.commit.committedDate;
+    if (!queueRemovalAppliesToHead({
+        parentOids,
+        headOid: raw.headRefOid,
+        ...(headCommittedAt && { headCommittedAtUnix: parseCreatedAt(headCommittedAt) }),
+        removedAtUnix: Math.floor(Date.parse(removal.createdAt) / 1000),
+    })) {
         return undefined;
+    }
     return removal.beforeCommit;
 }
 /** Hydrate all status contexts for the active or most recently removed queue commit. */

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

@@ -0,0 +1,12 @@
+import { type RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/**
+ * Complete the compact summary's `last: 100` status-context windows in place.
+ *
+ * Without this, a PR with more than 100 contexts always reports incomplete
+ * checks, so it can never earn or match a READY receipt. Every summary fetch
+ * path runs this before anything fingerprints `commits`, so one-PR receipts and
+ * aggregate stack reads hash the same evidence. A window that cannot be
+ * completed stays incomplete, which already fails readiness closed.
+ */
+export declare function hydratePollSummaryChecks(raw: RawSummaryPr, repo: RepoInfo): Promise<void>;

package/bin/github/poll-summary-check-hydration.mjs

@@ -0,0 +1,55 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { POLL_SUMMARY_CHECK_PAGE_QUERY } from "./queries.mjs";
+/**
+ * Complete the compact summary's `last: 100` status-context windows in place.
+ *
+ * Without this, a PR with more than 100 contexts always reports incomplete
+ * checks, so it can never earn or match a READY receipt. Every summary fetch
+ * path runs this before anything fingerprints `commits`, so one-PR receipts and
+ * aggregate stack reads hash the same evidence. A window that cannot be
+ * completed stays incomplete, which already fails readiness closed.
+ */
+export async function hydratePollSummaryChecks(raw, repo) {
+    const headCommit = raw.commits.nodes[0]?.commit;
+    if (headCommit)
+        await hydrateCommitContexts(headCommit, repo);
+    const queueCommit = raw.mergeQueueEntry?.headCommit;
+    if (queueCommit)
+        await hydrateCommitContexts(queueCommit, repo);
+}
+async function hydrateCommitContexts(commit, repo) {
+    const contexts = commit.statusCheckRollup?.contexts;
+    if (!contexts)
+        return;
+    const nodes = [...contexts.nodes];
+    let pageInfo = contexts.pageInfo;
+    while (pageInfo.hasPreviousPage && pageInfo.startCursor) {
+        const older = await fetchOlderContexts(commit.oid, pageInfo.startCursor, repo);
+        if (!older)
+            break;
+        nodes.unshift(...older.nodes);
+        pageInfo = older.pageInfo;
+    }
+    // A window that shifted between pages can repeat or skip contexts; the
+    // first page's total is the snapshot the hydrated list must account for.
+    const complete = !pageInfo.hasPreviousPage && nodes.length === contexts.totalCount;
+    commit.statusCheckRollup = {
+        contexts: {
+            totalCount: contexts.totalCount,
+            pageInfo: { hasPreviousPage: !complete },
+            nodes,
+        },
+    };
+}
+async function fetchOlderContexts(oid, before, repo) {
+    const { data } = await graphqlWithRateLimit(POLL_SUMMARY_CHECK_PAGE_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;
+}

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

@@ -19,10 +19,30 @@ export function fingerprintRawSummaryPr(raw) {
         reviewDecision: raw.reviewDecision,
         reviewRequests: raw.reviewRequests,
         latestReviews: raw.latestReviews,
-        comments: raw.comments,
-        reviews: raw.reviews,
-        reviewThreads: raw.reviewThreads,
-        commits: raw.commits,
+        comments: hideBodies(raw.comments),
+        reviews: hideBodies(raw.reviews),
+        reviewThreads: {
+            ...raw.reviewThreads,
+            nodes: raw.reviewThreads.nodes.map((thread) => ({
+                ...thread,
+                rootComments: thread.rootComments && hideBodies(thread.rootComments),
+                comments: hideBodies(thread.comments),
+            })),
+        },
+        commits: {
+            ...raw.commits,
+            nodes: raw.commits.nodes.map((node) => ({
+                ...node,
+                commit: { ...node.commit, committedDate: undefined },
+            })),
+        },
     };
     return createHash("sha256").update(JSON.stringify(evidence)).digest("hex");
 }
+/** Hidden bodies are not readiness evidence: bots keep editing hidden notices after a PR settles. */
+function hideBodies(connection) {
+    return {
+        ...connection,
+        nodes: connection.nodes.map((node) => (node.isMinimized ? { ...node, body: undefined } : node)),
+    };
+}

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

@@ -19,14 +19,16 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
     const removalEvent = currentQueueRemovalEvent(raw);
     let { action, reasons } = routePollSummary(raw, checks, review, opts);
     let remainingSeconds;
-    if (raw.isDraft && blockingReviewerInProgress && action === "mark_ready") {
+    if (raw.isDraft &&
+        blockingReviewerInProgress &&
+        (action === "mark_ready" || reasons.includes("draft-auto-mark-ready-disabled"))) {
         action = "wait";
         reasons = ["blocking-reviewer-in-progress"];
     }
     const appearsReady = reasons.includes("appears-ready");
     if (opts.stackPrNumber === undefined) {
         const readyDelaySeconds = opts.readyDelaySeconds ?? (loadConfig().watch?.readyDelayMinutes ?? 10) * 60;
-        const readyState = await updateReadyDelay(raw.number, appearsReady, readyDelaySeconds, repo.owner, repo.name, { retainElapsed: true });
+        const readyState = await updateReadyDelay(raw.number, appearsReady, readyDelaySeconds, repo.owner, repo.name, { headSha: raw.headRefOid });
         if (appearsReady && !readyState.shouldCancel) {
             action = "wait";
             reasons = ["ready-delay"];
@@ -93,9 +95,7 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
         ...((opts.stackPrNumber !== undefined && raw.state === "OPEN") ||
             (!["wait", "cancel"].includes(action) &&
                 !(opts.stackPrNumber !== undefined && raw.stack && action === "merge"))
-            ? {
-                pollCommand: buildPollCommand(repoName, raw.number, raw.isDraft, opts),
-            }
+            ? pollCommandFields(repoName, raw.number, raw.isDraft, opts)
             : {}),
     };
 }
@@ -116,7 +116,7 @@ function detectBlockingReviewer(raw) {
     return ((raw.reviewRequests?.nodes ?? []).some((request) => matches(request.requestedReviewer)) ||
         (raw.latestReviews?.nodes ?? []).some((review) => review.state === "PENDING" && matches(review.author)));
 }
-function buildPollCommand(repo, pr, isDraft, opts) {
+function pollCommandFields(repo, pr, isDraft, opts) {
     const autoMarkReadyDisabled = opts.noAutoMarkReady || loadConfig().actions.autoMarkReady === false;
     const boundedDraft = isDraft && autoMarkReadyDisabled;
     const args = boundedDraft
@@ -131,5 +131,6 @@ function buildPollCommand(repo, pr, isDraft, opts) {
     }
     if (opts.noAutoMarkReady && !boundedDraft)
         args.push("--no-auto-mark-ready");
-    return buildPrShepherdCommand(args).text;
+    const pollCommand = buildPrShepherdCommand(args).text;
+    return boundedDraft ? { pollCommand, pollProbe: true } : { pollCommand };
 }

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

@@ -1,3 +1,5 @@
+import { 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) {
     const removal = raw.mergeQueueRemovals?.nodes[0];
@@ -10,7 +12,14 @@ export function currentQueueRemovalEvent(raw) {
     if (addition && Date.parse(addition.createdAt) > removalTime)
         return null;
     const parents = removal.beforeCommit?.parents?.nodes.map((parent) => parent.oid);
-    if (!parents?.includes(raw.headRefOid))
+    const headCommittedAt = raw.commits?.nodes[0]?.commit.committedDate;
+    if (!queueRemovalAppliesToHead({
+        parentOids: parents,
+        headOid: raw.headRefOid,
+        ...(headCommittedAt && { headCommittedAtUnix: parseCreatedAt(headCommittedAt) }),
+        removedAtUnix: Math.floor(removalTime / 1000),
+    })) {
         return null;
+    }
     return removal;
 }

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

@@ -43,8 +43,23 @@ type RawCheckContext = {
     context: string;
     state: string;
 };
-interface RawCheckRollup {
-    contexts: SummaryConnection<RawCheckContext>;
+interface RawCheckContexts {
+    totalCount: number;
+    /** `startCursor` pages older contexts; hydration drops it so fingerprints never hash a cursor. */
+    pageInfo: {
+        hasPreviousPage: boolean;
+        startCursor?: string | null;
+    };
+    nodes: RawCheckContext[];
+}
+export interface RawCheckRollup {
+    contexts: RawCheckContexts;
+}
+/** A commit whose status contexts the compact summary reads. */
+export interface RawSummaryCommit {
+    oid: string;
+    committedDate?: string;
+    statusCheckRollup: RawCheckRollup | null;
 }
 export interface RawSummaryPr {
     number: number;
@@ -103,9 +118,7 @@ export interface RawSummaryPr {
         }>;
     } | null;
     mergeQueueEntry: {
-        headCommit: {
-            statusCheckRollup: RawCheckRollup | null;
-        } | null;
+        headCommit: RawSummaryCommit | null;
     } | null;
     stack: {
         number: number;
@@ -131,9 +144,7 @@ export interface RawSummaryPr {
     }>;
     commits: {
         nodes: Array<{
-            commit: {
-                statusCheckRollup: RawCheckRollup | null;
-            };
+            commit: RawSummaryCommit;
         }>;
     };
 }
@@ -142,27 +153,4 @@ export interface RawExplicitResponse {
         viewerCanAdminister: boolean;
     } & Record<string, RawSummaryPr | boolean | null>) | null;
 }
-export interface RawStackResponse {
-    repository: {
-        viewerCanAdminister: boolean;
-        pullRequest: {
-            stack: {
-                id: string;
-                number: number;
-                size: number;
-                baseRefName: string;
-                entries: {
-                    pageInfo: {
-                        hasNextPage: boolean;
-                        endCursor: string | null;
-                    };
-                    nodes: Array<{
-                        position: number;
-                        pullRequest: RawSummaryPr | null;
-                    }>;
-                };
-            } | null;
-        } | null;
-    } | null;
-}
 export {};

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

@@ -25,12 +25,15 @@ export function routePollSummary(raw, checks, review, opts) {
         return { action: "wait", reasons: ["pending-or-unknown"] };
     }
     if (raw.isDraft) {
-        if (opts.noAutoMarkReady || actions.autoMarkReady === false) {
-            return { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] };
+        const autoMarkReadyDisabled = opts.noAutoMarkReady || actions.autoMarkReady === false;
+        // The stack selector asks the agent to mark a disabled draft ready, so
+        // that transition needs the same capability as the automatic one.
+        if (!raw.viewerCanUpdate && (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+            return { action: "escalate", reasons: ["mark-ready-authorization-required"] };
         }
-        return raw.viewerCanUpdate
-            ? { action: "mark_ready", reasons: ["draft-appears-ready"] }
-            : { action: "escalate", reasons: ["mark-ready-authorization-required"] };
+        return autoMarkReadyDisabled
+            ? { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] }
+            : { action: "mark_ready", reasons: ["draft-appears-ready"] };
     }
     if (opts.merge && raw.isInMergeQueue) {
         return { action: "wait", reasons: ["already-in-merge-queue"] };

package/bin/github/poll-summary.mjs

@@ -1,8 +1,10 @@
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
-import { GitHubRequestError } from "./errors.mjs";
+import { missingRepositoryError } from "./errors.mjs";
+import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.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;
 export async function fetchPollSummary(opts, repo) {
     if (opts.stackPrNumber !== undefined)
@@ -42,93 +44,34 @@ async function fetchExplicitChunk(prs, repo) {
         ...variables,
     });
     if (!result.data.repository)
-        throw missingRepository(repo);
+        throw missingRepositoryError(repo);
     const rawPrs = prs.map((pr, index) => {
         const raw = result.data.repository[`pr${index}`];
         if (!raw)
             throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
         return raw;
     });
+    for (const raw of rawPrs)
+        await hydratePollSummaryChecks(raw, repo);
     return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
 }
+/**
+ * Read the stack's topology first so the hydrated page requests only as many
+ * entries as the stack holds: GitHub prices `first`, not the nodes returned.
+ */
 async function fetchStackSummary(opts, repo) {
     const anchor = opts.stackPrNumber;
-    let after = null;
-    let stackId = null;
-    let stackNumber = 0;
-    let stackSize = 0;
-    let viewerCanAdminister = false;
-    const entries = [];
-    do {
-        const response = (await graphqlWithRateLimit(POLL_STACK_SUMMARY_QUERY, {
-            owner: repo.owner,
-            repo: repo.name,
-            anchor,
-            after,
-        }));
-        const repository = response.data.repository;
-        if (!repository)
-            throw missingRepository(repo);
-        viewerCanAdminister = repository.viewerCanAdminister;
-        if (!repository.pullRequest) {
-            throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
-        }
-        const stack = repository.pullRequest.stack;
-        if (!stack) {
-            throw new ShepherdError(`PR #${anchor} is not part of a native GitHub stack`, EXIT.UNAVAILABLE);
-        }
-        if (stackId !== null && stack.id !== stackId) {
-            throw new ShepherdError("GitHub stack membership changed while it was being fetched; retry", EXIT.TEMPFAIL);
-        }
-        stackId = stack.id;
-        stackNumber = stack.number;
-        stackSize = stack.size;
-        for (const entry of stack.entries.nodes) {
-            if (!entry.pullRequest) {
-                throw new ShepherdError("GitHub returned an incomplete pull-request stack entry", EXIT.TEMPFAIL);
-            }
-            entries.push({ position: entry.position, pullRequest: entry.pullRequest });
-        }
-        const pageInfo = stack.entries.pageInfo;
-        if (pageInfo.hasNextPage && !pageInfo.endCursor) {
-            throw new ShepherdError("GitHub stack pagination did not include an end cursor", EXIT.TEMPFAIL);
-        }
-        after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
-    } while (after !== null);
-    const unique = new Map();
-    for (const entry of entries)
-        unique.set(entry.pullRequest.number, entry);
-    if (!unique.has(anchor) || unique.size !== stackSize) {
-        throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
-    }
-    const ordered = [...unique.values()].sort((left, right) => left.position - right.position);
-    const stackAncestry = [];
-    for (let index = 1; index < ordered.length; index++) {
-        const parent = ordered[index - 1].pullRequest;
-        const child = ordered[index].pullRequest;
-        if (parent.state !== "OPEN" || child.state !== "OPEN")
-            continue;
-        if (child.baseRefName === parent.headRefName && child.baseRefOid === parent.headRefOid) {
-            continue;
-        }
-        stackAncestry.push({
-            parentPr: parent.number,
-            parentHeadRefName: parent.headRefName,
-            parentHeadRefOid: parent.headRefOid,
-            childPr: child.number,
-            childBaseRefName: child.baseRefName,
-            childBaseRefOid: child.baseRefOid,
-        });
-    }
+    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) });
+    for (const pr of ordered)
+        await hydratePollSummaryChecks(pr, repo);
+    const stackAncestry = stackAncestryGaps(ordered);
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
-        prs: await Promise.all(ordered.map((entry) => summarizePollSummaryPr(entry.pullRequest, repo, opts, viewerCanAdminister))),
+        prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
         ...(stackAncestry.length > 0 && { stackAncestry }),
     };
 }
 function deduplicate(values) {
     return [...new Set(values)];
 }
-function missingRepository(repo) {
-    return new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
-}

package/bin/github/queries.d.mts

@@ -14,8 +14,15 @@ 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;
+/**
+ * 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;
 /** 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. */
+export declare const POLL_STACK_TOPOLOGY_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queries.mjs

@@ -16,10 +16,18 @@ export const BATCH_PR_QUERY = withSharedFragments(gql("batch-pr.gql"));
 export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
 /** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
 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 = gql("poll-summary-fragment.gql");
+export const POLL_SUMMARY_FRAGMENT = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.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")}`;
 /** 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. */
+export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

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

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export declare function queueRemovalAppliesToHead(input: {
+    parentOids: readonly string[] | null | undefined;
+    headOid: string;
+    headCommittedAtUnix?: number;
+    removedAtUnix?: number;
+}): boolean;

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

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+export function queueRemovalAppliesToHead(input) {
+    const parents = input.parentOids ?? [];
+    if (parents.length === 0)
+        return false;
+    if (parents.includes(input.headOid))
+        return true;
+    if (parents.length > 1)
+        return false;
+    if (input.headCommittedAtUnix !== undefined &&
+        input.removedAtUnix !== undefined &&
+        input.removedAtUnix > 0 &&
+        input.headCommittedAtUnix > input.removedAtUnix) {
+        return false;
+    }
+    return true;
+}

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

@@ -0,0 +1,34 @@
+import type { PollSummaryStackAncestry } from "../types.mts";
+import { type RepoInfo } from "./client.mts";
+/** GitHub's `first` ceiling for one native-stack entries page. */
+export declare const MAX_STACK_ENTRIES_PER_PAGE = 50;
+/** Fields every native-stack read needs to validate membership and adjacent ancestry. */
+export interface StackMemberRefs {
+    number: number;
+    state: string;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    baseRefOid: string;
+}
+/** One complete, validated native-stack membership read. */
+export interface StackRead<Pr extends StackMemberRefs> {
+    stackNumber: number;
+    stackSize: number;
+    viewerCanAdminister: boolean;
+    /** Every member, bottom-to-top, each observed in the same paged read. */
+    ordered: Pr[];
+}
+/**
+ * Page through one native stack and fail closed on anything short of the full
+ * membership: a missing repository, PR, or stack; a changed stack identity; a
+ * null entry; a page without a cursor; or fewer unique members than `size`.
+ */
+export declare function readStack<Pr extends StackMemberRefs>(query: string, anchor: number, repo: RepoInfo, variables?: Record<string, unknown>): Promise<StackRead<Pr>>;
+/** Membership and linking refs only — no per-PR CI or review hydration. */
+export declare function readStackTopology(anchor: number, repo: RepoInfo): Promise<StackRead<StackMemberRefs>>;
+/**
+ * Adjacent entries, both open, whose child base no longer matches the parent
+ * head. Both sides come from the same read, so each gap was observed together.
+ */
+export declare function stackAncestryGaps(ordered: StackMemberRefs[]): PollSummaryStackAncestry[];

package/bin/github/stack-read.mjs

@@ -0,0 +1,92 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { missingRepositoryError } from "./errors.mjs";
+import { POLL_STACK_TOPOLOGY_QUERY } from "./queries.mjs";
+/** GitHub's `first` ceiling for one native-stack entries page. */
+export const MAX_STACK_ENTRIES_PER_PAGE = 50;
+/**
+ * Page through one native stack and fail closed on anything short of the full
+ * membership: a missing repository, PR, or stack; a changed stack identity; a
+ * null entry; a page without a cursor; or fewer unique members than `size`.
+ */
+export async function readStack(query, anchor, repo, variables = {}) {
+    let after = null;
+    let stackId = null;
+    let stackNumber = 0;
+    let stackSize = 0;
+    let viewerCanAdminister = false;
+    const entries = [];
+    do {
+        const response = await graphqlWithRateLimit(query, { owner: repo.owner, repo: repo.name, anchor, after, ...variables });
+        const repository = response.data.repository;
+        if (!repository)
+            throw missingRepositoryError(repo);
+        viewerCanAdminister = repository.viewerCanAdminister;
+        if (!repository.pullRequest) {
+            throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
+        }
+        const stack = repository.pullRequest.stack;
+        if (!stack) {
+            throw new ShepherdError(`PR #${anchor} is not part of a native GitHub stack`, EXIT.UNAVAILABLE);
+        }
+        if (stackId !== null && stack.id !== stackId) {
+            throw new ShepherdError("GitHub stack membership changed while it was being fetched; retry", EXIT.TEMPFAIL);
+        }
+        stackId = stack.id;
+        stackNumber = stack.number;
+        stackSize = stack.size;
+        for (const entry of stack.entries.nodes) {
+            if (!entry.pullRequest) {
+                throw new ShepherdError("GitHub returned an incomplete pull-request stack entry", EXIT.TEMPFAIL);
+            }
+            entries.push({ position: entry.position, pullRequest: entry.pullRequest });
+        }
+        const pageInfo = stack.entries.pageInfo;
+        if (pageInfo.hasNextPage && !pageInfo.endCursor) {
+            throw new ShepherdError("GitHub stack pagination did not include an end cursor", EXIT.TEMPFAIL);
+        }
+        if (pageInfo.hasNextPage && pageInfo.endCursor === after) {
+            throw new ShepherdError("GitHub stack pagination returned a repeated end cursor", EXIT.TEMPFAIL);
+        }
+        after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
+    } while (after !== null);
+    const unique = new Map();
+    for (const entry of entries)
+        unique.set(entry.pullRequest.number, entry);
+    if (!unique.has(anchor) || unique.size !== stackSize) {
+        throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
+    }
+    const ordered = [...unique.values()]
+        .sort((left, right) => left.position - right.position)
+        .map((entry) => entry.pullRequest);
+    return { stackNumber, stackSize, viewerCanAdminister, ordered };
+}
+/** Membership and linking refs only — no per-PR CI or review hydration. */
+export function readStackTopology(anchor, repo) {
+    return readStack(POLL_STACK_TOPOLOGY_QUERY, anchor, repo);
+}
+/**
+ * Adjacent entries, both open, whose child base no longer matches the parent
+ * head. Both sides come from the same read, so each gap was observed together.
+ */
+export function stackAncestryGaps(ordered) {
+    const gaps = [];
+    for (let index = 1; index < ordered.length; index++) {
+        const parent = ordered[index - 1];
+        const child = ordered[index];
+        if (parent.state !== "OPEN" || child.state !== "OPEN")
+            continue;
+        if (child.baseRefName === parent.headRefName && child.baseRefOid === parent.headRefOid) {
+            continue;
+        }
+        gaps.push({
+            parentPr: parent.number,
+            parentHeadRefName: parent.headRefName,
+            parentHeadRefOid: parent.headRefOid,
+            childPr: child.number,
+            childBaseRefName: child.baseRefName,
+            childBaseRefOid: child.baseRefOid,
+        });
+    }
+    return gaps;
+}

package/bin/log/log-file.d.mts

@@ -1,7 +1,7 @@
 /**
  * Append-only per-worktree markdown log.
  *
- * Log path: $PR_SHEPHERD_STATE_DIR/<owner>-<repo>/worktrees/<basename>-<sha8>.md
+ * Log path: $PR_SHEPHERD_STATE_DIR/<owner>/<repo>/worktrees/<basename>-<sha8>.md
  *
  * Always-on by default. Set PR_SHEPHERD_LOG_DISABLED=1 or CI=true to disable.
  * Write failures flip an internal disabled flag so the CLI never crashes because