pr-shepherd 0.27.0 → 0.29.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -210,11 +210,13 @@ export default rule;
 
 `suppress: true` hides the item from agent output. `autoResolve: true` queues it for the minimize/resolve mutation. Both can apply together.
 
+TypeScript rules are loaded by the runtime's native TypeScript support; keep them to erasable syntax such as type annotations and `import type`. Runtime TypeScript features that need transpilation, such as enums, namespaces, parameter properties, and decorators, are not supported. Use `.mts` for portable ESM rules across Node, Bun, and Deno.
+
 Ready-to-use examples for common patterns are in [`examples/classification/`](examples/classification/).
 
 ## Requirements
 
-- Node.js >= 22.0.0
+- Node.js >= 22.18.0, Bun, or Deno
 - A GitHub token or authenticated `gh` CLI; private repositories require `repo` scope.
 - `git`
 

package/bin/classify/loader.mjs

@@ -32,22 +32,6 @@ function collectRuleFiles(dir) {
         .map((name) => join(dir, name))
         .sort();
 }
-let tsxAttempted = false;
-async function ensureTsxRegistered() {
-    if (tsxAttempted)
-        return;
-    tsxAttempted = true;
-    try {
-        const { register } = await import("tsx/esm/api");
-        register();
-        /* c8 ignore start */
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`pr-shepherd: failed to register tsx — .ts/.mts classification rules will not load: ${msg}\n`);
-    }
-    /* c8 ignore stop */
-}
 const ruleCache = new Map();
 export async function loadRules(files) {
     if (files.length === 0)
@@ -56,9 +40,6 @@ export async function loadRules(files) {
     const cached = ruleCache.get(cacheKey);
     if (cached !== undefined)
         return cached;
-    const hasTs = files.some((f) => f.endsWith(".ts") || f.endsWith(".mts"));
-    if (hasTs)
-        await ensureTsxRegistered();
     const rules = [];
     for (const file of files) {
         try {

package/bin/cli/list-formatters.mjs

@@ -94,11 +94,17 @@ export function renderEditedCommentTag(c) {
     return c.edited ? "[edited since first look]" : undefined;
 }
 export function renderReviewBullet(r, opts = {}) {
-    if (r.staleBotCr) {
-        return `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)}) [pending dismissal — already surfaced; include in \`--dismiss-review-ids\`]`;
-    }
+    const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`;
+    const staleTag = r.staleReview
+        ? " [stale — review is on an old commit, all threads resolved]"
+        : "";
+    if (r.staleBotCr)
+        return `${base}${staleTag} [pending dismissal — already surfaced; include in \`--dismiss-review-ids\`]`;
+    const humanStaleTag = r.staleReview
+        ? " [stale — review is on an old commit, all threads resolved; ask reviewer to re-review or dismiss]"
+        : "";
     const bodySuffix = opts.includeBody && r.body != null && r.body !== "" ? `: ${renderBodyPreview(r.body)}` : "";
-    return `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})${bodySuffix}`;
+    return `${base}${humanStaleTag}${bodySuffix}`;
 }
 export function renderReviewListSection(heading, items) {
     if (items.length === 0)

package/bin/commands/iterate/check-instructions.mjs

@@ -1,3 +1,13 @@
+/** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
+export function buildCrStaleClause(reviews) {
+    const bot = reviews.some((r) => r.staleBotCr)
+        ? " `[pending dismissal — already surfaced]` bullets are bot CRs from a prior tick."
+        : "";
+    const human = reviews.some((r) => r.staleReview && !r.staleBotCr)
+        ? " `[stale]` bullets are human CRs on an old commit; ask reviewer to re-review."
+        : "";
+    return bot + human;
+}
 export function buildFailingCheckInstructions(checks) {
     if (checks.length === 0)
         return [];

package/bin/commands/iterate/render.mjs

@@ -1,5 +1,5 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
-import { buildFailingCheckInstructions } from "./check-instructions.mjs";
+import { buildFailingCheckInstructions, buildCrStaleClause } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
@@ -72,9 +72,7 @@ resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], f
         instructions.push(`For each item under \`## Check annotations\`: inspect the referenced file range and decide whether the annotation requires a code change. These annotations are surfaced once per PR and do not need any resolve/minimize mutation.`);
     }
     if (changesRequestedReviews.length > 0) {
-        const staleClause = changesRequestedReviews.some((r) => r.staleBotCr)
-            ? " Bullets tagged `[pending dismissal — already surfaced]` are bot CR reviews you saw on a previous tick; the CLI hides re-surfaced bodies to keep output lean — re-read the prior tick if you need the body."
-            : "";
+        const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.${staleClause}`);
         if ((resolveCommand.dismissReviewIds?.length ?? 0) > 0)
             instructions.push(`Pass every ID listed in \`--dismiss-review-ids\` to the \`resolve:\` command verbatim — these are bot/non-human CR reviews that the agent (not the author) must dismiss. Dropping an ID leaves the PR in \`CHANGES_REQUESTED\` state; the next tick re-surfaces it as \`[pending dismissal]\` and an unattended bot CR escalates after \`iterate.stallTimeoutMinutes\`.`);

package/bin/commands/poll.mjs

@@ -1,7 +1,5 @@
 import { runIterate } from "./iterate/index.mjs";
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
+import { sleep } from "../util/sleep.mjs";
 function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
     if (verbose) {
         process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);

package/bin/comments/sha-poll.mjs

@@ -1,5 +1,6 @@
 import { getPrHeadSha } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
+import { sleep } from "../util/sleep.mjs";
 export async function waitForSha(pr, repo, expectedSha) {
     const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
     for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
@@ -20,6 +21,3 @@ export async function waitForSha(pr, repo, expectedSha) {
     }
     throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}

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

@@ -27,6 +27,19 @@ export function latestApprovedLogins(latest) {
         .filter((r) => r.login !== "unknown" && (r.state === "APPROVED" || r.state === "DISMISSED"))
         .map((r) => r.login));
 }
+/**
+ * A CR review is stale when its commit.oid differs from the PR head AND every
+ * associated review thread is resolved or outdated. Reviews with no associated
+ * threads are treated conservatively (not marked stale).
+ */
+export function isReviewStale(review, headRefOid, reviewThreads) {
+    if (!review.commitOid || review.commitOid === headRefOid)
+        return false;
+    const associated = reviewThreads.filter((t) => t.reviewId === review.id);
+    if (associated.length === 0)
+        return false;
+    return associated.every((t) => t.isResolved || t.isOutdated);
+}
 export function mapStatusContextState(state) {
     switch (state) {
         case "SUCCESS":

package/bin/github/batch-parsers.mjs

@@ -1,14 +1,18 @@
-import { mapAuthorType, parseCreatedAt, extractRunId, extractCheckRunSummary, mapStatusContextState, latestApprovedLogins, } from "./batch-parser-helpers.mjs";
+import { mapAuthorType, parseCreatedAt, extractRunId, extractCheckRunSummary, mapStatusContextState, latestApprovedLogins, isReviewStale, } from "./batch-parser-helpers.mjs";
 import { buildPrActivitySummary } from "./activity.mjs";
 import { parseBranchProtection } from "./branch-protection.mjs";
 function parseReviewNode(r) {
-    return {
+    const base = {
         id: r.id,
         author: r.author?.login ?? "unknown",
         authorType: mapAuthorType(r.author?.__typename, r.author?.login),
         body: r.body,
         createdAtUnix: r.createdAt ? parseCreatedAt(r.createdAt) : 0,
     };
+    if ("commit" in r && r.commit?.oid) {
+        base.commitOid = r.commit.oid;
+    }
+    return base;
 }
 export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes) {
     const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
@@ -58,7 +62,13 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         url: c.url,
         createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,
     }));
-    const allChangesRequestedReviews = rawReviewNodes.map((r) => parseReviewNode(r));
+    const allChangesRequestedReviews = rawReviewNodes.map((r) => {
+        const review = parseReviewNode(r);
+        if (isReviewStale(review, raw.headRefOid, reviewThreads)) {
+            review.staleReview = true;
+        }
+        return review;
+    });
     const changesRequestedReviews = allChangesRequestedReviews.filter((r) => !crDone.has(r.author));
     const reviewSummaries = rawReviewSummaryNodes
         .filter((r) => !r.isMinimized && r.body.trim() !== "")

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

@@ -132,6 +132,9 @@ query BatchPr(
           }
           body
           createdAt
+          commit {
+            oid
+          }
         }
       }
       reviewSummaries: reviews(states: COMMENTED, last: 50, before: $reviewSummariesCursor) {

package/bin/github/http-request.mjs

@@ -1,6 +1,27 @@
 import { clearTokenCache, hasCachedToken } from "./http-auth.mjs";
+import { isTransportError } from "./http-utils.mjs";
+import { sleep } from "../util/sleep.mjs";
+const TRANSPORT_RETRY_DELAYS = [250, 500];
+async function fetchWithTransportRetry(fn) {
+    let lastErr;
+    for (let attempt = 1; attempt <= TRANSPORT_RETRY_DELAYS.length + 1; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (!isTransportError(err))
+                throw err;
+            lastErr = err;
+            const delay = TRANSPORT_RETRY_DELAYS[attempt - 1];
+            if (delay === undefined)
+                break;
+            await sleep(delay);
+        }
+    }
+    throw lastErr;
+}
 export async function requestWithTokenRetry(fn, t0, onIntermediate) {
-    const res = await fn();
+    const res = await fetchWithTransportRetry(fn);
     if (res.status === 401 && hasCachedToken()) {
         onIntermediate?.(401, Math.round(performance.now() - t0));
         try {
@@ -9,7 +30,7 @@ export async function requestWithTokenRetry(fn, t0, onIntermediate) {
         catch { }
         clearTokenCache();
         const retryT0 = performance.now();
-        return { res: await fn(), attempt: 2, retryT0 };
+        return { res: await fetchWithTransportRetry(fn), attempt: 2, retryT0 };
     }
     return { res, attempt: 1, retryT0: t0 };
 }

package/bin/github/http-utils.mjs

@@ -1,3 +1,25 @@
+const TRANSPORT_ERROR_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+export function isTransportError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    if (code && TRANSPORT_ERROR_CODES.has(code))
+        return true;
+    const cause = err.cause;
+    if (cause instanceof Error) {
+        const causeCode = cause.code;
+        if (causeCode && TRANSPORT_ERROR_CODES.has(causeCode))
+            return true;
+    }
+    return false;
+}
 export function sanitizeBody(body) {
     return body.replace(/Bearer\s+\S+/gi, "[REDACTED]").slice(0, 200);
 }

package/bin/util/sleep.mjs

@@ -0,0 +1,3 @@
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "pr-shepherd",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
   "type": "module",
   "bin": {
-    "pr-shepherd": "bin/pr-shepherd"
+    "pr-shepherd": "bin/index.mjs"
   },
   "files": [
     "bin/**",
@@ -20,11 +20,10 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.18.0"
   },
   "dependencies": {
     "picomatch": "^4.0.4",
-    "tsx": "^4.22.4",
     "yaml": "^2.7.0"
   },
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.27.0",
+  "version": "0.29.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

@@ -16,7 +16,7 @@ Poll dispatcher for iterating a PR to completion.
 
 1. **Resolve the PR number** (`$N`): use the number or URL in `$ARGUMENTS`; otherwise infer it with `gh pr view --json number --jq .number`. If none is found, report an error and stop.
 
-2. **Define the poll command once:** `pr-shepherd $N --interval 60s --timeout 4.5m`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
+2. **Define the poll command once:** `pr-shepherd $N --interval 60s --timeout 4.5m --quiet-status`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
 
 3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) is non-terminal: do its instructions, then poll again. The poll already bounds each wait via `--interval`/`--timeout`; do not add manual `sleep`s between ticks.
 

package/bin/pr-shepherd

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import("./index.mjs")