pr-shepherd 0.17.0 → 0.19.0

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/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/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.17.0",
+  "version": "0.19.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.17.0",
+  "version": "0.19.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

@@ -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 or polling loop (`while true`, repeated polling, etc.).
+   - **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";
-}