pr-shepherd 0.47.0 → 0.49.0

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();
+}

package/bin/quota-warning.mjs

@@ -2,5 +2,5 @@ export function buildQuotaAwareContinuation(warning, prefix) {
     const interval = `${warning.pollIntervalMinutes}m`;
     const timeout = `${warning.pollTimeoutMinutes}m`;
     const resetTime = new Date(warning.resetAt * 1000).toISOString();
-    return `${prefix} 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. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, replace any existing interval and timeout flags with \`--interval ${interval} --timeout ${timeout}\`, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
+    return `${prefix} 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. Do not substitute \`gh pr checks\` or \`gh pr watch\` for the Shepherd loop. Resume full-cadence pr-shepherd after the GraphQL quota resets at ${resetTime}. If you must keep polling before then, poll no more often than every ${warning.pollIntervalMinutes} minutes. With a polling CLI command, preserve the other options, raise any shorter interval and timeout flags to at least \`--interval ${interval} --timeout ${timeout}\`, keep any longer cadence, and omit \`--timeout\` when using \`--until-terminal\`. With a single-tick CLI, API, or MCP call, wait at least ${warning.pollIntervalMinutes} minutes before the next tick.`;
 }

package/bin/types/iterate.d.mts

@@ -153,10 +153,10 @@ export interface IterateCommandOptions extends GlobalOptions {
     /** Shepherd through readiness and emit the exact merge/queue command when ready. */
     merge?: boolean;
     /**
-     * Internal. Defers attaching a quota warning until an until-terminal poll actually
-     * breaks. Set only by `runPollCore`; excluded from the public `IterateInput` in
-     * api.mts.
+     * Internal. Defers quota warnings until an until-terminal poll breaks. Set only by
+     * `runPollCore`; excluded from the public `IterateInput` in api.mts.
      */
     deferQuotaWarning?: boolean;
+    quotaWarningMinimumPollIntervalMinutes?: number;
 }
 export {};

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

@@ -0,0 +1,82 @@
+import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
+import type { MergeableState, MergeStateStatus, ReviewDecision } from "./github.mts";
+import type { ShepherdAction } from "./iterate.mts";
+export interface PollSummaryChecks {
+    passing?: number;
+    failing?: number;
+    inProgress?: number;
+    skipped?: number;
+    filtered?: number;
+    ignored?: number;
+    superseded?: number;
+    incomplete?: true;
+}
+export interface PollSummaryReview {
+    comments?: number;
+    reviews?: number;
+    threads?: number;
+    actionable?: number;
+    incomplete?: true;
+}
+interface PollSummaryStack {
+    number: number;
+    size: number;
+    position: number;
+    baseRefName: string;
+}
+export interface PollSummaryItem {
+    pr: number;
+    repo: string;
+    title: string;
+    url: string;
+    /** Conservative routing hint; the selected one-PR poll makes the authoritative decision. */
+    action: ShepherdAction;
+    reasons: string[];
+    state: "OPEN" | "CLOSED" | "MERGED" | "UNKNOWN";
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+    reviewDecision?: ReviewDecision;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    isDraft?: true;
+    isInMergeQueue?: true;
+    blockingReviewerInProgress?: true;
+    remainingSeconds?: number;
+    checks?: PollSummaryChecks;
+    review?: PollSummaryReview;
+    stack?: PollSummaryStack;
+    pollCommand?: string;
+}
+export type PollSummarySelection = {
+    kind: "prs";
+    requested: number[];
+} | {
+    kind: "stack";
+    anchor: number;
+    stackNumber: number;
+    stackSize: number;
+};
+export interface PollSummaryResult {
+    mode: "summary";
+    repo: string;
+    selection: PollSummarySelection;
+    reason: "actionable" | "all_terminal" | "waiting" | "timeout";
+    prs: PollSummaryItem[];
+    apiUsage?: ApiUsage;
+    quotaWarning?: GraphqlQuotaWarning;
+}
+export interface PollSummaryCommandOptions {
+    prNumbers?: number[];
+    stackPrNumber?: number;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
+    merge?: boolean;
+    readyDelaySeconds?: number;
+    stallTimeoutSeconds?: number;
+    noAutoMarkReady?: boolean;
+    noAutoCancelActionable?: boolean;
+}
+export {};

package/bin/types/poll-summary.mjs

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

package/bin/types.d.mts

@@ -13,3 +13,4 @@ export * from "./types/merge-action.mts";
 export * from "./types/escalate.mts";
 export * from "./types/merge-queue.mts";
 export * from "./types/api-usage.mts";
+export * from "./types/poll-summary.mts";

package/bin/types.mjs

@@ -13,3 +13,4 @@ export * from "./types/merge-action.mjs";
 export * from "./types/escalate.mjs";
 export * from "./types/merge-queue.mjs";
 export * from "./types/api-usage.mjs";
+export * from "./types/poll-summary.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.47.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.49.0", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.47.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.49.0", "pr-shepherd-mcp"]
   }
 }

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -18,9 +18,9 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 ## Arguments: $ARGUMENTS
 
-1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL and an optional `--merge` flag from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
+1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
 
-2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the canonical poll command `pr-shepherd [PR] --until-terminal`, omitting `[PR]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; it returns for agent-facing work (including an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation), a quota warning, `[CANCEL]`, or `[ESCALATE]`. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference, plus `merge: true` when `--merge` was supplied, and print its full result.
+2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return when any row needs work or all rows are terminal. It also returns for a quota warning or an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when `--merge` was supplied, and print its full result.
 
 3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.