pr-shepherd 0.54.0 → 0.55.0

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

@@ -0,0 +1,51 @@
+import { loadConfig } from "../config/load.mjs";
+import { actionsWorkflowInProgress, selectMergeTargetContexts, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+/** Required contexts from the open layer whose base is the stack trunk. */
+export function trunkRequiredContexts(ordered) {
+    const trunk = ordered.find((pr) => pr.stack)?.stack?.baseRefName;
+    if (!trunk)
+        return undefined;
+    const bottom = ordered.find((pr) => pr.state === "OPEN" && pr.baseRefName === trunk);
+    if (!bottom)
+        return undefined;
+    return parseBranchRules(bottom.baseRef).requiredStatusCheckContexts;
+}
+/** Record missing required contexts. A running Actions workflow does not clear the names. */
+export function applyUnreportedRequiredChecks(raw, checks, mergeTargetContexts) {
+    const trunk = raw.stack?.baseRefName;
+    const required = selectMergeTargetContexts({
+        localContexts: parseBranchRules(raw.baseRef).requiredStatusCheckContexts,
+        ...(mergeTargetContexts !== undefined && { trunkContexts: mergeTargetContexts }),
+        baseRefName: raw.baseRefName,
+        ...(trunk !== undefined && mergeTargetContexts !== undefined && { trunkRefName: trunk }),
+    });
+    const missing = unreportedRequiredContexts(required, reportedNames(raw));
+    if (missing.length === 0)
+        return;
+    checks.unreportedRequired = missing;
+    const suites = raw.commits.nodes[0]?.commit.checkSuites?.nodes ?? [];
+    if (actionsWorkflowInProgress(suites, new Set(loadConfig().checks.ciTriggerEvents))) {
+        checks.actionsWorkflowInProgress = true;
+    }
+}
+function reportedNames(raw) {
+    const names = new Set();
+    const rollups = [
+        raw.commits.nodes[0]?.commit.statusCheckRollup,
+        raw.mergeQueueEntry?.headCommit?.statusCheckRollup,
+    ];
+    for (const rollup of rollups) {
+        for (const node of rollup?.contexts.nodes ?? []) {
+            if (!node)
+                continue;
+            const name = node.__typename === "CheckRun" ? node.name : node.context;
+            if (typeof name !== "string")
+                continue;
+            const trimmed = name.trim();
+            if (trimmed)
+                names.add(trimmed);
+        }
+    }
+    return names;
+}

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

@@ -5,6 +5,7 @@ export interface FetchedPollSummary {
     selection: PollSummarySelection;
     prs: PollSummaryItem[];
     stackAncestry?: PollSummaryStackAncestry[];
+    allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
 }
 export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;
 /** Fresh, read-only snapshot used to bind a one-PR READY receipt to stack routing. */

package/bin/github/poll-summary.mjs

@@ -1,8 +1,9 @@
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
-import { missingRepositoryError } from "./errors.mjs";
+import { GitHubRequestError, isRetryableGraphQlResourceLimit, missingRepositoryError, } from "./errors.mjs";
 import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
+import { trunkRequiredContexts } from "./poll-summary-unreported.mjs";
 import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
 import { MAX_STACK_ENTRIES_PER_PAGE, readStack, readStackTopology, stackAncestryGaps, } from "./stack-read.mjs";
 const MAX_EXPLICIT_PRS_PER_QUERY = 50;
@@ -62,16 +63,40 @@ async function fetchExplicitChunk(prs, repo) {
 async function fetchStackSummary(opts, repo) {
     const anchor = opts.stackPrNumber;
     const topology = await readStackTopology(anchor, repo);
-    const { stackNumber, stackSize, viewerCanAdminister, ordered } = await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first: Math.min(topology.stackSize, MAX_STACK_ENTRIES_PER_PAGE) });
+    const { stackNumber, stackSize, viewerLogin, viewerCanAdminister, ordered, allowedMergeMethods } = await readStackSummary(anchor, repo, topology.stackSize);
     for (const pr of ordered)
         await hydratePollSummaryChecks(pr, repo);
     const stackAncestry = stackAncestryGaps(ordered);
+    const required = trunkRequiredContexts(ordered);
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
-        prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
+        prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin))),
         ...(stackAncestry.length > 0 && { stackAncestry }),
+        ...(allowedMergeMethods && { allowedMergeMethods }),
     };
 }
+/**
+ * A wide check matrix can blow GitHub's per-query resource limit on the full
+ * page. Halve `first` down to one entry and let `readStack` follow `after`.
+ * The shared summary fragment stays intact: one layer is the same shape as an
+ * explicit summary, and check hydration still completes windows past 100.
+ */
+async function readStackSummary(anchor, repo, stackSize) {
+    let first = Math.min(stackSize, MAX_STACK_ENTRIES_PER_PAGE);
+    for (;;) {
+        try {
+            return await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first });
+        }
+        catch (err) {
+            if (!(err instanceof GitHubRequestError) ||
+                !isRetryableGraphQlResourceLimit(err.graphqlErrors) ||
+                first <= 1) {
+                throw err;
+            }
+            first = Math.floor(first / 2);
+        }
+    }
+}
 function deduplicate(values) {
     return [...new Set(values)];
 }

package/bin/github/queries.d.mts

@@ -14,15 +14,27 @@ 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;
+/** Trunk branch rules plus how far `headRef` is behind that branch. */
+export declare const REF_RULES_QUERY: string;
 /**
  * Pages older status contexts for one commit with the same node selection as
  * the compact summary, so hydrated and first-page nodes fingerprint alike.
  */
 export declare const POLL_SUMMARY_CHECK_PAGE_QUERY: string;
+/**
+ * Annotation totals for one commit, used only when a summary layer otherwise
+ * looks ready. `$before` pages older than the newest 100 contexts.
+ */
+export declare const POLL_SUMMARY_ANNOTATION_PROBE_QUERY: string;
 /** Discovers and summarizes every entry in one native GitHub pull-request stack. */
 export declare const POLL_STACK_SUMMARY_QUERY: string;
 /** Reads only native-stack membership and the refs that link adjacent entries. */
 export declare const POLL_STACK_TOPOLOGY_QUERY: string;
+/**
+ * Whether a conflicting upper stack layer already contains its PR base, plus
+ * the open stack entries needed to name the bottom layer. Not part of BatchPr.
+ */
+export declare const UPPER_LAYER_CONFLICT_TARGET_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

@@ -9,7 +9,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8");
-const withSharedFragments = (query) => `${gql("pr-merge-policy.gql")}\n${gql("commit-check-suites.gql")}\n${query}`;
+const withSharedFragments = (query) => `${gql("ref-rules.gql")}\n${gql("pr-merge-policy.gql")}\n${gql("commit-check-suites.gql")}\n${query}`;
 /** The primary batch query that fetches CI + comments + merge status in one round-trip. */
 export const BATCH_PR_QUERY = withSharedFragments(gql("batch-pr.gql"));
 /** Slim @include follow-up for outstanding batch-query connections. */
@@ -18,16 +18,28 @@ export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
 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 = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
+export const POLL_SUMMARY_FRAGMENT = `${gql("ref-rules.gql")}\n${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-fragment.gql")}`;
+/** 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")}`;
 /**
  * Pages older status contexts for one commit with the same node selection as
  * the compact summary, so hydrated and first-page nodes fingerprint alike.
  */
 export const POLL_SUMMARY_CHECK_PAGE_QUERY = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAGMENT}\n${gql("poll-summary-check-page.gql")}`;
+/**
+ * Annotation totals for one commit, used only when a summary layer otherwise
+ * looks ready. `$before` pages older than the newest 100 contexts.
+ */
+export const POLL_SUMMARY_ANNOTATION_PROBE_QUERY = gql("poll-summary-annotation-probe.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")}`;
 /** Reads only native-stack membership and the refs that link adjacent entries. */
 export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
+/**
+ * Whether a conflicting upper stack layer already contains its PR base, plus
+ * the open stack entries needed to name the bottom layer. Not part of BatchPr.
+ */
+export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-target.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/github/queue-removal-freshness.d.mts

@@ -1,16 +1,31 @@
+type PushCheckNode = {
+    __typename?: string;
+    checkSuite?: {
+        createdAt?: string | null;
+        workflowRun?: {
+            event?: string | null;
+            createdAt?: string | null;
+        } | null;
+    } | null;
+};
 /**
  * Whether a removed merge-queue commit still belongs to the current PR head.
  *
  * A merge-commit queue lists that head as a parent. Squash and rebase queues
- * build a one-parent commit on the base (or on the previous group commit), so
- * the PR head is not an ancestor. Missing parents are unverifiable: GitHub
- * keeps returning the latest removal after the synthetic commit is gone.
- * A one-parent removal is stale when the current head's committer time is
- * later than the removal, which is a push after the ejection.
+ * build a one-parent commit on the base, so parent identity cannot show a
+ * later push. Missing parents are unverifiable: GitHub keeps returning the
+ * latest removal after the synthetic commit is gone. A one-parent removal is
+ * stale once this head reached the PR after the removal. That time is the
+ * earliest pull_request check on the head, with the head's committer time as
+ * the fallback when no check time is available.
  */
 export declare function queueRemovalAppliesToHead(input: {
     parentOids: readonly string[] | null | undefined;
     headOid: string;
     headCommittedAtUnix?: number;
+    headPushedAtUnix?: number;
     removedAtUnix?: number;
 }): boolean;
+/** Earliest pull_request check-suite time on the head commit, when one exists. */
+export declare function headPushUnixFromCheckNodes(nodes: readonly (PushCheckNode | null)[] | null | undefined): number | undefined;
+export {};

package/bin/github/queue-removal-freshness.mjs

@@ -1,12 +1,15 @@
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
+const PULL_REQUEST_EVENTS = new Set(["pull_request", "pull_request_target"]);
 /**
  * Whether a removed merge-queue commit still belongs to the current PR head.
  *
  * A merge-commit queue lists that head as a parent. Squash and rebase queues
- * build a one-parent commit on the base (or on the previous group commit), so
- * the PR head is not an ancestor. Missing parents are unverifiable: GitHub
- * keeps returning the latest removal after the synthetic commit is gone.
- * A one-parent removal is stale when the current head's committer time is
- * later than the removal, which is a push after the ejection.
+ * build a one-parent commit on the base, so parent identity cannot show a
+ * later push. Missing parents are unverifiable: GitHub keeps returning the
+ * latest removal after the synthetic commit is gone. A one-parent removal is
+ * stale once this head reached the PR after the removal. That time is the
+ * earliest pull_request check on the head, with the head's committer time as
+ * the fallback when no check time is available.
  */
 export function queueRemovalAppliesToHead(input) {
     const parents = input.parentOids ?? [];
@@ -16,11 +19,35 @@ export function queueRemovalAppliesToHead(input) {
         return true;
     if (parents.length > 1)
         return false;
-    if (input.headCommittedAtUnix !== undefined &&
-        input.removedAtUnix !== undefined &&
-        input.removedAtUnix > 0 &&
-        input.headCommittedAtUnix > input.removedAtUnix) {
+    const removedAt = input.removedAtUnix;
+    if (removedAt === undefined || removedAt <= 0)
+        return true;
+    const pushedAt = input.headPushedAtUnix;
+    if (pushedAt !== undefined && pushedAt > 0)
+        return pushedAt <= removedAt;
+    const committedAt = input.headCommittedAtUnix;
+    if (committedAt !== undefined && committedAt > removedAt)
         return false;
-    }
     return true;
 }
+/** Earliest pull_request check-suite time on the head commit, when one exists. */
+export function headPushUnixFromCheckNodes(nodes) {
+    let earliest;
+    for (const node of nodes ?? []) {
+        if (node?.__typename !== "CheckRun")
+            continue;
+        const run = node.checkSuite?.workflowRun;
+        const event = run?.event;
+        if (event == null || !PULL_REQUEST_EVENTS.has(event))
+            continue;
+        const raw = node.checkSuite?.createdAt || run?.createdAt;
+        if (!raw)
+            continue;
+        const at = parseCreatedAt(raw);
+        if (at <= 0)
+            continue;
+        if (earliest === undefined || at < earliest)
+            earliest = at;
+    }
+    return earliest;
+}

package/bin/github/stack-read.d.mts

@@ -1,3 +1,4 @@
+import { type MergeMethod } from "../config/merge-method.mts";
 import type { PollSummaryStackAncestry } from "../types.mts";
 import { type RepoInfo } from "./client.mts";
 /** GitHub's `first` ceiling for one native-stack entries page. */
@@ -15,9 +16,12 @@ export interface StackMemberRefs {
 export interface StackRead<Pr extends StackMemberRefs> {
     stackNumber: number;
     stackSize: number;
+    viewerLogin: string | null;
     viewerCanAdminister: boolean;
     /** Every member, bottom-to-top, each observed in the same paged read. */
     ordered: Pr[];
+    /** Present when the query selected repository merge settings, including an empty list. */
+    allowedMergeMethods?: MergeMethod[];
 }
 /**
  * Page through one native stack and fail closed on anything short of the full

package/bin/github/stack-read.mjs

@@ -1,3 +1,4 @@
+import { readAllowedMergeMethods } from "../config/merge-method.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { missingRepositoryError } from "./errors.mjs";
@@ -15,13 +16,17 @@ export async function readStack(query, anchor, repo, variables = {}) {
     let stackNumber = 0;
     let stackSize = 0;
     let viewerCanAdminister = false;
+    let viewerLogin = null;
+    let allowedMergeMethods;
     const entries = [];
     do {
         const response = await graphqlWithRateLimit(query, { owner: repo.owner, repo: repo.name, anchor, after, ...variables });
+        viewerLogin = response.data.viewer?.login ?? viewerLogin;
         const repository = response.data.repository;
         if (!repository)
             throw missingRepositoryError(repo);
         viewerCanAdminister = repository.viewerCanAdminister;
+        allowedMergeMethods = readAllowedMergeMethods(repository) ?? allowedMergeMethods;
         if (!repository.pullRequest) {
             throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
         }
@@ -59,7 +64,14 @@ export async function readStack(query, anchor, repo, variables = {}) {
     const ordered = [...unique.values()]
         .sort((left, right) => left.position - right.position)
         .map((entry) => entry.pullRequest);
-    return { stackNumber, stackSize, viewerCanAdminister, ordered };
+    return {
+        stackNumber,
+        stackSize,
+        viewerLogin,
+        viewerCanAdminister,
+        ordered,
+        ...(allowedMergeMethods && { allowedMergeMethods }),
+    };
 }
 /** Membership and linking refs only — no per-PR CI or review hydration. */
 export function readStackTopology(anchor, repo) {

package/bin/mcp/server.mjs

@@ -7,6 +7,7 @@ import { isRepositoryQualifiedPrReference, normalizeRepositoryIdentity, parsePrR
 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 { projectStackOverview } from "../cli/stack-overview.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";
@@ -104,7 +105,11 @@ export function createPrShepherdMcpServer(options = {}) {
         };
         return runTool(() => runIterateSelector(shepherd, requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
             ? formatPollSummaryResult(result)
-            : formatIterateResult(result, opts), (result) => isPollSummary(result) ? result : projectIterateLean(result, opts));
+            : formatIterateResult(result, opts), (result) => isPollSummary(result)
+            ? result.selection.kind === "stack"
+                ? projectStackOverview(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.",

package/bin/state/ci-retrigger.d.mts

@@ -0,0 +1,25 @@
+/**
+ * One close/reopen of a head that was missing required checks.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/ci-retrigger.json`
+ * Reopening does not change the head SHA, so the next tick must not close the PR again.
+ */
+interface Retrigger {
+    headSha: string;
+    contexts: string[];
+}
+/** The stored head and context set, or undefined when no usable marker exists. */
+export declare function readCiRetrigger(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}): Promise<Retrigger | undefined>;
+/** Remember that this head was already closed and reopened for these contexts. */
+export declare function writeCiRetrigger(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, record: Retrigger): Promise<void>;
+/** True when this head was already retriggered for the same required contexts. */
+export declare function sameCiRetrigger(record: Retrigger | undefined, headSha: string, contexts: readonly string[]): boolean;
+export {};

package/bin/state/ci-retrigger.mjs

@@ -0,0 +1,48 @@
+/**
+ * One close/reopen of a head that was missing required checks.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/ci-retrigger.json`
+ * Reopening does not change the head SHA, so the next tick must not close the PR again.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+/** The stored head and context set, or undefined when no usable marker exists. */
+export async function readCiRetrigger(key) {
+    return readRetrigger(resolvePrStatePath(key, "ci-retrigger.json"));
+}
+/** Remember that this head was already closed and reopened for these contexts. */
+export async function writeCiRetrigger(key, record) {
+    const path = resolvePrStatePath(key, "ci-retrigger.json");
+    await mkdir(dirname(path), { recursive: true });
+    const next = {
+        headSha: record.headSha,
+        contexts: [...record.contexts].sort(),
+    };
+    await writeFile(path, JSON.stringify(next));
+}
+/** True when this head was already retriggered for the same required contexts. */
+export function sameCiRetrigger(record, headSha, contexts) {
+    if (!record || record.headSha !== headSha)
+        return false;
+    const stored = [...record.contexts].sort();
+    const current = [...contexts].sort();
+    return stored.length === current.length && stored.every((name, index) => name === current[index]);
+}
+async function readRetrigger(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return undefined;
+        const headSha = parsed.headSha;
+        const contexts = parsed.contexts;
+        if (typeof headSha !== "string" || !Array.isArray(contexts))
+            return undefined;
+        if (!contexts.every((name) => typeof name === "string"))
+            return undefined;
+        return { headSha, contexts };
+    }
+    catch {
+        return undefined;
+    }
+}

package/bin/state/conflicting-head-seen.d.mts

@@ -0,0 +1,13 @@
+/**
+ * When Shepherd first saw a conflicting head that had no CI.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/conflicting-head.json`
+ * GitHub's Commit object has no push timestamp, so the missing-CI grace
+ * starts at this observation instead of `committedDate`.
+ */
+/** Unix seconds of the first observation of `headSha`, or undefined when state cannot be used. */
+export declare function conflictingHeadFirstSeenUnix(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, headSha: string, nowMs: number): Promise<number | undefined>;

package/bin/state/conflicting-head-seen.mjs

@@ -0,0 +1,44 @@
+/**
+ * When Shepherd first saw a conflicting head that had no CI.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/conflicting-head.json`
+ * GitHub's Commit object has no push timestamp, so the missing-CI grace
+ * starts at this observation instead of `committedDate`.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+/** Unix seconds of the first observation of `headSha`, or undefined when state cannot be used. */
+export async function conflictingHeadFirstSeenUnix(key, headSha, nowMs) {
+    const nowUnix = Math.floor(nowMs / 1000);
+    try {
+        const path = resolvePrStatePath(key, "conflicting-head.json");
+        const existing = await readSeen(path);
+        if (existing?.headSha === headSha)
+            return existing.firstSeenAtUnix;
+        await mkdir(dirname(path), { recursive: true });
+        const next = { headSha, firstSeenAtUnix: nowUnix };
+        await writeFile(path, JSON.stringify(next));
+        return nowUnix;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readSeen(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return undefined;
+        const headSha = parsed.headSha;
+        const firstSeenAtUnix = parsed.firstSeenAtUnix;
+        if (typeof headSha !== "string" || typeof firstSeenAtUnix !== "number")
+            return undefined;
+        if (!Number.isFinite(firstSeenAtUnix))
+            return undefined;
+        return { headSha, firstSeenAtUnix };
+    }
+    catch {
+        return undefined;
+    }
+}

package/bin/types/escalate.d.mts

@@ -2,7 +2,7 @@ import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;

package/bin/types/github.d.mts

@@ -108,6 +108,8 @@ export interface Review {
     staleBotCr?: boolean;
     /** Commit OID the review was made against, when available from GraphQL. */
     commitOid?: string;
+    /** Review HTML URL, when the batch query selected it. */
+    url?: string;
     /** True when commitOid !== headRefOid AND all associated threads are resolved/outdated. Distinct from `staleBotCr` (time-based). Reviews with no threads are not marked stale. */
     staleReview?: boolean;
 }
@@ -139,10 +141,17 @@ export interface BatchPrData extends BatchPrMergeFields {
     mergeStateStatus: MergeStateStatus;
     reviewDecision: ReviewDecision;
     headRefOid: string;
+    /**
+     * Earliest pull_request check-suite time on the head commit. Omitted when
+     * that signal is unavailable; queue-removal freshness then uses committer time.
+     */
+    headPushedAtUnix?: number;
     headRefName: string;
     /** `"owner/name"` of the head repository; null when the fork has been deleted. */
     headRepoWithOwner: string | null;
     viewerAuthorization?: ViewerAuthorization;
+    /** GitHub `viewer.login` for the token that fetched this batch. */
+    viewerLogin?: string;
     baseRefName: string;
     /** Base commit GitHub recorded for this PR (`PullRequest.baseRefOid`), not the branch's live tip. */
     baseRefOid?: string;
@@ -164,6 +173,8 @@ export interface BatchPrData extends BatchPrMergeFields {
     removedMergeQueueChecks?: CheckRun[];
     removedMergeQueueChecksIncomplete?: true;
     branchProtection: BranchProtection | null;
+    /** Repository merge methods. Omitted when the batch did not select them. Empty when none are enabled. */
+    allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
     activity?: PrActivitySummary;
 }
 export {};

package/bin/types/iterate.d.mts

@@ -1,4 +1,4 @@
-import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment } from "./report.mts";
+import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment, RuleAutoResolveReport } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
 import type { BranchProtection, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
 import type { MergeRequirements, StackDraftHold } from "./merge-requirements.mts";
@@ -6,7 +6,7 @@ import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
 import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
-export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
+export type ShepherdAction = "wait" | "ready" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
 export interface IterateResultSummary {
     passing: number;
     skipped: number;
@@ -29,6 +29,11 @@ export interface IterateResultBase {
     summary: IterateResultSummary;
     /** Validated base branch (e.g. "main") for this PR. */
     baseBranch: string;
+    /**
+     * Set when a native-stack upper layer is conflicting but already contains its
+     * PR base, so the dirty state is against the stack trunk rather than that base.
+     */
+    stackTrunkConflict?: string;
     /** Null when no classic protection rule exists or the base ref is unavailable. */
     branchProtection: BranchProtection | null;
     mergeRequirements?: MergeRequirements;
@@ -40,11 +45,17 @@ export interface IterateResultBase {
     inProgressChecks?: ActiveCheck[];
     ignoredNames?: string[];
     supersededNames?: string[];
+    /** Required merge-target contexts with no check run and no status context. Omitted when empty. */
+    unreportedRequiredChecks?: string[];
+    /** Commits on the stack trunk that the bottom open layer does not contain. Omitted when zero. */
+    trunkBehindBy?: number;
     activity?: PrActivitySummary;
     mergeQueue?: import("./merge-queue.mts").MergeQueueReport;
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;
     fingerprintReused?: true;
+    /** Classification-rule resolve/minimize applied during this fetch. Omitted when nothing happened. */
+    ruleAutoResolve?: RuleAutoResolveReport;
 }
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
@@ -52,6 +63,11 @@ interface IterateResultWait extends IterateResultBase {
     deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
     stackDraftHold?: StackDraftHold;
 }
+/** Clean PR whose ready-delay is still counting. `--until-terminal` returns this instead of sleeping. */
+interface IterateResultReady extends IterateResultBase {
+    action: "ready";
+    log: string;
+}
 export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
 interface IterateResultCancel extends IterateResultBase {
     action: "cancel";
@@ -129,7 +145,7 @@ interface IterateResultEscalate extends IterateResultBase {
     action: "escalate";
     escalate: EscalateDetails;
 }
-export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultMerge | IterateResultEscalate;
+export type IterateResult = IterateResultWait | IterateResultReady | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultMerge | IterateResultEscalate;
 export interface IterateCommandOptions extends GlobalOptions {
     readyDelaySeconds?: number;
     noAutoMarkReady?: boolean;

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

@@ -11,6 +11,10 @@ export interface PollSummaryChecks {
     ignored?: number;
     superseded?: number;
     incomplete?: true;
+    /** Required contexts with no check run and no status context. Omitted when empty. */
+    unreportedRequired?: string[];
+    /** A relevant Actions workflow suite has not completed. */
+    actionsWorkflowInProgress?: true;
 }
 export interface PollSummaryReview {
     comments?: number;
@@ -39,6 +43,10 @@ export interface PollSummaryItem {
     repo: string;
     title: string;
     url: string;
+    /** GitHub author login, when the summary query returned one. */
+    authorLogin?: string;
+    /** Author login matches the authenticated viewer. */
+    owned?: true;
     /** Conservative routing hint; the selected one-PR poll makes the authoritative decision. */
     action: ShepherdAction;
     reasons: string[];
@@ -89,6 +97,11 @@ export interface PollSummaryResult {
     nextAction?: StackNextAction;
     /** Whether every open layer is independently ready and stack ancestry is linear. */
     stackMergeable?: boolean;
+    /**
+     * Repository merge methods for stack merge commands. Omitted from the lean
+     * stack overview. Empty when the repository enables none.
+     */
+    allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
     instructions?: string[];
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;