pr-shepherd 0.51.1 → 0.52.0

package/bin/commands/iterate/stale-ancestry.d.mts

@@ -0,0 +1,22 @@
+import type { RepoInfo } from "../../github/client.mts";
+import type { PollSummaryStackAncestry } from "../../types.mts";
+import type { ShepherdReport } from "../../types/report.mts";
+/**
+ * A verified stale boundary for the PR being shepherded.
+ *
+ * The aggregate stack read is authoritative for this check: it compares the
+ * child's recorded base OID with the current head OID of its immediate open
+ * parent. GitHub can report both PRs CLEAN while this boundary is stale.
+ */
+export interface StaleNativeStackAncestry extends PollSummaryStackAncestry {
+    instructions: string[];
+}
+/**
+ * Find a stale immediate parent boundary for one PR.
+ *
+ * This helper is intentionally read-only. A null result means either the PR is
+ * not a non-root native-stack layer, its boundary is current, or the boundary
+ * could not be verified. Callers must not emit a repair command from an
+ * unverified snapshot.
+ */
+export declare function findStaleNativeStackAncestry(report: Pick<ShepherdReport, "pr" | "mergeStatus">, repo: RepoInfo): Promise<StaleNativeStackAncestry | null>;

package/bin/commands/iterate/stale-ancestry.mjs

@@ -0,0 +1,37 @@
+import { fetchPollSummary } from "../../github/poll-summary.mjs";
+/**
+ * Find a stale immediate parent boundary for one PR.
+ *
+ * This helper is intentionally read-only. A null result means either the PR is
+ * not a non-root native-stack layer, its boundary is current, or the boundary
+ * could not be verified. Callers must not emit a repair command from an
+ * unverified snapshot.
+ */
+export async function findStaleNativeStackAncestry(report, repo) {
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (!stack || stack.position <= 1)
+        return null;
+    try {
+        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
+        const ancestry = summary.stackAncestry?.find((gap) => gap.childPr === report.pr);
+        if (!ancestry)
+            return null;
+        return {
+            ...ancestry,
+            instructions: buildStaleNativeStackAncestryInstructions(repo, ancestry),
+        };
+    }
+    catch {
+        // A stale repair is safe only when both OIDs were observed together. Let
+        // the caller retain the ordinary WAIT/ESCALATE path on an unreadable stack.
+        return null;
+    }
+}
+/** Build the one-PR repair guidance after a stale boundary was verified. */
+function buildStaleNativeStackAncestryInstructions(repo, ancestry) {
+    return [
+        `PR #${ancestry.childPr} records base \`${ancestry.childBaseRefName}\` at \`${ancestry.childBaseRefOid}\`, but its open parent PR #${ancestry.parentPr} currently ends at \`${ancestry.parentHeadRefName}\` \`${ancestry.parentHeadRefOid}\`.`,
+        `From a clean checkout of \`${repo.owner}/${repo.name}\`, check out the parent stack branch \`${ancestry.parentHeadRefName}\`.`,
+        "Run `gh stack rebase --upstack --no-trunk`, resolve any conflicts, and push the rewritten stack with `gh stack push`.",
+    ];
+}

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

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
@@ -5,135 +6,214 @@ export function withPollSummaryInstructions(result, mergeRequested) {
     if (result.selection.kind !== "stack") {
         return { ...result, instructions: explicitInstructions(result) };
     }
-    const planned = planStack(result, mergeRequested);
-    const reason = planned.action === "cancel"
-        ? "all_terminal"
-        : planned.action === "wait"
-            ? result.reason === "timeout"
-                ? "timeout"
-                : "waiting"
-            : "actionable";
+    const prs = [...result.prs].sort((left, right) => position(left) - position(right));
+    const staleChildren = new Set(result.stackAncestry?.map((gap) => gap.childPr) ?? []);
+    const firstUnready = prs.find((item) => item.state === "OPEN" && (!isReady(item) || staleChildren.has(item.pr)));
+    const blocked = prs.map((item) => firstUnready && item.state === "OPEN" && position(item) > position(firstUnready)
+        ? {
+            ...item,
+            ...(["cancel", "mark_ready", "merge"].includes(item.action) && {
+                action: "wait",
+                reasons: [...item.reasons, "lower-layer-not-ready"],
+            }),
+            blockedByPr: firstUnready.pr,
+            ...(item.isDraft &&
+                item.pollCommand && {
+                pollCommand: item.pollCommand.replace(" --until-terminal", " --timeout 1s --debounce 0s") +
+                    (item.pollCommand.includes("--no-auto-mark-ready") ? "" : " --no-auto-mark-ready"),
+            }),
+        }
+        : item.state === "OPEN" &&
+            (!isReady(item) || staleChildren.has(item.pr)) &&
+            ["cancel", "merge"].includes(item.action)
+            ? {
+                ...item,
+                action: "fix_code",
+                reasons: [
+                    ...item.reasons,
+                    staleChildren.has(item.pr) ? "stale-ancestry" : "ready-receipt-required",
+                ],
+            }
+            : item);
+    const projected = {
+        ...result,
+        prs: blocked.map((item) => {
+            if (item.state === "OPEN" && item.isInMergeQueue && item.action === "cancel") {
+                return {
+                    ...item,
+                    action: "wait",
+                    reasons: [...item.reasons, "already-in-merge-queue"],
+                };
+            }
+            if (item.state === "CLOSED" && closedDependency(blocked, item.pr)) {
+                return {
+                    ...item,
+                    action: "escalate",
+                    reasons: [...item.reasons, "closed-unmerged-dependency"],
+                };
+            }
+            if (item.state !== "OPEN" && item.state !== "MERGED") {
+                return {
+                    ...item,
+                    action: "escalate",
+                    reasons: [...item.reasons, "unverified-stack-state"],
+                };
+            }
+            return item;
+        }),
+    };
+    const planned = planStack(projected, mergeRequested);
     const instructions = [...planned.instructions];
-    if (result.quotaWarning && planned.action !== "wait" && planned.action !== "cancel") {
+    if (result.quotaWarning && planned.action === "shepherd") {
         instructions.push(buildQuotaAwareContinuation(result.quotaWarning, `${instructions.length + 1}. After completing the stack action,`));
     }
-    return { ...result, reason, nextAction: planned.action, instructions };
+    return {
+        ...projected,
+        reason: planned.action === "cancel"
+            ? "all_terminal"
+            : planned.waiting
+                ? result.reason === "timeout"
+                    ? "timeout"
+                    : "waiting"
+                : "actionable",
+        stackMergeable: planned.stackMergeable,
+        nextAction: planned.action,
+        instructions,
+    };
 }
 function planStack(result, mergeRequested) {
     const open = result.prs.filter((item) => item.state === "OPEN");
-    if (open.length === 0) {
-        return { action: "cancel", instructions: ["1. Stop — every selected PR is terminal."] };
+    const lastOpen = open.at(-1);
+    const closedDependencyPr = result.prs.find((item) => item.state === "CLOSED" && lastOpen && position(item) < position(lastOpen));
+    const unverifiedLayer = result.prs.find((item) => item.state !== "OPEN" && item.state !== "MERGED");
+    const gaps = result.stackAncestry ?? [];
+    const stackMergeable = gaps.length === 0 && open.every(isReady);
+    const candidates = open.filter((item) => !isReady(item) || gaps.some((gap) => gap.childPr === item.pr));
+    const autonomousCandidates = candidates.filter((item) => item.action !== "escalate");
+    const runnableCandidates = autonomousCandidates.filter((item) => item.pollCommand);
+    const missingCommands = autonomousCandidates.filter((item) => !item.pollCommand);
+    const escalated = result.prs.filter((item) => item.action === "escalate");
+    if (closedDependencyPr || unverifiedLayer || escalated.length > 0) {
+        const instructions = [];
+        appendAutonomousInstructions(instructions, runnableCandidates);
+        const stop = runnableCandidates.length === 0;
+        if (closedDependencyPr) {
+            instructions.push(`${instructions.length + 1}. PR #${closedDependencyPr.pr} was closed without merging below an open layer. ${stop ? "Stop and ask" : "After autonomous shepherding, ask"} the stack owner whether to restore that dependency or rebuild the upper branches.`);
+        }
+        if (unverifiedLayer && unverifiedLayer.pr !== closedDependencyPr?.pr) {
+            instructions.push(`${instructions.length + 1}. PR #${unverifiedLayer.pr} has state \`${unverifiedLayer.state}\` rather than open or merged. ${stop ? "Stop and ask" : "After autonomous shepherding, ask"} the stack owner to reconcile this layer before declaring the stack complete.`);
+        }
+        for (const item of escalated) {
+            if (item.pr === closedDependencyPr?.pr || item.pr === unverifiedLayer?.pr)
+                continue;
+            instructions.push(`${instructions.length + 1}. PR #${item.pr} requires human action (${item.reasons.join(", ")}). ${stop ? "Stop for that decision." : "Keep shepherding other PRs before the handoff."}`);
+        }
+        for (const item of missingCommands) {
+            instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. Ask for direction.`);
+        }
+        if (runnableCandidates.length > 0) {
+            instructions.push(`${instructions.length + 1}. After the listed one-PR sessions, rerun this same \`--stack\` selector. Stop for the human handoff only when no autonomous shepherding remains.`);
+        }
+        return { action: stop ? "escalate" : "shepherd", stackMergeable: false, instructions };
     }
-    const lastOpenPosition = positionOf(result, open.at(-1).pr);
-    const closedBelowOpen = result.prs.find((item) => item.state === "CLOSED" && positionOf(result, item.pr) < lastOpenPosition);
-    if (closedBelowOpen) {
+    if (open.length === 0) {
         return {
-            action: "escalate",
-            instructions: [
-                `1. PR #${closedBelowOpen.pr} is closed without merging below an open stack layer. Stop stack merge and rebase operations here; the closed dependency must be restored or the higher branches rebuilt on a valid base.`,
-                "2. Ask the stack owner which recovery path to take, then rerun the same aggregate `--stack` selector after the stack is repaired.",
-            ],
+            action: "cancel",
+            stackMergeable: true,
+            instructions: ["1. Stop — every stack layer is merged."],
         };
     }
-    const gap = result.stackAncestry?.[0];
-    const firstOpen = open[0];
-    if (firstOpen.mergeStateStatus === "BEHIND")
-        return rebaseWholeStack(result, firstOpen);
-    if (mergeRequested) {
-        const mergeTarget = readyLowerStackTarget(open, result.stackAncestry ?? []);
-        if (mergeTarget) {
-            const stackNumber = result.selection.kind === "stack" ? result.selection.stackNumber : 0;
+    if (!stackMergeable) {
+        if (missingCommands.length > 0) {
+            const instructions = [];
+            appendAutonomousInstructions(instructions, runnableCandidates);
+            for (const item of missingCommands) {
+                instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. ${runnableCandidates.length === 0 ? "Stop and ask" : "After autonomous shepherding, ask"} for direction.`);
+            }
+            if (runnableCandidates.length > 0) {
+                instructions.push(`${instructions.length + 1}. After the listed one-PR sessions, rerun this same \`--stack\` selector. Stop for the human handoff only when no autonomous shepherding remains.`);
+            }
             return {
-                action: "merge",
-                instructions: [
-                    `1. The contiguous ready lower stack ends at PR #${mergeTarget.pr}. Merge the native stack through that PR with \`gh stack merge --squash ${mergeTarget.pr}\`; verify that the selector names PR #${mergeTarget.pr} in stack #${stackNumber} before running it. This includes still-open lower layers and leaves higher layers open.`,
-                    "2. After GitHub completes the stack merge and updates the remaining branches, rerun the same aggregate `--stack` selector. If an ancestry mismatch remains, follow the rebase instructions returned then.",
-                ],
+                action: runnableCandidates.length > 0 ? "shepherd" : "escalate",
+                stackMergeable: false,
+                instructions,
             };
         }
-        if (firstOpen.action === "wait") {
-            return waitingStack(result);
-        }
-    }
-    const firstWork = open.find((item) => ["fix_code", "mark_ready", "escalate"].includes(item.action));
-    if (firstWork && (!gap || positionOf(result, firstWork.pr) <= positionOf(result, gap.childPr))) {
-        return pollOneLayer(firstWork);
+        const instructions = [];
+        appendAutonomousInstructions(instructions, autonomousCandidates);
+        instructions.push(`${instructions.length + 1}. After the selected one-PR sessions, rerun this same \`--stack\` selector.`);
+        return { action: "shepherd", stackMergeable: false, instructions };
     }
-    if (gap) {
+    if (open.some((item) => item.isInMergeQueue)) {
         return {
-            action: "fix_code",
+            action: "wait",
+            stackMergeable: true,
+            waiting: true,
             instructions: [
-                `1. PR #${gap.childPr} still records base \`${gap.childBaseRefName}\` at \`${gap.childBaseRefOid}\`, while parent PR #${gap.parentPr} now ends at \`${gap.parentHeadRefName}\` \`${gap.parentHeadRefOid}\`. From a clean checkout of \`${result.repo}\`, check out the parent stack branch \`${gap.parentHeadRefName}\`.`,
-                "2. Rebase the upstack branches onto that parent with `gh stack rebase --upstack --no-trunk`, resolve any conflicts, and push the rewritten branches with `gh stack push`.",
-                "3. Rerun the same aggregate `--stack` selector and follow the next returned action.",
+                "1. The stack is in the merge queue. Recheck at the configured polling cadence; finish only after every layer is merged, and route any ejected layer to its one-PR session.",
             ],
         };
     }
-    const behind = open.find((item) => item.mergeStateStatus === "BEHIND");
-    if (behind)
-        return rebaseWholeStack(result, behind);
-    if (firstWork)
-        return pollOneLayer(firstWork);
-    if (!mergeRequested && open.every((item) => item.action === "cancel")) {
+    if (!mergeRequested && result.prs.every((item) => item.action === "cancel")) {
         return {
             action: "cancel",
-            instructions: ["1. Stop — every open stack layer is ready and the stack is linear."],
+            stackMergeable: true,
+            instructions: ["1. Stop — every stack layer is terminal or fully READY."],
         };
     }
-    return waitingStack(result);
-}
-function rebaseWholeStack(result, behind) {
-    return {
-        action: "fix_code",
-        instructions: [
-            `1. GitHub reports PR #${behind.pr} is behind its base \`${behind.baseRefName}\`. From a clean checkout of \`${result.repo}\`, check out its stack branch \`${behind.headRefName}\`.`,
-            "2. Rebase that native stack from its trunk with `gh stack rebase`, resolving any conflicts.",
-            "3. Push the updated stack with `gh stack push` and rerun the same aggregate `--stack` selector.",
-        ],
-    };
-}
-function readyLowerStackTarget(open, gaps) {
-    const mismatchedChildren = new Set(gaps.map((gap) => gap.childPr));
-    let target;
-    for (const item of open) {
-        if (mismatchedChildren.has(item.pr) || item.action !== "merge")
-            break;
-        target = item;
-    }
-    return target;
-}
-function positionOf(result, pr) {
-    return result.prs.find((item) => item.pr === pr)?.stack?.position ?? Number.MAX_SAFE_INTEGER;
-}
-function pollOneLayer(item) {
-    if (!item.pollCommand) {
+    if (!mergeRequested) {
+        const instructions = [];
+        appendAutonomousInstructions(instructions, open.filter((item) => item.action !== "cancel"));
+        instructions.push(`${instructions.length + 1}. After the selected one-PR sessions, rerun this same \`--stack\` selector.`);
         return {
-            action: "escalate",
-            instructions: [
-                `1. PR #${item.pr} needs attention, but GitHub returned no one-PR poll command.`,
-            ],
+            action: "shepherd",
+            stackMergeable,
+            instructions,
         };
     }
+    const stackNumber = result.selection.kind === "stack" ? result.selection.stackNumber : 0;
     return {
-        action: item.action,
+        action: "merge",
+        stackMergeable: true,
         instructions: [
-            `1. Work on the lowest actionable layer, PR #${item.pr}: run \`${item.pollCommand}\`.`,
-            "2. Follow that one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
-            "3. Rerun the aggregate `--stack` selector before acting on a higher layer.",
+            "1. Check `gh stack merge --help`. If the `gh-stack` extension is unavailable, run `gh extension install github/gh-stack`, then rerun this same `--stack --merge` selector before merging.",
+            `2. Stack #${stackNumber} in \`${result.repo}\` is mergeable through PR #${open.at(-1).pr}. Run \`GH_REPO=${result.repo} gh stack merge --yes --squash ${stackNumber}\` to merge the whole native stack or enqueue it when the base uses a merge queue.`,
+            "3. After the merge attempt, rerun this same `--stack --merge` selector until every layer is merged (`CANCEL`); shepherd any layer that GitHub rejects or ejects.",
         ],
     };
 }
-function waitingStack(result) {
-    if (result.quotaWarning) {
-        return {
-            action: "wait",
-            instructions: [
-                buildQuotaAwareContinuation(result.quotaWarning, "1. This native stack is non-terminal. Before continuing,"),
-            ],
-        };
+function closedDependency(items, pr) {
+    const open = items.filter((item) => item.state === "OPEN");
+    const lastOpen = open.at(-1);
+    return Boolean(lastOpen &&
+        items.some((item) => item.pr === pr && item.state === "CLOSED" && position(item) < position(lastOpen)));
+}
+function appendAutonomousInstructions(instructions, candidates) {
+    if (candidates.length === 0)
+        return;
+    instructions.push(`${instructions.length + 1}. Start or delegate the relevant one-PR sessions below; review and CI work on separate layers can proceed concurrently.`);
+    for (const item of candidates) {
+        instructions.push(item.pollCommand
+            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.blockedByPr ? ` (stack-blocked by PR #${item.blockedByPr})` : ""}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
+            : `${instructions.length + 1}. PR #${item.pr} needs a one-PR Shepherd session, but no command was available.`);
     }
-    return {
-        action: "wait",
-        instructions: ["1. Recheck this native stack after the lowest open layer changes state."],
-    };
+    instructions.push(`${instructions.length + 1}. Keep upper draft PRs in draft until every lower layer has completed Shepherd READY.`);
+}
+function isReady(item) {
+    return (item.state === "OPEN" &&
+        item.stack !== undefined &&
+        item.readyReceipt === true &&
+        !item.isDraft &&
+        !item.queueRemoval &&
+        item.mergeable !== "CONFLICTING" &&
+        item.mergeStateStatus !== "DIRTY" &&
+        (item.isInMergeQueue || item.mergeable === "MERGEABLE") &&
+        (item.isInMergeQueue ||
+            !["DIRTY", "BEHIND", "UNKNOWN", "BLOCKED", "HAS_HOOKS"].includes(item.mergeStateStatus)) &&
+        (item.checks?.failing ?? 0) === 0 &&
+        (item.isInMergeQueue || (item.checks?.inProgress ?? 0) === 0) &&
+        (item.review?.actionable ?? 0) === 0);
+}
+function position(item) {
+    return item.stack?.position ?? Number.MAX_SAFE_INTEGER;
 }

package/bin/commands/poll-summary.mjs

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { loadConfig } from "../config/load.mjs";
 import { ShepherdError } from "../exit-codes.mjs";
 import { getRepoInfo } from "../github/client.mjs";
@@ -54,16 +55,31 @@ async function runAggregatePollCore(opts) {
                     stackPrNumber: undefined,
                     prNumbers: last.prs.map((item) => item.pr),
                 });
-                if (explicit.prs.every((item) => item.action === "cancel")) {
+                if (explicit.prs.every((item) => item.state === "MERGED")) {
                     const warning = await aggregateQuotaWarning(explicit, quotaBands, opts.intervalSeconds);
                     if (warning)
                         pendingQuotaWarning = warning;
                     return attachUsage({
                         ...explicit,
+                        selection: last.selection,
                         reason: "all_terminal",
+                        nextAction: "cancel",
+                        stackMergeable: true,
+                        instructions: ["1. Stop — every stack layer is merged."],
                         ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
                     }, opts.merge);
                 }
+                return attachUsage({
+                    ...explicit,
+                    selection: last.selection,
+                    reason: "actionable",
+                    nextAction: "escalate",
+                    stackMergeable: false,
+                    instructions: [
+                        `1. Native stack #${last.selection.stackNumber} disappeared before every tracked layer merged. Stop and ask the stack owner to reconcile the remaining PRs; do not claim the stack is complete.`,
+                    ],
+                    ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                }, opts.merge);
             }
             const retryMs = opts.untilTerminal ? pollGraphQlRetryAfterMs(error) : null;
             if (retryMs === null || rateLimitRetries >= 1)
@@ -77,10 +93,11 @@ async function runAggregatePollCore(opts) {
             ? last.nextAction === "cancel"
             : last.prs.every((item) => item.action === "cancel");
         const immediate = last.selection.kind === "stack"
-            ? ["escalate", "merge", "mark_ready"].includes(last.nextAction ?? "wait")
+            ? (last.nextAction === "escalate" || last.nextAction === "merge") &&
+                last.reason !== "waiting"
             : last.prs.some((item) => ["escalate", "merge", "mark_ready"].includes(item.action));
         const hasFix = last.selection.kind === "stack"
-            ? last.nextAction === "fix_code"
+            ? last.nextAction === "shepherd" && last.reason !== "waiting"
             : last.prs.some((item) => item.action === "fix_code");
         const warning = await aggregateQuotaWarning(last, quotaBands, opts.intervalSeconds);
         if (warning)
@@ -145,5 +162,12 @@ function isMissingStack(error) {
 }
 function attachUsage(result, mergeRequested) {
     const apiUsage = summarizeApiTelemetry();
-    return withPollSummaryInstructions(apiUsage ? { ...result, apiUsage } : result, mergeRequested === true);
+    const enriched = apiUsage ? { ...result, apiUsage } : result;
+    // A disappeared native stack is an aggregate-level terminal handoff. Keep
+    // that explicit escalation intact even when the one-PR fallback contains
+    // open orphan rows that would otherwise be re-planned as fix_code.
+    if (enriched.selection.kind === "stack" && enriched.nextAction === "escalate") {
+        return enriched;
+    }
+    return withPollSummaryInstructions(enriched, mergeRequested === true);
 }

package/bin/exit-codes.d.mts

@@ -25,6 +25,8 @@ export declare const EXIT: Readonly<{
     readonly CLOSED: 14;
     /** Agent should run the emitted merge or queue command. */
     readonly MERGE: 15;
+    /** Aggregate stack has PRs to shepherd through one-PR sessions. */
+    readonly SHEPHERD: 16;
     /** Bad/unknown flag, unknown subcommand, missing required arg, invalid duration. */
     readonly USAGE: 64;
     /** Malformed caller data: bad `--require-sha`, `PRRC_*` IDs, bad repo string. */

package/bin/exit-codes.mjs

@@ -24,6 +24,8 @@ export const EXIT = Object.freeze({
     CLOSED: 14,
     /** Agent should run the emitted merge or queue command. */
     MERGE: 15,
+    /** Aggregate stack has PRs to shepherd through one-PR sessions. */
+    SHEPHERD: 16,
     /** Bad/unknown flag, unknown subcommand, missing required arg, invalid duration. */
     USAGE: 64,
     /** Malformed caller data: bad `--require-sha`, `PRRC_*` IDs, bad repo string. */

package/bin/github/batch-parsers.mjs

@@ -125,6 +125,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
                 null,
         },
         baseRefName: raw.baseRefName,
+        ...(raw.baseRef?.target?.oid && { baseRefOid: raw.baseRef.target.oid }),
         reviewRequests,
         latestReviews,
         reviewThreads,

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

@@ -80,6 +80,9 @@ interface RawRuleParameters {
     }>;
 }
 export interface RawBaseRef {
+    target?: {
+        oid: string;
+    } | null;
     branchProtectionRule: RawBranchProtectionRule | null;
     rules: {
         pageInfo?: {

package/bin/github/gql/poll-summary-fragment.gql

@@ -3,6 +3,7 @@ fragment PollSummaryPr on PullRequest {
   title
   url
   state
+  updatedAt
   isDraft
   viewerCanUpdate
   headRefName
@@ -11,6 +12,26 @@ fragment PollSummaryPr on PullRequest {
   baseRefOid
   mergeable
   mergeStateStatus
+  lifecycleEvents: timelineItems(
+    last: 1
+    itemTypes: [CLOSED_EVENT, REOPENED_EVENT, CONVERT_TO_DRAFT_EVENT, READY_FOR_REVIEW_EVENT]
+  ) {
+    nodes {
+      __typename
+      ... on ClosedEvent {
+        createdAt
+      }
+      ... on ReopenedEvent {
+        createdAt
+      }
+      ... on ConvertToDraftEvent {
+        createdAt
+      }
+      ... on ReadyForReviewEvent {
+        createdAt
+      }
+    }
+  }
   reviewDecision
   reviewRequests(last: 50) {
     nodes {
@@ -38,6 +59,33 @@ fragment PollSummaryPr on PullRequest {
     }
   }
   isInMergeQueue
+  mergeQueueAdditions: timelineItems(last: 1, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT]) {
+    nodes {
+      ... on AddedToMergeQueueEvent {
+        createdAt
+      }
+    }
+  }
+  mergeQueueRemovals: timelineItems(last: 1, itemTypes: [REMOVED_FROM_MERGE_QUEUE_EVENT]) {
+    nodes {
+      ... on RemovedFromMergeQueueEvent {
+        id
+        reason
+        createdAt
+        actor {
+          login
+        }
+        beforeCommit {
+          oid
+          parents(first: 100) {
+            nodes {
+              oid
+            }
+          }
+        }
+      }
+    }
+  }
   mergeQueueEntry {
     headCommit {
       statusCheckRollup {
@@ -54,6 +102,9 @@ fragment PollSummaryPr on PullRequest {
               status
               conclusion
               detailsUrl
+              annotations(first: 1) {
+                totalCount
+              }
               checkSuite {
                 workflowRun {
                   databaseId
@@ -175,6 +226,9 @@ fragment PollSummaryPr on PullRequest {
                 status
                 conclusion
                 detailsUrl
+                annotations(first: 1) {
+                  totalCount
+                }
                 checkSuite {
                   workflowRun {
                     databaseId

package/bin/github/gql/pr-merge-policy.gql

@@ -1,6 +1,9 @@
 fragment PrMergePolicy on PullRequest {
   isMergeQueueEnabled
   baseRef {
+    target {
+      oid
+    }
     branchProtectionRule {
       requiresApprovingReviews
       requiredApprovingReviewCount

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

@@ -0,0 +1,8 @@
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/**
+ * Bind receipts to the review and head-commit CI evidence shared by one-PR
+ * completion and stack reconciliation. Queue entry, queue checks, and GitHub's
+ * computed merge state are checked separately: including them here would
+ * invalidate a READY receipt merely because a ready PR entered the queue.
+ */
+export declare function fingerprintRawSummaryPr(raw: RawSummaryPr): string | null;

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

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+/**
+ * Bind receipts to the review and head-commit CI evidence shared by one-PR
+ * completion and stack reconciliation. Queue entry, queue checks, and GitHub's
+ * computed merge state are checked separately: including them here would
+ * invalidate a READY receipt merely because a ready PR entered the queue.
+ */
+export function fingerprintRawSummaryPr(raw) {
+    if (!raw.updatedAt || !raw.headRefOid || !raw.baseRefOid)
+        return null;
+    const evidence = {
+        number: raw.number,
+        state: raw.state,
+        lifecycleEvents: raw.lifecycleEvents,
+        isDraft: raw.isDraft,
+        headRefOid: raw.headRefOid,
+        baseRefOid: raw.baseRefOid,
+        baseRefName: raw.baseRefName,
+        reviewDecision: raw.reviewDecision,
+        reviewRequests: raw.reviewRequests,
+        latestReviews: raw.latestReviews,
+        comments: raw.comments,
+        reviews: raw.reviews,
+        reviewThreads: raw.reviewThreads,
+        commits: raw.commits,
+    };
+    return createHash("sha256").update(JSON.stringify(evidence)).digest("hex");
+}