pr-shepherd 1.0.0 → 1.1.1

package/bin/github/rest-check-read.mjs

@@ -3,8 +3,9 @@ import { recordRestIdentity } from "./rest-identities.mjs";
 import { readRest as rest } from "./rest-reader-core.mjs";
 export async function readRestCommitChecks(oid, repo, pr = 0) {
     const prefix = restRepoPath(repo);
-    const checks = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
+    // Suites first: a COMPLETED suite read before the runs means a run still not COMPLETED is stuck.
     const suites = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-suites`, (body) => restCollection(body, "check_suites"));
+    const checks = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
     const statuses = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/statuses`);
     const workflowRuns = await readRestPages(`${prefix}/actions/runs?head_sha=${encodeURIComponent(oid)}`, (body) => restCollection(body, "workflow_runs"));
     for (const suite of suites.nodes) {
@@ -64,6 +65,7 @@ export async function readRestCommitChecks(oid, repo, pr = 0) {
             annotations: { totalCount: check.output.annotations_count, nodes: [] },
             checkSuite: suite
                 ? {
+                    status: suite.status.toUpperCase(),
                     createdAt: suite.created_at,
                     updatedAt: suite.updated_at,
                     workflowRun: run

package/bin/github/rest-reader-core.mjs

@@ -101,7 +101,9 @@ function nextRestPage(link, original) {
     if (!match)
         malformedRest(`invalid pagination link for ${original}`);
     const url = new URL(match[1], "https://api.github.com");
-    if (url.origin !== "https://api.github.com" || url.pathname !== original.split("?")[0])
+    const originalPath = original.split("?")[0];
+    if (url.origin !== "https://api.github.com" ||
+        !samePaginationResource(url.pathname, originalPath))
         malformedRest(`unsafe pagination link for ${original}`);
     if (url.searchParams.get("per_page") !== "100")
         malformedRest(`changed page size for ${original}`);
@@ -113,7 +115,16 @@ function nextRestPage(link, original) {
                 JSON.stringify(source.searchParams.getAll(key)))
             malformedRest(`changed pagination filter for ${original}`);
     }
-    return `${url.pathname}${url.search}`;
+    // Rebuild on the requested path so the repository id in a /repositories/{id} link is never trusted.
+    return `${originalPath}${url.search}`;
+}
+/** GitHub may link `/repos/{owner}/{repo}/…` pages through `/repositories/{id}/…`. */
+function samePaginationResource(linkPath, originalPath) {
+    if (linkPath === originalPath)
+        return true;
+    const linkSuffix = /^\/repositories\/\d+(\/.*)$/.exec(linkPath)?.[1];
+    const originalSuffix = /^\/repos\/[^/]+\/[^/]+(\/.*)$/.exec(originalPath)?.[1];
+    return linkSuffix !== undefined && linkSuffix === originalSuffix;
 }
 /** A pull request whose mergeability GitHub is still computing must be re-read, never replayed. */
 function isSettledBody(body) {

package/bin/github/rest-summary-read.mjs

@@ -99,7 +99,7 @@ export function restSummary(data, pull, feedback, checks, baseRef) {
                             nodes: checks.suites.map((suite) => ({
                                 status: suite.status.toUpperCase(),
                                 conclusion: suite.conclusion?.toUpperCase() ?? null,
-                                workflowRun: checks.workflowRuns.find((run) => run.check_suite_id === suite.id) ?? null,
+                                workflowRun: restSuiteWorkflowRun(checks.workflowRuns.find((run) => run.check_suite_id === suite.id)),
                             })),
                         },
                     },
@@ -110,3 +110,14 @@ export function restSummary(data, pull, feedback, checks, baseRef) {
         transportUnavailable: data.transportUnavailable,
     };
 }
+/** The GraphQL `workflowRun` shape, so summary readers see one suite format on either transport. */
+function restSuiteWorkflowRun(run) {
+    if (!run)
+        return null;
+    return {
+        databaseId: run.id,
+        event: run.event,
+        url: run.html_url,
+        workflow: { name: run.name },
+    };
+}

package/bin/github/rest-text.mjs

@@ -2,6 +2,7 @@ import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { githubFetch } from "./github-fetch.mjs";
+import { GITHUB_LOG_TIMEOUT_MS } from "./github-timeouts.mjs";
 import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody, } from "./http-utils.mjs";
@@ -19,7 +20,7 @@ export async function restText(path, onRateLimit) {
         const auth = await makeAuthHeaders();
         authSource = auth.source;
         credentialFingerprint = auth.fingerprint;
-        return githubFetch(url, { method: "GET", headers: auth.headers, redirect: "manual" });
+        return githubFetch(url, { method: "GET", headers: auth.headers, redirect: "manual" }, GITHUB_LOG_TIMEOUT_MS);
     }, t0, (response, durationMs) => recordIntermediateResponse({
         n,
         kind: "restText",
@@ -105,7 +106,7 @@ async function followRestTextRedirect(res, entry) {
     const logUrl = redactUrl(location);
     appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
     const t1 = performance.now();
-    const redirectRes = await githubFetch(location);
+    const redirectRes = await githubFetch(location, undefined, GITHUB_LOG_TIMEOUT_MS);
     appendEntry(formatResponseEntry({
         n: n2,
         kind: "restText",

package/bin/github/stack-handoff-page.mjs

@@ -90,6 +90,7 @@ export function batchResponseFromSummary(layer, source, runs) {
             ...(run.annotations && { annotations: run.annotations }),
             checkSuite: suite
                 ? {
+                    ...(suite.status && { status: suite.status }),
                     ...(suite.createdAt && { createdAt: suite.createdAt }),
                     ...(suite.updatedAt && { updatedAt: suite.updatedAt }),
                     workflowRun: workflowRun

package/bin/reporters/agent.mjs

@@ -59,6 +59,8 @@ export function toAgentCheck(c) {
         runId: c.runId,
         detailsUrl: c.detailsUrl,
         conclusion: c.conclusion,
+        ...(c.status !== "COMPLETED" &&
+            c.suiteStatus !== undefined && { status: c.status, suiteStatus: c.suiteStatus }),
         ...(c.runAttempt !== undefined && c.runAttempt > 1 && { runAttempt: c.runAttempt }),
         ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
         ...(c.jobName !== undefined && { jobName: c.jobName }),

package/bin/types/github.d.mts

@@ -57,9 +57,17 @@ export interface CheckRun {
     summary?: string;
     /** Workflow display name for GitHub Actions check runs, when GraphQL exposes it. */
     workflowName?: string;
+    /**
+     * Raw status of the check suite this run belongs to. Absent when GitHub did not report one
+     * (status contexts, synthetic checks, or a transport that cannot read it). A `COMPLETED`
+     * suite with a run that is not `COMPLETED` is a stuck check.
+     */
+    suiteStatus?: string;
     workflowId?: string;
     /** True when GraphQL reported at least one CheckRun annotation. Omitted when false. */
     hasAnnotations?: boolean;
+    /** Annotation total GraphQL reported for this CheckRun. Internal: validates cached lists. */
+    annotationCount?: number;
     /**
      * Every annotation on this run, when BatchPr's `annotations(first: 1)` page already held all
      * of them. Internal: lets the check path skip `CheckRunAnnotationsBatch`; never rendered.

package/bin/types/poll-summary.d.mts

@@ -3,6 +3,7 @@ import type { MergeableState, MergeStateStatus, ReviewDecision } from "./github.
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
 import type { ShepherdAction } from "./iterate.mts";
 import type { NextCheck } from "./next-check.mts";
+import type { AutoMinimizedItem } from "./report.mts";
 export interface PollSummaryChecks {
     passing?: number;
     failing?: number;
@@ -12,11 +13,26 @@ export interface PollSummaryChecks {
     ignored?: number;
     superseded?: number;
     incomplete?: true;
+    /**
+     * Non-SUCCESS checks with annotations the one-PR check has not shown yet (or that could not be
+     * read). Only set on a row that would otherwise claim ready; it routes to `triage`.
+     */
+    annotated?: number;
     /** Required contexts with no check run and no status context. Omitted when empty. */
     unreportedRequired?: string[];
     /** A relevant Actions workflow suite has not completed. */
     actionsWorkflowInProgress?: true;
 }
+/** The one-PR `ruleAutoResolve` content, with threads reduced to what a row needs: ID and link. */
+export interface PollSummaryRuleAutoResolve {
+    summary: string;
+    threads?: Array<{
+        id: string;
+        url?: string;
+    }>;
+    minimized?: AutoMinimizedItem[];
+    errors?: string[];
+}
 export interface PollSummaryReview {
     comments?: number;
     reviews?: number;
@@ -56,6 +72,8 @@ export interface PollSummaryItem {
     /** Conservative routing hint; the selected one-PR poll makes the authoritative decision. */
     action: ShepherdAction;
     reasons: string[];
+    /** Raw message of the error that stopped this PR's summary read (`summary-read-failed`). */
+    error?: string;
     state: "OPEN" | "CLOSED" | "MERGED" | "UNKNOWN";
     mergeable: MergeableState;
     mergeStateStatus: MergeStateStatus;
@@ -72,6 +90,11 @@ export interface PollSummaryItem {
     remainingSeconds?: number;
     checks?: PollSummaryChecks;
     review?: PollSummaryReview;
+    /**
+     * Rule-driven auto-resolve this tick performed or failed, in the one-PR `ruleAutoResolve`
+     * shape. Kept out of `review` so a one-tick event does not churn the status signature.
+     */
+    ruleAutoResolve?: PollSummaryRuleAutoResolve;
     stack?: PollSummaryStack;
     pollCommand?: string;
     /**

package/bin/types/report.d.mts

@@ -1,4 +1,4 @@
-import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, ViewerAuthorization, CheckConclusion, SuggestionBlock } from "./github.mts";
+import type { AuthorType, ReviewThread, PrComment, Review, MergeStatusResult, ViewerAuthorization, CheckConclusion, CheckStatus, SuggestionBlock } from "./github.mts";
 import type { ClassifiedCheck, RelatedFailedJob, TriagedCheck } from "./check-classification.mts";
 import type { AgentThreadComment } from "./agent-thread.mts";
 import type { CheckAnnotation } from "./check-annotations.mts";
@@ -196,6 +196,10 @@ export interface AgentCheck {
     detailsUrl: string | null;
     /** Raw GitHub check conclusion; may be null for some completed checks from upstream data. */
     conclusion: CheckConclusion;
+    /** Raw check status, present only for a stuck check: not `COMPLETED` while its suite is. */
+    status?: CheckStatus;
+    /** Raw check-suite status (`COMPLETED`), present only with `status` for a stuck check. */
+    suiteStatus?: string;
     /** Workflow display name (e.g. `"CI"`). Populated on a best-effort basis when available from the jobs API. */
     workflowName?: string;
     /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from check name for matrix builds. */

package/package.json

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

package/plugins/pr-shepherd/.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": "1.0.0",
+  "version": "1.1.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

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

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

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

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

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

@@ -13,6 +13,7 @@ Apply when a step says `Playbook: "CI failure triage"`. Use the excerpts and tag
 - Actions failure with a run id: read the excerpt. Fix a real test or build failure in code and never rerun it, even with a printed `rerun:`. Run a printed `rerun:` only for a transient cause; without one, finish the other work. Then iterate without waiting.
 - An empty excerpt is not evidence of a transient failure. A gate-job excerpt naming failed jobs (for example `test-playwright: failure`) is test-failure evidence even without a stack trace: read the `Other failed jobs in this run` tails first, and only when a named job's tail is absent or truncated run `gh run view <runId> --log-failed -R <owner/repo>`. Rerun only when those logs show a transient cause.
 - `CANCELLED` or `STARTUP_FAILURE` (no excerpt): run a printed `rerun:`, else finish the other work; iterate without waiting.
+- `[status: …, suite: COMPLETED]` (stuck run): the workflow finished but this check never completed, so there is nothing to fix in code. Run a printed `rerun:`, else finish the other work; iterate without waiting.
 - `ACTION_REQUIRED`: finish the other work and iterate. Shepherd escalates if manual approval is still required.
 - `external` with a URL: inspect the provider or reproduce locally, fix, and iterate. The URL alone is not `[ESCALATE]`.
 - `(no runId)` without a URL: keep the metadata. Shepherd escalates when nothing else remains.