pr-shepherd 0.42.0 → 0.43.0

package/bin/github/batch-parse-checks.mjs

@@ -0,0 +1,29 @@
+import { mapCheckRunNode, mapStatusContextState, parseCreatedAt } from "./batch-parser-helpers.mjs";
+export function parseCheckNodes(nodes, mergeCommitOid) {
+    return (nodes ?? []).flatMap((node) => {
+        const scope = mergeCommitOid
+            ? { scope: "merge_group", commitOid: mergeCommitOid }
+            : {};
+        if (node?.__typename === "CheckRun")
+            return [{ ...mapCheckRunNode(node), ...scope }];
+        if (node?.__typename !== "StatusContext")
+            return [];
+        const { status, conclusion } = mapStatusContextState(node.state);
+        const summary = node.description?.trim() || undefined;
+        const createdAtUnix = node.createdAt ? parseCreatedAt(node.createdAt) : undefined;
+        return [
+            {
+                name: node.context,
+                status,
+                conclusion,
+                source: "status_context",
+                detailsUrl: node.targetUrl ?? "",
+                event: null,
+                runId: null,
+                ...scope,
+                ...(createdAtUnix !== undefined && { createdAtUnix }),
+                ...(summary !== undefined && { summary }),
+            },
+        ];
+    });
+}

package/bin/github/batch-parsers-rules.d.mts

@@ -1,6 +1,8 @@
-import type { BranchRules, MergeQueueEntryStatus, StackStatus } from "../types.mts";
+import type { AutoMergeRequestStatus, BranchRules, MergeQueueEntryStatus, MergeQueueRemovalStatus, StackStatus } from "../types.mts";
 import type { RawBaseRef, RawPrMergeFields } from "./batch-raw-rules.mts";
 export declare const EMPTY_BRANCH_RULES: BranchRules;
 export declare function parseBranchRules(baseRef: RawBaseRef | null | undefined): BranchRules;
 export declare function parseMergeQueueEntry(raw: RawPrMergeFields["mergeQueueEntry"]): MergeQueueEntryStatus | null;
+export declare function parseAutoMergeRequest(raw: RawPrMergeFields["autoMergeRequest"]): AutoMergeRequestStatus | null;
+export declare function parseLatestMergeQueueRemoval(raw: RawPrMergeFields): MergeQueueRemovalStatus | null;
 export declare function parseStack(raw: RawPrMergeFields): StackStatus | null;

package/bin/github/batch-parsers-rules.mjs

@@ -32,8 +32,41 @@ export function parseMergeQueueEntry(raw) {
         position: raw.position,
         state: raw.state,
         estimatedTimeToMerge: raw.estimatedTimeToMerge,
+        ...(raw.headCommit?.oid && { headCommitOid: raw.headCommit.oid }),
+        ...(raw.enqueuedAt && { enqueuedAtUnix: parseUnix(raw.enqueuedAt) }),
+        ...(raw.enqueuer?.login && { enqueuer: raw.enqueuer.login }),
     };
 }
+export function parseAutoMergeRequest(raw) {
+    if (!raw)
+        return null;
+    return {
+        enabledAtUnix: parseUnix(raw.enabledAt),
+        mergeMethod: raw.mergeMethod,
+        ...(raw.enabledBy?.login && { enabledBy: raw.enabledBy.login }),
+    };
+}
+export function parseLatestMergeQueueRemoval(raw) {
+    const removal = raw.mergeQueueRemovals?.nodes[0];
+    if (!removal)
+        return null;
+    const lastAddedAt = raw.mergeQueueAdditions?.nodes[0]?.createdAt;
+    if (lastAddedAt && Date.parse(lastAddedAt) > Date.parse(removal.createdAt))
+        return null;
+    return {
+        reason: removal.reason,
+        createdAtUnix: parseUnix(removal.createdAt),
+        ...(removal.actor?.login && { actor: removal.actor.login }),
+        ...(removal.beforeCommit?.oid && { beforeCommitOid: removal.beforeCommit.oid }),
+        ...(removal.beforeCommit?.parents && {
+            beforeCommitParentOids: removal.beforeCommit.parents.nodes.map((parent) => parent.oid),
+        }),
+    };
+}
+function parseUnix(value) {
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
 export function parseStack(raw) {
     if (!raw.stack)
         return null;

package/bin/github/batch-parsers.mjs

@@ -1,7 +1,9 @@
-import { mapAuthorType, parseCreatedAt, mapStatusContextState, latestApprovedLogins, isReviewStale, mapCheckRunNode, } from "./batch-parser-helpers.mjs";
+import { mapAuthorType, parseCreatedAt, latestApprovedLogins, isReviewStale, } from "./batch-parser-helpers.mjs";
+import { parseCheckNodes } from "./batch-parse-checks.mjs";
+import { requireContextNodes } from "./batch-response.mjs";
 import { buildPrActivitySummary } from "./activity.mjs";
 import { parseBranchProtection } from "./branch-protection.mjs";
-import { parseBranchRules, parseMergeQueueEntry, parseStack } from "./batch-parsers-rules.mjs";
+import { parseAutoMergeRequest, parseBranchRules, parseLatestMergeQueueRemoval, parseMergeQueueEntry, parseStack, } from "./batch-parsers-rules.mjs";
 function parseReviewNode(r) {
     const base = {
         id: r.id,
@@ -86,30 +88,15 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
     const approvedReviews = rawApprovedReviewNodes
         .filter((r) => !r.isMinimized)
         .map((r) => parseReviewNode(r));
-    const checks = rawCheckNodes.flatMap((node) => {
-        if (node.__typename === "CheckRun") {
-            return [mapCheckRunNode(node)];
-        }
-        if (node.__typename === "StatusContext") {
-            const { status, conclusion } = mapStatusContextState(node.state);
-            const summary = node.description?.trim() || undefined;
-            const createdAtUnix = node.createdAt ? parseCreatedAt(node.createdAt) : undefined;
-            return [
-                {
-                    name: node.context,
-                    status,
-                    conclusion,
-                    source: "status_context",
-                    detailsUrl: node.targetUrl ?? "",
-                    event: null,
-                    runId: null,
-                    ...(createdAtUnix !== undefined && { createdAtUnix }),
-                    ...(summary !== undefined && { summary }),
-                },
-            ];
-        }
-        return [];
-    });
+    const checks = parseCheckNodes(rawCheckNodes);
+    const queueHead = raw.mergeQueueEntry?.headCommit;
+    const removedQueueHead = raw.mergeQueueRemovals?.nodes[0]?.beforeCommit;
+    const mergeQueueChecks = parseCheckNodes(queueHead?.statusCheckRollup
+        ? requireContextNodes(queueHead.statusCheckRollup.contexts.nodes)
+        : undefined, queueHead?.oid);
+    const removedMergeQueueChecks = parseCheckNodes(removedQueueHead?.statusCheckRollup
+        ? requireContextNodes(removedQueueHead.statusCheckRollup.contexts.nodes)
+        : undefined, removedQueueHead?.oid);
     return {
         nodeId: raw.id,
         number: raw.number,
@@ -135,6 +122,16 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         isInMergeQueue: raw.isInMergeQueue ?? false,
         isMergeQueueEnabled: raw.isMergeQueueEnabled ?? false,
         mergeQueueEntry: parseMergeQueueEntry(raw.mergeQueueEntry),
+        autoMergeRequest: parseAutoMergeRequest(raw.autoMergeRequest),
+        latestMergeQueueRemoval: parseLatestMergeQueueRemoval(raw),
+        ...(mergeQueueChecks.length > 0 && { mergeQueueChecks }),
+        ...(queueHead?.statusCheckRollup?.contexts.pageInfo.hasNextPage && {
+            mergeQueueChecksIncomplete: true,
+        }),
+        ...(removedMergeQueueChecks.length > 0 && { removedMergeQueueChecks }),
+        ...(removedQueueHead?.statusCheckRollup?.contexts.pageInfo.hasNextPage && {
+            removedMergeQueueChecksIncomplete: true,
+        }),
         stack: parseStack(raw),
         activity: buildPrActivitySummary(raw, comments, reviewThreads, reviewSummaries, allChangesRequestedReviews, approvedReviews),
     };

package/bin/github/batch-raw-rules.d.mts

@@ -12,10 +12,49 @@ export interface RawBranchProtectionRule {
     requiresDeployments?: boolean;
     requiredDeploymentEnvironments?: string[] | null;
 }
+import type { RawContextNode } from "./batch-raw-types.mts";
+interface RawCheckCommit {
+    oid: string;
+    committedDate?: string;
+    parents?: {
+        nodes: Array<{
+            oid: string;
+        }>;
+    };
+    statusCheckRollup: {
+        contexts: {
+            pageInfo: {
+                hasNextPage: boolean;
+                endCursor: string | null;
+            };
+            nodes: Array<RawContextNode | null>;
+        };
+    } | null;
+}
 interface RawMergeQueueEntry {
     position: number;
     state: string;
     estimatedTimeToMerge: number | null;
+    headCommit?: RawCheckCommit | null;
+    enqueuedAt?: string;
+    enqueuer?: {
+        login: string;
+    } | null;
+}
+interface RawAutoMergeRequest {
+    enabledAt: string;
+    mergeMethod: string;
+    enabledBy?: {
+        login: string;
+    } | null;
+}
+interface RawMergeQueueRemoval {
+    reason: string | null;
+    actor?: {
+        login: string;
+    } | null;
+    createdAt: string;
+    beforeCommit?: RawCheckCommit | null;
 }
 interface RawStack {
     number: number;
@@ -50,6 +89,15 @@ export interface RawPrMergeFields {
     isInMergeQueue?: boolean;
     isMergeQueueEnabled?: boolean;
     mergeQueueEntry?: RawMergeQueueEntry | null;
+    autoMergeRequest?: RawAutoMergeRequest | null;
+    mergeQueueRemovals?: {
+        nodes: RawMergeQueueRemoval[];
+    } | null;
+    mergeQueueAdditions?: {
+        nodes: Array<{
+            createdAt: string;
+        }>;
+    } | null;
     stack?: RawStack | null;
     stackEntry?: {
         position: number;

package/bin/github/batch-raw-types.mjs

@@ -1,2 +1 @@
-// Private raw GraphQL response types for the batch PR query.
 export {};

package/bin/github/batch.mjs

@@ -6,6 +6,7 @@ import { parseCheckSuitesComplete, parseSuiteStartupFailures } from "./batch-par
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { paginateBatchConnections } from "./batch-page.mjs";
 import { requireRawPr } from "./batch-response.mjs";
+import { hydrateMergeQueueChecks } from "./merge-queue-checks.mjs";
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
  */
@@ -16,6 +17,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
         pr,
     });
     const raw = requireRawPr(result.data, pr, repo);
+    await hydrateMergeQueueChecks(raw, repo);
     const paged = await paginateBatchConnections(pr, repo, raw, opts, result.rateLimit);
     const rawThreadPages = await hydrateThreadCommentPages(paged.threads);
     const data = parseRawPr(raw, rawThreadPages, paged.comments, paged.changesRequested, paged.reviewSummaries, paged.approvedReviews, paged.checks);

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

@@ -18,10 +18,45 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
       baseRefName
       isInMergeQueue
       isMergeQueueEnabled
+      autoMergeRequest {
+        enabledAt
+        mergeMethod
+        enabledBy {
+          login
+        }
+      }
       mergeQueueEntry {
         position
         state
         estimatedTimeToMerge
+        enqueuedAt
+        enqueuer {
+          login
+        }
+        headCommit {
+          ...QueueCheckCommit
+        }
+      }
+      mergeQueueAdditions: timelineItems(last: 1, itemTypes: [ADDED_TO_MERGE_QUEUE_EVENT]) {
+        nodes {
+          ... on AddedToMergeQueueEvent {
+            createdAt
+          }
+        }
+      }
+      mergeQueueRemovals: timelineItems(last: 1, itemTypes: [REMOVED_FROM_MERGE_QUEUE_EVENT]) {
+        nodes {
+          ... on RemovedFromMergeQueueEvent {
+            reason
+            createdAt
+            actor {
+              login
+            }
+            beforeCommit {
+              ...QueueCheckCommit
+            }
+          }
+        }
       }
       stack {
         number
@@ -289,3 +324,60 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
     }
   }
 }
+
+fragment QueueCheckCommit on Commit {
+  oid
+  committedDate
+  parents(first: 100) {
+    nodes {
+      oid
+    }
+  }
+  statusCheckRollup {
+    contexts(first: 100) {
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      nodes {
+        __typename
+        ... on CheckRun {
+          id
+          name
+          status
+          conclusion
+          detailsUrl
+          completedAt
+          startedAt
+          title
+          summary
+          annotations(first: 1) {
+            nodes {
+              message
+            }
+          }
+          checkSuite {
+            createdAt
+            updatedAt
+            workflowRun {
+              event
+              createdAt
+              updatedAt
+              workflow {
+                name
+                databaseId
+              }
+            }
+          }
+        }
+        ... on StatusContext {
+          context
+          state
+          createdAt
+          targetUrl
+          description
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/commit-check-contexts.gql

@@ -0,0 +1,58 @@
+query CommitCheckContexts($owner: String!, $repo: String!, $oid: String!, $cursor: String) {
+  repository(owner: $owner, name: $repo) {
+    object(expression: $oid) {
+      __typename
+      ... on Commit {
+        oid
+        statusCheckRollup {
+          contexts(first: 100, after: $cursor) {
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+            nodes {
+              __typename
+              ... on CheckRun {
+                id
+                name
+                status
+                conclusion
+                detailsUrl
+                completedAt
+                startedAt
+                title
+                summary
+                annotations(first: 1) {
+                  nodes {
+                    message
+                  }
+                }
+                checkSuite {
+                  createdAt
+                  updatedAt
+                  workflowRun {
+                    event
+                    createdAt
+                    updatedAt
+                    workflow {
+                      name
+                      databaseId
+                    }
+                    databaseId
+                  }
+                }
+              }
+              ... on StatusContext {
+                context
+                state
+                description
+                targetUrl
+                createdAt
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

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

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

@@ -0,0 +1,48 @@
+import { graphql } from "./client.mjs";
+import { requireContextNodes } from "./batch-response.mjs";
+import { COMMIT_CHECK_CONTEXTS_QUERY } from "./queries.mjs";
+async function hydrateCommitContexts(commit, repo) {
+    const contexts = commit.statusCheckRollup?.contexts;
+    if (!contexts)
+        return;
+    contexts.nodes = requireContextNodes(contexts.nodes);
+    if (contexts.pageInfo.hasNextPage && !contexts.pageInfo.endCursor) {
+        throw new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${commit.oid}. Retry.`);
+    }
+    let cursor = contexts.pageInfo.hasNextPage ? contexts.pageInfo.endCursor : null;
+    while (cursor) {
+        // eslint-disable-next-line no-await-in-loop
+        const result = await graphql(COMMIT_CHECK_CONTEXTS_QUERY, {
+            owner: repo.owner,
+            repo: repo.name,
+            oid: commit.oid,
+            cursor,
+        });
+        const object = result.data.repository?.object;
+        if (object?.__typename !== "Commit" || object.oid !== commit.oid) {
+            throw new Error(`Merge queue check pagination interrupted: commit ${commit.oid} disappeared or changed. Retry.`);
+        }
+        const next = object.statusCheckRollup?.contexts;
+        if (!next) {
+            throw new Error(`Merge queue check pagination interrupted: statusCheckRollup disappeared for ${commit.oid}. Retry.`);
+        }
+        contexts.nodes.push(...requireContextNodes(next.nodes));
+        contexts.pageInfo = next.pageInfo;
+        cursor = next.pageInfo.hasNextPage ? next.pageInfo.endCursor : null;
+        if (next.pageInfo.hasNextPage && !cursor) {
+            throw new Error(`Merge queue check pagination interrupted: GitHub omitted the next cursor for ${commit.oid}. Retry.`);
+        }
+    }
+}
+/** Hydrate all status contexts for the active or most recently removed queue commit. */
+export async function hydrateMergeQueueChecks(raw, repo) {
+    const active = raw.mergeQueueEntry?.headCommit;
+    const removal = raw.mergeQueueRemovals?.nodes[0];
+    const addition = raw.mergeQueueAdditions?.nodes[0];
+    const removalIsCurrent = Boolean(removal && (!addition || Date.parse(removal.createdAt) >= Date.parse(addition.createdAt)));
+    const removed = removalIsCurrent ? removal?.beforeCommit : undefined;
+    if (active)
+        await hydrateCommitContexts(active, repo);
+    if (removed && removed.oid !== active?.oid)
+        await hydrateCommitContexts(removed, repo);
+}

package/bin/github/queries.d.mts

@@ -16,6 +16,8 @@ export declare const SUGGESTION_THREADS_QUERY: string;
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export declare const CHECK_RUN_ANNOTATIONS_QUERY: string;
+/** Fetches additional status contexts for a merge queue synthetic commit. */
+export declare const COMMIT_CHECK_CONTEXTS_QUERY: string;
 /** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
 export declare const GET_PR_HEAD_SHA_QUERY: string;
 /** Look up PR number by branch name (for getCurrentPrNumber). */

package/bin/github/queries.mjs

@@ -19,6 +19,8 @@ export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export const CHECK_RUN_ANNOTATIONS_QUERY = gql("check-run-annotations.gql");
+/** Fetches additional status contexts for a merge queue synthetic commit. */
+export const COMMIT_CHECK_CONTEXTS_QUERY = gql("commit-check-contexts.gql");
 /** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
 export const GET_PR_HEAD_SHA_QUERY = gql("get-pr-head-sha.gql");
 /** Look up PR number by branch name (for getCurrentPrNumber). */

package/bin/mcp/server.mjs

@@ -18,6 +18,7 @@ const iterateInputSchema = z.object({
     readyDelaySeconds: z.number().nonnegative().optional(),
     stallTimeoutSeconds: z.number().nonnegative().optional(),
     noAutoMarkReady: z.boolean().optional(),
+    merge: z.boolean().optional(),
     noAutoCancelActionable: z.boolean().optional(),
     neverCancelRuns: z.array(z.string()).optional(),
 });

package/bin/reporters/agent.mjs

@@ -61,6 +61,8 @@ export function toAgentCheck(c) {
         ...(c.summary !== undefined && { summary: c.summary }),
         ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
         ...(c.annotations !== undefined && { annotations: c.annotations }),
+        ...(c.scope !== undefined && { scope: c.scope }),
+        ...(c.commitOid !== undefined && { commitOid: c.commitOid }),
     };
 }
 export function toAgentStalledCheck(c, nowSeconds) {
@@ -85,13 +87,14 @@ export function toAgentStalledCheck(c, nowSeconds) {
  * log tail, so they are all kept.
  */
 export function toAgentChecks(checks) {
-    const seenNames = new Set();
+    const seenKeys = new Set();
     const result = [];
     for (const c of checks) {
         if (c.runId === null) {
-            if (seenNames.has(c.name))
+            const key = `${c.scope ?? "pr"}:${c.commitOid ?? "head"}:${c.name}`;
+            if (seenKeys.has(key))
                 continue;
-            seenNames.add(c.name);
+            seenKeys.add(key);
         }
         result.push(toAgentCheck(c));
     }

package/bin/types/activity.d.mts

@@ -26,5 +26,7 @@ export interface ActiveCheck {
     detailsUrl: string | null;
     workflowName?: string;
     summary?: string;
+    scope?: "merge_group";
+    commitOid?: string;
 }
 export {};

package/bin/types/escalate.d.mts

@@ -0,0 +1,30 @@
+import type { AgentComment, AgentThread } from "./report.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" | "thread-missing-location" | "bot-cr-not-dismissed" | "merge-queue-removed";
+export interface AgentStalledCheck {
+    name: string;
+    status: CheckStatus;
+    source: "check_run" | "status_context" | "startup_failure";
+    runId: string | null;
+    detailsUrl: string | null;
+    createdAtUnix?: number;
+    startedAtUnix?: number;
+    updatedAtUnix?: number;
+    ageSeconds: number;
+    summary?: string;
+}
+export interface EscalateDetails {
+    triggers: EscalateTrigger[];
+    unresolvedThreads: AgentThread[];
+    ambiguousComments: AgentComment[];
+    changesRequestedReviews: Review[];
+    stalledChecks?: AgentStalledCheck[];
+    thrashHistory?: Array<{
+        threadId: string;
+        attempts: number;
+    }>;
+    suggestion: string;
+    humanMessage: string;
+    mergeQueueRemoval?: MergeQueueRemovalStatus;
+}

package/bin/types/escalate.mjs

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

package/bin/types/github.d.mts

@@ -19,6 +19,10 @@ export interface CheckRun {
     detailsUrl: string;
     event: string | null;
     runId: string | null;
+    /** Commit scope that supplied this check. Omitted for ordinary PR-head checks. */
+    scope?: "merge_group";
+    /** Synthetic merge-group commit OID, when `scope` is `merge_group`. */
+    commitOid?: string;
     createdAtUnix?: number;
     startedAtUnix?: number;
     completedAtUnix?: number;
@@ -133,6 +137,10 @@ export interface BatchPrData extends BatchPrMergeFields {
     reviewSummaries: Review[];
     approvedReviews: Review[];
     checks: CheckRun[];
+    mergeQueueChecks?: CheckRun[];
+    mergeQueueChecksIncomplete?: true;
+    removedMergeQueueChecks?: CheckRun[];
+    removedMergeQueueChecksIncomplete?: true;
     branchProtection: BranchProtection | null;
     activity?: PrActivitySummary;
 }

package/bin/types/github.mjs

@@ -1,4 +1 @@
-// GitHub primitives, check runs, review threads, and batch PR data types.
-// Check classification types (CheckCategory/ClassifiedCheck/TriagedCheck) live in
-// check-classification.mts to stay under the file-length cap.
 export {};

package/bin/types/iterate.d.mts

@@ -1,37 +1,11 @@
 import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
-import type { BranchProtection, CheckStatus, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
+import type { BranchProtection, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
 import type { MergeRequirements } from "./merge-requirements.mts";
+import type { EscalateDetails } from "./escalate.mts";
+import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
-export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "cancel" | "escalate";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "thread-missing-location" | "bot-cr-not-dismissed";
-export interface AgentStalledCheck {
-    name: string;
-    status: CheckStatus;
-    source: "check_run" | "status_context" | "startup_failure";
-    runId: string | null;
-    detailsUrl: string | null;
-    createdAtUnix?: number;
-    startedAtUnix?: number;
-    updatedAtUnix?: number;
-    ageSeconds: number;
-    summary?: string;
-}
-export interface EscalateDetails {
-    triggers: EscalateTrigger[];
-    unresolvedThreads: AgentThread[];
-    ambiguousComments: AgentComment[];
-    changesRequestedReviews: Review[];
-    /** Pending/unstarted CI checks that exceeded the stall timeout. */
-    stalledChecks?: AgentStalledCheck[];
-    /** Populated when fix-thrash triggered — threads that have been attempted too many times. */
-    thrashHistory?: Array<{
-        threadId: string;
-        attempts: number;
-    }>;
-    suggestion: string;
-    humanMessage: string;
-}
+export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
 export interface IterateResultSummary {
     passing: number;
     skipped: number;
@@ -66,6 +40,7 @@ export interface IterateResultBase {
     ignoredNames?: string[];
     supersededNames?: string[];
     activity?: PrActivitySummary;
+    mergeQueue?: import("./merge-queue.mts").MergeQueueReport;
 }
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
@@ -123,6 +98,8 @@ interface FixRebaseAndPush {
     inProgressRunIds: string[];
     /** Workflow runs deliberately excluded from cancellation by actions.neverCancelRuns. */
     protectedRuns: ProtectedRun[];
+    /** Requeue command emitted after merge-group remediation. */
+    requeue?: MergeCommandPlan;
     /** First-look threads — previously hidden, surfaced for acknowledgment only. */
     firstLookThreads: FirstLookThread[];
     /** First-look comments — previously hidden, surfaced for acknowledgment only. */
@@ -138,11 +115,15 @@ interface IterateResultMarkReady extends IterateResultBase {
     markedReady: boolean;
     log: string;
 }
+export interface IterateResultMerge extends IterateResultBase {
+    action: "merge";
+    merge: MergeCommandPlan;
+}
 interface IterateResultEscalate extends IterateResultBase {
     action: "escalate";
     escalate: EscalateDetails;
 }
-export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultEscalate;
+export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultMerge | IterateResultEscalate;
 export interface IterateCommandOptions extends GlobalOptions {
     readyDelaySeconds?: number;
     noAutoMarkReady?: boolean;
@@ -152,5 +133,7 @@ export interface IterateCommandOptions extends GlobalOptions {
     /** Case-insensitive workflow/check glob patterns Shepherd must not cancel. */
     neverCancelRuns?: string[];
     persistSeen?: boolean;
+    /** Shepherd through readiness and emit the exact merge/queue command when ready. */
+    merge?: boolean;
 }
 export {};