pr-shepherd 0.48.0 → 0.49.0

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

@@ -0,0 +1,81 @@
+import { loadConfig } from "../config/load.mjs";
+import { updateReadyDelay } from "../commands/ready-delay.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { loadSeenMap } from "../state/seen-comments.mjs";
+import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
+import { summarizePollSummaryReview } from "./poll-summary-review.mjs";
+import { normalizePollSummaryState, routePollSummary } from "./poll-summary-route.mjs";
+export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdminister = false) {
+    const repoName = `${repo.owner}/${repo.name}`;
+    const seen = await loadSeenMap({ owner: repo.owner, repo: repo.name, pr: raw.number });
+    const checks = summarizePollSummaryChecks(raw);
+    const review = await summarizePollSummaryReview(raw, seen, viewerCanAdminister);
+    const blockingReviewerInProgress = detectBlockingReviewer(raw);
+    let { action, reasons } = routePollSummary(raw, checks, review, opts);
+    let remainingSeconds;
+    if (raw.isDraft && blockingReviewerInProgress && action === "mark_ready") {
+        action = "wait";
+        reasons = ["blocking-reviewer-in-progress"];
+    }
+    const appearsReady = reasons.includes("appears-ready");
+    const readyDelaySeconds = opts.readyDelaySeconds ?? (loadConfig().watch?.readyDelayMinutes ?? 10) * 60;
+    const readyState = await updateReadyDelay(raw.number, appearsReady, readyDelaySeconds, repo.owner, repo.name, { retainElapsed: true });
+    if (appearsReady && !readyState.shouldCancel) {
+        action = "wait";
+        reasons = ["ready-delay"];
+        remainingSeconds = readyState.remainingSeconds;
+    }
+    const stack = raw.stack
+        ? {
+            number: raw.stack.number,
+            size: raw.stack.size,
+            position: raw.stackEntry?.position ?? 0,
+            baseRefName: raw.stack.baseRefName,
+        }
+        : undefined;
+    return {
+        pr: raw.number,
+        repo: repoName,
+        title: raw.title,
+        url: raw.url || formatPrUrl(repoName, raw.number),
+        action,
+        reasons,
+        state: normalizePollSummaryState(raw.state),
+        mergeable: raw.mergeable,
+        mergeStateStatus: raw.mergeStateStatus,
+        ...(raw.reviewDecision && { reviewDecision: raw.reviewDecision }),
+        headRefName: raw.headRefName,
+        headRefOid: raw.headRefOid,
+        baseRefName: raw.baseRefName,
+        ...(raw.isDraft && { isDraft: true }),
+        ...(raw.isInMergeQueue && { isInMergeQueue: true }),
+        ...(blockingReviewerInProgress && { blockingReviewerInProgress: true }),
+        ...(remainingSeconds !== undefined && { remainingSeconds }),
+        ...(Object.keys(checks).length > 0 && { checks }),
+        ...(Object.keys(review).length > 0 && { review }),
+        ...(stack && { stack }),
+        ...(!["wait", "cancel"].includes(action) && {
+            pollCommand: buildPollCommand(repoName, raw.number, opts),
+        }),
+    };
+}
+function detectBlockingReviewer(raw) {
+    const prefixes = (loadConfig().mergeStatus?.blockingReviewerLogins ?? []).map((login) => login.toLowerCase());
+    const matches = (author) => author !== null && prefixes.some((prefix) => author.login.toLowerCase().startsWith(prefix));
+    return ((raw.reviewRequests?.nodes ?? []).some((request) => matches(request.requestedReviewer)) ||
+        (raw.latestReviews?.nodes ?? []).some((review) => review.state === "PENDING" && matches(review.author)));
+}
+function buildPollCommand(repo, pr, opts) {
+    const args = [formatPrUrl(repo, pr), "--until-terminal"];
+    if (opts.merge)
+        args.push("--merge");
+    if (opts.readyDelaySeconds !== undefined)
+        args.push("--ready-delay", `${opts.readyDelaySeconds}s`);
+    if (opts.stallTimeoutSeconds !== undefined) {
+        args.push("--stall-timeout", `${opts.stallTimeoutSeconds}s`);
+    }
+    if (opts.noAutoMarkReady)
+        args.push("--no-auto-mark-ready");
+    return buildPrShepherdCommand(args).text;
+}

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

@@ -0,0 +1,134 @@
+export interface RawAuthor {
+    __typename?: string;
+    login: string;
+}
+interface RawSummaryComment {
+    id: string;
+    body: string;
+    isMinimized: boolean;
+    viewerDidAuthor?: boolean;
+    authorAssociation?: string;
+    url?: string;
+    author: RawAuthor | null;
+}
+interface SummaryConnection<T> {
+    totalCount: number;
+    pageInfo: {
+        hasPreviousPage: boolean;
+    };
+    nodes: T[];
+}
+type RawCheckContext = {
+    __typename: "CheckRun";
+    id?: string;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    detailsUrl?: string;
+    checkSuite: {
+        workflowRun: {
+            databaseId?: string | number;
+            event: string;
+            workflow?: {
+                name: string;
+                databaseId: string | number;
+            } | null;
+        } | null;
+    } | null;
+} | {
+    __typename: "StatusContext";
+    context: string;
+    state: string;
+};
+interface RawCheckRollup {
+    contexts: SummaryConnection<RawCheckContext>;
+}
+export interface RawSummaryPr {
+    number: number;
+    title: string;
+    url: string;
+    state: string;
+    isDraft: boolean;
+    viewerCanUpdate: boolean;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    mergeable: string;
+    mergeStateStatus: string;
+    reviewDecision: string | null;
+    reviewRequests?: {
+        nodes: Array<{
+            requestedReviewer: RawAuthor | null;
+        }>;
+    };
+    latestReviews?: {
+        nodes: Array<{
+            state: string;
+            author: RawAuthor | null;
+        }>;
+    };
+    isInMergeQueue: boolean;
+    mergeQueueEntry: {
+        headCommit: {
+            statusCheckRollup: RawCheckRollup | null;
+        } | null;
+    } | null;
+    stack: {
+        number: number;
+        size: number;
+        baseRefName: string;
+    } | null;
+    stackEntry: {
+        position: number;
+    } | null;
+    comments: SummaryConnection<RawSummaryComment>;
+    reviews: SummaryConnection<RawSummaryComment & {
+        state: string;
+    }>;
+    reviewThreads: SummaryConnection<{
+        id: string;
+        isResolved: boolean;
+        isOutdated: boolean;
+        path: string | null;
+        rootComments?: {
+            nodes: RawSummaryComment[];
+        };
+        comments: SummaryConnection<RawSummaryComment>;
+    }>;
+    commits: {
+        nodes: Array<{
+            commit: {
+                statusCheckRollup: RawCheckRollup | null;
+            };
+        }>;
+    };
+}
+export interface RawExplicitResponse {
+    repository: ({
+        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-raw.mjs

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+import { type SeenMarker } from "../state/seen-comments.mts";
+import type { PollSummaryReview } from "../types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+export declare function summarizePollSummaryReview(raw: RawSummaryPr, seen: Map<string, SeenMarker>, viewerCanAdminister: boolean): Promise<PollSummaryReview>;

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

@@ -0,0 +1,85 @@
+import { normalizeBotUsernames } from "../comments/authors.mjs";
+import { applyRules } from "../classify/apply.mjs";
+import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { getEffectiveCwd } from "../execution-context.mjs";
+import { classifyItem } from "../state/seen-comments.mjs";
+const THREAD_COMMENT_SEPARATOR = "\n\n--- thread comment ---\n\n";
+export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister) {
+    const config = loadConfig();
+    const bots = normalizeBotUsernames(config.botUsernames);
+    const rules = await loadRules(discoverRuleFiles(getEffectiveCwd()));
+    let actionable = 0;
+    let incomplete = raw.comments.pageInfo.hasPreviousPage ||
+        raw.reviews.pageInfo.hasPreviousPage ||
+        raw.reviewThreads.pageInfo.hasPreviousPage;
+    for (const comment of raw.comments.nodes) {
+        if (!comment.isMinimized &&
+            !isSuppressed(rules, "pr-comment", comment) &&
+            classifyItem(comment.id, comment.body, seen) !== "unchanged")
+            actionable += 1;
+    }
+    const latestStateByAuthor = new Map((raw.latestReviews?.nodes ?? []).flatMap((review) => review.author ? [[review.author.login.toLowerCase(), review.state]] : []));
+    for (const review of raw.reviews.nodes) {
+        if (review.state === "COMMENTED") {
+            if (review.body.trim() !== "" &&
+                !review.isMinimized &&
+                !isSuppressed(rules, "review-summary", review) &&
+                classifyItem(review.id, review.body, seen) !== "unchanged")
+                actionable += 1;
+            continue;
+        }
+        if (review.state !== "CHANGES_REQUESTED")
+            continue;
+        const login = review.author?.login.toLowerCase();
+        if (login && latestStateByAuthor.get(login) === "APPROVED")
+            continue;
+        if (isSuppressed(rules, "changes-requested", review))
+            continue;
+        const isBot = review.author?.__typename === "Bot" || bots.has(review.author?.login.toLowerCase() ?? "");
+        if ((isBot && viewerCanAdminister) ||
+            classifyItem(review.id, review.body, seen) !== "unchanged")
+            actionable += 1;
+    }
+    for (const thread of raw.reviewThreads.nodes) {
+        if (thread.comments.pageInfo.hasPreviousPage)
+            incomplete = true;
+        const root = thread.rootComments?.nodes[0] ?? thread.comments.nodes[0];
+        const transcript = thread.comments.nodes
+            .map((comment) => comment.body)
+            .join(THREAD_COMMENT_SEPARATOR);
+        if (isSuppressed(rules, "review-thread", root, thread.id, thread.path, transcript))
+            continue;
+        const repeatable = root?.viewerDidAuthor === true ||
+            root?.author?.__typename === "Bot" ||
+            bots.has(root?.author?.login.toLowerCase() ?? "");
+        const unseen = classifyItem(thread.id, transcript, seen) !== "unchanged";
+        if ((!thread.isResolved && (repeatable || unseen)) ||
+            ((thread.isResolved || thread.isOutdated) && unseen))
+            actionable += 1;
+    }
+    return {
+        ...(raw.comments.totalCount > 0 && { comments: raw.comments.totalCount }),
+        ...(raw.reviews.totalCount > 0 && { reviews: raw.reviews.totalCount }),
+        ...(raw.reviewThreads.totalCount > 0 && { threads: raw.reviewThreads.totalCount }),
+        ...(actionable > 0 && { actionable }),
+        ...(incomplete && { incomplete: true }),
+    };
+}
+function isSuppressed(rules, kind, raw, id = raw?.id ?? "unknown", path, body = raw?.body ?? "") {
+    const item = {
+        kind,
+        id,
+        author: raw?.author?.login ?? "unknown",
+        authorType: raw?.author?.__typename === "Bot"
+            ? "Bot"
+            : raw?.author?.__typename === "User"
+                ? "User"
+                : "Unknown",
+        ...(raw?.authorAssociation && { authorAssociation: raw.authorAssociation }),
+        body,
+        ...(raw?.url && { url: raw.url }),
+        ...(kind === "review-thread" && { path }),
+    };
+    return applyRules(rules, item).suppress === true;
+}

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

@@ -0,0 +1,4 @@
+import type { PollSummaryChecks, PollSummaryCommandOptions, PollSummaryItem, PollSummaryReview } from "../types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+export declare function routePollSummary(raw: RawSummaryPr, checks: PollSummaryChecks, review: PollSummaryReview, opts: PollSummaryCommandOptions): Pick<PollSummaryItem, "action" | "reasons">;
+export declare function normalizePollSummaryState(state: string): PollSummaryItem["state"];

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

@@ -0,0 +1,47 @@
+import { loadConfig } from "../config/load.mjs";
+export function routePollSummary(raw, checks, review, opts) {
+    const actions = loadConfig().actions;
+    const state = normalizePollSummaryState(raw.state);
+    if (state === "MERGED" || state === "CLOSED") {
+        return { action: "cancel", reasons: [state.toLowerCase()] };
+    }
+    if (raw.mergeable === "CONFLICTING" || raw.mergeStateStatus === "DIRTY") {
+        return { action: "fix_code", reasons: ["merge-conflicts"] };
+    }
+    if ((checks.failing ?? 0) > 0)
+        return { action: "fix_code", reasons: ["failing-checks"] };
+    if ((review.actionable ?? 0) > 0) {
+        if (opts.merge && raw.isInMergeQueue && actions.workWhileQueued !== true) {
+            return { action: "wait", reasons: ["review-work-deferred-while-queued"] };
+        }
+        return { action: "fix_code", reasons: ["review-work"] };
+    }
+    if ((checks.inProgress ?? 0) > 0 ||
+        raw.mergeable === "UNKNOWN" ||
+        raw.mergeStateStatus === "UNKNOWN" ||
+        raw.mergeStateStatus === "BEHIND" ||
+        raw.mergeStateStatus === "BLOCKED" ||
+        raw.mergeStateStatus === "HAS_HOOKS") {
+        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"] };
+        }
+        return raw.viewerCanUpdate
+            ? { action: "mark_ready", reasons: ["draft-appears-ready"] }
+            : { action: "escalate", reasons: ["mark-ready-authorization-required"] };
+    }
+    if (opts.merge && raw.isInMergeQueue) {
+        return { action: "wait", reasons: ["already-in-merge-queue"] };
+    }
+    if (opts.merge && raw.stack) {
+        return { action: "fix_code", reasons: ["authoritative-poll-required"] };
+    }
+    if (opts.merge && !raw.stack)
+        return { action: "merge", reasons: ["appears-ready"] };
+    return { action: "cancel", reasons: ["appears-ready"] };
+}
+export function normalizePollSummaryState(state) {
+    return state === "OPEN" || state === "CLOSED" || state === "MERGED" ? state : "UNKNOWN";
+}

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

@@ -0,0 +1,7 @@
+import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection } from "../types.mts";
+import { type RepoInfo } from "./client.mts";
+export interface FetchedPollSummary {
+    selection: PollSummarySelection;
+    prs: PollSummaryItem[];
+}
+export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;

package/bin/github/poll-summary.mjs

@@ -0,0 +1,110 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
+import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
+const MAX_EXPLICIT_PRS_PER_QUERY = 50;
+export async function fetchPollSummary(opts, repo) {
+    if (opts.stackPrNumber !== undefined)
+        return fetchStackSummary(opts, repo);
+    const requested = deduplicate(opts.prNumbers ?? []);
+    if (requested.length === 0) {
+        throw new ShepherdError("Aggregate poll requires at least two PRs or --stack <PR>", EXIT.USAGE);
+    }
+    const raw = [];
+    let viewerCanAdminister = false;
+    for (let offset = 0; offset < requested.length; offset += MAX_EXPLICIT_PRS_PER_QUERY) {
+        const chunk = requested.slice(offset, offset + MAX_EXPLICIT_PRS_PER_QUERY);
+        const fetched = await fetchExplicitChunk(chunk, repo);
+        viewerCanAdminister = fetched.viewerCanAdminister;
+        raw.push(...fetched.prs);
+    }
+    return {
+        selection: { kind: "prs", requested },
+        prs: await Promise.all(raw.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
+    };
+}
+async function fetchExplicitChunk(prs, repo) {
+    const declarations = prs.map((_, index) => `$pr${index}: Int!`).join(", ");
+    const aliases = prs
+        .map((_, index) => `pr${index}: pullRequest(number: $pr${index}) { ...PollSummaryPr }`)
+        .join("\n");
+    const query = `${POLL_SUMMARY_FRAGMENT}\nquery PollSummary($owner: String!, $repo: String!, ${declarations}) {\n  _shepherdRateLimit: rateLimit { cost limit nodeCount remaining resetAt used }\n  repository(owner: $owner, name: $repo) {\n    viewerCanAdminister\n    ${aliases}\n  }\n}`;
+    const variables = Object.fromEntries(prs.map((pr, index) => [`pr${index}`, pr]));
+    const result = await graphqlWithRateLimit(query, {
+        owner: repo.owner,
+        repo: repo.name,
+        ...variables,
+    });
+    if (!result.data.repository)
+        throw missingRepository(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;
+    });
+    return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
+}
+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);
+    return {
+        selection: { kind: "stack", anchor, stackNumber, stackSize },
+        prs: await Promise.all(ordered.map((entry) => summarizePollSummaryPr(entry.pullRequest, repo, opts, viewerCanAdminister))),
+    };
+}
+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

@@ -12,6 +12,10 @@ export declare const BATCH_PR_QUERY: string;
 export declare const BATCH_PR_PAGE_QUERY: string;
 /** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
 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;
+/** Discovers and summarizes every entry in one native GitHub pull-request stack. */
+export declare const POLL_STACK_SUMMARY_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,6 +16,10 @@ 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"));
+/** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
+export const POLL_SUMMARY_FRAGMENT = gql("poll-summary-fragment.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")}`;
 /** 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/mcp/server.mjs

@@ -3,9 +3,10 @@ import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
-import { isRepositoryQualifiedPrReference } from "../pr-reference.mjs";
+import { isRepositoryQualifiedPrReference, normalizeRepositoryIdentity, parsePrReference, } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
 import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
+import { formatPollSummaryResult } from "../cli/poll-summary-formatter.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
@@ -14,8 +15,11 @@ const pr = z
     .refine(isRepositoryQualifiedPrReference, { message: QUALIFIED_PR_ERROR })
     .describe("GitHub pull-request URL or owner/repo#number; the explicit repository may differ from the server working directory");
 const ids = z.array(z.string().min(1)).optional();
-const iterateInputSchema = z.object({
-    pr,
+const iterateInputSchema = z
+    .object({
+    pr: pr.optional(),
+    prs: z.array(pr).min(1).optional(),
+    stack: pr.optional(),
     readyDelaySeconds: z.number().nonnegative().optional(),
     stallTimeoutSeconds: z.number().nonnegative().optional(),
     noAutoMarkReady: z.boolean().optional(),
@@ -28,7 +32,12 @@ const iterateInputSchema = z.object({
         .array(z.string())
         .optional()
         .describe("Deprecated per-call no-op retained for compatibility."),
-});
+})
+    .refine((input) => [input.pr, input.prs, input.stack].filter((value) => value !== undefined).length === 1, {
+    message: "exactly one of pr, prs, or stack is required",
+})
+    .refine((input) => !input.prs ||
+    new Set(input.prs.map((ref) => normalizeRepositoryIdentity(parsePrReference(ref)?.repository ?? ""))).size === 1, { message: "all prs must belong to the same repository" });
 const reviewMutationsOperationSchema = z.object({
     type: z.literal("review_mutations"),
     resolveThreadIds: ids,
@@ -80,7 +89,7 @@ export function createPrShepherdMcpServer(options = {}) {
     const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
     server.registerTool("iterate", {
-        description: "Inspect the specified pull request and return the next Shepherd state.",
+        description: "Inspect one pull request, an explicit same-repository set, or a native stack and return one Shepherd tick.",
         inputSchema: iterateInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -93,7 +102,9 @@ export function createPrShepherdMcpServer(options = {}) {
         const opts = {
             readyDelaySuffix: input.readyDelaySeconds === undefined ? undefined : `${input.readyDelaySeconds}s`,
         };
-        return runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), (result) => formatIterateResult(result, opts), (result) => projectIterateLean(result, opts));
+        return runTool(() => runIterateSelector(shepherd, requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
+            ? formatPollSummaryResult(result)
+            : formatIterateResult(result, opts), (result) => isPollSummary(result) ? result : projectIterateLean(result, opts));
     });
     server.registerTool("apply", {
         description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
@@ -127,6 +138,28 @@ export function createPrShepherdMcpServer(options = {}) {
     }, async (input) => runTool(() => shepherd.buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
     return server;
 }
+function runIterateSelector(shepherd, input) {
+    return "prs" in input || "stack" in input
+        ? shepherd.iterate(input)
+        : shepherd.iterate(input);
+}
+function requireRepositoryQualifiedIterate(input) {
+    if ([input.pr, input.prs, input.stack].filter((value) => value !== undefined).length !== 1) {
+        throw new PrShepherdValidationError("exactly one of pr, prs, or stack is required");
+    }
+    const refs = Array.isArray(input.prs) ? input.prs : [input.pr ?? input.stack];
+    if (refs.length === 0 || refs.some((ref) => !isRepositoryQualifiedPrReference(ref))) {
+        throw new PrShepherdValidationError(QUALIFIED_PR_ERROR);
+    }
+    const repositories = new Set(refs.map((ref) => normalizeRepositoryIdentity(parsePrReference(ref)?.repository ?? "")));
+    if (repositories.size !== 1) {
+        throw new PrShepherdValidationError("all prs must belong to the same repository");
+    }
+    return input;
+}
+function isPollSummary(result) {
+    return "mode" in result && result.mode === "summary";
+}
 function requireRepositoryQualifiedPr(input) {
     if (!isRepositoryQualifiedPrReference(input.pr)) {
         throw new PrShepherdValidationError(QUALIFIED_PR_ERROR);

package/bin/pr-reference.d.mts

@@ -18,3 +18,5 @@ export declare function resolveParsedPrTarget(parsed: ParsedPrReference): Resolv
 /** Canonical collision-safe PR reference for generated commands and escalation messages. */
 export declare function formatPrUrl(repository: string, prNumber: number): string;
 export declare function isRepositoryQualifiedPrReference(pr: unknown): pr is string;
+/** GitHub owner and repository names are case-insensitive. */
+export declare function normalizeRepositoryIdentity(repository: string): string;

package/bin/pr-reference.mjs

@@ -56,3 +56,7 @@ export function isRepositoryQualifiedPrReference(pr) {
         return false;
     return parsePrReference(pr)?.repository !== undefined;
 }
+/** GitHub owner and repository names are case-insensitive. */
+export function normalizeRepositoryIdentity(repository) {
+    return repository.toLowerCase();
+}