pr-shepherd 0.53.1 → 0.54.1

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

@@ -9,6 +9,7 @@ import { summarizePollSummaryReview } from "./poll-summary-review.mjs";
 import { fingerprintRawSummaryPr } from "./poll-summary-fingerprint.mjs";
 import { currentQueueRemovalEvent } from "./poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "./poll-summary-readiness.mjs";
+import { applyOpenCheckBlockers } from "./poll-summary-check-blockers.mjs";
 import { normalizePollSummaryState, routePollSummary } from "./poll-summary-route.mjs";
 export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdminister = false) {
     const repoName = `${repo.owner}/${repo.name}`;
@@ -69,6 +70,9 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
         : removalEvent
             ? projectQueueRemoval(removalEvent)
             : undefined;
+    const blocked = await applyOpenCheckBlockers(raw, repo, { action, reasons }, checks, review, opts.stackPrNumber !== undefined);
+    action = blocked.action;
+    reasons = blocked.reasons;
     return {
         pr: raw.number,
         repo: repoName,
@@ -97,6 +101,7 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
                 !(opts.stackPrNumber !== undefined && raw.stack && action === "merge"))
             ? pollCommandFields(repoName, raw.number, raw.isDraft, opts)
             : {}),
+        ...(blocked.pollProbe ? { pollProbe: true } : {}),
     };
 }
 function projectQueueRemoval(removal) {

package/bin/github/queries.d.mts

@@ -23,12 +23,23 @@ export declare const POLL_SUMMARY_CHECK_PAGE_QUERY: string;
 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. */
 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;
+/**
+ * First annotation page for many CheckRuns. Chunked at 20 ids so the nested
+ * `annotations` connections stay a 1-point query. Further pages use
+ * `CHECK_RUN_ANNOTATIONS_QUERY`.
+ */
+export declare const CHECK_RUN_ANNOTATIONS_BATCH_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. */

package/bin/github/queries.mjs

@@ -28,12 +28,23 @@ export const POLL_SUMMARY_CHECK_PAGE_QUERY = `${POLL_SUMMARY_CHECK_CONTEXTS_FRAG
 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. */
 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");
+/**
+ * First annotation page for many CheckRuns. Chunked at 20 ids so the nested
+ * `annotations` connections stay a 1-point query. Further pages use
+ * `CHECK_RUN_ANNOTATIONS_QUERY`.
+ */
+export const CHECK_RUN_ANNOTATIONS_BATCH_QUERY = gql("check-run-annotations-batch.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. */

package/bin/state/check-blockers.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Per-PR records that a failing check is blocked on an external PR or issue.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/check-blockers.json`
+ */
+export interface CheckBlockerRef {
+    owner: string;
+    name: string;
+    number: number;
+    kind: "pull" | "issue";
+}
+export interface CheckBlockerRecord {
+    checkName: string;
+    blocker: CheckBlockerRef;
+    /** Unix seconds. */
+    recordedAt: number;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function formatCheckBlockerRef(blocker: CheckBlockerRef): string;
+/** Missing, unreadable, or malformed state is an empty list. Does not throw. */
+export declare function readCheckBlockers(key: StateKey): Promise<CheckBlockerRecord[]>;
+/** Insert or replace the record for `checkName`. Returns false when the file cannot be written. */
+export declare function writeCheckBlocker(key: StateKey, record: CheckBlockerRecord): Promise<boolean>;
+/** Drop one check's record. A missing record is success and does not create a file. */
+export declare function clearCheckBlocker(key: StateKey, checkName: string): Promise<boolean>;
+export {};

package/bin/state/check-blockers.mjs

@@ -0,0 +1,88 @@
+/**
+ * Per-PR records that a failing check is blocked on an external PR or issue.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/check-blockers.json`
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+const FILE = "check-blockers.json";
+export function formatCheckBlockerRef(blocker) {
+    return `${blocker.owner}/${blocker.name}#${blocker.number}`;
+}
+/** Missing, unreadable, or malformed state is an empty list. Does not throw. */
+export async function readCheckBlockers(key) {
+    try {
+        const parsed = JSON.parse(await readFile(resolvePrStatePath(key, FILE), "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return [];
+        const blockers = parsed.blockers;
+        if (!Array.isArray(blockers))
+            return [];
+        return blockers.filter(isRecord);
+    }
+    catch {
+        return [];
+    }
+}
+/** Insert or replace the record for `checkName`. Returns false when the file cannot be written. */
+export async function writeCheckBlocker(key, record) {
+    const blockers = (await readCheckBlockers(key)).filter((item) => item.checkName !== record.checkName);
+    blockers.push(record);
+    return writeAll(key, blockers);
+}
+/** Drop one check's record. A missing record is success and does not create a file. */
+export async function clearCheckBlocker(key, checkName) {
+    const current = await readCheckBlockers(key);
+    const blockers = current.filter((item) => item.checkName !== checkName);
+    if (blockers.length === current.length)
+        return true;
+    return writeAll(key, blockers);
+}
+async function writeAll(key, blockers) {
+    let tmp;
+    try {
+        const path = resolvePrStatePath(key, FILE);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, `${JSON.stringify({ blockers })}\n`, "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // The failed write may not have created the temp file.
+            }
+        }
+    }
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.checkName === "string" &&
+        record.checkName.length > 0 &&
+        typeof record.recordedAt === "number" &&
+        Number.isFinite(record.recordedAt) &&
+        isBlocker(record.blocker));
+}
+function isBlocker(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const blocker = value;
+    return ((blocker.kind === "pull" || blocker.kind === "issue") &&
+        typeof blocker.owner === "string" &&
+        typeof blocker.name === "string" &&
+        typeof blocker.number === "number" &&
+        Number.isInteger(blocker.number) &&
+        blocker.number > 0);
+}

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/iterate.d.mts

@@ -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;

package/bin/types/report.d.mts

@@ -33,6 +33,8 @@ export interface ShepherdReport {
     baseBranch: string;
     /** Base commit GitHub recorded for this PR (`PullRequest.baseRefOid`), not the branch's live tip. */
     baseRefOid?: string;
+    /** True when the head commit's check-suite page is complete and has no suites. */
+    headCheckSuitesEmpty?: true;
     mergeStatus: MergeStatusResult;
     checks: {
         passing: ClassifiedCheck[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.53.1",
+  "version": "0.54.1",
   "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.53.1",
+  "version": "0.54.1",
   "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.53.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.54.1", "pr-shepherd-mcp"]
     }
   }
 }

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

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