pr-shepherd 0.51.0 → 0.52.0

package/bin/commands/iterate/index.mjs

@@ -16,6 +16,14 @@ import { buildReadyMergeOutcome, handleActiveMergeState } from "./merge-state.mj
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
 import { withIterateApiUsage } from "./run.mjs";
+import { fetchRawSummaryPr } from "../../github/poll-summary.mjs";
+import { summarizePollSummaryPr } from "../../github/poll-summary-projector.mjs";
+import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.mjs";
+import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
+import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
+import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
+import { parentBlocksMarkReady } from "./parent-first.mjs";
+import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -80,8 +88,19 @@ async function runIterateCore(opts) {
         editedSummaries.length > 0 ||
         (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
     const activeMerge = Boolean(opts.merge && (report.mergeQueue?.inQueue || report.mergeQueue?.autoMergeRequest));
-    const isCleanReadyState = report.status === "READY" && !hasActionableWork && !activeMerge;
+    const staleAncestry = await findStaleNativeStackAncestry(report, {
+        owner: repoOwner,
+        name: repoName,
+    });
+    const isCleanReadyState = report.status === "READY" &&
+        !report.mergeStatus.isDraft &&
+        !hasActionableWork &&
+        !activeMerge &&
+        staleAncestry === null;
     const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName);
+    if (report.mergeStatus.mergeRequirements?.stack) {
+        await invalidateStaleReadyReceipt({ owner: repoOwner, repo: repoName, pr: report.pr }, report, hasActionableWork);
+    }
     const base = buildIterateBase(report, readyState);
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
@@ -126,13 +145,50 @@ async function runIterateCore(opts) {
     });
     if (mergeStateResult)
         return mergeStateResult;
+    if (staleAncestry) {
+        return handleFixCode({
+            base,
+            report,
+            opts: { ...opts, prNumber, neverCancelRuns },
+            headSha,
+            stallKey,
+            prNumber,
+            stallTimeoutSeconds,
+            repoOwner,
+            repoName,
+            reviewSummaryIds,
+            firstLookSummaries,
+            editedSummaries,
+            surfacedApprovals,
+            botUsernames,
+            repairInstructions: staleAncestry.instructions,
+            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
+        });
+    }
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
-    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady, base, report);
+    const blockedByParent = canMarkReady
+        ? await parentBlocksMarkReady(report, { owner: repoOwner, name: repoName })
+        : false;
+    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !blockedByParent && !opts.noAutoMarkReady && config.actions.autoMarkReady, base, report);
     if (markReadyResult)
         return markReadyResult;
-    if (readyState.shouldCancel) {
+    if (readyState.shouldCancel && !report.mergeStatus.isDraft) {
+        const needsStackReceipt = report.mergeStatus.mergeRequirements?.stack !== undefined;
+        const receiptWritten = needsStackReceipt
+            ? await recordReadyReceipt({ owner: repoOwner, repo: repoName, pr: report.pr }, report)
+            : true;
+        if (!receiptWritten) {
+            const receiptWait = {
+                ...base,
+                action: "wait",
+                shouldCancel: false,
+                remainingSeconds: readyDelaySeconds,
+                log: `WAIT: PR #${base.pr} reached ready-delay but its stack readiness receipt could not be persisted`,
+            };
+            return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, report, reviewSummaryIds);
+        }
         await clearStallState(stallKey);
         const mergeResult = buildReadyMergeOutcome(opts.merge, true, base, report);
         if (mergeResult)
@@ -147,3 +203,84 @@ async function runIterateCore(opts) {
     }
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, { ...base, action: "wait", log: buildWaitLog(base) }, report, reviewSummaryIds);
 }
+async function recordReadyReceipt(key, report) {
+    if (report.status !== "READY" ||
+        report.mergeStatus.state !== "OPEN" ||
+        report.mergeStatus.isDraft ||
+        !report.headSha ||
+        !report.baseRefOid)
+        return false;
+    try {
+        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const fingerprint = fingerprintRawSummaryPr(raw);
+        if (fingerprint === null ||
+            raw.state !== "OPEN" ||
+            raw.isDraft ||
+            raw.headRefOid !== report.headSha ||
+            raw.baseRefOid !== report.baseRefOid)
+            return false;
+        const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
+        if (!isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {}))
+            return false;
+        const removalEvent = currentQueueRemovalEvent(raw);
+        await writeReadyReceipt({
+            version: 1,
+            ...key,
+            headRefOid: raw.headRefOid,
+            baseRefOid: raw.baseRefOid,
+            status: "READY",
+            isDraft: false,
+            readinessFingerprint: fingerprint,
+            ...(removalEvent?.id && {
+                acknowledgedQueueRemovalId: removalEvent.id,
+            }),
+            recordedAtUnix: Math.floor(Date.now() / 1000),
+        });
+        return true;
+    }
+    catch {
+        // The receipt is supplementary evidence. A transient summary fetch or
+        // state-directory failure must not turn a completed one-PR poll into a
+        // different Shepherd action.
+        return false;
+    }
+}
+async function invalidateStaleReadyReceipt(key, report, hasActionableWork) {
+    const receipt = await readReadyReceipt(key);
+    if (!receipt)
+        return;
+    const retainQueuedReceipt = report.mergeQueue?.inQueue === true &&
+        report.mergeStatus.state === "OPEN" &&
+        !report.mergeStatus.isDraft &&
+        Boolean(report.headSha && report.baseRefOid);
+    if (report.mergeStatus.state !== "OPEN" ||
+        report.mergeStatus.isDraft ||
+        !report.headSha ||
+        !report.baseRefOid ||
+        (!retainQueuedReceipt && (report.status !== "READY" || hasActionableWork))) {
+        await clearReadyReceipt(key);
+        return;
+    }
+    try {
+        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        // Queue predecessors can advance the target branch without changing this
+        // PR's source. Compare against the receipt's base only while both fresh
+        // views still place the PR in the queue.
+        const queuedBaseAdvanced = retainQueuedReceipt && raw.isInMergeQueue;
+        const fingerprint = fingerprintRawSummaryPr(queuedBaseAdvanced ? { ...raw, baseRefOid: receipt.baseRefOid } : raw);
+        if (fingerprint === null ||
+            !isReadyReceiptCurrent(receipt, {
+                headRefOid: raw.headRefOid,
+                baseRefOid: queuedBaseAdvanced ? receipt.baseRefOid : raw.baseRefOid,
+                readinessFingerprint: fingerprint,
+                status: "READY",
+                isDraft: raw.isDraft,
+            })) {
+            await clearReadyReceipt(key);
+        }
+    }
+    catch {
+        // Fail closed: an unreadable current snapshot cannot validate old evidence.
+        await clearReadyReceipt(key);
+    }
+}

package/bin/commands/iterate/merge-state.mjs

@@ -2,26 +2,41 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
 import { buildMergeCommandPlan } from "./merge.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
-/** A stacked PR's merge is human-only: `gh pr merge` targets the PR's own base, which for a
- * mid-stack layer is an unmerged parent branch, and auto-merge is unsupported on stacks. */
-function buildStackedEscalateResult(base, report, stack) {
-    const escalateBase = {
-        triggers: ["stacked-pr"],
-        unresolvedThreads: [],
-        ambiguousComments: [],
-        changesRequestedReviews: [],
-        stack,
-        suggestion: buildEscalateSuggestion(["stacked-pr"], String(report.pr)),
-    };
+/**
+ * A one-PR poll cannot prove every native-stack layer is ready or linear. Route it through the
+ * aggregate stack selector, which does that reconciliation before emitting the whole-stack merge.
+ */
+function buildStackedRouteResult(base, report, stack) {
+    const prUrl = formatPrUrl(report.repo, report.pr);
     return {
         ...base,
-        action: "escalate",
-        escalate: {
-            ...escalateBase,
-            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
-                merge: true,
-            }),
+        action: "fix_code",
+        fix: {
+            threads: [],
+            resolutionOnlyThreads: [],
+            actionableComments: [],
+            reviewSummaryIds: [],
+            firstLookSummaries: [],
+            editedSummaries: [],
+            surfacedApprovals: [],
+            checks: [],
+            changesRequestedReviews: [],
+            resolveCommand: {
+                argv: ["pr-shepherd", "apply", "review", prUrl],
+                requiresHeadSha: false,
+                requiresDismissMessage: false,
+                hasMutations: false,
+            },
+            instructions: [
+                `PR #${report.pr} is layer ${stack.position} of ${stack.size} in native stack #${stack.number}; do not run \`gh pr merge\` for this layer.`,
+                `Run \`pr-shepherd --stack ${prUrl} --until-terminal --merge\` to reconcile the complete stack and run its emitted whole-stack merge command.`,
+            ],
+            inProgressRunIds: [],
+            protectedRuns: [],
+            firstLookThreads: [],
+            firstLookComments: [],
         },
+        cancelled: [],
     };
 }
 export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
@@ -29,7 +44,7 @@ export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
         return null;
     const stack = report.mergeStatus.mergeRequirements?.stack;
     if (stack)
-        return buildStackedEscalateResult(base, report, stack);
+        return buildStackedRouteResult(base, report, stack);
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
     return {

package/bin/commands/iterate/parent-first.d.mts

@@ -0,0 +1,9 @@
+import type { RepoInfo } from "../../github/client.mts";
+import type { ShepherdReport } from "../../types.mts";
+/**
+ * Draft children may only be converted after their immediate parent has
+ * independently completed a one-PR ready-delay and the stack boundary is
+ * still linear.  A failed or incomplete stack read blocks this mutation but
+ * does not block ordinary review/CI work in the caller.
+ */
+export declare function parentBlocksMarkReady(report: ShepherdReport, repo: RepoInfo): Promise<boolean>;

package/bin/commands/iterate/parent-first.mjs

@@ -0,0 +1,57 @@
+import { fetchPollSummary } from "../../github/poll-summary.mjs";
+/**
+ * Draft children may only be converted after their immediate parent has
+ * independently completed a one-PR ready-delay and the stack boundary is
+ * still linear.  A failed or incomplete stack read blocks this mutation but
+ * does not block ordinary review/CI work in the caller.
+ */
+export async function parentBlocksMarkReady(report, repo) {
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (!stack || stack.position === 1)
+        return false;
+    if (stack.position < 1)
+        return true;
+    try {
+        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
+        const child = summary.prs.find((item) => item.pr === report.pr);
+        const lowerLayers = summary.prs
+            .filter((item) => (item.stack?.position ?? Number.MAX_SAFE_INTEGER) < stack.position)
+            .sort((left, right) => (left.stack?.position ?? Number.MAX_SAFE_INTEGER) -
+            (right.stack?.position ?? Number.MAX_SAFE_INTEGER));
+        if (!child || child.state !== "OPEN" || lowerLayers.length !== stack.position - 1)
+            return true;
+        // Any stale boundary up through the child means at least one lower layer
+        // is no longer the base it was reviewed against. Ignore gaps above this
+        // child because they do not affect its immediate promotion boundary.
+        const checkedLayers = new Set([report.pr, ...lowerLayers.map((item) => item.pr)]);
+        if (summary.stackAncestry?.some((gap) => checkedLayers.has(gap.childPr)))
+            return true;
+        for (const parent of lowerLayers) {
+            // A merged parent is already satisfied; GitHub may have retargeted the
+            // child to the trunk as part of the merge.
+            if (parent.state === "MERGED")
+                continue;
+            if (parent.state !== "OPEN")
+                return true;
+            if (parent.isDraft || parent.mergeable === "CONFLICTING")
+                return true;
+            if (["DIRTY", "BEHIND", "UNKNOWN"].includes(parent.mergeStateStatus))
+                return true;
+            // A receipt only establishes readiness after a merge-queue removal once
+            // the one-PR session has observed and acknowledged that exact removal.
+            // The aggregate projection preserves an unacknowledged removal here, so
+            // do not let its otherwise-current receipt promote a child draft.
+            if (parent.queueRemoval)
+                return true;
+            // A parent that looks ready but has not completed its own one-PR receipt
+            // is not sufficient evidence for a child draft transition.
+            if (parent.readyReceipt !== true)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        // Never convert a child draft based on an unverifiable parent.
+        return true;
+    }
+}

package/bin/commands/iterate/stale-ancestry.d.mts

@@ -0,0 +1,22 @@
+import type { RepoInfo } from "../../github/client.mts";
+import type { PollSummaryStackAncestry } from "../../types.mts";
+import type { ShepherdReport } from "../../types/report.mts";
+/**
+ * A verified stale boundary for the PR being shepherded.
+ *
+ * The aggregate stack read is authoritative for this check: it compares the
+ * child's recorded base OID with the current head OID of its immediate open
+ * parent. GitHub can report both PRs CLEAN while this boundary is stale.
+ */
+export interface StaleNativeStackAncestry extends PollSummaryStackAncestry {
+    instructions: string[];
+}
+/**
+ * Find a stale immediate parent boundary for one PR.
+ *
+ * This helper is intentionally read-only. A null result means either the PR is
+ * not a non-root native-stack layer, its boundary is current, or the boundary
+ * could not be verified. Callers must not emit a repair command from an
+ * unverified snapshot.
+ */
+export declare function findStaleNativeStackAncestry(report: Pick<ShepherdReport, "pr" | "mergeStatus">, repo: RepoInfo): Promise<StaleNativeStackAncestry | null>;

package/bin/commands/iterate/stale-ancestry.mjs

@@ -0,0 +1,37 @@
+import { fetchPollSummary } from "../../github/poll-summary.mjs";
+/**
+ * Find a stale immediate parent boundary for one PR.
+ *
+ * This helper is intentionally read-only. A null result means either the PR is
+ * not a non-root native-stack layer, its boundary is current, or the boundary
+ * could not be verified. Callers must not emit a repair command from an
+ * unverified snapshot.
+ */
+export async function findStaleNativeStackAncestry(report, repo) {
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (!stack || stack.position <= 1)
+        return null;
+    try {
+        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
+        const ancestry = summary.stackAncestry?.find((gap) => gap.childPr === report.pr);
+        if (!ancestry)
+            return null;
+        return {
+            ...ancestry,
+            instructions: buildStaleNativeStackAncestryInstructions(repo, ancestry),
+        };
+    }
+    catch {
+        // A stale repair is safe only when both OIDs were observed together. Let
+        // the caller retain the ordinary WAIT/ESCALATE path on an unreadable stack.
+        return null;
+    }
+}
+/** Build the one-PR repair guidance after a stale boundary was verified. */
+function buildStaleNativeStackAncestryInstructions(repo, ancestry) {
+    return [
+        `PR #${ancestry.childPr} records base \`${ancestry.childBaseRefName}\` at \`${ancestry.childBaseRefOid}\`, but its open parent PR #${ancestry.parentPr} currently ends at \`${ancestry.parentHeadRefName}\` \`${ancestry.parentHeadRefOid}\`.`,
+        `From a clean checkout of \`${repo.owner}/${repo.name}\`, check out the parent stack branch \`${ancestry.parentHeadRefName}\`.`,
+        "Run `gh stack rebase --upstack --no-trunk`, resolve any conflicts, and push the rewritten stack with `gh stack push`.",
+    ];
+}