pr-shepherd 0.55.1 → 0.56.0

package/bin/github/gql/batch-pr.gql

@@ -279,6 +279,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
                     title
                     summary
                     annotations(first: 1) {
+                      totalCount
                       nodes {
                         message
                       }

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

@@ -4,6 +4,14 @@ query PollSummaryAnnotationProbe(
   $oid: GitObjectID!
   $before: String
 ) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     object(oid: $oid) {
       __typename

package/bin/github/gql/reply-thread-comments.gql

@@ -0,0 +1,25 @@
+query ReplyThreadComments($id: ID!, $cursor: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  node(id: $id) {
+    __typename
+    ... on PullRequestReviewThread {
+      id
+      comments(first: 100, after: $cursor) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          body
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/reply-thread-transcripts.gql

@@ -0,0 +1,31 @@
+query ReplyThreadTranscripts($ids: [ID!]!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  nodes(ids: $ids) {
+    __typename
+    ... on PullRequestReviewThread {
+      id
+      pullRequest {
+        number
+        repository {
+          nameWithOwner
+        }
+      }
+      comments(first: 100) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          body
+        }
+      }
+    }
+  }
+}

package/bin/github/merge-queue-checks.d.mts

@@ -1,4 +1,5 @@
+import { type RateLimitInfo } from "./client.mts";
 import type { RepoInfo } from "./client.mts";
 import type { RawPr } from "./batch-raw-types.mts";
 /** Hydrate all status contexts for the active or most recently removed queue commit. */
-export declare function hydrateMergeQueueChecks(raw: RawPr, repo: RepoInfo): Promise<void>;
+export declare function hydrateMergeQueueChecks(raw: RawPr, repo: RepoInfo, initialRateLimit?: RateLimitInfo): Promise<RateLimitInfo | undefined>;

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

@@ -1,5 +1,6 @@
 import { parseCreatedAt } from "./batch-parser-helpers.mjs";
-import { graphql } from "./client.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
 import { headPushUnixFromCheckNodes, queueRemovalAppliesToHead, } from "./queue-removal-freshness.mjs";
 import { requireContextNodes } from "./batch-response.mjs";
 import { COMMIT_CHECK_CONTEXTS_QUERY } from "./queries.mjs";
@@ -18,13 +19,20 @@ function initialQueueCursor(existing, oid) {
         return null;
     return nextPageCursor(existing, oid);
 }
-async function fetchQueuePage(oid, repo, cursor) {
-    const result = await graphql(COMMIT_CHECK_CONTEXTS_QUERY, {
+async function fetchQueuePage(oid, repo, cursor, gate) {
+    if (gate.rateLimit?.remaining === 0) {
+        throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; merge queue check pagination incomplete", {
+            status: 403,
+            rateLimit: gate.rateLimit,
+        });
+    }
+    const result = await graphqlWithRateLimit(COMMIT_CHECK_CONTEXTS_QUERY, {
         owner: repo.owner,
         repo: repo.name,
         oid,
         ...(cursor !== null && { cursor }),
     });
+    gate.rateLimit = result.rateLimit ?? gate.rateLimit;
     const object = result.data.repository?.object;
     if (object?.__typename !== "Commit" || object.oid !== oid) {
         if (cursor === null)
@@ -33,13 +41,13 @@ async function fetchQueuePage(oid, repo, cursor) {
     }
     return object.statusCheckRollup?.contexts ?? null;
 }
-async function hydrateCommitContexts(commit, repo) {
+async function hydrateCommitContexts(commit, repo, gate) {
     const existing = commit.statusCheckRollup?.contexts;
     const nodes = existing ? [...requireContextNodes(existing.nodes)] : [];
     let cursor = initialQueueCursor(existing, commit.oid);
     while (cursor !== undefined) {
         // eslint-disable-next-line no-await-in-loop
-        const next = await fetchQueuePage(commit.oid, repo, cursor);
+        const next = await fetchQueuePage(commit.oid, repo, cursor, gate);
         if (!next) {
             if (cursor === null) {
                 cursor = undefined;
@@ -78,11 +86,13 @@ function currentRemovalCommit(raw) {
     return removal.beforeCommit;
 }
 /** Hydrate all status contexts for the active or most recently removed queue commit. */
-export async function hydrateMergeQueueChecks(raw, repo) {
+export async function hydrateMergeQueueChecks(raw, repo, initialRateLimit) {
+    const gate = { rateLimit: initialRateLimit };
     const active = raw.mergeQueueEntry?.headCommit;
     const removed = currentRemovalCommit(raw);
     if (active)
-        await hydrateCommitContexts(active, repo);
+        await hydrateCommitContexts(active, repo, gate);
     if (removed && removed.oid !== active?.oid)
-        await hydrateCommitContexts(removed, repo);
+        await hydrateCommitContexts(removed, repo, gate);
+    return gate.rateLimit;
 }

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

@@ -1,3 +1,4 @@
+import type { CheckExecutionContext } from "../commands/check-execution-context.mts";
 export interface MergeTargetStatus {
     contexts: string[];
     trunkBehindBy?: number;
@@ -17,7 +18,7 @@ export declare function loadMergeTargetStatus(input: {
     stack?: {
         baseRefName: string;
     } | null;
-}): Promise<MergeTargetStatus>;
+}, context?: CheckExecutionContext): Promise<MergeTargetStatus>;
 /**
  * Commits on the PR base that `headRef` does not contain.
  * Pass the head commit OID. A fork's branch name can exist on the base

package/bin/github/merge-target-rules.mjs

@@ -8,14 +8,14 @@ import { readStackTopology } from "./stack-read.mjs";
  * 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.
  */
-export async function loadMergeTargetStatus(input) {
+export async function loadMergeTargetStatus(input, context) {
     const trunk = input.stack?.baseRefName;
     if (!trunk)
         return { contexts: [...input.localContexts] };
     let headRef = input.headRefName;
     let stackBottomPr = input.pr;
     if (trunk !== input.baseRefName) {
-        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, trunk);
+        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, trunk, context);
         headRef = bottom.headRefName;
         stackBottomPr = bottom.number;
     }
@@ -26,8 +26,8 @@ export async function loadMergeTargetStatus(input) {
         stackBottomPr,
     };
 }
-async function bottomOpenLayer(pr, repo, trunk) {
-    const topology = await readStackTopology(pr, repo);
+async function bottomOpenLayer(pr, repo, trunk, context) {
+    const topology = await (context?.readStackTopology(pr, repo) ?? readStackTopology(pr, repo));
     const bottom = topology.ordered.find((member) => member.state === "OPEN" && member.baseRefName === trunk);
     if (!bottom) {
         throw new ShepherdError(`Native stack for PR #${pr} has no open layer based on ${trunk}`, EXIT.TEMPFAIL);

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

@@ -1,5 +1,7 @@
 import { type RepoInfo } from "./client.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/** Annotation totals copied from the same full-snapshot request; no follow-up probe is needed. */
+export declare function markReadyAnnotationProbeComplete(pr: RawSummaryPr): void;
 /**
  * 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:

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

@@ -4,6 +4,11 @@ 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");
+const COMPLETE_FROM_BATCH = new WeakSet();
+/** Annotation totals copied from the same full-snapshot request; no follow-up probe is needed. */
+export function markReadyAnnotationProbeComplete(pr) {
+    COMPLETE_FROM_BATCH.add(pr);
+}
 /**
  * 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:
@@ -24,6 +29,8 @@ export function readyFingerprint(raw, stored) {
  * a check gains an annotation.
  */
 export async function hydrateReadyAnnotationProbe(pr, repo, review) {
+    if (COMPLETE_FROM_BATCH.has(pr))
+        return;
     const checks = summarizePollSummaryChecks(pr);
     if (!isCurrentSummaryReady(pr, checks, review))
         return;

package/bin/github/queries.d.mts

@@ -14,6 +14,8 @@ 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;
+/** Exact compact summary sibling only when a one-PR READY receipt needs evidence. */
+export declare const BATCH_PR_RECEIPT_QUERY: 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. */
@@ -41,6 +43,9 @@ export declare const UPPER_LAYER_CONFLICT_TARGET_QUERY: string;
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;
+/** Requested review-thread transcripts for best-effort reply seen markers. */
+export declare const REPLY_THREAD_TRANSCRIPTS_QUERY: string;
+export declare const REPLY_THREAD_COMMENTS_QUERY: string;
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export declare const CHECK_RUN_ANNOTATIONS_QUERY: string;
 /**

package/bin/github/queries.mjs

@@ -19,6 +19,8 @@ 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("ref-rules.gql")}\n${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
+/** Exact compact summary sibling only when a one-PR READY receipt needs evidence. */
+export const BATCH_PR_RECEIPT_QUERY = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}\n${BATCH_PR_QUERY.replace("    pullRequest(number: $pr) {", "    receiptSummary: pullRequest(number: $pr) { ...PollSummaryPr }\n    pullRequest(number: $pr) {")}`;
 /** 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. */
@@ -46,6 +48,9 @@ export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-targe
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");
+/** Requested review-thread transcripts for best-effort reply seen markers. */
+export const REPLY_THREAD_TRANSCRIPTS_QUERY = gql("reply-thread-transcripts.gql");
+export const REPLY_THREAD_COMMENTS_QUERY = gql("reply-thread-comments.gql");
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export const CHECK_RUN_ANNOTATIONS_QUERY = gql("check-run-annotations.gql");
 /**

package/bin/github/rate-limit-kind.d.mts

@@ -0,0 +1,13 @@
+import type { RateLimitInfo } from "./http-utils.mts";
+export type RateLimitKind = "primary" | "secondary";
+/** Interpret GitHub's throttle signals independently of the quota resource header. */
+export declare function rateLimitKind(input: {
+    status: number;
+    message: string;
+    responseMessage?: string;
+    rateLimit?: RateLimitInfo;
+    retryAfterSeconds?: number;
+    graphqlErrors?: Array<{
+        message: string;
+    }>;
+}): RateLimitKind | null;

package/bin/github/rate-limit-kind.mjs

@@ -0,0 +1,25 @@
+/** Interpret GitHub's throttle signals independently of the quota resource header. */
+export function rateLimitKind(input) {
+    const exhausted = input.rateLimit !== undefined && input.rateLimit.remaining <= 0;
+    const responseText = input.responseMessage ?? input.message;
+    const graphqlMessages = (input.graphqlErrors ?? []).map((error) => error.message);
+    const textThrottleCapable = input.status === 403 || input.status === 429;
+    const explicitlySecondary = /secondary (?:rate )?limit|abuse detection/i;
+    if ((textThrottleCapable && explicitlySecondary.test(responseText)) ||
+        graphqlMessages.some((message) => explicitlySecondary.test(message))) {
+        return "secondary";
+    }
+    // A 429 with an empty primary bucket is an actual primary-limit response.
+    if (input.status === 429 && exhausted)
+        return "primary";
+    if (exhausted)
+        return "primary";
+    if (input.status === 429 ||
+        input.retryAfterSeconds !== undefined ||
+        (textThrottleCapable && /\brate limit\b/i.test(responseText)) ||
+        graphqlMessages.some((message) => /\brate limit\b/i.test(message))) {
+        // Without a measured empty bucket, do not spend REST core on a probe.
+        return "secondary";
+    }
+    return null;
+}

package/bin/github/reply-thread-transcripts.d.mts

@@ -0,0 +1,3 @@
+import { type RepoInfo } from "./client.mts";
+/** Best-effort transcript evidence; it never filters user-supplied mutation IDs. */
+export declare function fetchReplyThreadTranscripts(pr: number, repo: RepoInfo, requestedIds: readonly string[]): Promise<Map<string, string>>;

package/bin/github/reply-thread-transcripts.mjs

@@ -0,0 +1,89 @@
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { rateLimitKind } from "./rate-limit-kind.mjs";
+import { REPLY_THREAD_COMMENTS_QUERY, REPLY_THREAD_TRANSCRIPTS_QUERY } from "./queries.mjs";
+import { threadTranscriptBodies } from "../threads/transcript.mjs";
+import { mapPool } from "../util/pool.mjs";
+const IDS_PER_REQUEST = 20;
+const CONCURRENCY = 4;
+const MAX_COMMENT_PAGES = 100;
+/** Best-effort transcript evidence; it never filters user-supplied mutation IDs. */
+export async function fetchReplyThreadTranscripts(pr, repo, requestedIds) {
+    const ids = [...new Set(requestedIds)];
+    if (ids.length === 0)
+        return new Map();
+    const expectedRepo = `${repo.owner}/${repo.name}`.toLowerCase();
+    const requested = new Set(ids);
+    const chunks = [];
+    for (let offset = 0; offset < ids.length; offset += IDS_PER_REQUEST) {
+        chunks.push(ids.slice(offset, offset + IDS_PER_REQUEST));
+    }
+    let stopped = false;
+    const firstPages = await mapPool(chunks, CONCURRENCY, async (chunk) => {
+        if (stopped)
+            return [];
+        try {
+            const result = await graphqlWithRateLimit(REPLY_THREAD_TRANSCRIPTS_QUERY, {
+                ids: chunk,
+            });
+            if (result.rateLimit?.remaining === 0)
+                stopped = true;
+            return result.data.nodes.filter((node) => node?.__typename === "PullRequestReviewThread" &&
+                node.id !== undefined &&
+                requested.has(node.id) &&
+                node.pullRequest?.number === pr &&
+                node.pullRequest.repository.nameWithOwner.toLowerCase() === expectedRepo &&
+                node.comments !== undefined);
+        }
+        catch (error) {
+            if (isThrottle(error))
+                stopped = true;
+            return [];
+        }
+    });
+    const threads = firstPages.flat();
+    const completed = await mapPool(threads, CONCURRENCY, async (thread) => {
+        try {
+            return await completeThread(thread, () => stopped, () => {
+                stopped = true;
+            });
+        }
+        catch (error) {
+            if (isThrottle(error))
+                stopped = true;
+            return null;
+        }
+    });
+    return new Map(completed.filter((entry) => entry !== null));
+}
+async function completeThread(thread, isStopped, stop) {
+    if (!thread.id || !thread.comments)
+        return null;
+    const bodies = thread.comments.nodes.map((comment) => comment.body);
+    let page = thread.comments;
+    const seenCursors = new Set();
+    let pages = 1;
+    while (page.pageInfo.hasNextPage) {
+        const cursor = page.pageInfo.endCursor;
+        if (!cursor || seenCursors.has(cursor) || pages >= MAX_COMMENT_PAGES || isStopped())
+            return null;
+        seenCursors.add(cursor);
+        const result = await graphqlWithRateLimit(REPLY_THREAD_COMMENTS_QUERY, {
+            id: thread.id,
+            cursor,
+        });
+        if (result.rateLimit?.remaining === 0)
+            stop();
+        const next = result.data.node;
+        if (next?.__typename !== "PullRequestReviewThread" || next.id !== thread.id || !next.comments) {
+            return null;
+        }
+        page = next.comments;
+        bodies.push(...page.nodes.map((comment) => comment.body));
+        pages += 1;
+    }
+    return bodies.length > 0 ? [thread.id, threadTranscriptBodies(bodies)] : null;
+}
+function isThrottle(error) {
+    return error instanceof GitHubRequestError && rateLimitKind(error) !== null;
+}

package/bin/github/rest-http.mjs

@@ -98,6 +98,7 @@ export async function restWithRateLimit(method, path, body, opts) {
             rateLimit,
             retryAfterSeconds,
             authSource,
+            responseMessage: sanitizeBody(text),
         });
     }
     if (ct.includes("application/json")) {

package/bin/github/rest-text.d.mts

@@ -1 +1,2 @@
-export declare function restText(path: string): Promise<string>;
+import { type RateLimitInfo } from "./http-utils.mts";
+export declare function restText(path: string, onRateLimit?: (rateLimit?: RateLimitInfo) => void): Promise<string>;

package/bin/github/rest-text.mjs

@@ -3,11 +3,11 @@ import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
-import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody, } from "./http-utils.mjs";
 import { recordApiTelemetry } from "./api-telemetry.mjs";
 import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
-export async function restText(path) {
+export async function restText(path, onRateLimit) {
     const url = `${BASE_URL}${path}`;
     const n = nextEntry();
     appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
@@ -28,6 +28,7 @@ export async function restText(path) {
     }));
     const durationMs = Math.round(performance.now() - retryT0);
     const rateLimit = parseRateLimit(res.headers) ?? undefined;
+    onRateLimit?.(rateLimit);
     const retryAfterSeconds = parseRetryAfter(res.headers);
     recordApiTelemetry({ kind: "REST", method: "GET", authSource, rateLimit });
     if ([301, 302, 307, 308].includes(res.status)) {
@@ -62,6 +63,7 @@ export async function restText(path) {
             rateLimit,
             retryAfterSeconds,
             authSource,
+            responseMessage: sanitizeBody(text),
         });
     }
     appendEntry(formatResponseEntry({
@@ -114,6 +116,7 @@ async function followRestTextRedirect(res, entry) {
             status: redirectRes.status,
             rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
             retryAfterSeconds: parseRetryAfter(redirectRes.headers),
+            responseMessage: "",
         });
     }
     return redirectRes.text();

package/bin/github/thread-comments.d.mts

@@ -1,2 +1,6 @@
+import { type RateLimitInfo } from "./client.mts";
 import type { RawThread } from "./batch-raw-types.mts";
-export declare function hydrateThreadCommentPages(threads: RawThread[]): Promise<RawThread[]>;
+export declare function hydrateThreadCommentPages(threads: RawThread[], initialRateLimit?: RateLimitInfo): Promise<{
+    threads: RawThread[];
+    rateLimit?: RateLimitInfo;
+}>;

package/bin/github/thread-comments.mjs

@@ -4,23 +4,47 @@ import { paginateForward } from "./pagination.mjs";
 import { REVIEW_THREAD_COMMENTS_QUERY } from "./queries.mjs";
 import { mapPool } from "../util/pool.mjs";
 const THREAD_COMMENT_PAGE_CONCURRENCY = 4;
-export async function hydrateThreadCommentPages(threads) {
-    const gate = {};
-    return mapPool(threads, THREAD_COMMENT_PAGE_CONCURRENCY, (thread) => hydrateThreadCommentPage(thread, gate));
+export async function hydrateThreadCommentPages(threads, initialRateLimit) {
+    const gate = {
+        rateLimit: initialRateLimit,
+        exhausted: initialRateLimit?.remaining === 0,
+    };
+    const hydrated = await mapPool(threads, THREAD_COMMENT_PAGE_CONCURRENCY, async (thread) => {
+        if (gate.error !== undefined)
+            return thread;
+        try {
+            return await hydrateThreadCommentPage(thread, gate);
+        }
+        catch (error) {
+            gate.error ??= error;
+            return thread;
+        }
+    });
+    if (gate.error !== undefined)
+        throw gate.error;
+    return { threads: hydrated, rateLimit: gate.rateLimit };
 }
 async function hydrateThreadCommentPage(thread, gate) {
     const pageInfo = thread.comments.pageInfo;
     if (!pageInfo?.hasNextPage || !pageInfo.endCursor)
         return thread;
     const extra = await paginateForward(async (cursor) => {
-        if (gate.remaining === 0) {
-            throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; thread comment pagination incomplete", { status: 403 });
+        if (gate.error !== undefined)
+            throw gate.error;
+        if (gate.exhausted) {
+            throw new GitHubRequestError("GitHub GraphQL rate limit remaining is 0; thread comment pagination incomplete", { status: 403, rateLimit: gate.rateLimit });
         }
         const res = await graphqlWithRateLimit(REVIEW_THREAD_COMMENTS_QUERY, {
             threadId: thread.id,
             ...(cursor ? { commentsCursor: cursor } : {}),
         });
-        gate.remaining = res.rateLimit?.remaining;
+        if (res.rateLimit?.remaining === 0) {
+            gate.rateLimit = res.rateLimit;
+            gate.exhausted = true;
+        }
+        else if (!gate.exhausted) {
+            gate.rateLimit = res.rateLimit ?? gate.rateLimit;
+        }
         const node = res.data.node;
         if (!node?.comments) {
             const nodeType = node?.__typename ?? "null";

package/bin/mcp/server.mjs

@@ -10,6 +10,7 @@ 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";
+import { extractShepherdJournal } from "../journal/index.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
 const pr = z
     .string()
@@ -87,7 +88,8 @@ const suggestionPatchesInputSchema = z.object({
 });
 /** Creates a local-only MCP server with Shepherd's public operations. */
 export function createPrShepherdMcpServer(options = {}) {
-    const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
+    let shepherd = options.shepherd;
+    const getShepherd = () => (shepherd ??= createPrShepherd({ cwd: options.cwd }));
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
     server.registerTool("iterate", {
         description: "Inspect one pull request, an explicit same-repository set, or a native stack and return one Shepherd tick.",
@@ -103,7 +105,7 @@ export function createPrShepherdMcpServer(options = {}) {
         const opts = {
             readyDelaySuffix: input.readyDelaySeconds === undefined ? undefined : `${input.readyDelaySeconds}s`,
         };
-        return runTool(() => runIterateSelector(shepherd, requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
+        return runTool(() => runIterateSelector(getShepherd(), requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
             ? formatPollSummaryResult(result)
             : formatIterateResult(result, opts), (result) => isPollSummary(result)
             ? result.selection.kind === "stack"
@@ -120,7 +122,32 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.apply(requireRepositoryQualifiedPr(input)), formatApplyResult));
+    }, async (input) => runTool(() => getShepherd().apply(requireRepositoryQualifiedPr(input)), formatApplyResult));
+    server.registerTool("extract_journal", {
+        description: "Extract the validated Shepherd Journal from a supplied Markdown body without I/O.",
+        inputSchema: z.object({ body: z.string() }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (input) => runTool(async () => {
+        if (typeof input.body !== "string") {
+            throw new PrShepherdValidationError("body must be a Markdown string");
+        }
+        return extractShepherdJournal(input.body);
+    }, JSON.stringify));
+    server.registerTool("get_journal", {
+        description: "Fetch one pull request body with GraphQL and extract its Shepherd Journal.",
+        inputSchema: z.object({ pr }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => getShepherd().getJournal(requireRepositoryQualifiedPr(input)), JSON.stringify));
     server.registerTool("build_suggestion_patches", {
         description: "Build, but never apply, an ordered list of eligible review suggestion patches.",
         inputSchema: suggestionPatchesInputSchema,
@@ -130,7 +157,7 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
+    }, async (input) => runTool(() => getShepherd().buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
     server.registerTool("build_suggestion_patch", {
         description: "Deprecated: use build_suggestion_patches with a one-item suggestions array.",
         inputSchema: suggestionPatchInputSchema,
@@ -140,7 +167,7 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
+    }, async (input) => runTool(() => getShepherd().buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
     return server;
 }
 function runIterateSelector(shepherd, input) {

package/bin/quota-warning.mjs

@@ -5,8 +5,8 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const opening = warning.resource === "combined"
         ? "GitHub's GraphQL and REST core quotas are both low. Keep using pr-shepherd at the cadence below. Do not shift incidental calls between GraphQL and REST."
         : warning.resource === "core"
-            ? `GitHub's REST core quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below. Do not add incidental REST \`gh\` calls (\`gh pr view\`, \`gh pr review\`, \`gh api\`) while REST core is below its warning threshold.`
-            : `GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR operations that do not need Shepherd's full snapshot, prefer non-GraphQL \`gh\` CLI commands (e.g. \`gh pr view\`, \`gh pr review\`, \`gh api\` REST endpoints) — they draw on the separate REST budget, not the depleted GraphQL pool.`;
+            ? `GitHub's REST core quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below. Do not add incidental REST \`gh api repos/OWNER/REPO/pulls/PR\` calls while REST core is below its warning threshold.`
+            : `GitHub's GraphQL API quota is low (crossed the ${warning.thresholdPercent}% remaining threshold). Keep using pr-shepherd at the cadence below; for incidental PR reads that do not need Shepherd's full snapshot, use explicit REST endpoints such as \`gh api repos/OWNER/REPO/pulls/PR\` — they draw on the separate REST budget, not the depleted GraphQL pool.`;
     const resetLabel = warning.resource === "combined"
         ? "both quotas have reset"
         : warning.resource === "core"

package/bin/reporters/agent.mjs

@@ -66,6 +66,7 @@ export function toAgentCheck(c) {
         ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
         ...(c.summary !== undefined && { summary: c.summary }),
         ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
+        ...(c.relatedJobs !== undefined && { relatedJobs: c.relatedJobs }),
         ...(c.annotations !== undefined && { annotations: c.annotations }),
         ...(c.scope !== undefined && { scope: c.scope }),
         ...(c.commitOid !== undefined && { commitOid: c.commitOid }),

package/bin/threads/transcript.d.mts

@@ -13,4 +13,5 @@ export declare function threadComments(thread: {
         viewerDidAuthor?: true;
     } & Partial<Pick<ReviewThreadComment, "isMinimized" | "createdAtUnix">>>;
 }): ReviewThreadComment[];
+export declare function threadTranscriptBodies(bodies: string[]): string;
 export declare function threadTranscriptBody(thread: ReviewThread, appendedBodies?: string[]): string;

package/bin/threads/transcript.mjs

@@ -29,9 +29,12 @@ export function threadComments(thread) {
     ];
 }
 const THREAD_COMMENT_SEPARATOR = "\n\n--- thread comment ---\n\n";
+export function threadTranscriptBodies(bodies) {
+    return bodies.join(THREAD_COMMENT_SEPARATOR);
+}
 export function threadTranscriptBody(thread, appendedBodies = []) {
     const bodies = thread.comments && thread.comments.length > 0
         ? threadComments(thread).map((c) => c.body)
         : [thread.body];
-    return [...bodies, ...appendedBodies].join(THREAD_COMMENT_SEPARATOR);
+    return threadTranscriptBodies([...bodies, ...appendedBodies]);
 }