pr-shepherd 0.56.1 → 0.56.3

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

@@ -1,10 +1,9 @@
 import { classifyChecks } from "../checks/classify.mjs";
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
 export function summarizePollSummaryChecks(raw) {
     const rollups = summaryRollups(raw);
     const counts = {};
-    for (const check of classifyChecks(checkRuns(rollups), {
-        additionalRelevantEvents: ["merge_group"],
-    })) {
+    for (const check of classifiedSummaryChecks(raw)) {
         const key = {
             passed: "passing",
             failing: "failing",
@@ -17,33 +16,36 @@ export function summarizePollSummaryChecks(raw) {
         counts[key] = (counts[key] ?? 0) + 1;
     }
     const summary = counts;
-    if (rollups.some((rollup) => rollup.contexts.pageInfo.hasPreviousPage)) {
+    if (rollups.some(({ rollup }) => rollup.contexts.pageInfo.hasPreviousPage)) {
         summary.incomplete = true;
     }
     return summary;
 }
 /** Names of failing checks in the loaded summary rollup. */
 export function failingSummaryCheckNames(raw) {
-    return classifyChecks(checkRuns(summaryRollups(raw)), {
-        additionalRelevantEvents: ["merge_group"],
-    })
+    return classifiedSummaryChecks(raw)
         .filter((check) => check.category === "failing")
         .map((check) => check.name);
 }
 function summaryRollups(raw) {
     return [
-        raw.commits.nodes[0]?.commit.statusCheckRollup,
-        raw.mergeQueueEntry?.headCommit?.statusCheckRollup,
-    ].filter((rollup) => rollup !== null && rollup !== undefined);
+        { rollup: raw.commits.nodes[0]?.commit.statusCheckRollup, scope: undefined },
+        {
+            rollup: raw.mergeQueueEntry?.headCommit?.statusCheckRollup,
+            scope: "merge_group",
+        },
+    ].flatMap(({ rollup, scope }) => (rollup ? [{ rollup, scope }] : []));
 }
-function checkRuns(rollups) {
-    return rollups.flatMap((rollup, rollupIndex) => rollup.contexts.nodes.map((context) => {
+function classifiedSummaryChecks(raw) {
+    // A successful check on the queue commit cannot cover a PR-head cancellation, or vice versa.
+    return summaryRollups(raw).flatMap(({ rollup, scope }) => classifyChecks(checkRuns(rollup, scope), scope === "merge_group" ? { additionalRelevantEvents: ["merge_group"] } : {}));
+}
+function checkRuns(rollup, scope) {
+    return rollup.contexts.nodes.map((context) => {
         if (context.__typename === "StatusContext") {
             return {
                 name: context.context,
-                status: context.state === "PENDING" || context.state === "EXPECTED"
-                    ? "IN_PROGRESS"
-                    : "COMPLETED",
+                status: context.state === "PENDING" || context.state === "EXPECTED" ? "IN_PROGRESS" : "COMPLETED",
                 conclusion: context.state === "SUCCESS"
                     ? "SUCCESS"
                     : context.state === "FAILURE" || context.state === "ERROR"
@@ -53,7 +55,7 @@ function checkRuns(rollups) {
                 detailsUrl: "",
                 event: null,
                 runId: null,
-                ...(rollupIndex === 1 && { scope: "merge_group" }),
+                ...(scope && { scope }),
             };
         }
         const run = context.checkSuite?.workflowRun;
@@ -70,7 +72,9 @@ function checkRuns(rollups) {
             ...(run?.workflow?.databaseId != null && {
                 workflowId: String(run.workflow.databaseId),
             }),
-            ...(rollupIndex === 1 && { scope: "merge_group" }),
+            ...(context.startedAt && { startedAtUnix: parseCreatedAt(context.startedAt) }),
+            ...(context.completedAt && { completedAtUnix: parseCreatedAt(context.completedAt) }),
+            ...(scope && { scope }),
         };
-    }));
+    });
 }

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

@@ -8,6 +8,10 @@ import { createHash } from "node:crypto";
 export function fingerprintRawSummaryPr(raw) {
     if (!raw.updatedAt || !raw.headRefOid || !raw.baseRefOid)
         return null;
+    const reviewTruncated = raw.comments.pageInfo.hasPreviousPage ||
+        raw.reviews.pageInfo.hasPreviousPage ||
+        raw.reviewThreads.pageInfo.hasPreviousPage ||
+        raw.reviewThreads.nodes.some((thread) => thread.comments.pageInfo.hasPreviousPage);
     const evidence = {
         number: raw.number,
         state: raw.state,
@@ -19,6 +23,9 @@ export function fingerprintRawSummaryPr(raw) {
         reviewDecision: raw.reviewDecision,
         reviewRequests: raw.reviewRequests,
         latestReviews: raw.latestReviews,
+        // Omitted bodies cannot participate in the hash. Bind truncated evidence
+        // to the PR revision instead, so updates require a fresh full review poll.
+        ...(reviewTruncated && { reviewUpdatedAt: raw.updatedAt }),
         comments: hideBodies(raw.comments),
         reviews: hideBodies(raw.reviews),
         reviewThreads: {

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

@@ -26,6 +26,8 @@ type RawCheckContext = {
     status: string;
     conclusion: string | null;
     detailsUrl?: string;
+    startedAt?: string | null;
+    completedAt?: string | null;
     annotations?: {
         totalCount: number;
     };

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

@@ -1,4 +1,6 @@
 import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+import { rulesComplete } from "./fingerprint-fields.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;
@@ -8,9 +10,17 @@ export function isCurrentSummaryReady(raw, checks, review, options = {}) {
     const sourceChecks = queued
         ? summarizePollSummaryChecks({ ...raw, mergeQueueEntry: null })
         : checks;
+    // The full one-PR check already surfaces review feedback. Certification
+    // need not reread historical conversations unless their resolution is a
+    // merge requirement. GitHub's CLEAN state proves that requirement is
+    // satisfied. BLOCKED is not conversation-specific, and queue progress
+    // alone is not that proof.
+    const requiresConversationResolution = parseBranchRules(raw.baseRef).requiresConversationResolution;
     return (checks.incomplete !== true &&
         sourceChecks.incomplete !== true &&
-        review.incomplete !== true &&
+        (review.incomplete !== true ||
+            raw.mergeStateStatus === "CLEAN" ||
+            (rulesComplete(raw.baseRef) && !requiresConversationResolution)) &&
         raw.state === "OPEN" &&
         !raw.isDraft &&
         raw.mergeable !== "CONFLICTING" &&

package/bin/mcp/server.mjs

@@ -60,6 +60,12 @@ const appendJournalOperationSchema = z.object({
     item: z.string(),
     dryRun: z.boolean().optional(),
 });
+const acknowledgeQueueRemovalOperationSchema = z.object({
+    type: z.literal("acknowledge_queue_removal"),
+    requireSha: z.string().regex(/^[0-9a-f]{40}$/),
+    queueCommitOid: z.string().regex(/^[0-9a-f]{40}$/),
+    removedAtUnix: z.number().int().positive().safe(),
+});
 const applyInputSchema = z.object({
     pr,
     operations: z
@@ -67,6 +73,7 @@ const applyInputSchema = z.object({
         reviewMutationsOperationSchema,
         markFilesViewedOperationSchema,
         appendJournalOperationSchema,
+        acknowledgeQueueRemovalOperationSchema,
     ]))
         .min(1),
 });
@@ -234,6 +241,17 @@ function formatApplyResult(result) {
                 return `${heading}\n\n${formatMarkFilesAsViewedResult(operation.result)}`;
             case "append_journal":
                 return `${heading}\n\n${formatJournalResult(operation.result)}`;
+            case "acknowledge_queue_removal": {
+                const result = operation.result;
+                return [
+                    heading,
+                    "",
+                    `PR: ${result.repo}#${result.pr}`,
+                    `headSha: ${result.acknowledgment.headSha}`,
+                    `queueCommitOid: ${result.acknowledgment.queueCommitOid}`,
+                    `removedAtUnix: ${result.acknowledgment.removedAtUnix}`,
+                ].join("\n");
+            }
         }
     })
         .join("\n\n");

package/bin/state/queue-removal-ack.d.mts

@@ -0,0 +1,19 @@
+/** A caller's acknowledgment of one observed CI-driven native-stack queue removal. */
+export interface QueueRemovalAcknowledgment {
+    headSha: string;
+    queueCommitOid: string;
+    removedAtUnix: number;
+}
+type StateKey = {
+    owner: string;
+    repo: string;
+    pr: number;
+};
+/** The only removal reasons that indicate a CI-driven queue ejection. */
+export declare function isCiQueueRemovalReason(reason: string | null | undefined): boolean;
+/** Missing, unreadable, or malformed acknowledgment state is treated as absent. */
+export declare function readQueueRemovalAcknowledgment(key: StateKey): Promise<QueueRemovalAcknowledgment | null>;
+/** Atomically store one acknowledgment. */
+export declare function writeQueueRemovalAcknowledgment(key: StateKey, acknowledgment: QueueRemovalAcknowledgment): Promise<boolean>;
+export declare function matchesQueueRemovalAcknowledgment(acknowledgment: QueueRemovalAcknowledgment | null, expected: Pick<QueueRemovalAcknowledgment, "headSha" | "queueCommitOid" | "removedAtUnix">): acknowledgment is QueueRemovalAcknowledgment;
+export {};

package/bin/state/queue-removal-ack.mjs

@@ -0,0 +1,66 @@
+/** A caller's acknowledgment of one observed CI-driven native-stack queue removal. */
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+const FILE = "queue-removal-ack.json";
+/** The only removal reasons that indicate a CI-driven queue ejection. */
+export function isCiQueueRemovalReason(reason) {
+    return reason === "CI_FAILURE" || reason === "MERGE_QUEUE_POLICY_CHECK_FAILURE";
+}
+/** Missing, unreadable, or malformed acknowledgment state is treated as absent. */
+export async function readQueueRemovalAcknowledgment(key) {
+    try {
+        const parsed = JSON.parse(await readFile(resolvePrStatePath(key, FILE), "utf8"));
+        return isAcknowledgment(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomically store one acknowledgment. */
+export async function writeQueueRemovalAcknowledgment(key, acknowledgment) {
+    if (!isAcknowledgment(acknowledgment))
+        return false;
+    let tmp;
+    try {
+        const path = resolvePrStatePath(key, FILE);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, `${JSON.stringify(acknowledgment)}\n`, "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // A failed write may not have created the temporary file.
+            }
+        }
+    }
+}
+export function matchesQueueRemovalAcknowledgment(acknowledgment, expected) {
+    return (acknowledgment !== null &&
+        acknowledgment.headSha === expected.headSha &&
+        acknowledgment.queueCommitOid === expected.queueCommitOid &&
+        acknowledgment.removedAtUnix === expected.removedAtUnix);
+}
+function isAcknowledgment(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.headSha === "string" &&
+        /^[0-9a-f]{40}$/.test(candidate.headSha) &&
+        typeof candidate.queueCommitOid === "string" &&
+        /^[0-9a-f]{40}$/.test(candidate.queueCommitOid) &&
+        typeof candidate.removedAtUnix === "number" &&
+        Number.isSafeInteger(candidate.removedAtUnix) &&
+        candidate.removedAtUnix > 0);
+}

package/bin/types/iterate.d.mts

@@ -124,6 +124,10 @@ interface FixRebaseAndPush {
     protectedRuns: ProtectedRun[];
     /** Requeue command emitted after merge-group remediation. */
     requeue?: MergeCommandPlan;
+    /** Acknowledge an unrelated native-stack queue failure before fresh READY validation. */
+    queueRemovalAcknowledgment?: {
+        argv: string[];
+    };
     /** First-look threads — previously hidden, surfaced for acknowledgment only. */
     firstLookThreads: FirstLookThread[];
     /** First-look comments — previously hidden, surfaced for acknowledgment only. */

package/bin/types/merge-queue.d.mts

@@ -10,6 +10,8 @@ export interface MergeQueueReport {
     checksIncomplete?: true;
     /** The current PR head is not a parent of the removed synthetic queue commit. */
     headUpdatedAfterRemoval?: true;
+    /** The caller acknowledged this exact native-stack removal on the current head. */
+    removalAcknowledged?: true;
 }
 /**
  * Raw counts of actionable work held back while the PR sits in the merge queue

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.56.1",
+  "version": "0.56.3",
   "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.68.0",
+    "oxfmt": "^0.70.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.56.1",
+  "version": "0.56.3",
   "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.56.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.56.3", "pr-shepherd-mcp"]
     }
   }
 }

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

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

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

@@ -8,7 +8,7 @@ allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
 
 # pr-shepherd
 
-Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop at `[CANCEL]` or `[ESCALATE]`.
+Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop polling the selected pull request at `[CANCEL]` or `[ESCALATE]`.
 
 ## Create a PR
 
@@ -21,7 +21,8 @@ Poll with the CLI. Use MCP `iterate` only when the CLI is unavailable. Stop at `
 ## Dispatch
 
 - Parse `$ARGUMENTS` for PR numbers, `owner/repo#N`, GitHub PR URLs, one `--stack PR`, and an optional `--merge`. Reject any other argument.
-- A request to merge, land, or enqueue the selected PR or stack sets `--merge`. Creating or opening a PR does not.
+- A user-supplied `--merge` explicitly authorizes merging or enqueueing the selected PR or stack. Run the emitted merge/enqueue commands without asking for another conversational confirmation; request runtime escalation when the host requires it.
+- A request to merge, land, or enqueue the selected PR or stack also sets `--merge`. Creating or opening a PR without merge intent leaves merge mode off.
 - A request to shepherd or merge a native stack, with an anchor PR and no literal `--stack`, uses that PR as the `--stack` selector. Otherwise infer the current branch PR.
 - Follow the target repository's `AGENTS.md` while editing.
 - CLI: turn `owner/repo#N` into `https://github.com/owner/repo/pull/N`. Pass other URLs and bare numbers through.

package/plugins/pr-shepherd/skills/pr-shepherd/references/ci-failure-triage.md

@@ -6,6 +6,7 @@ Apply when a step says `Playbook: "CI failure triage"`. For a GitHub Actions row
 - `[rerun authorized]` plus a `rerun:` command means the viewer can rerun Actions (WRITE+) and this is the original attempt. Shepherd checked `repositoryPermission` and `run_attempt`.
 - Run that printed command at most once. An `[attempt: N]` check never gets another rerun. A log excerpt on a later attempt is still investigation work. A later attempt with no usable evidence escalates when nothing else remains.
 - A run in progress, `[conclusion: ACTION_REQUIRED]`, a check whose run id is not a GitHub Actions workflow, or a run with no attempt metadata never gets `[rerun authorized]`.
+- A check with `scope: merge_group` never gets a rerun command. Rerunning cannot restore a removed queue entry and overwrites the failure evidence. If the failure belongs to this PR, fix the PR head. If it does not, follow the printed requeue instruction when a plan is present. Without `--merge`, report the failure without enqueueing. For native stacks, child sessions omit `--merge` and may still record the printed local acknowledgment after inspecting logs or an external provider URL. Complete fresh one-PR READY validation before returning to the aggregate selector with its original options; never enqueue a stack layer directly.
 - Do not invent a handoff from `[FIX_CODE]`. Shepherd returns `[ESCALATE]` when no autonomous follow-up remains.
 - Several bullets can share one run id (matrix jobs). The `rerun:` command is printed once, on the first bullet. Run it once.