pr-shepherd 0.55.1 → 0.56.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.55.1",
+  "version": "0.56.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -27,7 +27,7 @@ Full reference: [docs/README.md](docs/README.md). Feature matrix: [docs/features
 
 `pr-shepherd` moves deterministic PR orchestration into a local MCP server, with a CLI for shells and CI. Both interfaces fetch the same GitHub state, emit raw-enough context, and return a numbered plan for the calling agent to follow.
 
-The MCP server exposes canonical `iterate`, `apply`, and `build_suggestion_patches` tools. `apply` accepts ordered review mutations, file-view mutations, and journal entries; the deprecated singular suggestion tool remains temporarily as an adapter. Direct MCP calls require a repository-qualified `pr`: a GitHub PR URL or `owner/repo#N`; the explicit repository is the target for GitHub I/O, even when it differs from the local checkout. The CLI and programmatic API also retain bare-number and current-branch PR discovery. The shipped skills are thin dispatchers for those tools.
+The MCP server exposes `iterate`, `apply`, `build_suggestion_patches`, `extract_journal`, and `get_journal`. `apply` accepts ordered review mutations, file-view mutations, and journal entries; the deprecated singular suggestion tool remains temporarily as an adapter. PR-targeted MCP calls require a repository-qualified `pr`: a GitHub PR URL or `owner/repo#N`; the explicit repository is the target for GitHub I/O, even when it differs from the local checkout. `extract_journal` takes a Markdown body string and performs no I/O. The CLI and programmatic API also retain bare-number and current-branch PR discovery. The shipped skills are thin dispatchers for those tools.
 
 Each tick returns exactly one action:
 
@@ -73,13 +73,12 @@ Conversations Resolved: No [Not Required]
 
 1. Review each item under `## Review threads` and `## Failing checks` and decide whether it needs a code change.
 2. Apply every warranted review fix in each file referenced above.
-3. Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.
-4. If you changed code, commit any remaining changes and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue.
-5. Substitute any command placeholders and run the generated review mutations.
-6. If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA.
-7. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
-8. Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.
-9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options; without code changes, complete the authorized review mutations and iterate immediately.
+3. Triage `## Failing checks`. Playbook: "CI failure triage".
+4. If you changed code, commit any remaining changes and push to the PR head branch. If you did not, do not commit.
+5. If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)` (it must equal the remote PR head). If you did, use the pushed SHA.
+6. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
+7. Run the `apply review:` command above. Playbook: "Review-mutation mechanics".
+8. `[FIX_CODE]` is non-terminal. Iterate immediately with the same options.
 ```
 
 See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`16`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
@@ -123,7 +122,7 @@ Grok:
 /pr-shepherd 42
 ```
 
-MCP clients call `iterate` once per tick, then use `apply` for review/file/journal mutations and `build_suggestion_patches` for anchored suggestions. Every direct MCP call supplies the same repository-qualified PR reference. `iterate` returns the same structured action data as the CLI, including its review mutation arguments. The client owns recurrence, so this works consistently in Codex, Claude Code, Grok, and any other stdio MCP client.
+MCP clients call `iterate` once per tick, then use `apply` for review/file/journal mutations and `build_suggestion_patches` for anchored suggestions. To read journal entries, call `extract_journal` with a body already in hand or `get_journal` with a repository-qualified PR reference. `iterate` returns the same structured action data as the CLI, including its review mutation arguments. The client owns recurrence, so this works consistently in Codex, Claude Code, Grok, and any other stdio MCP client.
 
 The CLI remains useful for shell workflows. Its canonical polling form is:
 
@@ -190,6 +189,10 @@ complete Markdown list item with LF line endings. It fails closed for malformed
 containers and ignores journal-shaped examples hidden in Markdown constructs. The full journal API,
 including append and reconciliation helpers, is documented in [docs/api.md](docs/api.md).
 
+MCP clients can call `extract_journal({ body: prBody })` for the same pure result without writing a
+file, or `get_journal({ pr: "owner/repo#123" })` to fetch a PR body through GraphQL and extract it.
+Both return the typed extraction JSON in `structuredContent` and `content`; neither mutates the PR.
+
 For shell automation that already has a PR body, use the equivalent local-only command:
 
 ```sh

package/bin/api.d.mts

@@ -2,6 +2,7 @@ import { type JournalResult } from "./commands/journal/index.mts";
 import { type MarkFilesAsViewedResult } from "./commands/mark-files-as-viewed.mts";
 import type { ResolveResult } from "./comments/resolve.mts";
 import type { BuildSuggestionPatchesResult, CommitSuggestionResult, IterateCommandOptions, IterateResult, PollSummaryResult } from "./types.mts";
+import { type ShepherdJournalExtraction } from "./journal/index.mts";
 export interface CreatePrShepherdOptions {
     /** Working directory used for git, config, and classification-rule lookups. */
     cwd?: string;
@@ -81,12 +82,16 @@ export interface BuildSuggestionPatchesInput {
     pr?: PrReference;
     suggestions: SuggestionPatchInput[];
 }
+export interface GetJournalInput {
+    pr: PrReference;
+}
 export interface PrShepherd {
     iterate(input?: SingleIterateInput): Promise<IterateResult>;
     iterate(input: AggregateIterateInput): Promise<PollSummaryResult>;
     iterate(input: IterateInput): Promise<IterateResult | PollSummaryResult>;
     apply(input: ApplyInput): Promise<ApplyResult>;
     buildSuggestionPatches(input: BuildSuggestionPatchesInput): Promise<BuildSuggestionPatchesResult>;
+    getJournal(input: GetJournalInput): Promise<ShepherdJournalExtraction>;
     /** Compatibility adapter; prefer buildSuggestionPatches. */
     buildSuggestionPatch(input: BuildSuggestionPatchInput): Promise<CommitSuggestionResult>;
 }

package/bin/api.mjs

@@ -10,7 +10,8 @@ import { runMarkFilesAsViewed, } from "./commands/mark-files-as-viewed.mjs";
 import { runResolveMutate } from "./commands/resolve-mutate.mjs";
 import { runWithExecutionCwd } from "./execution-context.mjs";
 import { parsePrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "./pr-reference.mjs";
-import { getRepoInfo } from "./github/client.mjs";
+import { getPullRequestBody, getRepoInfo } from "./github/client.mjs";
+import { extractShepherdJournal } from "./journal/index.mjs";
 /** Raised before any API mutation when an input cannot be validated. */
 export class PrShepherdValidationError extends Error {
     constructor(message) {
@@ -50,6 +51,16 @@ export function createPrShepherd(options = {}) {
     }
     return Object.freeze({
         iterate,
+        getJournal(input) {
+            return runWithExecutionCwd(cwd, async () => {
+                const { prNumber, targetRepository } = resolvePrReference(input.pr);
+                if (!prNumber)
+                    throw new PrShepherdValidationError("getJournal requires a PR reference");
+                const { owner, name } = targetRepository ?? (await getRepoInfo());
+                const { body } = await getPullRequestBody(prNumber, owner, name);
+                return extractShepherdJournal(body);
+            });
+        },
         apply(input) {
             return runWithExecutionCwd(cwd, async () => {
                 validateApplyInput(input);

package/bin/checks/job-log.d.mts

@@ -0,0 +1,9 @@
+import type { RepoInfo } from "../github/client.mts";
+import { type StateKey } from "../state/rest-cache.mts";
+import type { TriageBudget } from "./triage-budget.mts";
+/**
+ * `cacheable` gates the cross-tick cache — only set once the matched job has
+ * a terminal conclusion, so an in-progress job's (possibly partial) log
+ * never gets frozen into the cache.
+ */
+export declare function fetchJobLogExcerpt(jobId: number, repo: RepoInfo, stateKey?: StateKey, cacheable?: boolean, budget?: TriageBudget): Promise<string | undefined>;

package/bin/checks/job-log.mjs

@@ -0,0 +1,30 @@
+import { restText } from "../github/http.mjs";
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
+import { buildLogExcerpt } from "./log-excerpt.mjs";
+/**
+ * `cacheable` gates the cross-tick cache — only set once the matched job has
+ * a terminal conclusion, so an in-progress job's (possibly partial) log
+ * never gets frozen into the cache.
+ */
+export async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false, budget) {
+    const cacheName = `joblog-v2-${jobId}`;
+    if (stateKey && cacheable) {
+        const cached = await loadDerived(stateKey, cacheName);
+        if (cached)
+            return cached.value ?? undefined;
+    }
+    const { owner, name } = repo;
+    try {
+        if (!budget?.canScheduleOptional())
+            return undefined;
+        const excerpt = buildLogExcerpt(await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`, (rateLimit) => budget?.observe(rateLimit)));
+        if (stateKey && cacheable) {
+            await storeDerived(stateKey, cacheName, excerpt ?? null);
+        }
+        return excerpt;
+    }
+    catch (error) {
+        budget?.observeError(error);
+        return undefined;
+    }
+}

package/bin/checks/jobs-types.d.mts

@@ -0,0 +1,14 @@
+export interface ActionsJob {
+    id?: number;
+    name: string;
+    workflow_name?: string;
+    conclusion: string | null;
+    run_attempt?: number;
+    steps?: Array<{
+        name: string;
+        number: number;
+        conclusion: string | null;
+    }>;
+}
+/** Name of the first step with a non-success, non-skipped, non-neutral conclusion. */
+export declare function pickFailedStep(job: ActionsJob): string | undefined;

package/bin/checks/jobs-types.mjs

@@ -0,0 +1,7 @@
+/** Name of the first step with a non-success, non-skipped, non-neutral conclusion. */
+export function pickFailedStep(job) {
+    return job.steps?.find((s) => s.conclusion !== null &&
+        s.conclusion !== "success" &&
+        s.conclusion !== "skipped" &&
+        s.conclusion !== "neutral")?.name;
+}

package/bin/checks/related-jobs.d.mts

@@ -0,0 +1,11 @@
+import type { RepoInfo } from "../github/client.mts";
+import type { StateKey } from "../state/rest-cache.mts";
+import type { RelatedFailedJob } from "../types/check-classification.mts";
+import { type ActionsJob } from "./jobs-types.mts";
+import type { TriageBudget } from "./triage-budget.mts";
+/**
+ * Other failed jobs in the same workflow run, excluding the matched job and any
+ * job already surfaced as its own failing check (`surfacedNames`).
+ */
+export declare function pickRelatedFailedJobs(jobs: ActionsJob[], matchedJobId: number | undefined, surfacedNames: ReadonlySet<string>): ActionsJob[];
+export declare function fetchRelatedJobs(jobs: ActionsJob[], repo: RepoInfo, stateKey?: StateKey, budget?: TriageBudget): Promise<RelatedFailedJob[]>;

package/bin/checks/related-jobs.mjs

@@ -0,0 +1,32 @@
+import { fetchJobLogExcerpt } from "./job-log.mjs";
+import { pickFailedStep } from "./jobs-types.mjs";
+/** Max sibling failed jobs reported (and log-fetched) per workflow run. */
+const MAX_RELATED_JOBS = 5;
+const FAILED_JOB_CONCLUSIONS = new Set(["failure", "timed_out"]);
+/**
+ * Other failed jobs in the same workflow run, excluding the matched job and any
+ * job already surfaced as its own failing check (`surfacedNames`).
+ */
+export function pickRelatedFailedJobs(jobs, matchedJobId, surfacedNames) {
+    return jobs
+        .filter((j) => j.conclusion !== null &&
+        FAILED_JOB_CONCLUSIONS.has(j.conclusion) &&
+        (j.id === undefined || j.id !== matchedJobId) &&
+        !surfacedNames.has(j.name))
+        .slice(0, MAX_RELATED_JOBS);
+}
+export async function fetchRelatedJobs(jobs, repo, stateKey, budget) {
+    const logs = await Promise.all(jobs.map((job) => job.id === undefined
+        ? undefined
+        : fetchJobLogExcerpt(job.id, repo, stateKey, job.conclusion !== null, budget)));
+    return jobs.map((job, i) => {
+        const failedStep = pickFailedStep(job);
+        const logExcerpt = logs[i];
+        return {
+            name: job.name,
+            conclusion: (job.conclusion ?? "").toUpperCase(),
+            ...(failedStep !== undefined && { failedStep }),
+            ...(logExcerpt !== undefined && { logExcerpt }),
+        };
+    });
+}

package/bin/checks/triage-budget.d.mts

@@ -0,0 +1,17 @@
+import type { RateLimitInfo } from "../github/client.mts";
+/** One optional Actions-enrichment budget for the entire PR snapshot. */
+export declare class TriageBudget {
+    private exhausted;
+    private secondaryError;
+    private omitted;
+    private omissionReported;
+    get canSchedule(): boolean;
+    get primaryExhausted(): boolean;
+    /** Call only when a needed optional request is about to be scheduled. */
+    canScheduleOptional(): boolean;
+    observe(rateLimit?: RateLimitInfo): void;
+    observeError(error: unknown): void;
+    throwIfSecondary(): void;
+    reportOmissionIfNeeded(): void;
+    private stopForPrimaryLimit;
+}

package/bin/checks/triage-budget.mjs

@@ -0,0 +1,49 @@
+import { pollRateLimitRetryAfterMs } from "../commands/poll-quota.mjs";
+/** One optional Actions-enrichment budget for the entire PR snapshot. */
+export class TriageBudget {
+    exhausted = false;
+    secondaryError;
+    omitted = false;
+    omissionReported = false;
+    get canSchedule() {
+        return !this.exhausted && this.secondaryError === undefined;
+    }
+    get primaryExhausted() {
+        return this.exhausted;
+    }
+    /** Call only when a needed optional request is about to be scheduled. */
+    canScheduleOptional() {
+        if (this.canSchedule)
+            return true;
+        if (this.exhausted)
+            this.omitted = true;
+        return false;
+    }
+    observe(rateLimit) {
+        if (rateLimit?.remaining === 0)
+            this.stopForPrimaryLimit();
+    }
+    observeError(error) {
+        const retry = pollRateLimitRetryAfterMs(error);
+        if (retry?.kind === "secondary") {
+            this.secondaryError ??= error;
+        }
+        else if (retry?.kind === "primary") {
+            this.stopForPrimaryLimit();
+            this.omitted = true;
+        }
+    }
+    throwIfSecondary() {
+        if (this.secondaryError !== undefined)
+            throw this.secondaryError;
+    }
+    reportOmissionIfNeeded() {
+        if (!this.omitted || this.omissionReported || this.secondaryError !== undefined)
+            return;
+        this.omissionReported = true;
+        process.stderr.write("pr-shepherd: REST core quota is exhausted; optional Actions job and log enrichment is incomplete\n");
+    }
+    stopForPrimaryLimit() {
+        this.exhausted = true;
+    }
+}

package/bin/checks/triage.d.mts

@@ -1,5 +1,8 @@
 import type { CheckRun, ClassifiedCheck, TriagedCheck } from "../types.mts";
 import type { RepoInfo } from "../github/client.mts";
-import { type StateKey } from "../state/rest-cache.mts";
-export declare function triageFailingChecks(failingChecks: ClassifiedCheck[], repo: RepoInfo, stateKey?: StateKey): Promise<TriagedCheck[]>;
-export declare function fetchStartupFailureChecks(repo: RepoInfo, headSha: string, prNumber: number, stateKey?: StateKey): Promise<CheckRun[]>;
+import type { StateKey } from "../state/rest-cache.mts";
+import { TriageBudget } from "./triage-budget.mts";
+export declare function triageFailingChecks(failingChecks: ClassifiedCheck[], repo: RepoInfo, stateKey?: StateKey, budget?: TriageBudget, 
+/** Non-failing checks (ignored, filtered, superseded, …) whose jobs must not resurface as related jobs. */
+otherChecks?: ClassifiedCheck[]): Promise<TriagedCheck[]>;
+export declare function fetchStartupFailureChecks(repo: RepoInfo, headSha: string, prNumber: number, stateKey?: StateKey, budget?: TriageBudget): Promise<CheckRun[]>;

package/bin/checks/triage.mjs

@@ -1,22 +1,38 @@
 /* eslint-disable max-lines */
-import { restWithRateLimit, restText } from "../github/http.mjs";
-import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
-import { buildLogExcerpt } from "./log-excerpt.mjs";
+import { restWithRateLimit } from "../github/http.mjs";
+import { fetchJobLogExcerpt } from "./job-log.mjs";
+import { pickFailedStep } from "./jobs-types.mjs";
+import { pickRelatedFailedJobs, fetchRelatedJobs } from "./related-jobs.mjs";
+import { TriageBudget } from "./triage-budget.mjs";
+import { mapPool } from "../util/pool.mjs";
 const STARTUP_FAILURE_STATUS = "startup_failure";
-export function triageFailingChecks(failingChecks, repo, stateKey) {
+export async function triageFailingChecks(failingChecks, repo, stateKey, budget = new TriageBudget(), 
+/** Non-failing checks (ignored, filtered, superseded, …) whose jobs must not resurface as related jobs. */
+otherChecks = []) {
     const jobsCache = new Map();
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, stateKey)));
+    const surfaced = surfacedNamesByRun([...failingChecks, ...otherChecks]);
+    const relatedOwners = firstCheckPerRun(failingChecks);
+    const checks = await mapPool(failingChecks, 4, (check) => triageCheck(check, repo, jobsCache, stateKey, budget, relatedOwners.has(check) ? surfaced.get(check.runId ?? "") : undefined));
+    budget.throwIfSecondary();
+    budget.reportOmissionIfNeeded();
+    return checks;
 }
-async function triageCheck(check, repo, jobsCache, stateKey) {
+async function triageCheck(check, repo, jobsCache, stateKey, budget, relatedSurfaced) {
     if (check.runId === null || check.conclusion === "STARTUP_FAILURE") {
         return { ...check };
     }
-    const jobs = await fetchJobs(check.runId, repo, jobsCache, stateKey);
+    if (!jobsCache.has(check.runId) && !budget?.canScheduleOptional()) {
+        return { ...check };
+    }
+    const jobs = await fetchJobs(check.runId, repo, jobsCache, stateKey, budget);
     const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
     const runAttempt = jobs ? pickRunAttempt(jobs) : undefined;
     const logExcerpt = check.conclusion !== "CANCELLED" && jobInfo?.jobId
-        ? await fetchJobLogExcerpt(jobInfo.jobId, repo, stateKey, jobInfo.jobConclusion != null)
+        ? await fetchJobLogExcerpt(jobInfo.jobId, repo, stateKey, jobInfo.jobConclusion != null, budget)
         : undefined;
+    const relatedJobs = jobs && relatedSurfaced && check.conclusion !== "CANCELLED"
+        ? await fetchRelatedJobs(pickRelatedFailedJobs(jobs, jobInfo?.jobId, relatedSurfaced), repo, stateKey, budget)
+        : [];
     return {
         ...check,
         ...(runAttempt !== undefined && { runAttempt }),
@@ -24,40 +40,79 @@ async function triageCheck(check, repo, jobsCache, stateKey) {
         ...(jobInfo?.jobName !== undefined && { jobName: jobInfo.jobName }),
         ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
         ...(logExcerpt !== undefined && { logExcerpt }),
+        ...(relatedJobs.length > 0 && { relatedJobs }),
     };
 }
-export async function fetchStartupFailureChecks(repo, headSha, prNumber, stateKey) {
+function surfacedNamesByRun(checks) {
+    const byRun = new Map();
+    for (const check of checks) {
+        if (check.runId === null)
+            continue;
+        const names = byRun.get(check.runId) ?? new Set();
+        names.add(check.name);
+        byRun.set(check.runId, names);
+    }
+    return byRun;
+}
+/** Sibling failed jobs are reported once per run, on its first failing check. */
+function firstCheckPerRun(checks) {
+    const seen = new Set();
+    const first = new Set();
+    for (const check of checks) {
+        if (check.runId === null || seen.has(check.runId))
+            continue;
+        if (check.conclusion === "CANCELLED" || check.conclusion === "STARTUP_FAILURE")
+            continue;
+        seen.add(check.runId);
+        first.add(check);
+    }
+    return first;
+}
+export async function fetchStartupFailureChecks(repo, headSha, prNumber, stateKey, budget = new TriageBudget()) {
     try {
-        return await fetchStartupFailureChecksUncached(repo, headSha, prNumber, stateKey);
+        return await fetchStartupFailureChecksUncached(repo, headSha, prNumber, stateKey, budget);
     }
     catch (err) {
+        budget.observeError(err);
+        budget.throwIfSecondary();
+        if (budget.primaryExhausted)
+            return [];
         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, stateKey) {
+async function fetchStartupFailureChecksUncached(repo, headSha, prNumber, stateKey, budget) {
     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, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`, undefined, stateKey
-            ? {
-                conditional: {
-                    key: stateKey,
-                    name: `runs-startupfailure-${headSha}-p${page}`,
-                    headSha,
-                },
-            }
-            : undefined);
+        if (!budget?.canScheduleOptional())
+            break;
+        let result;
+        try {
+            result = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs?head_sha=${encodeURIComponent(headSha)}&status=${STARTUP_FAILURE_STATUS}&per_page=${perPage}&page=${page}`, undefined, stateKey
+                ? {
+                    conditional: {
+                        key: stateKey,
+                        name: `runs-startupfailure-${headSha}-p${page}`,
+                        headSha,
+                    },
+                }
+                : undefined);
+        }
+        catch (error) {
+            budget?.observeError(error);
+            if (budget?.primaryExhausted)
+                break;
+            throw error;
+        }
+        const { data, rateLimit } = result;
+        budget?.observe(rateLimit);
         checks.push(...data.workflow_runs
             .filter((run) => runBelongsToPr(run, prNumber, headSha))
             .map(workflowRunToCheckRun));
-        if (rateLimit?.remaining === 0) {
-            process.stderr.write(`pr-shepherd: REST rate limit remaining is 0 while listing startup-failure runs for ${headSha} — detection may be incomplete\n`);
-            break;
-        }
         if (data.workflow_runs.length < perPage)
             break;
         if (page === MAX_RUN_PAGES) {
@@ -95,15 +150,15 @@ function pickRunAttempt(jobs) {
 function runBelongsToPr(run, prNumber, headSha) {
     return (run.pull_requests ?? []).some((pr) => pr.number === prNumber && (pr.head?.sha ?? headSha) === headSha);
 }
-function fetchJobs(runId, repo, cache, stateKey) {
+function fetchJobs(runId, repo, cache, stateKey, budget) {
     const cached = cache.get(runId);
     if (cached)
         return cached;
-    const promise = fetchJobsUncached(runId, repo, stateKey);
+    const promise = fetchJobsUncached(runId, repo, stateKey, budget);
     cache.set(runId, promise);
     return promise;
 }
-async function fetchJobsUncached(runId, repo, stateKey) {
+async function fetchJobsUncached(runId, repo, stateKey, budget) {
     const { owner, name } = repo;
     const perPage = 100;
     const MAX_JOB_PAGES = 20; // 2000 jobs max
@@ -111,6 +166,8 @@ async function fetchJobsUncached(runId, repo, stateKey) {
     const allJobs = [];
     try {
         for (let page = 1;; page++) {
+            if (!budget?.canScheduleOptional())
+                break;
             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;
@@ -118,17 +175,15 @@ async function fetchJobsUncached(runId, repo, stateKey) {
             const { data, rateLimit } = await restWithRateLimit("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`, undefined, stateKey
                 ? { conditional: { key: stateKey, name: `jobs-run-${runId}-p${page}` } }
                 : undefined);
+            budget?.observe(rateLimit);
             allJobs.push(...data.jobs);
-            if (rateLimit?.remaining === 0) {
-                process.stderr.write(`pr-shepherd: REST rate limit remaining is 0 while listing jobs for run ${runId} — triage may be incomplete\n`);
-                break;
-            }
             if (data.jobs.length < perPage)
                 break;
         }
     }
-    catch {
-        return undefined;
+    catch (error) {
+        budget?.observeError(error);
+        return budget?.primaryExhausted ? allJobs : undefined;
     }
     return allJobs;
 }
@@ -140,10 +195,7 @@ function pickJobInfo(jobs, checkName) {
         matchedJobs[0];
     if (!job)
         return undefined;
-    const failedStep = job.steps?.find((s) => s.conclusion !== null &&
-        s.conclusion !== "success" &&
-        s.conclusion !== "skipped" &&
-        s.conclusion !== "neutral")?.name;
+    const failedStep = pickFailedStep(job);
     return {
         ...(job.id !== undefined && { jobId: job.id }),
         workflowName: job.workflow_name,
@@ -152,27 +204,3 @@ function pickJobInfo(jobs, checkName) {
         jobConclusion: job.conclusion,
     };
 }
-/**
- * `cacheable` gates the cross-tick cache — only set once the matched job has
- * a terminal conclusion, so an in-progress job's (possibly partial) log
- * never gets frozen into the cache.
- */
-async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false) {
-    const cacheName = `joblog-v2-${jobId}`;
-    if (stateKey && cacheable) {
-        const cached = await loadDerived(stateKey, cacheName);
-        if (cached)
-            return cached.value ?? undefined;
-    }
-    const { owner, name } = repo;
-    try {
-        const excerpt = buildLogExcerpt(await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`));
-        if (stateKey && cacheable) {
-            await storeDerived(stateKey, cacheName, excerpt ?? null);
-        }
-        return excerpt;
-    }
-    catch {
-        return undefined;
-    }
-}

package/bin/cli/api-usage-formatter.mjs

@@ -31,9 +31,9 @@ function recommendation(warning) {
         return "- Recommendation: keep polling pr-shepherd at the cadence above; both GraphQL and REST core are below their warning thresholds, so do not shift work between them. Do not substitute `gh pr checks` or `gh pr watch`";
     }
     if (warning.resource === "core") {
-        return "- Recommendation: keep polling pr-shepherd at the cadence above; do not add incidental REST `gh` calls (`gh pr view`, `gh pr review`, `gh api`) while REST core is low. Do not substitute `gh pr checks` or `gh pr watch`";
+        return "- Recommendation: keep polling pr-shepherd at the cadence above; do not add incidental REST `gh api repos/OWNER/REPO/pulls/PR` calls while REST core is low. Do not substitute `gh pr checks` or `gh pr watch`";
     }
-    return "- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR operations prefer REST `gh` (`gh pr view`, `gh pr review`, `gh api`); do not substitute `gh pr checks` or `gh pr watch`";
+    return "- Recommendation: keep polling pr-shepherd at the cadence above; for incidental PR reads use explicit REST endpoints such as `gh api repos/OWNER/REPO/pulls/PR`; do not substitute `gh pr checks` or `gh pr watch`";
 }
 export function formatApiUsage(usage) {
     if (usage === undefined)

package/bin/cli/fix-formatter.mjs

@@ -6,6 +6,7 @@ import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag
 import { BODY_TRUNCATE_MAX_CHARS } from "./body-truncate.mjs";
 import { numberInstructions } from "./iterate-instructions.mjs";
 import { renderCheckAnnotation, renderProtectedRun } from "./fix-formatter-extra.mjs";
+import { renderRelatedJobLines } from "./related-jobs-format.mjs";
 import { isFailingAgentCheck } from "../checks/conclusions.mjs";
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 import { partitionFixThreads } from "../commands/iterate/fix-instruction-threads.mjs";
@@ -81,6 +82,7 @@ export function formatFixCodeResult(header, result, opts = {}) {
                     lines.push(`  > ${ch.summary}`);
                 if (ch.logExcerpt)
                     lines.push(indentBlockquote(ch.logExcerpt, "  "));
+                lines.push(...renderRelatedJobLines(ch.relatedJobs));
             }
             if (ch.rerunCommand && ch.runId && !seenRerunRunIds.has(ch.runId)) {
                 seenRerunRunIds.add(ch.runId);

package/bin/cli/help-command-pages.d.mts

@@ -212,7 +212,7 @@ Flags:
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  READY       Clean PR is inside the ready-delay. Wait out remainingSeconds, then poll again.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until READY, FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 

package/bin/cli/help-iterate-poll-pages.d.mts

@@ -1,4 +1,4 @@
-export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  READY       Clean PR is inside the ready-delay. Wait out remainingSeconds, then poll again.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
 export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until READY, FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
 /** Public help page for the default PR polling invocation. */
 export declare const DEFAULT_USAGE: string;

package/bin/cli/help-iterate-poll-pages.mjs

@@ -21,7 +21,7 @@ Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decima
 Actions:
   WAIT        No immediate action; continue with the next poll.
   MARK_READY  Draft PR was marked ready; continue with the next poll.
-  READY       Clean PR is inside the ready-delay. Wait out remainingSeconds, then poll again.
+  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.
   FIX_CODE    Agent action is required; follow the instructions, then continue polling.
   CANCEL      Stop polling: merged/closed or ready-delay elapsed.
   ESCALATE    Stop polling until a human provides direction.