pr-shepherd 0.56.5 → 0.57.0

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

@@ -16,10 +16,12 @@ fragment PollSummaryCheckContexts on StatusCheckRollupContextConnection {
       completedAt
       checkSuite {
         createdAt
+        updatedAt
         workflowRun {
           databaseId
           event
           createdAt
+          updatedAt
           workflow {
             databaseId
             name
@@ -30,6 +32,9 @@ fragment PollSummaryCheckContexts on StatusCheckRollupContextConnection {
     ... on StatusContext {
       context
       state
+      createdAt
+      targetUrl
+      description
     }
   }
 }

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

@@ -1,4 +1,7 @@
 fragment PollSummaryPr on PullRequest {
+  # Scalars and objects below marked "handoff" add no connection, so the stack
+  # summary keeps its price; they let a routed layer's first tick skip BatchPr.
+  id
   number
   title
   url
@@ -10,12 +13,33 @@ fragment PollSummaryPr on PullRequest {
   updatedAt
   isDraft
   viewerCanUpdate
+  # handoff
+  viewerDidAuthor
+  viewerCanEnableAutoMerge
+  viewerCanEditFiles
+  headRepository {
+    nameWithOwner
+    viewerPermission
+  }
+  isMergeQueueEnabled
+  # Aliased: the summary's own `autoMergeRequest` is the REST-projected status.
+  batchAutoMergeRequest: autoMergeRequest {
+    enabledAt
+    mergeMethod
+    enabledBy {
+      login
+    }
+  }
   headRefName
   headRefOid
   baseRefName
   baseRefOid
   baseRef {
     ...RefRules
+    # handoff: the live base tip
+    target {
+      oid
+    }
   }
   mergeable
   mergeStateStatus
@@ -53,6 +77,9 @@ fragment PollSummaryPr on PullRequest {
         ... on Mannequin {
           login
         }
+        ... on Team {
+          name
+        }
       }
     }
   }
@@ -127,12 +154,15 @@ fragment PollSummaryPr on PullRequest {
       id
       body
       isMinimized
+      viewerCanMinimize
       url
       authorAssociation
       author {
         __typename
         login
       }
+      createdAt
+      updatedAt
     }
   }
   reviews(last: 100) {
@@ -145,11 +175,18 @@ fragment PollSummaryPr on PullRequest {
       body
       state
       isMinimized
+      viewerCanMinimize
       authorAssociation
       author {
         __typename
         login
       }
+      createdAt
+      updatedAt
+      url
+      commit {
+        oid
+      }
     }
   }
   reviewThreads(last: 20) {
@@ -161,27 +198,21 @@ fragment PollSummaryPr on PullRequest {
       id
       isResolved
       isOutdated
+      viewerCanReply
+      viewerCanResolve
       path
-      rootComments: comments(first: 1) {
-        nodes {
-          id
-          body
-          url
-          viewerDidAuthor
-          authorAssociation
-          author {
-            __typename
-            login
-          }
-        }
-      }
-      comments(last: 5) {
+      line
+      startLine
+      # One window from the root: a second nested connection would cost 20 more
+      # connection-requests per PR. `hasPreviousPage` marks comments outside it.
+      comments(first: 5) {
         totalCount
         pageInfo {
-          hasPreviousPage
+          hasPreviousPage: hasNextPage
         }
         nodes {
           id
+          isMinimized
           body
           url
           authorAssociation
@@ -190,25 +221,44 @@ fragment PollSummaryPr on PullRequest {
             __typename
             login
           }
+          pullRequestReview {
+            id
+          }
+          path
+          line
+          startLine
+          createdAt
+          updatedAt
         }
       }
     }
   }
   commits(last: 1) {
+    totalCount
     nodes {
       commit {
         oid
         committedDate
         checkSuites(first: 50) {
+          pageInfo {
+            hasNextPage
+          }
           nodes {
+            id
             status
             conclusion
             workflowRun {
+              databaseId
               event
+              url
+              workflow {
+                name
+              }
             }
           }
         }
         statusCheckRollup {
+          state
           contexts(last: 100) {
             ...PollSummaryCheckContexts
           }

package/bin/github/gql/stack-handoff-check-runs.gql

@@ -0,0 +1,42 @@
+# The CheckRun fields BatchPr reads that the stack summary does not, for the
+# routed layers' handoffs. One request per run, so 100 runs price at 1 point.
+query StackHandoffCheckRuns($ids: [ID!]!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  nodes(ids: $ids) {
+    __typename
+    ... on CheckRun {
+      id
+      title
+      summary
+      annotations(first: 1) {
+        totalCount
+        nodes {
+          fullDatabaseId
+          path
+          annotationLevel
+          title
+          message
+          rawDetails
+          blobUrl
+          location {
+            start {
+              line
+              column
+            }
+            end {
+              line
+              column
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/upper-layer-conflict-target.gql

@@ -16,21 +16,6 @@ query UpperLayerConflictTarget($owner: String!, $name: String!, $number: Int!, $
           behindBy
         }
       }
-      stack {
-        entries(first: 100) {
-          pageInfo {
-            hasNextPage
-          }
-          nodes {
-            position
-            pullRequest {
-              number
-              state
-              baseRefName
-            }
-          }
-        }
-      }
     }
   }
 }

package/bin/github/graphql-http.mjs

@@ -2,8 +2,10 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
-import { withGraphQlInternalRetry } from "./graphql-internal-retry.mjs";
+import { isGraphQlMutationDocument, withGraphQlInternalRetry } from "./graphql-internal-retry.mjs";
+import { githubFetch } from "./github-fetch.mjs";
 import { formatGraphQlErrors, parseGraphQlPayload } from "./graphql-response.mjs";
+import { CCR_GRAPHQL_REFUSAL_MESSAGE, isCcrGraphqlRefusal } from "./graphql-session-refusal.mjs";
 import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
@@ -27,7 +29,7 @@ async function graphqlInner(query, vars, opts) {
         const auth = await makeAuthHeaders();
         authSource = auth.source;
         credentialFingerprint = auth.fingerprint;
-        return fetch(url, {
+        return githubFetch(url, {
             method: "POST",
             headers: auth.headers,
             body: JSON.stringify({ query, variables: vars }),
@@ -41,7 +43,7 @@ async function graphqlInner(query, vars, opts) {
         durationMs,
         authSource,
         credentialFingerprint,
-    }));
+    }), !isGraphQlMutationDocument(query), true);
     const durationMs = Math.round(performance.now() - retryT0);
     const headerRateLimit = parseRateLimit(res.headers);
     const retryAfterSeconds = parseRetryAfter(res.headers);
@@ -67,11 +69,14 @@ async function graphqlInner(query, vars, opts) {
             credentialFingerprint,
             rateLimit: headerRateLimit ?? undefined,
         });
-        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
+        throw new GitHubRequestError(isCcrGraphqlRefusal(res.status, body)
+            ? CCR_GRAPHQL_REFUSAL_MESSAGE
+            : `GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
             status: res.status,
             rateLimit: headerRateLimit ?? undefined,
             retryAfterSeconds,
             authSource,
+            responseMessage: redactToken(body),
         });
     }
     let parsed;

package/bin/github/graphql-internal-retry.d.mts

@@ -1,2 +1,4 @@
+/** True when the root operation is a mutation. Anonymous `{...}` is a query. */
+export declare function isGraphQlMutationDocument(document: string): boolean;
 /** Retry GitHub GraphQL engine crashes and resource-limit failures on reads. */
 export declare function withGraphQlInternalRetry<T>(document: string, run: () => Promise<T>): Promise<T>;

package/bin/github/graphql-internal-retry.mjs

@@ -2,7 +2,7 @@ import { sleep } from "../util/sleep.mjs";
 import { GitHubRequestError, isRetryableGraphQlInternal, isRetryableGraphQlResourceLimit, } from "./errors.mjs";
 const GRAPHQL_INTERNAL_RETRY_DELAYS = [500, 1500];
 /** True when the root operation is a mutation. Anonymous `{...}` is a query. */
-function isGraphQlMutationDocument(document) {
+export function isGraphQlMutationDocument(document) {
     let rest = document;
     for (;;) {
         rest = rest.replace(/^\s+/, "");

package/bin/github/graphql-quota-probe.d.mts

@@ -0,0 +1,6 @@
+import type { GitHubRequestError } from "./errors.mts";
+/** Decide whether a quota-shaped GraphQL error needs proof from REST's resource endpoint. */
+export declare function needsGraphQlQuotaProbe(error: GitHubRequestError): boolean;
+export declare function hasMixedGraphQlQuotaErrors(errors: GitHubRequestError["graphqlErrors"]): boolean;
+/** REST can prove exhaustion when the GraphQL refusal has no usable quota sample. */
+export declare function isPrimaryGraphQlQuotaExhausted(): Promise<boolean>;

package/bin/github/graphql-quota-probe.mjs

@@ -0,0 +1,56 @@
+import { rest } from "./rest-http.mjs";
+/** Decide whether a quota-shaped GraphQL error needs proof from REST's resource endpoint. */
+export function needsGraphQlQuotaProbe(error) {
+    const response = error.responseMessage ?? "";
+    const messages = [
+        response,
+        error.message,
+        ...(error.graphqlErrors?.map((entry) => entry.message) ?? []),
+    ].join(" ");
+    if (error.retryAfterSeconds !== undefined ||
+        /secondary (?:rate )?limit|abuse detection/i.test(messages))
+        return false;
+    if (error.rateLimit && (!error.rateLimit.resource || error.rateLimit.resource === "graphql"))
+        return false;
+    const errors = error.graphqlErrors;
+    if (hasMixedGraphQlQuotaErrors(errors))
+        return false;
+    const quotaRefusal = errors?.length
+        ? errors.every(isQuotaError)
+        : /api rate limit exceeded/i.test(parseResponseMessage(response) || error.message);
+    return quotaRefusal && [200, 403, 429].includes(error.status);
+}
+export function hasMixedGraphQlQuotaErrors(errors) {
+    return !!errors?.some(isQuotaError) && !errors.every(isQuotaError);
+}
+function isQuotaError(error) {
+    return (error.type?.toUpperCase() === "RATE_LIMITED" || /api rate limit exceeded/i.test(error.message));
+}
+/** REST can prove exhaustion when the GraphQL refusal has no usable quota sample. */
+export async function isPrimaryGraphQlQuotaExhausted() {
+    try {
+        const value = await rest("GET", "/rate_limit");
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return false;
+        const resources = value["resources"];
+        if (!resources || typeof resources !== "object" || Array.isArray(resources))
+            return false;
+        const graphql = resources["graphql"];
+        if (!graphql || typeof graphql !== "object" || Array.isArray(graphql))
+            return false;
+        const remaining = graphql["remaining"];
+        return typeof remaining === "number" && Number.isFinite(remaining) && remaining <= 0;
+    }
+    catch {
+        return false;
+    }
+}
+function parseResponseMessage(response) {
+    try {
+        const parsed = JSON.parse(response);
+        if (typeof parsed.message === "string")
+            return parsed.message;
+    }
+    catch { }
+    return response.trim();
+}

package/bin/github/graphql-session-refusal.d.mts

@@ -0,0 +1,8 @@
+/**
+ * Whether a GraphQL response is the Claude Code cloud proxy's blanket refusal. Inspects the raw
+ * body, because the proxy appends a long list of REST routes that pushes the refusal past the
+ * truncated error message.
+ */
+export declare function isCcrGraphqlRefusal(status: number, raw: string): boolean;
+/** Exit-77 message for an explicit `--transport graphql` run inside a Claude Code cloud session. */
+export declare const CCR_GRAPHQL_REFUSAL_MESSAGE: string;

package/bin/github/graphql-session-refusal.mjs

@@ -0,0 +1,14 @@
+/** Text the Claude Code cloud proxy returns, with HTTP 403, for every GraphQL request. */
+const CCR_GRAPHQL_REFUSAL = "GitHub GraphQL is not available from Claude Code sessions";
+/**
+ * Whether a GraphQL response is the Claude Code cloud proxy's blanket refusal. Inspects the raw
+ * body, because the proxy appends a long list of REST routes that pushes the refusal past the
+ * truncated error message.
+ */
+export function isCcrGraphqlRefusal(status, raw) {
+    return status === 403 && raw.includes(CCR_GRAPHQL_REFUSAL);
+}
+/** Exit-77 message for an explicit `--transport graphql` run inside a Claude Code cloud session. */
+export const CCR_GRAPHQL_REFUSAL_MESSAGE = "GitHub GraphQL is not available from Claude Code sessions (HTTP 403 from the Claude Code proxy). " +
+    "Rerun with `--transport rest` or `--transport auto` (the default), or set `github.transport` " +
+    "to `rest` or `auto`.";

package/bin/github/http-request.d.mts

@@ -1,5 +1,5 @@
 type RetryLogFn = (response: Response, durationMs: number) => void;
-export declare function requestWithTokenRetry(fn: () => Promise<Response>, t0: number, onIntermediate?: RetryLogFn): Promise<{
+export declare function requestWithTokenRetry(fn: () => Promise<Response>, t0: number, onIntermediate?: RetryLogFn, safeRead?: boolean, retryServerErrors?: boolean): Promise<{
     res: Response;
     attempt: number;
     retryT0: number;

package/bin/github/http-request.mjs

@@ -2,14 +2,26 @@ import { clearTokenCache, hasCachedToken } from "./http-auth.mjs";
 import { isTransportError } from "./http-utils.mjs";
 import { sleep } from "../util/sleep.mjs";
 const TRANSPORT_RETRY_DELAYS = [250, 500];
-async function fetchWithTransportRetry(fn) {
+async function fetchWithTransportRetry(fn, safeRead, retryServerErrors, onRetry) {
     let lastErr;
     for (let attempt = 1; attempt <= TRANSPORT_RETRY_DELAYS.length + 1; attempt++) {
         try {
-            return await fn();
+            const startedAt = performance.now();
+            const response = await fn();
+            const delay = TRANSPORT_RETRY_DELAYS[attempt - 1];
+            if (safeRead && retryServerErrors && response.status >= 500 && delay !== undefined) {
+                onRetry?.(response, Math.round(performance.now() - startedAt));
+                try {
+                    await response.arrayBuffer();
+                }
+                catch { }
+                await sleep(delay);
+                continue;
+            }
+            return response;
         }
         catch (err) {
-            if (!isTransportError(err))
+            if (!safeRead || !isTransportError(err))
                 throw err;
             lastErr = err;
             const delay = TRANSPORT_RETRY_DELAYS[attempt - 1];
@@ -20,8 +32,8 @@ async function fetchWithTransportRetry(fn) {
     }
     throw lastErr;
 }
-export async function requestWithTokenRetry(fn, t0, onIntermediate) {
-    const res = await fetchWithTransportRetry(fn);
+export async function requestWithTokenRetry(fn, t0, onIntermediate, safeRead = true, retryServerErrors = false) {
+    const res = await fetchWithTransportRetry(fn, safeRead, retryServerErrors, onIntermediate);
     if (res.status === 401 && hasCachedToken()) {
         onIntermediate?.(res, Math.round(performance.now() - t0));
         try {
@@ -30,7 +42,11 @@ export async function requestWithTokenRetry(fn, t0, onIntermediate) {
         catch { }
         clearTokenCache();
         const retryT0 = performance.now();
-        return { res: await fetchWithTransportRetry(fn), attempt: 2, retryT0 };
+        return {
+            res: await fetchWithTransportRetry(fn, safeRead, retryServerErrors, onIntermediate),
+            attempt: 2,
+            retryT0,
+        };
     }
     return { res, attempt: 1, retryT0: t0 };
 }

package/bin/github/http-utils.mjs

@@ -3,7 +3,13 @@ const TRANSPORT_ERROR_CODES = new Set([
     "ETIMEDOUT",
     "ECONNREFUSED",
     "EAI_AGAIN",
+    "ENOTFOUND",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "EPIPE",
     "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT",
     "UND_ERR_SOCKET",
 ]);
 export function isTransportError(err) {

package/bin/github/merge-target-rules.d.mts

@@ -1,12 +1,19 @@
+import { type BaseBehindCacheOptions } from "./base-behind-cache.mts";
 import type { CheckExecutionContext } from "../commands/check-execution-context.mts";
 export interface MergeTargetStatus {
     contexts: string[];
-    trunkBehindBy?: number;
+    /**
+     * Commits on the trunk that the bottom open layer does not contain. Present only for a
+     * native stack; callers load it only when a required check is unreported.
+     */
+    trunkBehindBy?: () => Promise<number>;
     stackBottomPr?: number;
 }
 /**
  * Required status contexts for the branch GitHub actually merges into.
- * A native stack uses the trunk ref, and `behindBy` is that trunk against the bottom open layer.
+ * A native stack uses the trunk ref, and `trunkBehindBy` compares that trunk against the bottom
+ * open layer. The trunk rules and the stack topology come from this tick's `BatchPr` when the
+ * context holds them; otherwise `RefRules` and `PollStackTopology` read them.
  */
 export declare function loadMergeTargetStatus(input: {
     owner: string;
@@ -14,6 +21,8 @@ export declare function loadMergeTargetStatus(input: {
     pr: number;
     baseRefName: string;
     headRefName: string;
+    /** Head commit; preferred over the branch name for the trunk compare. */
+    headRefOid?: string;
     localContexts: readonly string[];
     stack?: {
         baseRefName: string;
@@ -26,4 +35,8 @@ export declare function loadMergeTargetStatus(input: {
  * `mergeStateStatus` stays `BLOCKED` when a conversation or an expected check
  * is also open, so this compare is the behind count that status hides.
  */
-export declare function loadBaseBehindBy(owner: string, name: string, baseRefName: string, headRef: string): Promise<number>;
+export declare function loadBaseBehindBy(owner: string, name: string, baseRefName: string, headRef: string, cache?: BaseBehindCacheOptions): Promise<number>;
+export declare function loadRefRules(owner: string, name: string, qualifiedName: string, headRef: string): Promise<{
+    contexts: string[];
+    behindBy: number;
+}>;