pr-shepherd 0.16.4 → 0.18.0

package/bin/comments/resolve.mjs

@@ -1,9 +1,48 @@
+/* eslint-disable max-lines */
 import { graphqlWithRateLimit } from "../github/client.mjs";
 import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "./rate-limit.mjs";
 import { setPendingOps } from "./pending-ops.mjs";
 import { waitForSha } from "./sha-poll.mjs";
+const COMMENTED_DISMISS_ERROR_PATTERNS = [
+    /can\s*not\s+dismiss[\s\S]*?commented pull request review/i,
+];
+function dedupeIds(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+function isCommentedDismissError(message) {
+    return COMMENTED_DISMISS_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+function dismissReviewNonDismissibleMessage(id) {
+    return `Not dismissed: ${id} is a COMMENTED review. Use --minimize-comment-ids instead; --dismiss-review-ids is only for CHANGES_REQUESTED reviews.`;
+}
 export async function applyResolveOptions(pr, repo, opts) {
-    if ((opts.dismissReviewIds?.length ?? 0) > 0 && !opts.dismissMessage) {
+    const resolveThreadIds = dedupeIds(opts.resolveThreadIds ?? []);
+    const minimizeCommentIds = opts.minimizeCommentIds ?? [];
+    const dismissReviewIds = dedupeIds(opts.dismissReviewIds ?? []);
+    const minimizeCommentIdSet = new Set(minimizeCommentIds);
+    const filteredDismissReviewIds = dismissReviewIds.filter((id) => !minimizeCommentIdSet.has(id));
+    const overlappingDismissIds = dismissReviewIds.filter((id) => minimizeCommentIdSet.has(id));
+    const result = {
+        resolvedThreads: [],
+        minimizedComments: [],
+        dismissedReviews: [],
+        errors: [],
+    };
+    if (overlappingDismissIds.length > 0) {
+        result.skippedDismissals = [];
+        for (const id of overlappingDismissIds) {
+            result.skippedDismissals.push(id);
+        }
+    }
+    if (filteredDismissReviewIds.length > 0 && !opts.dismissMessage) {
         throw new Error("--message is required when dismissing reviews");
     }
     if (opts.requireSha) {
@@ -11,13 +50,7 @@ export async function applyResolveOptions(pr, repo, opts) {
         // before reviewers see the fix.
         await waitForSha(pr, repo, opts.requireSha);
     }
-    const result = {
-        resolvedThreads: [],
-        minimizedComments: [],
-        dismissedReviews: [],
-        errors: [],
-    };
-    await bulkApply(opts.resolveThreadIds ?? [], opts.minimizeCommentIds ?? [], opts.dismissReviewIds ?? [], opts.dismissMessage ?? "", result);
+    await bulkApply(resolveThreadIds, minimizeCommentIds, filteredDismissReviewIds, opts.dismissMessage ?? "", result);
     return result;
 }
 export async function autoResolveOutdated(threadIds) {
@@ -65,13 +98,15 @@ async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessag
     if (resolveIds.length === 0 && minimizeIds.length === 0 && dismissIds.length === 0)
         return false;
     const doc = buildBulkMutation(resolveIds, minimizeIds, dismissIds, dismissMessage);
-    let data;
+    let data = {};
+    let graphQlErrors = [];
     let rateLimitStop;
     let suppressCurrentChunkErrors = false;
     try {
         const resp = await graphqlWithRateLimit(doc, {});
         data = resp.data;
-        const graphQlErrorMessages = resp.errors?.map((e) => e.message) ?? [];
+        graphQlErrors = (resp.errors ?? []);
+        const graphQlErrorMessages = graphQlErrors.map((e) => e.message);
         suppressCurrentChunkErrors = graphQlErrorMessages.some(isRateLimitMessage);
         rateLimitStop = rateLimitFromGraphQlResult(graphQlErrorMessages, {
             rateLimit: resp.rateLimit,
@@ -109,12 +144,27 @@ async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessag
         else if (!suppressCurrentChunkErrors)
             result.errors.push(`${minimizeIds[i]}: minimize returned null or comment not minimized`);
     }
+    const singleDismiss = dismissIds.length === 1;
+    const commentedDismissErrorIndexes = new Set();
+    let hasUnmappedCommentedDismissError = false;
+    for (const error of graphQlErrors) {
+        if (!isCommentedDismissError(error.message))
+            continue;
+        const alias = dismissErrorAliasIndex(error);
+        if (alias === undefined) {
+            hasUnmappedCommentedDismissError = true;
+            continue;
+        }
+        commentedDismissErrorIndexes.add(alias);
+    }
     for (let i = 0; i < dismissIds.length; i++) {
         const d = data[`d${i}`];
         if (d?.pullRequestReview != null)
             result.dismissedReviews.push(dismissIds[i]);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${dismissIds[i]}: dismiss returned null`);
+            result.errors.push(commentedDismissErrorIndexes.has(i) || (singleDismiss && hasUnmappedCommentedDismissError)
+                ? dismissReviewNonDismissibleMessage(dismissIds[i])
+                : `${dismissIds[i]}: dismiss returned null`);
     }
     if (rateLimitStop) {
         result.errors.push(`rate limit: ${rateLimitStop.message}`);
@@ -123,3 +173,12 @@ async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessag
     }
     return false;
 }
+function dismissErrorAliasIndex(error) {
+    if (!Array.isArray(error.path))
+        return undefined;
+    const alias = error.path.find((part) => typeof part === "string" && /^d\d+$/.test(part));
+    if (typeof alias !== "string")
+        return undefined;
+    const parsed = Number.parseInt(alias.slice(1), 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}

package/bin/github/batch-parser-helpers.mjs

@@ -0,0 +1,38 @@
+export function mapAuthorType(typeName) {
+    if (typeName === "User" || typeName === "Bot")
+        return typeName;
+    return "Unknown";
+}
+export function parseCreatedAt(iso) {
+    const ms = new Date(iso).getTime();
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
+export function extractRunId(url) {
+    if (!url)
+        return null;
+    const m = /\/runs\/(\d+)/.exec(url);
+    return m ? (m[1] ?? null) : null;
+}
+export function extractCheckRunSummary(title, summary) {
+    const t = title?.trim();
+    if (t)
+        return t;
+    const firstLine = summary
+        ?.split("\n")
+        ?.find((l) => l.trim() !== "")
+        ?.trim();
+    return firstLine || undefined;
+}
+export function mapStatusContextState(state) {
+    switch (state) {
+        case "SUCCESS":
+            return { status: "COMPLETED", conclusion: "SUCCESS" };
+        case "FAILURE":
+        case "ERROR":
+            return { status: "COMPLETED", conclusion: "FAILURE" };
+        case "PENDING":
+        case "EXPECTED":
+        default:
+            return { status: "IN_PROGRESS", conclusion: null };
+    }
+}

package/bin/github/batch-parsers.mjs

@@ -1,3 +1,4 @@
+import { mapAuthorType, parseCreatedAt, extractRunId, extractCheckRunSummary, mapStatusContextState, } from "./batch-parser-helpers.mjs";
 export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes) {
     const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
         const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
@@ -92,6 +93,16 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         }
         return [];
     });
+    const rawProtection = raw.baseRef?.branchProtectionRule ?? null;
+    const branchProtection = rawProtection
+        ? {
+            requiresApprovingReviews: rawProtection.requiresApprovingReviews,
+            requiredApprovingReviewCount: rawProtection.requiredApprovingReviewCount,
+            requiresConversationResolution: rawProtection.requiresConversationResolution,
+            requiresStatusChecks: rawProtection.requiresStatusChecks,
+            requiredStatusCheckContexts: rawProtection.requiredStatusCheckContexts ?? [],
+        }
+        : null;
     return {
         nodeId: raw.id,
         number: raw.number,
@@ -112,43 +123,6 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         reviewSummaries,
         approvedReviews,
         checks,
+        branchProtection,
     };
 }
-function mapAuthorType(typeName) {
-    if (typeName === "User" || typeName === "Bot")
-        return typeName;
-    return "Unknown";
-}
-function parseCreatedAt(iso) {
-    const ms = new Date(iso).getTime();
-    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
-}
-function extractRunId(url) {
-    if (!url)
-        return null;
-    const m = /\/runs\/(\d+)/.exec(url);
-    return m ? (m[1] ?? null) : null;
-}
-function extractCheckRunSummary(title, summary) {
-    const t = title?.trim();
-    if (t)
-        return t;
-    const firstLine = summary
-        ?.split("\n")
-        ?.find((l) => l.trim() !== "")
-        ?.trim();
-    return firstLine || undefined;
-}
-function mapStatusContextState(state) {
-    switch (state) {
-        case "SUCCESS":
-            return { status: "COMPLETED", conclusion: "SUCCESS" };
-        case "FAILURE":
-        case "ERROR":
-            return { status: "COMPLETED", conclusion: "FAILURE" };
-        case "PENDING":
-        case "EXPECTED":
-        default:
-            return { status: "IN_PROGRESS", conclusion: null };
-    }
-}

package/bin/github/client.mjs

@@ -34,7 +34,16 @@ export async function getCurrentPrNumber() {
         if (branch === "HEAD")
             return null;
         const repo = await getRepoInfo();
-        const result = await httpGraphql(PR_NUMBER_BY_BRANCH_QUERY, { owner: repo.owner, repo: repo.name, branch });
+        return getPrNumberForBranch(branch, repo.owner, repo.name);
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns the PR number for a given branch, or null if no open PR is found. */
+export async function getPrNumberForBranch(branch, owner, repo) {
+    try {
+        const result = await httpGraphql(PR_NUMBER_BY_BRANCH_QUERY, { owner, repo, branch });
         return result.data.repository?.pullRequests.nodes[0]?.number ?? null;
     }
     catch {

package/bin/github/gql/batch-pr.gql

@@ -24,6 +24,15 @@ query BatchPr(
         nameWithOwner
       }
       baseRefName
+      baseRef {
+        branchProtectionRule {
+          requiresApprovingReviews
+          requiredApprovingReviewCount
+          requiresConversationResolution
+          requiresStatusChecks
+          requiredStatusCheckContexts
+        }
+      }
       # Not paginated — capped at 50; PRs with more pending reviewers truncate silently.
       reviewRequests(last: 50) {
         nodes {

package/bin/state/base.mjs

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 export function resolveStateBase() {
-    return process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const envDir = process.env["PR_SHEPHERD_STATE_DIR"];
+    return envDir ? envDir : join(tmpdir(), "pr-shepherd-state");
 }

package/bin/state/seen-comments.mjs

@@ -33,30 +33,35 @@ export function classifyItem(id, body, map) {
  * Returns an empty Set if the directory does not yet exist.
  */
 export async function loadSeenSet(key) {
-    try {
-        const dir = resolveDir(key);
-        const entries = await readdir(dir);
-        return new Set(entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5)));
-    }
-    catch {
-        return new Set();
-    }
+    const map = await loadSeenMap(key);
+    return new Set(map.keys());
 }
 /**
  * Read the seen/ directory and return a Map from ID to SeenMarker.
  * Used when the caller needs the stored bodyHash to detect in-place edits.
  * Returns an empty Map if the directory does not yet exist.
+ *
+ * Map keys are the stored `id` field when present (guarding against
+ * case-insensitive filesystem collisions), falling back to the filename for
+ * legacy markers that predate this field.
  */
 export async function loadSeenMap(key) {
     const map = new Map();
     try {
         const dir = resolveDir(key);
         const entries = await readdir(dir);
-        const ids = entries.filter((e) => e.endsWith(".json")).map((e) => e.slice(0, -5));
-        for (const id of ids) {
+        for (const entry of entries.filter((e) => e.endsWith(".json"))) {
             try {
-                const raw = await readFile(join(dir, `${id}.json`), "utf8");
-                map.set(id, JSON.parse(raw));
+                const raw = await readFile(join(dir, entry), "utf8");
+                const marker = JSON.parse(raw);
+                // Prefer the stored id field; fall back to filename stem for legacy markers.
+                const mapKey = typeof marker.id === "string" ? marker.id : entry.slice(0, -5);
+                // Hash-based markers (those with an id field) take priority over legacy
+                // filename-based markers so that a stale legacy file cannot overwrite a
+                // newer hash-based entry that maps to the same key.
+                if (!map.has(mapKey) || typeof marker.id === "string") {
+                    map.set(mapKey, marker);
+                }
             }
             catch {
                 // unreadable or malformed — skip
@@ -82,7 +87,7 @@ export async function hasSeen(key, id) {
  * Write (or update) a "seen" marker for this id, storing the body hash so
  * in-place edits can be detected on future fetches.
  *
- * - First call (no existing marker): creates `{ seenAt: now, bodyHash }`.
+ * - First call (no existing marker): creates `{ seenAt: now, bodyHash, id }`.
  * - Subsequent call, hash unchanged: no-op (skips the write).
  * - Subsequent call, hash changed: updates `bodyHash`, preserves original `seenAt`.
  *
@@ -106,7 +111,10 @@ export async function markSeen(key, id, body) {
             return;
         const seenAt = existing?.seenAt ?? Date.now();
         tmp = `${path}.${randomUUID()}.tmp`;
-        await writeFile(tmp, JSON.stringify({ seenAt, bodyHash: newHash }), "utf8");
+        // Store `id` in the payload so loadSeenMap can key by the original ID
+        // rather than the filename, guarding against case-insensitive filesystems
+        // (e.g. macOS APFS) where IDs differing only in case would collide.
+        await writeFile(tmp, JSON.stringify({ seenAt, bodyHash: newHash, id }), "utf8");
         await rename(tmp, path);
         tmp = undefined;
     }
@@ -153,5 +161,11 @@ function resolvePath(key, id) {
     if (!SAFE_SEGMENT.test(id)) {
         throw new Error(`Invalid state key segment "id": ${id}`);
     }
-    return join(resolveDir(key), `${id}.json`);
+    // Hash the ID to produce a case-insensitive filename. On case-insensitive
+    // filesystems (macOS APFS), IDs that differ only in case (e.g. base64 IDs
+    // from GitHub like `ChG7F` vs `ChG7f`) would otherwise share the same file,
+    // causing seen-markers to overwrite each other and items to re-surface every
+    // tick. SHA-256 is case-sensitive so distinct IDs get distinct files.
+    const hash = createHash("sha256").update(id, "utf8").digest("hex");
+    return join(resolveDir(key), `${hash}.json`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.16.4",
+  "version": "0.18.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.16.4",
+  "version": "0.18.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

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

@@ -29,12 +29,12 @@ One-tick dispatcher for iterating a PR to completion.
    If `MERGED` or `CLOSED`, output: `PR #N is already merged/closed. Nothing to do.` and stop.
 
 3. **Select the package runner** from the target repository root:
-   - Prefer `package.json` `packageManager`: `pnpm@...` → `pnpm exec`, `yarn@...` → `yarn run`, `npm@...` → `npx`.
-   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` → `pnpm exec`, `yarn.lock` → `yarn run`, `package-lock.json` or no signal → `npx`.
+   - Prefer `package.json` `packageManager`: `pnpm@...` → `pnpm exec`, `yarn@...` → `yarn run`, `bun@...` → `bunx`, `npm@...` → `npx`.
+   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` → `pnpm exec`, `yarn.lock` → `yarn run`, `bun.lock` / `bun.lockb` → `bunx`, `package-lock.json` or no signal → `npx`.
 
 4. **Run one iterate tick:**
 
-   If the package is missing in the target repository, tell the user to install pr-shepherd with the matching dev-dependency command: `pnpm add -D pr-shepherd`, `yarn add -D pr-shepherd`, or `npm install --save-dev pr-shepherd`.
+   If the package is missing in the target repository, tell the user to install pr-shepherd with the matching dev-dependency command: `pnpm add -D pr-shepherd`, `yarn add -D pr-shepherd`, `bun add -d pr-shepherd`, or `npm install --save-dev pr-shepherd`.
 
    ```bash
    <runner> pr-shepherd <N>
@@ -42,7 +42,18 @@ One-tick dispatcher for iterating a PR to completion.
 
    Print the full output. Follow the `## Instructions` section exactly.
 
-5. **Stop conditions:**
+5. **Persistence:** Do not stop polling/iterating unless directed by the human or until the CLI returns a terminal state (`[CANCEL]` or `[ESCALATE]`). Every other action — `[WAIT]`, `[MARK_READY]`, `[FIX_CODE]` — is non-terminal and must be followed by another tick via one of the strategies below.
+
+6. **Stop conditions (terminal states):**
    - Stop when the CLI emits `[CANCEL]` (ready-delay completed, or PR merged/closed).
    - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures.
-   - All other actions (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) are non-terminal: follow the `## Instructions`. For Claude, schedule exactly one next session-only iteration and end the turn; do not sleep inline and do not create a recurring cron.
+   - **Do NOT merge the pull request** unless the human has explicitly requested or allowed it.
+
+7. **Non-terminal actions** (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) — follow the `## Instructions` in the output. Pick one iteration strategy:
+   - **Blocking poll** — rerun as `<runner> pr-shepherd poll <N> [--interval <duration>] [--timeout <duration>]` (defaults: interval 30s, timeout 5m). Holds the agent turn until the action is non-WAIT or the timeout fires. Simplest when the agent cannot reliably schedule its own follow-up.
+   - **Scheduled wakeup + one tick** — schedule a single session-only follow-up task to rerun `<runner> pr-shepherd <N>` after a fresh 30s–4m delay, then end the turn.
+   - **Inline sleep + rerun** — sleep inline for a fresh 30s–4m delay, then rerun.
+
+   **Never write a custom polling loop** (shell `while`/`until` loops, script files that loop over pr-shepherd output, etc.). Custom loops poll only for terminal states and silently skip `[FIX_CODE]` handling — actionable review threads, failing checks, and resolve commands get missed. Use `pr-shepherd poll` for WAIT-state waiting; it exits on any non-WAIT action so the caller handles `[FIX_CODE]` and other actionable outputs normally.
+
+   Do not combine strategies (e.g., poll AND schedule a wakeup). Remember step 5 — every non-terminal output requires a follow-up tick.

package/bin/agent-runtime.mjs

@@ -1,7 +0,0 @@
-export function detectAgentRuntime(env = process.env) {
-    if (env.AGENT?.trim().toLowerCase() === "codex")
-        return "codex";
-    if (env.CODEX_CI === "1")
-        return "codex";
-    return "claude";
-}