pr-shepherd 0.51.0 → 0.52.0

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

@@ -3,8 +3,12 @@ import { updateReadyDelay } from "../commands/ready-delay.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 import { loadSeenMap } from "../state/seen-comments.mjs";
+import { isReadyReceiptCurrent, readReadyReceipt } from "../state/ready-receipts.mjs";
 import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
 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 { normalizePollSummaryState, routePollSummary } from "./poll-summary-route.mjs";
 export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdminister = false) {
     const repoName = `${repo.owner}/${repo.name}`;
@@ -12,6 +16,7 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
     const checks = summarizePollSummaryChecks(raw);
     const review = await summarizePollSummaryReview(raw, seen, viewerCanAdminister);
     const blockingReviewerInProgress = detectBlockingReviewer(raw);
+    const removalEvent = currentQueueRemovalEvent(raw);
     let { action, reasons } = routePollSummary(raw, checks, review, opts);
     let remainingSeconds;
     if (raw.isDraft && blockingReviewerInProgress && action === "mark_ready") {
@@ -19,12 +24,14 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
         reasons = ["blocking-reviewer-in-progress"];
     }
     const appearsReady = reasons.includes("appears-ready");
-    const readyDelaySeconds = opts.readyDelaySeconds ?? (loadConfig().watch?.readyDelayMinutes ?? 10) * 60;
-    const readyState = await updateReadyDelay(raw.number, appearsReady, readyDelaySeconds, repo.owner, repo.name, { retainElapsed: true });
-    if (appearsReady && !readyState.shouldCancel) {
-        action = "wait";
-        reasons = ["ready-delay"];
-        remainingSeconds = readyState.remainingSeconds;
+    if (opts.stackPrNumber === undefined) {
+        const readyDelaySeconds = opts.readyDelaySeconds ?? (loadConfig().watch?.readyDelayMinutes ?? 10) * 60;
+        const readyState = await updateReadyDelay(raw.number, appearsReady, readyDelaySeconds, repo.owner, repo.name, { retainElapsed: true });
+        if (appearsReady && !readyState.shouldCancel) {
+            action = "wait";
+            reasons = ["ready-delay"];
+            remainingSeconds = readyState.remainingSeconds;
+        }
     }
     const stack = raw.stack
         ? {
@@ -34,6 +41,32 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
             baseRefName: raw.stack.baseRefName,
         }
         : undefined;
+    const fingerprint = opts.stackPrNumber !== undefined ? fingerprintRawSummaryPr(raw) : null;
+    const receipt = fingerprint
+        ? await readReadyReceipt({ owner: repo.owner, repo: repo.name, pr: raw.number })
+        : null;
+    // A queued PR's target branch can advance as earlier queue entries merge.
+    // Keep the pre-enqueue base binding for the receipt comparison while the
+    // merge group itself supplies the current mergeability evidence.
+    const receiptFingerprint = raw.isInMergeQueue && receipt
+        ? fingerprintRawSummaryPr({ ...raw, baseRefOid: receipt.baseRefOid })
+        : fingerprint;
+    const currentReady = isCurrentSummaryReady(raw, checks, review, {
+        allowQueuedProgress: opts.stackPrNumber !== undefined && raw.isInMergeQueue,
+    });
+    const readyReceipt = receiptFingerprint !== null &&
+        isReadyReceiptCurrent(receipt, {
+            headRefOid: raw.headRefOid,
+            baseRefOid: raw.isInMergeQueue && receipt ? receipt.baseRefOid : raw.baseRefOid,
+            readinessFingerprint: receiptFingerprint,
+            status: currentReady ? "READY" : "PENDING",
+            isDraft: raw.isDraft,
+        });
+    const queueRemoval = removalEvent?.id && readyReceipt && receipt?.acknowledgedQueueRemovalId === removalEvent.id
+        ? undefined
+        : removalEvent
+            ? projectQueueRemoval(removalEvent)
+            : undefined;
     return {
         pr: raw.number,
         repo: repoName,
@@ -50,15 +83,31 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
         baseRefName: raw.baseRefName,
         ...(raw.isDraft && { isDraft: true }),
         ...(raw.isInMergeQueue && { isInMergeQueue: true }),
+        ...(queueRemoval && { queueRemoval }),
         ...(blockingReviewerInProgress && { blockingReviewerInProgress: true }),
         ...(remainingSeconds !== undefined && { remainingSeconds }),
         ...(Object.keys(checks).length > 0 && { checks }),
         ...(Object.keys(review).length > 0 && { review }),
         ...(stack && { stack }),
-        ...(!["wait", "cancel"].includes(action) &&
-            !(opts.stackPrNumber !== undefined && raw.stack && action === "merge") && {
-            pollCommand: buildPollCommand(repoName, raw.number, opts),
-        }),
+        ...(readyReceipt && { readyReceipt: true }),
+        ...((opts.stackPrNumber !== undefined && raw.state === "OPEN") ||
+            (!["wait", "cancel"].includes(action) &&
+                !(opts.stackPrNumber !== undefined && raw.stack && action === "merge"))
+            ? {
+                pollCommand: buildPollCommand(repoName, raw.number, raw.isDraft, opts),
+            }
+            : {}),
+    };
+}
+function projectQueueRemoval(removal) {
+    const removalTime = Date.parse(removal.createdAt);
+    const parents = removal.beforeCommit?.parents?.nodes.map((parent) => parent.oid) ?? [];
+    return {
+        reason: removal.reason,
+        createdAtUnix: Math.floor(removalTime / 1000),
+        ...(removal.actor?.login && { actor: removal.actor.login }),
+        ...(removal.beforeCommit?.oid && { beforeCommitOid: removal.beforeCommit.oid }),
+        beforeCommitParentOids: parents,
     };
 }
 function detectBlockingReviewer(raw) {
@@ -67,16 +116,20 @@ function detectBlockingReviewer(raw) {
     return ((raw.reviewRequests?.nodes ?? []).some((request) => matches(request.requestedReviewer)) ||
         (raw.latestReviews?.nodes ?? []).some((review) => review.state === "PENDING" && matches(review.author)));
 }
-function buildPollCommand(repo, pr, opts) {
-    const args = [formatPrUrl(repo, pr), "--until-terminal"];
-    if (opts.merge)
+function buildPollCommand(repo, pr, isDraft, opts) {
+    const autoMarkReadyDisabled = opts.noAutoMarkReady || loadConfig().actions.autoMarkReady === false;
+    const boundedDraft = isDraft && autoMarkReadyDisabled;
+    const args = boundedDraft
+        ? [formatPrUrl(repo, pr), "--timeout", "1s", "--debounce", "0s", "--no-auto-mark-ready"]
+        : [formatPrUrl(repo, pr), "--until-terminal"];
+    if (opts.merge && opts.stackPrNumber === undefined)
         args.push("--merge");
     if (opts.readyDelaySeconds !== undefined)
         args.push("--ready-delay", `${opts.readyDelaySeconds}s`);
     if (opts.stallTimeoutSeconds !== undefined) {
         args.push("--stall-timeout", `${opts.stallTimeoutSeconds}s`);
     }
-    if (opts.noAutoMarkReady)
+    if (opts.noAutoMarkReady && !boundedDraft)
         args.push("--no-auto-mark-ready");
     return buildPrShepherdCommand(args).text;
 }

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

@@ -0,0 +1,5 @@
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+type QueueRemovalEvent = NonNullable<RawSummaryPr["mergeQueueRemovals"]>["nodes"][number];
+/** Latest queue removal that still applies to this PR head, not an older attempt. */
+export declare function currentQueueRemovalEvent(raw: RawSummaryPr): QueueRemovalEvent | null;
+export {};

package/bin/github/poll-summary-queue-removal.mjs

@@ -0,0 +1,16 @@
+/** Latest queue removal that still applies to this PR head, not an older attempt. */
+export function currentQueueRemovalEvent(raw) {
+    const removal = raw.mergeQueueRemovals?.nodes[0];
+    if (!removal || raw.isInMergeQueue)
+        return null;
+    const removalTime = Date.parse(removal.createdAt);
+    if (!Number.isFinite(removalTime))
+        return null;
+    const addition = raw.mergeQueueAdditions?.nodes[0];
+    if (addition && Date.parse(addition.createdAt) > removalTime)
+        return null;
+    const parents = removal.beforeCommit?.parents?.nodes.map((parent) => parent.oid);
+    if (!parents?.includes(raw.headRefOid))
+        return null;
+    return removal;
+}

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

@@ -25,6 +25,9 @@ type RawCheckContext = {
     status: string;
     conclusion: string | null;
     detailsUrl?: string;
+    annotations?: {
+        totalCount: number;
+    };
     checkSuite: {
         workflowRun: {
             databaseId?: string | number;
@@ -48,6 +51,13 @@ export interface RawSummaryPr {
     title: string;
     url: string;
     state: string;
+    updatedAt?: string;
+    lifecycleEvents?: {
+        nodes: Array<{
+            __typename: string;
+            createdAt: string;
+        }>;
+    } | null;
     isDraft: boolean;
     viewerCanUpdate: boolean;
     headRefName: string;
@@ -69,6 +79,29 @@ export interface RawSummaryPr {
         }>;
     };
     isInMergeQueue: boolean;
+    mergeQueueAdditions?: {
+        nodes: Array<{
+            createdAt: string;
+        }>;
+    } | null;
+    mergeQueueRemovals?: {
+        nodes: Array<{
+            id?: string;
+            reason: string | null;
+            createdAt: string;
+            actor: {
+                login: string;
+            } | null;
+            beforeCommit: {
+                oid: string;
+                parents: {
+                    nodes: Array<{
+                        oid: string;
+                    }>;
+                } | null;
+            } | null;
+        }>;
+    } | null;
     mergeQueueEntry: {
         headCommit: {
             statusCheckRollup: RawCheckRollup | null;

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

@@ -0,0 +1,6 @@
+import type { PollSummaryChecks, PollSummaryReview } from "../types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/** Fresh compact evidence required before a READY receipt can be used. */
+export declare function isCurrentSummaryReady(raw: RawSummaryPr, checks: PollSummaryChecks, review: PollSummaryReview, options?: {
+    allowQueuedProgress?: boolean;
+}): boolean;

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

@@ -0,0 +1,25 @@
+import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
+/** Fresh compact evidence required before a READY receipt can be used. */
+export function isCurrentSummaryReady(raw, checks, review, options = {}) {
+    const queued = options.allowQueuedProgress === true && raw.isInMergeQueue;
+    // Merge-group checks may still be running after the PR earned its receipt;
+    // source-commit checks must remain complete. A fresh pending source check is
+    // not made ready merely by entering the queue.
+    const sourceChecks = queued
+        ? summarizePollSummaryChecks({ ...raw, mergeQueueEntry: null })
+        : checks;
+    return (checks.incomplete !== true &&
+        sourceChecks.incomplete !== true &&
+        review.incomplete !== true &&
+        raw.state === "OPEN" &&
+        !raw.isDraft &&
+        raw.mergeable !== "CONFLICTING" &&
+        raw.mergeStateStatus !== "DIRTY" &&
+        (queued || raw.mergeable === "MERGEABLE") &&
+        (queued ||
+            !["DIRTY", "BEHIND", "UNKNOWN", "BLOCKED", "HAS_HOOKS"].includes(raw.mergeStateStatus)) &&
+        (checks.failing ?? 0) === 0 &&
+        (sourceChecks.failing ?? 0) === 0 &&
+        (sourceChecks.inProgress ?? 0) === 0 &&
+        (review.actionable ?? 0) === 0);
+}

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

@@ -1,8 +1,11 @@
 import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection, PollSummaryStackAncestry } from "../types.mts";
 import { type RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
 export interface FetchedPollSummary {
     selection: PollSummarySelection;
     prs: PollSummaryItem[];
     stackAncestry?: PollSummaryStackAncestry[];
 }
 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. */
+export declare function fetchRawSummaryPr(pr: number, repo: RepoInfo): Promise<RawSummaryPr>;

package/bin/github/poll-summary.mjs

@@ -24,6 +24,11 @@ export async function fetchPollSummary(opts, repo) {
         prs: await Promise.all(raw.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
     };
 }
+/** Fresh, read-only snapshot used to bind a one-PR READY receipt to stack routing. */
+export async function fetchRawSummaryPr(pr, repo) {
+    const fetched = await fetchExplicitChunk([pr], repo);
+    return fetched.prs[0];
+}
 async function fetchExplicitChunk(prs, repo) {
     const declarations = prs.map((_, index) => `$pr${index}: Int!`).join(", ");
     const aliases = prs

package/bin/state/ready-receipts.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Durable evidence that a single-PR Shepherd poll observed a ready PR after
+ * its ready-delay elapsed.  The ref OIDs and readiness fingerprint are part of
+ * the evidence: a receipt is never a general-purpose "this PR is ready"
+ * cache.
+ */
+export interface ReadyReceipt {
+    version: 1;
+    owner: string;
+    repo: string;
+    pr: number;
+    headRefOid: string;
+    baseRefOid: string;
+    status: "READY";
+    isDraft: false;
+    /** Canonical representation of the readiness inputs observed by Shepherd. */
+    readinessFingerprint: string;
+    /** Exact merge-queue removal observed by the one-PR session, if any. */
+    acknowledgedQueueRemovalId?: string;
+    recordedAtUnix: number;
+}
+export interface ReadyReceiptKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export interface ReadyReceiptCurrentState {
+    headRefOid: string;
+    baseRefOid: string;
+    readinessFingerprint: string;
+    status: string;
+    isDraft: boolean;
+}
+/** Read a persisted one-PR readiness receipt. Invalid/stale-shaped files are ignored. */
+export declare function readReadyReceipt(key: ReadyReceiptKey): Promise<ReadyReceipt | null>;
+/** Persist evidence for a completed one-PR ready-delay observation. */
+export declare function writeReadyReceipt(receipt: ReadyReceipt): Promise<void>;
+/** Remove a receipt after the observed PR state no longer matches it. */
+export declare function clearReadyReceipt(key: ReadyReceiptKey): Promise<void>;
+/**
+ * Check the complete binding before using a receipt for aggregate routing.
+ * Callers must provide a fresh fingerprint from the same readiness inputs used
+ * to create the receipt; ref OIDs alone are not sufficient.
+ */
+export declare function isReadyReceiptCurrent(receipt: ReadyReceipt | null, current: ReadyReceiptCurrentState): receipt is ReadyReceipt;

package/bin/state/ready-receipts.mjs

@@ -0,0 +1,86 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+/** Read a persisted one-PR readiness receipt. Invalid/stale-shaped files are ignored. */
+export async function readReadyReceipt(key) {
+    const path = receiptPath(key);
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        return isReadyReceipt(parsed) && sameKey(parsed, key) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist evidence for a completed one-PR ready-delay observation. */
+export async function writeReadyReceipt(receipt) {
+    if (!isReadyReceipt(receipt))
+        throw new Error("Invalid ready receipt");
+    const path = receiptPath(receipt);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(receipt)}\n`, "utf8");
+}
+/** Remove a receipt after the observed PR state no longer matches it. */
+export async function clearReadyReceipt(key) {
+    try {
+        await unlink(receiptPath(key));
+    }
+    catch (error) {
+        // Missing receipts are already clear. Any other failure must reach the
+        // caller so stale evidence cannot be silently retained as if it cleared.
+        if (isNodeErrorCode(error, "ENOENT"))
+            return;
+        throw error;
+    }
+}
+function isNodeErrorCode(error, code) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === code);
+}
+/**
+ * Check the complete binding before using a receipt for aggregate routing.
+ * Callers must provide a fresh fingerprint from the same readiness inputs used
+ * to create the receipt; ref OIDs alone are not sufficient.
+ */
+export function isReadyReceiptCurrent(receipt, current) {
+    return (receipt !== null &&
+        receipt.status === "READY" &&
+        receipt.isDraft === false &&
+        current.status === "READY" &&
+        current.isDraft === false &&
+        receipt.headRefOid === current.headRefOid &&
+        receipt.baseRefOid === current.baseRefOid &&
+        receipt.readinessFingerprint === current.readinessFingerprint);
+}
+function receiptPath(key) {
+    return resolvePrStatePath(key, "ready-receipt.json");
+}
+function sameKey(receipt, key) {
+    return receipt.owner === key.owner && receipt.repo === key.repo && receipt.pr === key.pr;
+}
+function isReadyReceipt(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (candidate.version === 1 &&
+        typeof candidate.owner === "string" &&
+        typeof candidate.repo === "string" &&
+        typeof candidate.pr === "number" &&
+        Number.isInteger(candidate.pr) &&
+        candidate.pr > 0 &&
+        typeof candidate.headRefOid === "string" &&
+        candidate.headRefOid.length > 0 &&
+        typeof candidate.baseRefOid === "string" &&
+        candidate.baseRefOid.length > 0 &&
+        candidate.status === "READY" &&
+        candidate.isDraft === false &&
+        typeof candidate.readinessFingerprint === "string" &&
+        candidate.readinessFingerprint.length > 0 &&
+        (candidate.acknowledgedQueueRemovalId === undefined ||
+            (typeof candidate.acknowledgedQueueRemovalId === "string" &&
+                candidate.acknowledgedQueueRemovalId.length > 0)) &&
+        typeof candidate.recordedAtUnix === "number" &&
+        Number.isFinite(candidate.recordedAtUnix));
+}

package/bin/types/escalate.d.mts

@@ -1,8 +1,8 @@
 import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
-import type { MergeQueueRemovalStatus, StackStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed" | "stacked-pr";
+import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;
@@ -39,7 +39,6 @@ export interface EscalateDetails {
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;
-    stack?: StackStatus;
     authorization?: Array<{
         action: "mark-ready" | "merge-or-enqueue";
         targetIds: string[];

package/bin/types/github.d.mts

@@ -144,6 +144,8 @@ export interface BatchPrData extends BatchPrMergeFields {
     headRepoWithOwner: string | null;
     viewerAuthorization?: ViewerAuthorization;
     baseRefName: string;
+    /** Git OID of the base branch tip observed with this PR, when available. */
+    baseRefOid?: string;
     reviewRequests: Array<{
         login: string;
     }>;

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

@@ -1,5 +1,6 @@
 import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
 import type { MergeableState, MergeStateStatus, ReviewDecision } from "./github.mts";
+import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
 import type { ShepherdAction } from "./iterate.mts";
 export interface PollSummaryChecks {
     passing?: number;
@@ -50,12 +51,17 @@ export interface PollSummaryItem {
     baseRefName: string;
     isDraft?: true;
     isInMergeQueue?: true;
+    queueRemoval?: MergeQueueRemovalStatus;
     blockingReviewerInProgress?: true;
     remainingSeconds?: number;
     checks?: PollSummaryChecks;
     review?: PollSummaryReview;
     stack?: PollSummaryStack;
     pollCommand?: string;
+    /** A current one-PR READY-after-delay completion was verified. */
+    readyReceipt?: true;
+    /** Lowest unready ancestor that prevents this layer from being stack-mergeable. */
+    blockedByPr?: number;
 }
 export type PollSummarySelection = {
     kind: "prs";
@@ -66,6 +72,8 @@ export type PollSummarySelection = {
     stackNumber: number;
     stackSize: number;
 };
+/** Aggregate-only transition; one-PR actions remain unchanged. */
+export type StackNextAction = "shepherd" | "wait" | "merge" | "cancel" | "escalate";
 export interface PollSummaryResult {
     mode: "summary";
     repo: string;
@@ -74,8 +82,10 @@ export interface PollSummaryResult {
     prs: PollSummaryItem[];
     /** Present only for native-stack boundaries whose recorded refs differ. */
     stackAncestry?: PollSummaryStackAncestry[];
-    /** The next stack-level transition, which may differ from an individual row's hint. */
-    nextAction?: ShepherdAction;
+    /** Immediate stack transition; human blockers surface in rows while shepherdable work remains. */
+    nextAction?: StackNextAction;
+    /** Whether every open layer is independently ready and stack ancestry is linear. */
+    stackMergeable?: boolean;
     instructions?: string[];
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;

package/bin/types/report.d.mts

@@ -31,6 +31,8 @@ export interface ShepherdReport {
     status: ShepherdStatus;
     /** PR base branch from the GraphQL batch. */
     baseBranch: string;
+    /** Git OID of the base branch tip observed with this report, when available. */
+    baseRefOid?: string;
     mergeStatus: MergeStatusResult;
     checks: {
         passing: ClassifiedCheck[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -85,14 +85,14 @@
   "devDependencies": {
     "@types/node": "^26.0.0",
     "@types/picomatch": "^4.0.3",
-    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/coverage-v8": "^5.0.0",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
     "marked": "^18.0.11",
-    "oxfmt": "^0.65.0",
+    "oxfmt": "^0.67.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.4"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22.18.0"

package/plugins/pr-shepherd/.codex-plugin/plugin.json

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

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -20,11 +20,11 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. A clear request to merge, land, or enqueue the selected PR or stack also opts into `--merge` without a literal flag; a request only to create or open a PR does not. When the user asks to shepherd or merge a native stack and supplies an anchor PR without a literal `--stack`, use that PR as the `--stack` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
 
-2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return when any row needs work or all rows are terminal. It also returns for a quota warning or an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when merge intent was requested, and print its full result.
+2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return their next stack action or terminal result. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when merge intent was requested, and print its full result.
 
 3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
 
-4. After completing the returned instructions, immediately repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, and only `[ESCALATE]` hands work to a human. After a push or `rerun:`, do not wait for CI to finish first — you may pull check logs, but do not poll with `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters.
+4. After completing the returned instructions, immediately repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, as is stack-level `[SHEPHERD]`; only `[ESCALATE]` hands work to a human. After a push or `rerun:`, do not wait for CI to finish first — you may pull check logs, but do not poll with `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters.
 
 ## Playbooks
 
@@ -59,7 +59,7 @@ Match each failure's `[conclusion: …]` tag under `## Failing checks` to a rule
 
 More specific rows win over the general "GitHub Actions failure" row — check conclusion first.
 
-A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository role grants GitHub's Actions rerun capability (WRITE+) and GitHub reports the original workflow attempt — Shepherd verified these from `repositoryPermission` and `run_attempt`. Run the printed command at most once. Later attempts carry an `[attempt: N]` tag, never get another command, and return `[ESCALATE]` when no other autonomous work remains, even when a log excerpt exists. A run still in progress, an `ACTION_REQUIRED` run (paused pending manual workflow approval — a rerun cannot grant that approval), a check whose runId does not resolve to a GitHub Actions workflow, or a run whose attempt metadata is unavailable never gets `[rerun authorized]`. When a check has no autonomous follow-up and no other agent work remains, Shepherd returns `[ESCALATE]`; do not invent a handoff from a `[FIX_CODE]` result.
+A `[rerun authorized]` tag with a `rerun:` command means the viewer's repository role grants GitHub's Actions rerun capability (WRITE+) and GitHub reports the original workflow attempt — Shepherd verified these from `repositoryPermission` and `run_attempt`. Run the printed command at most once. Later attempts carry an `[attempt: N]` tag and never get another rerun command; an included log excerpt remains autonomous investigation work, while a later attempt without usable evidence can return `[ESCALATE]` when no other work remains. A run still in progress, an `ACTION_REQUIRED` run (paused pending manual workflow approval — a rerun cannot grant that approval), a check whose runId does not resolve to a GitHub Actions workflow, or a run whose attempt metadata is unavailable never gets `[rerun authorized]`. When a check has no autonomous follow-up and no other agent work remains, Shepherd returns `[ESCALATE]`; do not invent a handoff from a `[FIX_CODE]` result.
 
 When several bullets share one runId (matrix jobs from the same run), the `rerun:` command is printed once, on the first bullet; every bullet for that runId still carries `[rerun authorized]` and is covered by that single command — do not run it more than once.
 

package/bin/state/bot-cr-seen.d.mts

@@ -1,51 +0,0 @@
-/**
- * Persistent first-seen state for bot CHANGES_REQUESTED reviews.
- *
- * Bot CRs are auto-dismissed via `--dismiss-review-ids` in the post-push
- * `apply review:` command. If the agent drops that flag, the bot CR keeps the PR in
- * `CHANGES_REQUESTED` state. This file tracks when each bot CR was first
- * observed so the iterate loop can escalate after `iterate.stallTimeoutMinutes`
- * — independent of the broader fingerprint-based `stall-timeout` mechanism in
- * `iterate-stall.mts` (which only fires when no field of the iterate result
- * changed).
- *
- * State lives in
- * `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/bot-cr-seen.json`.
- *
- * `bodyHash` lets us reset `firstSeenAt` when the bot re-issues the review
- * with a different body, so a fresh review gets the full timeout window.
- */
-interface BotCrSeenEntry {
-    /** Unix timestamp (seconds) when this review was first observed undismissed. */
-    firstSeenAt: number;
-    /** SHA-256 body-hash prefix; reset firstSeenAt when this changes. */
-    bodyHash: string;
-}
-export interface BotCrSeenState {
-    reviews: Record<string, BotCrSeenEntry>;
-}
-interface StateKey {
-    owner: string;
-    repo: string;
-    pr: number;
-}
-export declare function readBotCrSeenState(key: StateKey): Promise<BotCrSeenState | null>;
-export declare function writeBotCrSeenState(key: StateKey, state: BotCrSeenState): Promise<void>;
-/**
- * Update tracked entries against the current set of bot CR reviews:
- * - Insert any new IDs with `firstSeenAt = now` and the current body hash.
- * - Reset `firstSeenAt` for entries whose body hash changed (review re-issued).
- * - Drop entries whose IDs are no longer in the input (review was dismissed
- *   or superseded by an approval).
- *
- * Pure function: returns the next state and the IDs whose age has reached the
- * `stallTimeoutSeconds` threshold (escalate candidates).
- */
-export declare function updateBotCrSeenState(previous: BotCrSeenState | null, currentBotCrReviews: ReadonlyArray<{
-    id: string;
-    body: string;
-}>, nowSeconds: number, stallTimeoutSeconds: number): {
-    next: BotCrSeenState;
-    staleIds: string[];
-};
-export {};