pr-shepherd 0.51.1 → 0.52.1

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,22 @@ export interface PollSummaryItem {
     baseRefName: string;
     isDraft?: true;
     isInMergeQueue?: true;
+    queueRemoval?: MergeQueueRemovalStatus;
     blockingReviewerInProgress?: true;
     remainingSeconds?: number;
     checks?: PollSummaryChecks;
     review?: PollSummaryReview;
     stack?: PollSummaryStack;
     pollCommand?: string;
+    /**
+     * `pollCommand` is one bounded tick without automatic mark-ready: it surfaces and routes review
+     * or CI work but cannot advance this draft, so repeating it for a waiting layer changes nothing.
+     */
+    pollProbe?: true;
+    /** 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 +77,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 +87,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;
+    /** Base commit GitHub recorded for this PR (`PullRequest.baseRefOid`), not the branch's live tip. */
+    baseRefOid?: string;
     mergeStatus: MergeStatusResult;
     checks: {
         passing: ClassifiedCheck[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.51.1",
+  "version": "0.52.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -89,7 +89,7 @@
     "husky": "^9.1.7",
     "knip": "^6.14.1",
     "marked": "^18.0.11",
-    "oxfmt": "^0.66.0",
+    "oxfmt": "^0.67.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"

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

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

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

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.51.1", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.52.1", "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 {};

package/bin/state/bot-cr-seen.mjs

@@ -1,100 +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.
- */
-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";
-import { hashBody } from "./seen-comments.mjs";
-export async function readBotCrSeenState(key) {
-    try {
-        const raw = await readFile(resolvePath(key), "utf8");
-        const parsed = JSON.parse(raw);
-        if (parsed === null || typeof parsed !== "object")
-            return null;
-        const reviews = parsed["reviews"];
-        if (reviews === null || typeof reviews !== "object" || Array.isArray(reviews))
-            return null;
-        const validated = {};
-        for (const [id, entry] of Object.entries(reviews)) {
-            if (entry === null || typeof entry !== "object")
-                continue;
-            const e = entry;
-            if (typeof e["firstSeenAt"] !== "number" || !Number.isFinite(e["firstSeenAt"]))
-                continue;
-            if (typeof e["bodyHash"] !== "string")
-                continue;
-            validated[id] = { firstSeenAt: e["firstSeenAt"], bodyHash: e["bodyHash"] };
-        }
-        return { reviews: validated };
-    }
-    catch {
-        return null;
-    }
-}
-export async function writeBotCrSeenState(key, state) {
-    let tmp;
-    try {
-        const path = resolvePath(key);
-        tmp = `${path}.${randomUUID()}.tmp`;
-        await mkdir(dirname(path), { recursive: true });
-        await writeFile(tmp, JSON.stringify(state), "utf8");
-        await rename(tmp, path);
-        tmp = undefined;
-    }
-    catch {
-        // best-effort
-    }
-    finally {
-        if (tmp !== undefined) {
-            try {
-                await unlink(tmp);
-            }
-            catch {
-                // best-effort cleanup
-            }
-        }
-    }
-}
-/**
- * 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 function updateBotCrSeenState(previous, currentBotCrReviews, nowSeconds, stallTimeoutSeconds) {
-    const previousReviews = previous?.reviews ?? {};
-    const next = {};
-    const staleIds = [];
-    for (const r of currentBotCrReviews) {
-        const bodyHash = hashBody(r.body);
-        const prior = previousReviews[r.id];
-        const entry = prior && prior.bodyHash === bodyHash ? prior : { firstSeenAt: nowSeconds, bodyHash };
-        next[r.id] = entry;
-        if (stallTimeoutSeconds > 0 && nowSeconds - entry.firstSeenAt >= stallTimeoutSeconds) {
-            staleIds.push(r.id);
-        }
-    }
-    return { next: { reviews: next }, staleIds };
-}
-function resolvePath(key) {
-    return resolvePrStatePath(key, "bot-cr-seen.json");
-}