pr-shepherd 0.14.1 → 0.15.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.14.1",
+  "version": "0.15.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/checks/startup-failures.mjs

@@ -0,0 +1,22 @@
+export function mergeStartupFailureChecks(checks, startupFailureChecks) {
+    const byRunId = new Map();
+    checks.forEach((check, index) => {
+        if (check.runId === null)
+            return;
+        const indices = byRunId.get(check.runId) ?? [];
+        indices.push(index);
+        byRunId.set(check.runId, indices);
+    });
+    const merged = [...checks];
+    const removed = new Set();
+    for (const startupFailure of startupFailureChecks) {
+        const indices = startupFailure.runId === null ? undefined : byRunId.get(startupFailure.runId);
+        if (indices === undefined) {
+            merged.push(startupFailure);
+            continue;
+        }
+        merged[indices[0]] = startupFailure;
+        indices.slice(1).forEach((index) => removed.add(index));
+    }
+    return merged.filter((_, index) => !removed.has(index));
+}

package/bin/checks/triage.mjs

@@ -1,10 +1,13 @@
 import { rest } from "../github/http.mjs";
+const STARTUP_FAILURE_STATUS = "startup_failure";
 export function triageFailingChecks(failingChecks, repo) {
     const jobsCache = new Map();
     return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
 }
 async function triageCheck(check, repo, jobsCache) {
-    if (check.runId === null || check.conclusion === "CANCELLED") {
+    if (check.runId === null ||
+        check.conclusion === "CANCELLED" ||
+        check.conclusion === "STARTUP_FAILURE") {
         return { ...check };
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache);
@@ -16,6 +19,49 @@ async function triageCheck(check, repo, jobsCache) {
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
     };
 }
+export async function fetchStartupFailureChecks(repo, headSha, prNumber) {
+    try {
+        return await fetchStartupFailureChecksUncached(repo, headSha, prNumber);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`pr-shepherd: startup-failure run fetch failed for PR #${prNumber} at ${headSha} (ignored): ${msg}\n`);
+        return [];
+    }
+}
+async function fetchStartupFailureChecksUncached(repo, headSha, prNumber) {
+    const { owner, name } = repo;
+    const perPage = 100;
+    const MAX_RUN_PAGES = 10;
+    const checks = [];
+    for (let page = 1; page <= MAX_RUN_PAGES; page++) {
+        const data = await rest("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`);
+        checks.push(...data.workflow_runs
+            .filter((run) => runBelongsToPr(run, prNumber, headSha))
+            .map(workflowRunToCheckRun));
+        if (data.workflow_runs.length < perPage)
+            break;
+        if (page === MAX_RUN_PAGES) {
+            process.stderr.write(`pr-shepherd: startup-failure run pagination cap (${MAX_RUN_PAGES * perPage} runs) reached for ${headSha} — startup-failure detection may be incomplete\n`);
+        }
+    }
+    return checks;
+}
+function workflowRunToCheckRun(run) {
+    const summary = run.display_title?.trim() || undefined;
+    return {
+        name: run.name?.trim() || `workflow run ${run.id}`,
+        status: "COMPLETED",
+        conclusion: "STARTUP_FAILURE",
+        detailsUrl: run.html_url,
+        event: run.event,
+        runId: String(run.id),
+        ...(summary !== undefined && { summary }),
+    };
+}
+function runBelongsToPr(run, prNumber, headSha) {
+    return (run.pull_requests ?? []).some((pr) => pr.number === prNumber && (pr.head?.sha ?? headSha) === headSha);
+}
 function fetchJobs(runId, repo, cache) {
     const cached = cache.get(runId);
     if (cached)

package/bin/commands/check.mjs

@@ -1,7 +1,8 @@
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getRepoInfo, getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
-import { triageFailingChecks } from "../checks/triage.mjs";
+import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
+import { fetchStartupFailureChecks, triageFailingChecks } from "../checks/triage.mjs";
 import { getOutdatedThreads } from "../comments/outdated.mjs";
 import { autoResolveOutdated } from "../comments/resolve.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
@@ -28,7 +29,9 @@ export async function runCheck(opts) {
             mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
         };
     }
-    const classifiedChecks = classifyChecks(batchData.checks);
+    const startupFailureChecks = await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
+    const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
+    const classifiedChecks = classifyChecks(allChecks);
     const verdict = getCiVerdict(classifiedChecks);
     const passing = classifiedChecks.filter((c) => c.category === "passed");
     const failing = classifiedChecks.filter((c) => c.category === "failing");

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

@@ -0,0 +1,24 @@
+export function buildFailingCheckInstructions(checks) {
+    const instructions = [];
+    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED" && c.conclusion !== "STARTUP_FAILURE");
+    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
+    const startupFailureRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "STARTUP_FAILURE");
+    const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
+    const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
+    if (failedRunIdChecks.length > 0) {
+        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` or \`[conclusion: STARTUP_FAILURE]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`, `If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`, `If the log shows a real test/build failure: apply a code fix.`);
+    }
+    if (cancelledRunIdChecks.length > 0) {
+        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
+    }
+    if (startupFailureRunIdChecks.length > 0) {
+        instructions.push(`For each \`[conclusion: STARTUP_FAILURE]\` bullet under \`## Failing checks\`: the workflow failed before jobs/logs were created. Run \`gh run view <runId>\` to inspect the run metadata, then run \`gh run rerun <runId>\` if the workflow should be attempted again.`);
+    }
+    if (externalChecks.length > 0) {
+        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
+    }
+    if (bareChecks.length > 0) {
+        instructions.push(`For each bullet in \`## Failing checks\` starting with \`(no runId)\`: there is no run or details URL to inspect. Escalate these to a human — they require manual investigation outside the pr-shepherd flow.`);
+    }
+    return instructions;
+}

package/bin/commands/iterate/render.mjs

@@ -1,4 +1,5 @@
 import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
+import { buildFailingCheckInstructions } from "./check-instructions.mjs";
 export const FIX_INSTRUCTION_STOP_AFTER_PUSH = "Stop this iteration — CI needs time to run on the new push before the next tick.";
 export const FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK = "Stop this iteration before the next tick.";
 export const FIX_INSTRUCTION_END_ITERATION = "End this iteration.";
@@ -41,24 +42,7 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (resolutionOnlyThreads.length > 0) {
         instructions.push(`Resolve the threads under \`## Review threads to resolve\` with the \`resolve:\` command shown below. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
     }
-    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
-    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED");
-    const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
-    const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
-    if (failedRunIdChecks.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log.`);
-        instructions.push(`If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill): run \`gh run rerun <runId> --failed\`.`);
-        instructions.push(`If the log shows a real test/build failure: apply a code fix.`);
-    }
-    if (cancelledRunIdChecks.length > 0) {
-        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
-    }
-    if (externalChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
-    }
-    if (bareChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`(no runId)\`: there is no run or details URL to inspect. Escalate these to a human — they require manual investigation outside the pr-shepherd flow.`);
-    }
+    instructions.push(...buildFailingCheckInstructions(checks));
     if (reviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }

package/bin/reporters/agent.mjs

@@ -4,7 +4,7 @@
  * These strip fields that are always-false by the time items reach iterate
  * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
  * monitor prompt never reads (event, status, category).
- * conclusion is preserved on AgentCheck so the formatter can branch on CANCELLED.
+ * conclusion is preserved on AgentCheck so the formatter can branch on run-level conclusions.
  * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
  * The original domain types are preserved for check command output.
  */

package/bin/reporters/check-instructions.mjs

@@ -35,7 +35,9 @@ export function buildCheckInstructions(report, opts) {
         const diagnosisHint = c.runId
             ? c.conclusion === "CANCELLED"
                 ? `cancelled — if unintended, rerun with \`gh run rerun ${c.runId}\``
-                : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
+                : c.conclusion === "STARTUP_FAILURE"
+                    ? `startup failure — run \`gh run view ${c.runId}\` to inspect the workflow run; rerun with \`gh run rerun ${c.runId}\` if appropriate`
+                    : `run \`gh run view ${c.runId} --log-failed\`${stepHint} to diagnose — if transient, rerun with \`gh run rerun ${c.runId} --failed\`; otherwise apply a fix`
             : c.detailsUrl
                 ? `open the check details (${c.detailsUrl}) to diagnose the failure`
                 : `no run or details URL available — escalate to a human`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.14.1",
+  "version": "0.15.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.14.1",
+  "version": "0.15.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",