pr-shepherd 0.7.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -1,16 +1,26 @@
 # pr-shepherd
 
 Autonomous PR CI monitor and review-comment resolver for Claude Code.
+The goal is to have an agent take a plan to a human-reviewable PR autonomously.
+
+Example Workflow:
+
+1. `/model opusplan`
+2. Create a plan
+3. Accept the plan
+4. Switch to Auto Mode
+5. Prompt: `make a PR, then run /pr-shepherd:monitor`
+6. ...
+7. Human reviews PR with passing CI, no open threads, and all comments minimized
 
 ## Why pr-shepherd
 
 Concrete improvements to an agentic PR-review workflow:
 
 - **Faster monitor loops** — one batched GraphQL query per tick (see [docs/graphql.md](docs/graphql.md)) instead of N REST round-trips
-- **Lower context usage per iteration** — classification lives in TypeScript; the agent receives one decision per tick and never sees raw GraphQL payloads or resolved threads
-- **Deterministic output** — `--format=json` and `--format=text` surface equivalent information, so both scripts and agents see the same state
+- **Lower context usage per iteration** — classification lives in the CLI; the agent receives one decision per tick and never sees raw GraphQL payloads or resolved threads
 - **Prompt-cache friendly** — the 4-minute default tick is tuned to Claude's 5-minute prompt-cache TTL (tunable via `watch.interval`)
-- **Reduced GitHub rate-limit exposure** — read results share a 5-minute file cache with atomic writes (see [docs/cache.md](docs/cache.md))
+- **Reduced GitHub rate-limit exposure** — one batched GraphQL read per tick; loop-state files (fix-attempts, stall detection, ready-delay timer) are kept in `$TMPDIR/pr-shepherd-state/`
 - **No MCP surface** — skills call the CLI via `npx`; no long-lived MCP server, no extra auth boundary, smaller reasoning surface
 - **Skills over subagents** — skill prompts inject into the main conversation rather than spawning a subagent that reloads CLAUDE.md every turn
 - **Safe to interrupt** — all state lives in the PR on GitHub; the cron loop self-terminates when the PR is merged, closed, or settles after ready-delay
@@ -20,130 +30,9 @@ Concrete improvements to an agentic PR-review workflow:
 - **Reduced agent context** — logic lives in the CLI, not the prompt
 - **Reduced GitHub rate-limit exhaustion** — primary PR state is fetched via a batched GraphQL query
 - **Fewer tool calls** — comment resolutions are batched; resolved threads never reach the agent
-- **No MCP** — smaller reasoning surface, much faster than the GitHub MCP
-- **No vendor lock-in** — runs against `gh` + `git`; no hosted service required
 - **Skills over subagents** — subagents reload all CLAUDE.md context on every turn; skills inject into the main conversation instead, keeping cost low
 - **JSON/text parity** — `--format=json` and `--format=text` carry equivalent information; every field in one has a representation in the other
 
-## Features
-
-pr-shepherd is split into a CLI (deterministic, pure GitHub I/O) and three Claude Code skills that wrap the CLI with model-driven flow and mutation.
-
-### What the CLI does
-
-Deterministic commands that fetch, classify, and mutate PR state without invoking the model:
-
-- **`check`** — one-shot PR snapshot (merge state, CI results, unresolved comments) via a single batched GraphQL query
-- **`resolve`** — fetch/triage mode auto-resolves outdated threads and returns actionable items; mutate mode batch-resolves threads, minimizes comments, and dismisses reviews by ID, polling `--require-sha` so reviewers see the push before threads close
-- **`iterate`** — classifies current PR state and emits exactly one of eight actions: `cooldown`, `wait`, `rerun_ci`, `mark_ready`, `rebase`, `fix_code`, `cancel`, `escalate` (see [docs/actions.md](docs/actions.md))
-- **`status`** — multi-PR summary table, one lightweight GraphQL query per PR in parallel
-
-Cross-cutting machinery: file cache with atomic writes ([docs/cache.md](docs/cache.md)), merge-status derivation ([docs/merge-status.md](docs/merge-status.md)), CI failure classification into `actionable` / `infrastructure` / `timeout` / `flaky` ([docs/checks.md](docs/checks.md)), outdated-thread detection ([docs/comments.md](docs/comments.md)), deprecation-warning-aware RC loader.
-
-### What the skills do
-
-Claude Code skills that wrap the CLI with model-driven triage, code edits, and flow control:
-
-- **`/pr-shepherd:check`** — calls `check --format=json` and prints a human summary; never declares "ready to merge" unless every gate passes (merge status CLEAN, status READY, Copilot review not in progress)
-- **`/pr-shepherd:monitor`** — creates a `/loop` cron job (4-minute default, 8-hour expiry, 50-turn cap), deduplicates via a `# pr-shepherd-loop:pr=<N>` tag in `CronList`, dispatches on the `[ACTION]` H1 tag each tick, runs rebase scripts and fix instructions in the main conversation
-- **`/pr-shepherd:resolve`** — runs `resolve --fetch`, triages every returned item into Fixed / Actionable / Not-relevant / Outdated / Acknowledge (no silent drops — this is a project invariant), applies edits, cancels stale CI runs, pushes, then calls `resolve` in mutate mode with `--require-sha`
-
-See [docs/skills.md](docs/skills.md) for full skill reference.
-
-## Install
-
-> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `npx pr-shepherd`, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so `npx` resolves it without prompting:
->
-> ```bash
-> npm install --save-dev pr-shepherd
-> ```
->
-> A plain `npm install pr-shepherd` adds it to regular dependencies instead; use that only if you specifically want it under `dependencies`. Or install globally: `npm install -g pr-shepherd`.
-
-### As individual skills via `npx skills`
-
-```bash
-npx skills add jonathanong/pr-shepherd
-```
-
-Installs the three skills (`check`, `monitor`, `resolve`) into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
-
-### As a Claude Code plugin (recommended)
-
-```bash
-claude /plugin marketplace add jonathanong/pr-shepherd
-claude /plugin install pr-shepherd
-```
-
-This repo ships two `marketplace.json` files that serve different install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
-
-See [Usage](#usage) below.
-
-### Without the plugin — custom slash command
-
-If you don't want the full plugin, create a project-local (or user-scope)
-slash command that wraps the CLI directly. This still requires `pr-shepherd`
-to be installed in the repository first (`npm install pr-shepherd`), so that
-`npx pr-shepherd ...` runs without prompting to install the package.
-
-1. **Create the command file:**
-   - Project-scope: `.claude/commands/pr-check.md`
-   - User-scope: `~/.claude/commands/pr-check.md`
-
-2. **Paste this as the file contents:**
-
-   ````markdown
-   ---
-   description: "Check GitHub CI status and review comments for the current PR"
-   argument-hint: "[PR number or URL ...]"
-   allowed-tools: ["Bash", "Read", "Grep"]
-   ---
-
-   # PR Status Check
-
-   ## Arguments: $ARGUMENTS
-
-   ## Resolve PR number(s)
-
-   1. If `$ARGUMENTS` contains PR numbers or GitHub PR URLs, extract the number(s).
-   2. Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
-   3. If no PR found, report an error and stop.
-
-   ## Run the check
-
-   ```bash
-   npx pr-shepherd check <PR_NUMBER> --format=json
-   ```
-
-   Parse the JSON and report:
-
-   - **Merge status** (`report.mergeStatus.status`): CLEAN | BEHIND | CONFLICTS | BLOCKED | UNSTABLE | DRAFT | UNKNOWN
-   - **CI check results** (`report.checks`): passing count, failing names, in-progress names
-   - **Unresolved review comments** (`report.threads.actionable` + `report.comments.actionable`): count + details
-   ````
-
-3. **Use it in Claude Code:**
-
-   ```
-   /pr-check
-   /pr-check 42
-   ```
-
-For `monitor` and `resolve` custom commands, do **not** copy the
-[`plugin/skills/`](plugin/skills/) files directly — those contain skill/plugin-specific
-frontmatter that is not valid for `.claude/commands/` files. Instead, create
-`.claude/commands/pr-monitor.md` and/or `.claude/commands/pr-resolve.md`
-using the same command-file structure as the `pr-check` example above, with
-the CLI invocation changed to `npx pr-shepherd iterate ...` or
-`npx pr-shepherd resolve ...`. To drive the CLI without Claude at all, see
-[docs/usage.md](docs/usage.md).
-
-### As a global CLI
-
-```bash
-npm install -g pr-shepherd
-```
-
 ## Usage
 
 ### Monitor a PR
@@ -185,174 +74,45 @@ See [docs/skills.md](docs/skills.md) for full argument reference.
 
 ## Workflow
 
-On each tick (4-minute default, tunable via `watch.interval`): fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (fix code, rebase, rerun CI, mark ready, or wait). See [docs/flow.md](docs/flow.md) for the full decision tree.
-
-## CLI
+On each tick (4-minute default, tunable via `watch.interval`): fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (fix code, rebase, rerun CI, mark ready, or wait). See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
 
-```sh
-pr-shepherd check [PR]                                # read-only PR status snapshot
-pr-shepherd resolve [PR] [--fetch | --resolve-thread-ids …]
-pr-shepherd iterate [PR] [--cooldown-seconds N] [--ready-delay Nm] [--last-push-time N]
-pr-shepherd status PR1 [PR2 …]                        # multi-PR table
-```
-
-Common flags (all subcommands):
-
-| Flag                  | Default | Description                                                                         |
-| --------------------- | ------- | ----------------------------------------------------------------------------------- |
-| `--format text\|json` | `text`  | Output format                                                                       |
-| `--no-cache`          | false   | Bypass the 5-minute file cache                                                      |
-| `--cache-ttl N`       | `300`   | Cache TTL in seconds; takes precedence over `PR_SHEPHERD_CACHE_TTL_SECONDS` env var |
-
-### pr-shepherd check [PR]
-
-Read-only PR status snapshot. Fetches CI results, merge state, and review comments in one GraphQL batch. PR number is inferred from the current branch when omitted.
-
-```sh
-pr-shepherd check           # infer PR from current branch
-pr-shepherd check 42
-pr-shepherd check 42 --format=json
-pr-shepherd check 42 --no-cache
-```
-
-Exit codes: `0` READY · `2` IN_PROGRESS · `3` UNRESOLVED_COMMENTS · `1` all other statuses
-
-**Example output:**
-
-```
-PR #42 — owner/repo
-Status: UNRESOLVED_COMMENTS
-
-Merge Status: CLEAN
-  mergeStateStatus:       CLEAN
-  mergeable:              MERGEABLE
-  reviewDecision:         APPROVED
-  isDraft:                false
-  copilotReviewInProgress:false
-
-CI Checks: 3/3 passed
-
-Actionable Review Threads (1):
-  - threadId=RT_kwDOBxyz123 src/api.ts:47 (@reviewer)
-    Please add error handling here
-
-Summary: 1 actionable item(s) remaining
-```
-
-### pr-shepherd resolve [PR]
-
-Two modes: **fetch** (default) auto-resolves outdated threads and returns actionable items; **mutate** resolves/minimizes/dismisses specific IDs after you push fixes.
-
-**Fetch mode:**
-
-```sh
-pr-shepherd resolve           # fetch + auto-resolve outdated threads
-pr-shepherd resolve 42 --fetch --format=json
-```
-
-```
-Actionable Review Threads (2):
-  - threadId=RT_kwDOabc src/api.ts:47 (@reviewer): Please add error handling here
-  - threadId=RT_kwDOdef src/utils.ts:12 (@bot): Consider using a const here
-
-Summary: 2 actionable item(s)
-```
-
-**Mutate mode** (after pushing fixes):
-
-```sh
-pr-shepherd resolve 42 \
-  --resolve-thread-ids RT_kwDOabc,RT_kwDOdef \
-  --minimize-comment-ids IC_kwDOxyz \
-  --dismiss-review-ids PRR_kwDO123 \
-  --message "Switched query to parameterized form in src/db.ts" \
-  --require-sha $(git rev-parse HEAD)
-```
-
-```
-Resolved threads (2): RT_kwDOabc, RT_kwDOdef
-Minimized comments (1): IC_kwDOxyz
-Dismissed reviews (1): PRR_kwDO123
-```
-
-`--require-sha` polls GitHub until the PR head matches the SHA before mutating — ensures reviewers see the fix before threads are closed. Exit code: always `0`. `--message` is required only when `--dismiss-review-ids` is set, and should describe the specific fix — it is shown to the reviewer on GitHub.
+## Install
 
-### pr-shepherd iterate [PR]
+> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `npx pr-shepherd`, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so `npx` resolves it without prompting:
+>
+> ```bash
+> npm install --save-dev pr-shepherd
+> ```
+>
+> A plain `npm install pr-shepherd` adds it to regular dependencies instead; use that only if you specifically want it under `dependencies`. Or install globally: `npm install -g pr-shepherd`.
 
-One monitor tick: classifies current PR state and emits a single action. Used by the cron loop; the monitor skill calls this every 4 minutes and acts on the result. See [docs/iterate-flow.md](docs/iterate-flow.md) for the full decision tree.
+### As individual skills via `npx skills`
 
-```sh
-pr-shepherd iterate 42 --no-cache --format=json \
-  --ready-delay 10m \
-  --last-push-time "$(git log -1 --format=%ct HEAD)"
+```bash
+npx skills add jonathanong/pr-shepherd
 ```
 
-Flags:
-
-| Flag                          | Default | Description                                       |
-| ----------------------------- | ------- | ------------------------------------------------- |
-| `--ready-delay Nm`            | `10m`   | Settle window before the loop cancels after READY |
-| `--cooldown-seconds N`        | `30`    | Wait after a push before reading CI               |
-| `--last-push-time N`          | —       | Unix timestamp hint embedded in the result        |
-| `--no-auto-rerun`             | false   | Return `wait` instead of rerunning transient CI   |
-| `--no-auto-mark-ready`        | false   | Skip converting draft → ready-for-review          |
-| `--no-auto-cancel-actionable` | false   | Skip cancelling actionable failing runs           |
-
-**Markdown output** (default). The monitor SKILL reads the `[ACTION]` tag from the H1 heading to decide what to do. Every action emits an H1, a bolded base-fields line, a bolded summary line, then an action-specific body. Example for `[WAIT]`:
-
-```markdown
-# PR #42 [WAIT]
-
-**status** `READY` · **merge** `CLEAN` · **state** `OPEN` · **repo** `owner/repo`
-**summary** 3 passing, 0 skipped, 0 filtered, 0 inProgress · **remainingSeconds** 540 · **copilotReviewInProgress** false · **isDraft** false · **shouldCancel** false
+Installs the three skills (`check`, `monitor`, `resolve`) into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
 
-WAIT: 3 passing, 0 in-progress — 540s until auto-cancel
-```
+### As a Claude Code plugin (recommended)
 
-See [docs/actions.md](docs/actions.md) for the other seven actions — `cooldown`, `rerun_ci`, `mark_ready`, `cancel`, `rebase`, `fix_code`, `escalate`. `fix_code` is the richest: it emits sections for `## Review threads`, `## Actionable comments`, `## Failing checks`, `## Changes-requested reviews`, `## Noise (minimize only)`, `## Cancelled runs`, `## Rebase`, and `## Instructions`.
-
-Both `--format=text` (default Markdown) and `--format=json` carry equivalent information — every field exposed in JSON has a corresponding Markdown representation, and vice versa.
-
-**JSON output** (`--format=json`, compact single line):
-
-```json
-{
-  "pr": 42,
-  "repo": "owner/repo",
-  "status": "READY",
-  "state": "OPEN",
-  "mergeStateStatus": "CLEAN",
-  "copilotReviewInProgress": false,
-  "isDraft": false,
-  "shouldCancel": false,
-  "remainingSeconds": 540,
-  "summary": { "passing": 3, "skipped": 0, "filtered": 0, "inProgress": 0 },
-  "action": "wait"
-}
+```bash
+claude /plugin marketplace add jonathanong/pr-shepherd
+claude /plugin install pr-shepherd
 ```
 
-Exit codes: `0` wait/cooldown/rerun_ci/mark_ready · `1` fix_code/rebase · `2` cancel · `3` escalate
-
-### pr-shepherd status PR1 [PR2 …]
-
-Multi-PR summary table. One lightweight GraphQL query per PR, run in parallel.
+This repo ships two `marketplace.json` files that serve different install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
 
-```sh
-pr-shepherd status 41 42 43
-pr-shepherd status 100 --format=json
-```
+### Without the plugin
 
-```
+See [docs/custom-commands.md](docs/custom-commands.md) for a project-local slash command that wraps the CLI without the plugin.
 
-# owner/repo — PR status (3)
+### As a global CLI
 
-PR #41    Add new feature for user authentication           READY        SUCCESS
-PR #42    Refactor internal module                          IN PROGRESS  PENDING
-PR #43    Fix edge case in parser                           BLOCKED      SUCCESS (threads truncated — run shepherd check for full count)
+```bash
+npm install -g pr-shepherd
 ```
 
-Exit code: `0` if every PR is READY, `1` otherwise.
-
 ## Configuration
 
 Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to override defaults. The loader walks up from `cwd` to `$HOME` (if `$HOME` is on that path) or the filesystem root; the first match wins.
@@ -369,32 +129,7 @@ actions:
   autoRebase: false # disable for repos that enforce merge commits
 ```
 
-All supported keys:
-
-| Key                                  | Default                                   | Purpose                                                                          |
-| ------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------- |
-| `cache.ttlSeconds`                   | `300`                                     | File-cache TTL for read operations                                               |
-| `iterate.cooldownSeconds`            | `30`                                      | Wait after a push before reading CI                                              |
-| `iterate.fixAttemptsPerThread`       | `3`                                       | Max fix attempts per unresolved thread before `escalate`                         |
-| `watch.interval`                     | `"4m"`                                    | Monitor tick interval (tuned to Claude's 5-min prompt-cache TTL)                 |
-| `watch.readyDelayMinutes`            | `10`                                      | Settle window after READY before the monitor loop cancels                        |
-| `watch.expiresHours`                 | `8`                                       | Max lifetime of a monitor cron job                                               |
-| `watch.maxTurns`                     | `50`                                      | Max monitor ticks per session                                                    |
-| `resolve.concurrency`                | `4`                                       | Parallel fanout for per-thread GraphQL fetches                                   |
-| `resolve.shaPoll.intervalMs`         | `2000`                                    | Poll interval when waiting for `--require-sha` to land on GitHub                 |
-| `resolve.shaPoll.maxAttempts`        | `10`                                      | Max `--require-sha` polls before giving up                                       |
-| `resolve.fetchReviewSummaries`       | `true`                                    | Surface `COMMENTED` review summaries in `resolve --fetch` output                 |
-| `checks.ciTriggerEvents`             | `["pull_request", "pull_request_target"]` | Workflow `on:` events treated as PR CI (add `merge_group` for merge-queue repos) |
-| `checks.timeoutPatterns`             | see [`src/config.json`](src/config.json)  | Log patterns that classify a failure as `timeout`                                |
-| `checks.infraPatterns`               | see [`src/config.json`](src/config.json)  | Log patterns that classify a failure as `infrastructure`                         |
-| `checks.logMaxLines`                 | `50`                                      | Max log lines kept per failing check                                             |
-| `checks.logMaxChars`                 | `3000`                                    | Max log characters kept per failing check                                        |
-| `mergeStatus.blockingReviewerLogins` | `["copilot"]`                             | Reviewer logins whose pending review blocks `mark_ready`                         |
-| `actions.autoResolveOutdated`        | `true`                                    | Auto-resolve threads that point to code no longer in the PR diff                 |
-| `actions.autoRebase`                 | `true`                                    | Emit `rebase` for flaky failures when the branch is behind base                  |
-| `actions.autoMarkReady`              | `true`                                    | Emit `mark_ready` when a draft PR's CI goes clean                                |
-
-Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_CACHE_DIR` (override cache base dir), `PR_SHEPHERD_CACHE_TTL_SECONDS` (override cache TTL; `--cache-ttl` takes precedence over this env var, which in turn takes precedence over the RC/config value).
+Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_STATE_DIR` (override loop-state base dir).
 
 See [docs/configuration.md](docs/configuration.md) for full semantics and deprecated-key migration.
 

package/bin/checks/classify.mjs

@@ -9,7 +9,6 @@
  *      pass/fail tally. Report them as "skipped" for transparency but don't block on them.
  */
 import { loadConfig } from "../config/load.mjs";
-const RELEVANT_EVENTS = new Set(loadConfig().checks.ciTriggerEvents);
 /**
  * Classify a list of raw check runs into shepherd categories.
  *
@@ -17,11 +16,13 @@ const RELEVANT_EVENTS = new Set(loadConfig().checks.ciTriggerEvents);
  * @returns Classified checks. "filtered" items were excluded from the tally.
  */
 export function classifyChecks(checks) {
-    return checks.map((c) => classify(c));
+    const relevantEvents = new Set(loadConfig().checks.ciTriggerEvents);
+    return checks.map((c) => classify(c, relevantEvents));
 }
-function classify(check) {
+function classify(check, relevantEvents) {
     // Filter: runs from non-PR events don't count toward PR readiness.
-    if (check.event !== null && !RELEVANT_EVENTS.has(check.event)) {
+    // event === null means a commit StatusContext — these are always relevant regardless of ciTriggerEvents.
+    if (check.event !== null && !relevantEvents.has(check.event)) {
         return { ...check, category: "filtered" };
     }
     const { status, conclusion } = check;

package/bin/checks/triage.mjs

@@ -1,92 +1,106 @@
 /**
- * Triage failing check runs into four categories:
- *   - timeout: conclusion is TIMED_OUT or logs contain timeout markers.
- *   - infrastructure: conclusion is CANCELLED + infra-error log patterns.
- *   - actionable: compile error, test failure, lint violation from the PR's changes.
- *   - flaky: pre-existing or timing-dependent failures in untouched files.
+ * Triage failing check runs into three categories based solely on GitHub's
+ * own conclusion field — no log-content classification:
+ *   - timeout: conclusion is TIMED_OUT.
+ *   - cancelled: conclusion is CANCELLED, STARTUP_FAILURE, or STALE.
+ *   - actionable: everything else (FAILURE, ACTION_REQUIRED, …).
  *
- * Shepherd computes and returns triage results, including `failureKind`, for
- * downstream callers or slash-command logic to consume.
+ * Exception: checks with runId === null are always classified as "actionable"
+ * regardless of conclusion, so they surface in fix_code where the monitor
+ * escalates to the user (no run to rerun/inspect).
+ *
+ * For all checks with a non-null runId, the jobs API is called once per runId
+ * (results are cached across checks that share a run) to fetch workflow name
+ * and, for actionable checks, the first failed step name. No log fetching is done.
+ *
+ * Note on infrastructure-killed FAILURE runs: GitHub reports these as
+ * conclusion === "FAILURE", so they classify as "actionable". The jobs API
+ * surfaces their failedStep (e.g. "Set up job") which gives the agent a
+ * GitHub-native signal to distinguish runner setup deaths from real test
+ * failures — without any log-pattern analysis at the CLI level.
  */
-import { rest, restText } from "../github/http.mjs";
-import { loadConfig } from "../config/load.mjs";
-const config = loadConfig();
-const TIMEOUT_PATTERNS = config.checks.timeoutPatterns.map((p) => new RegExp(p, "i"));
-const INFRA_PATTERNS = config.checks.infraPatterns.map((p) => new RegExp(p, "i"));
+import { rest } from "../github/http.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 /**
- * Fetch logs and triage each failing check.
+ * Triage each failing check: classify by GitHub conclusion and call the jobs
+ * API for each check with a non-null runId to fetch workflow name and (for
+ * actionable failures) the name of the first failed step.
  *
- * Fetching logs is skipped for checks that have no `runId` (e.g. StatusContext nodes).
+ * Jobs responses are cached by runId so checks that share a run (e.g. matrix
+ * builds or multiple required steps in one workflow) make only one API call.
  */
 export function triageFailingChecks(failingChecks, repo) {
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo)));
+    const jobsCache = new Map();
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
 }
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
-async function triageCheck(check, repo) {
+async function triageCheck(check, repo, jobsCache) {
+    const failureKind = check.runId === null ? "actionable" : classifyConclusion(check.conclusion);
     if (check.runId === null) {
-        return { ...check, failureKind: "actionable" };
+        return { ...check, failureKind };
     }
-    const logExcerpt = await fetchFailedLogs(check.runId, repo);
-    const failureKind = classifyLogs(check, logExcerpt);
+    const jobs = await fetchJobs(check.runId, repo, jobsCache);
+    const jobInfo = jobs ? pickJobInfo(jobs, check.name, failureKind) : undefined;
     return {
         ...check,
         failureKind,
-        logExcerpt: logExcerpt.slice(-config.checks.logMaxChars) || undefined,
+        workflowName: jobInfo?.workflowName,
+        ...(failureKind === "actionable" && { failedStep: jobInfo?.failedStep }),
     };
 }
-async function fetchFailedLogs(runId, repo) {
+function classifyConclusion(c) {
+    if (c === "TIMED_OUT")
+        return "timeout";
+    if (c === "CANCELLED" || c === "STARTUP_FAILURE" || c === "STALE")
+        return "cancelled";
+    return "actionable";
+}
+function fetchJobs(runId, repo, cache) {
+    const cached = cache.get(runId);
+    if (cached)
+        return cached;
+    const promise = fetchJobsUncached(runId, repo);
+    cache.set(runId, promise);
+    return promise;
+}
+async function fetchJobsUncached(runId, repo) {
+    const { owner, name } = repo;
+    const perPage = 100;
+    const MAX_JOB_PAGES = 20; // 2000 jobs max
+    let pagesFetched = 0;
+    const allJobs = [];
     try {
-        const { owner, name } = repo;
-        const perPage = 100;
-        const allJobs = [];
         for (let page = 1;; page++) {
-            const jobsData = await rest("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`);
-            allJobs.push(...jobsData.jobs);
-            if (jobsData.jobs.length < perPage)
+            if (++pagesFetched > MAX_JOB_PAGES) {
+                process.stderr.write(`pr-shepherd: job pagination cap (${MAX_JOB_PAGES * 100} jobs) reached for run ${runId} — triage may be incomplete\n`);
                 break;
-        }
-        const failedJobs = allJobs.filter((j) => ["failure", "timed_out", "cancelled"].includes(j.conclusion ?? ""));
-        if (failedJobs.length === 0)
-            return "";
-        const logParts = await Promise.all(failedJobs.map(async (job) => {
-            try {
-                // Job-level endpoint (jobs/{id}/logs) redirects to plain text, unlike
-                // run-level (runs/{id}/logs) which returns a ZIP archive.
-                const logs = await restText(`/repos/${owner}/${name}/actions/jobs/${job.id}/logs`);
-                return logs.trim() ? `===== job: ${job.name} =====\n${logs}` : "";
             }
-            catch {
-                return "";
-            }
-        }));
-        const combined = logParts.filter(Boolean).join("\n");
-        const ansiEscapes = /\u001B\[[0-9;]*m/g;
-        return combined
-            .replace(ansiEscapes, "")
-            .split("\n")
-            .slice(-config.checks.logMaxLines)
-            .join("\n");
+            const data = await rest("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`);
+            allJobs.push(...data.jobs);
+            if (data.jobs.length < perPage)
+                break;
+        }
     }
     catch {
-        return "";
+        return undefined;
     }
+    return allJobs;
 }
-function classifyLogs(check, logs) {
-    if (check.conclusion === "TIMED_OUT")
-        return "timeout";
-    if (TIMEOUT_PATTERNS.some((re) => re.test(logs)))
-        return "timeout";
-    if (check.conclusion === "CANCELLED" && INFRA_PATTERNS.some((re) => re.test(logs))) {
-        return "infrastructure";
-    }
-    if (!logs.trim())
-        return "infrastructure";
-    if (/flaky|timing|race condition|retry/i.test(logs))
-        return "flaky";
-    return "actionable";
+function pickJobInfo(jobs, checkName, failureKind) {
+    // Match by name. For matrix jobs sharing a check name, prefer a failing one.
+    // Fall back to prefix matching for matrix jobs whose workflow-API name includes
+    // a suffix like "(ubuntu)" while checkName is just the base name.
+    const exactMatches = jobs.filter((j) => j.name === checkName);
+    const matchedJobs = exactMatches.length > 0 ? exactMatches : jobs.filter((j) => j.name.startsWith(checkName));
+    const job = matchedJobs.find((j) => j.conclusion === "failure") ?? matchedJobs[0];
+    if (!job)
+        return undefined;
+    const failedStep = failureKind === "actionable"
+        ? job.steps?.find((s) => s.conclusion === "failure")?.name
+        : undefined;
+    return { workflowName: job.workflow_name, failedStep };
 }