pr-shepherd 0.54.0 → 0.54.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.54.0",
+  "version": "0.54.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/cli/iterate-branch-segment.d.mts

@@ -0,0 +1,3 @@
+import type { IterateResult } from "../types.mts";
+/** Summary-line branch phrase. Empty when the PR is not behind or conflicting. */
+export declare function branchStateSegment(result: IterateResult): string;

package/bin/cli/iterate-branch-segment.mjs

@@ -0,0 +1,13 @@
+/** Summary-line branch phrase. Empty when the PR is not behind or conflicting. */
+export function branchStateSegment(result) {
+    if (result.mergeStatus === "BEHIND" && result.baseBranch) {
+        return `**branch** behind PR base \`${result.baseBranch}\``;
+    }
+    if (result.mergeStatus === "CONFLICTS" && result.stackTrunkConflict) {
+        return `**branch** conflicts with stack trunk \`${result.stackTrunkConflict}\``;
+    }
+    if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
+        return `**branch** conflicts with PR base \`${result.baseBranch}\``;
+    }
+    return "";
+}

package/bin/cli/iterate-formatter.mjs

@@ -6,6 +6,7 @@ import { formatMergeRequirementLines } from "../merge-status/requirements-format
 import { appendMergeQueueHeader, formatDeferredWorkLine, formatMergeAction, } from "./iterate-merge-formatter.mjs";
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { formatActivityLine } from "./iterate-activity-formatter.mjs";
+import { branchStateSegment } from "./iterate-branch-segment.mjs";
 /**
  * Format an IterateResult as human-readable Markdown.
  *
@@ -29,15 +30,10 @@ export function formatIterateResult(result, opts) {
         : "";
     const baseBranchSeg = verbose && result.baseBranch ? ` · **baseBranch** \`${result.baseBranch}\`` : "";
     const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\`${baseBranchSeg}`;
+    const branchSeg = branchStateSegment(result);
     let summaryLine;
     if (verbose) {
-        let verboseBranch = "";
-        if (result.mergeStatus === "BEHIND" && result.baseBranch) {
-            verboseBranch = ` · **branch** behind PR base \`${result.baseBranch}\``;
-        }
-        else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
-            verboseBranch = ` · **branch** conflicts with PR base \`${result.baseBranch}\``;
-        }
+        const verboseBranch = branchSeg ? ` · ${branchSeg}` : "";
         summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}`;
     }
     else {
@@ -58,12 +54,8 @@ export function formatIterateResult(result, opts) {
             segs.push(`**blockingBotReviewInProgress**`);
         if (result.isDraft)
             segs.push(`**isDraft**`);
-        if (result.mergeStatus === "BEHIND" && result.baseBranch) {
-            segs.push(`**branch** behind PR base \`${result.baseBranch}\``);
-        }
-        else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
-            segs.push(`**branch** conflicts with PR base \`${result.baseBranch}\``);
-        }
+        if (branchSeg)
+            segs.push(branchSeg);
         summaryLine = segs.join(" · ");
     }
     // Surface an explicit `--ready-delay` override (set only when the user passed the flag)

package/bin/cli/iterate-lean.mjs

@@ -41,6 +41,7 @@ export function projectIterateLean(result, opts) {
             remainingSeconds: result.remainingSeconds,
         }),
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
+        ...(result.stackTrunkConflict && { stackTrunkConflict: result.stackTrunkConflict }),
         ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
         ...(result.mergeRequirements && { mergeRequirements: result.mergeRequirements }),
         ...(result.mergeQueue && { mergeQueue: result.mergeQueue }),

package/bin/commands/check.mjs

@@ -259,6 +259,7 @@ export async function runCheck(opts) {
         status,
         baseBranch: batchData.baseRefName,
         ...(batchData.baseRefOid && { baseRefOid: batchData.baseRefOid }),
+        ...(result.headCheckSuitesEmpty && { headCheckSuitesEmpty: true }),
         mergeStatus,
         checks: {
             passing: merged.passing,

package/bin/commands/iterate/conflicting-head-ci.d.mts

@@ -0,0 +1,18 @@
+export declare function conflictingHeadCiNote(input: {
+    hasConflicts: boolean;
+    headCheckSuitesEmpty: boolean;
+    checkRunCount: number;
+    /** Unix seconds when Shepherd first saw this head. Omit when that time is unknown. */
+    firstSeenAtUnix: number | null | undefined;
+    nowMs: number;
+}): string | undefined;
+export declare function countReportedChecks(checks: {
+    passing: readonly unknown[];
+    failing: readonly unknown[];
+    inProgress: readonly unknown[];
+    skipped: readonly unknown[];
+    filtered: readonly unknown[];
+    ignored?: readonly unknown[];
+}): number;
+/** Place the missing-CI note with the conflict step, ahead of later repair lines. */
+export declare function insertConflictingHeadCiNote(instructions: string[], note: string | undefined): void;

package/bin/commands/iterate/conflicting-head-ci.mjs

@@ -0,0 +1,32 @@
+/** How long a conflicting head may sit with no CI before Shepherd says none will start. */
+const CONFLICTING_HEAD_CI_GRACE_MS = 2 * 60 * 1000;
+const NO_CI_NOTE = "GitHub did not start pull_request workflows for this conflicting head: no check suites or workflow runs have appeared for at least 2 minutes. Missing CI is a consequence of the conflict, not an outage, and pushing this same head again will not start them.";
+export function conflictingHeadCiNote(input) {
+    if (!input.hasConflicts || !input.headCheckSuitesEmpty || input.checkRunCount > 0) {
+        return undefined;
+    }
+    if (typeof input.firstSeenAtUnix !== "number")
+        return undefined;
+    const ageMs = input.nowMs - input.firstSeenAtUnix * 1000;
+    if (!Number.isFinite(ageMs) || ageMs < CONFLICTING_HEAD_CI_GRACE_MS)
+        return undefined;
+    return NO_CI_NOTE;
+}
+export function countReportedChecks(checks) {
+    return (checks.passing.length +
+        checks.failing.length +
+        checks.inProgress.length +
+        checks.skipped.length +
+        checks.filtered.length +
+        (checks.ignored?.length ?? 0));
+}
+/** Place the missing-CI note with the conflict step, ahead of later repair lines. */
+export function insertConflictingHeadCiNote(instructions, note) {
+    if (!note)
+        return;
+    const conflictAt = instructions.findIndex((step) => step.includes("merge conflicts"));
+    if (conflictAt >= 0)
+        instructions.splice(conflictAt + 1, 0, note);
+    else
+        instructions.unshift(note);
+}

package/bin/commands/iterate/fix-code.mjs

@@ -8,6 +8,9 @@ import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./thre
 import { buildFixInstructions } from "./render.mjs";
 import { buildReleasedBlockerInstruction } from "./check-instructions.mjs";
 import { buildNativeStackLayerRebase } from "./native-stack-rebase.mjs";
+import { lookupUpperLayerTrunkConflict } from "./stack-trunk-conflict.mjs";
+import { conflictingHeadCiNote, countReportedChecks, insertConflictingHeadCiNote, } from "./conflicting-head-ci.mjs";
+import { conflictingHeadFirstSeenUnix } from "../../state/conflicting-head-seen.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
@@ -282,9 +285,21 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    const headRef = report.headSha;
+    // Only an upper layer can be dirty against trunk while already containing its parent.
+    const trunkConflict = hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
+        ? await lookupUpperLayerTrunkConflict({
+            owner: repoOwner,
+            name: repoName,
+            pr: prNumber,
+            headRef,
+            trunk: stack.baseRefName,
+        })
+        : undefined;
     // Conflicts, and a behind branch whose rerun already failed, both ask for a branch update.
     const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0)
-        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, report.mergeStatus.mergeRequirements?.stack)
+        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict)
         : undefined;
     const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase);
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {
@@ -296,9 +311,23 @@ export async function handleFixCode(ctx) {
     if (repairInstructions && repairInstructions.length > 0) {
         instructions.unshift(...repairInstructions);
     }
+    const checkRunCount = countReportedChecks(report.checks);
+    const suitesEmpty = report.headCheckSuitesEmpty === true;
+    const nowMs = Date.now();
+    const firstSeenAtUnix = hasConflicts && suitesEmpty && checkRunCount === 0 && report.headSha
+        ? await conflictingHeadFirstSeenUnix({ owner: repoOwner, repo: repoName, pr: prNumber }, report.headSha, nowMs)
+        : undefined;
+    insertConflictingHeadCiNote(instructions, conflictingHeadCiNote({
+        hasConflicts,
+        headCheckSuitesEmpty: suitesEmpty,
+        checkRunCount,
+        firstSeenAtUnix,
+        nowMs,
+    }));
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
+        ...(trunkConflict && { stackTrunkConflict: trunkConflict.trunk }),
         action: "fix_code",
         fix: {
             threads,

package/bin/commands/iterate/native-stack-rebase.d.mts

@@ -7,6 +7,8 @@ export type NativeStackRebaseStart = {
     parentBranch: string;
 } | {
     bottomPr: number;
+} | {
+    trunk: string;
 };
 /**
  * One gh-stack rebase step. A native stack layer must not be rebased or merged from its base
@@ -22,12 +24,16 @@ export declare function buildNativeStackRebaseInstruction(repo: string, stackNum
  * workflow keeps failing); undefined outside a stack.
  * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
  * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
- * layer is an upper layer whose parent is its own PR base branch.
+ * layer is an upper layer whose parent is its own PR base branch. `trunkConflict` means that
+ * upper layer already contains its parent, so the rebase starts at the bottom open layer.
  */
 export declare function buildNativeStackLayerRebase(repo: string, pr: {
     number: number;
     baseBranch: string;
-}, stack: StackStatus | undefined): string | undefined;
+}, stack: StackStatus | undefined, trunkConflict?: {
+    trunk: string;
+    bottomPr?: number;
+}): string | undefined;
 /** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
 export declare function buildConflictInstruction(stackRebase: string | undefined): string;
 /** Push a conflict resolution or branch refresh: one branch, or the whole rewritten native stack. */

package/bin/commands/iterate/native-stack-rebase.mjs

@@ -12,7 +12,9 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
             `check out the parent stack branch \`${start.parentBranch}\``,
             "gh stack rebase --upstack --no-trunk",
         ]
-        : [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"];
+        : "bottomPr" in start
+            ? [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"]
+            : [`check out the bottom open layer whose base is \`${start.trunk}\``, "gh stack rebase"];
     const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\`, then confirm every layer's local branch is at its PR's head commit — a stale local layer would overwrite that PR's newer commits on push`;
     return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`; if it stops on a conflict, resolve it and run \`gh stack rebase --continue\`.`;
 }
@@ -21,12 +23,20 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
  * workflow keeps failing); undefined outside a stack.
  * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
  * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
- * layer is an upper layer whose parent is its own PR base branch.
+ * layer is an upper layer whose parent is its own PR base branch. `trunkConflict` means that
+ * upper layer already contains its parent, so the rebase starts at the bottom open layer.
  */
-export function buildNativeStackLayerRebase(repo, pr, stack) {
+export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict) {
     if (!stack)
         return undefined;
-    return buildNativeStackRebaseInstruction(repo, stack.number, pr.baseBranch === stack.baseRefName ? { bottomPr: pr.number } : { parentBranch: pr.baseBranch });
+    const start = trunkConflict
+        ? trunkConflict.bottomPr !== undefined
+            ? { bottomPr: trunkConflict.bottomPr }
+            : { trunk: trunkConflict.trunk }
+        : pr.baseBranch === stack.baseRefName
+            ? { bottomPr: pr.number }
+            : { parentBranch: pr.baseBranch };
+    return buildNativeStackRebaseInstruction(repo, stack.number, start);
 }
 /** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
 export function buildConflictInstruction(stackRebase) {

package/bin/commands/iterate/stack-trunk-conflict.d.mts

@@ -0,0 +1,13 @@
+/** An upper layer already contains its parent, so the dirty state is against trunk. */
+export interface UpperLayerTrunkConflict {
+    trunk: string;
+    /** Open layer whose PR base is the trunk. Omitted when that layer is not on this page. */
+    bottomPr?: number;
+}
+export declare function lookupUpperLayerTrunkConflict(input: {
+    owner: string;
+    name: string;
+    pr: number;
+    headRef: string;
+    trunk: string;
+}): Promise<UpperLayerTrunkConflict | undefined>;

package/bin/commands/iterate/stack-trunk-conflict.mjs

@@ -0,0 +1,51 @@
+import { graphql } from "../../github/client.mjs";
+import { UPPER_LAYER_CONFLICT_TARGET_QUERY } from "../../github/queries.mjs";
+import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
+/** Lowest-position open layer whose base is the stack trunk, if this page contains one. */
+function selectBottomOpenLayer(nodes, trunk) {
+    const onTrunk = nodes.flatMap((node) => {
+        const pull = node?.pullRequest;
+        if (!node || !pull || pull.state !== "OPEN" || pull.baseRefName !== trunk)
+            return [];
+        return [{ position: node.position, number: pull.number }];
+    });
+    onTrunk.sort((a, b) => a.position - b.position);
+    return onTrunk[0]?.number;
+}
+export async function lookupUpperLayerTrunkConflict(input) {
+    let data;
+    try {
+        ({ data } = await graphql(UPPER_LAYER_CONFLICT_TARGET_QUERY, {
+            owner: input.owner,
+            name: input.name,
+            number: input.pr,
+            headRef: input.headRef,
+        }));
+    }
+    catch (err) {
+        if (pollRateLimitRetryAfterMs(err) !== null)
+            throw err;
+        ignore(input.pr, err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+    const pull = data.repository?.pullRequest;
+    const behindBy = pull?.baseRef?.compare?.behindBy;
+    if (!pull || behindBy == null) {
+        ignore(input.pr, pull ? "base comparison unavailable" : "pull request not found");
+        return undefined;
+    }
+    // behindBy > 0: the layer is still behind its parent. Keep the parent rebase.
+    if (behindBy !== 0)
+        return undefined;
+    const entries = pull.stack?.entries;
+    const bottomPr = entries ? selectBottomOpenLayer(entries.nodes, input.trunk) : undefined;
+    if (bottomPr === undefined) {
+        ignore(input.pr, entries?.pageInfo.hasNextPage
+            ? "stack entry page truncated before the trunk layer"
+            : "bottom open layer not found");
+    }
+    return { trunk: input.trunk, ...(bottomPr !== undefined && { bottomPr }) };
+}
+function ignore(pr, message) {
+    process.stderr.write(`pr-shepherd: upper-layer conflict target unavailable for PR #${pr} (ignored): ${message}\n`);
+}

package/bin/github/batch-parse-suites.d.mts

@@ -1,4 +1,6 @@
 import type { CheckRun } from "../types.mts";
 import type { RawPr } from "./batch-raw-types.mts";
 export declare function parseCheckSuitesComplete(raw: RawPr): boolean;
+/** True only when the head commit's suite page finished and listed nothing. */
+export declare function parseHeadCheckSuitesEmpty(raw: RawPr): boolean;
 export declare function parseSuiteStartupFailures(raw: RawPr): CheckRun[];

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

@@ -1,6 +1,11 @@
 export function parseCheckSuitesComplete(raw) {
     return raw.commits.nodes[0]?.commit.checkSuites?.pageInfo.hasNextPage === false;
 }
+/** True only when the head commit's suite page finished and listed nothing. */
+export function parseHeadCheckSuitesEmpty(raw) {
+    const suites = raw.commits.nodes[0]?.commit.checkSuites;
+    return suites?.pageInfo.hasNextPage === false && suites.nodes.length === 0;
+}
 export function parseSuiteStartupFailures(raw) {
     const suites = raw.commits.nodes[0]?.commit.checkSuites;
     if (!suites)

package/bin/github/batch.d.mts

@@ -7,6 +7,8 @@ interface BatchResult {
     rateLimit?: RateLimitInfo;
     /** True when GraphQL returned a complete CheckSuite page; skip REST startup-failure fetch. */
     checkSuitesComplete?: boolean;
+    /** True when that complete page listed no check suites on the head commit. */
+    headCheckSuitesEmpty?: true;
 }
 interface FetchPrBatchOptions {
     /**

package/bin/github/batch.mjs

@@ -2,7 +2,7 @@ import { graphqlWithRateLimit } from "./client.mjs";
 import { hydrateThreadCommentPages } from "./thread-comments.mjs";
 import { BATCH_PR_QUERY } from "./queries.mjs";
 import { parseRawPr } from "./batch-parsers.mjs";
-import { parseCheckSuitesComplete, parseSuiteStartupFailures } from "./batch-parse-suites.mjs";
+import { parseCheckSuitesComplete, parseHeadCheckSuitesEmpty, parseSuiteStartupFailures, } from "./batch-parse-suites.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { paginateBatchConnections } from "./batch-page.mjs";
 import { requireRawPr } from "./batch-response.mjs";
@@ -28,5 +28,6 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
         fingerprint: fingerprintFromRaw(raw, result.data.repository?.viewerPermission ?? null, result.data.viewer?.login ?? null),
         rateLimit: paged.rateLimit ?? result.rateLimit,
         ...(parseCheckSuitesComplete(raw) && { checkSuitesComplete: true }),
+        ...(parseHeadCheckSuitesEmpty(raw) && { headCheckSuitesEmpty: true }),
     };
 }

package/bin/github/gql/upper-layer-conflict-target.gql

@@ -0,0 +1,36 @@
+query UpperLayerConflictTarget($owner: String!, $name: String!, $number: Int!, $headRef: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      # compare() is invoked on the PR base. behindBy is commits on that base
+      # that the head does not contain — the same direction as REST base...head.
+      baseRef {
+        compare(headRef: $headRef) {
+          behindBy
+        }
+      }
+      stack {
+        entries(first: 100) {
+          pageInfo {
+            hasNextPage
+          }
+          nodes {
+            position
+            pullRequest {
+              number
+              state
+              baseRefName
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/queries.d.mts

@@ -23,6 +23,11 @@ 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. */

package/bin/github/queries.mjs

@@ -28,6 +28,11 @@ 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. */

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.54.0",
+  "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.54.0",
+  "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.54.0", "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.54.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.54.1", "pr-shepherd-mcp"]
   }
 }