pr-shepherd 0.32.4 → 0.33.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.32.4",
+  "version": "0.33.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -190,7 +190,7 @@ actions:
 
 Environment variables:
 
-- `GH_TOKEN` / `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` for auth; `gh auth token` is used as a fallback.
+- `GH_TOKEN` / `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` for auth; `gh auth token` is used as a fallback. See [GitHub authentication and token access](docs/authentication.md) for required PAT permissions.
 - `PR_SHEPHERD_STATE_DIR` to override state and log location.
 - `PR_SHEPHERD_LOG_DISABLED=1` to disable per-worktree debug logging.
 
@@ -221,7 +221,7 @@ Ready-to-use examples for common patterns are in [`examples/classification/`](ex
 ## Requirements
 
 - Node.js >= 22.18.0, Bun, or Deno
-- A GitHub token or authenticated `gh` CLI; private repositories require `repo` scope.
+- A GitHub token or authenticated `gh` CLI with the [required repository access](docs/authentication.md). A classic PAT needs the `repo` scope for complete operation.
 - `git`
 
 ## Docs

package/bin/cli/help-command-pages.mjs

@@ -169,12 +169,18 @@ Creates the section at the end if absent. Idempotent — duplicate items are ski
 
 Usage:
   pr-shepherd journal [PR] <item> [--dry-run] [--format text|json]
+  pr-shepherd journal [PR] --file <path> [--dry-run] [--format text|json]
+  pr-shepherd journal [PR] --file - [--dry-run] [--format text|json]
 
   PR     PR number or GitHub pull request URL. Defaults to current branch PR.
   item   Markdown list item: must start with "- " followed by non-whitespace text.
          Example: '- Rejected suggestion: kept existing pattern for consistency.'
+         Provide it as a positional argument, or via --file to avoid shell-escaping
+         backticks and multi-line Markdown. Exactly one of the two is required.
 
 Flags:
+  --file <path>        Read the entry from a file instead of a positional argument.
+                        Pass --file - to read from stdin.
   --dry-run            Preview the new PR body without writing it to GitHub.
   --format text|json   Output format. Default: text.
   --help, -h           Print this help and exit before any GitHub I/O.

package/bin/cli/journal-handler.mjs

@@ -1,5 +1,6 @@
+import { readFile } from "node:fs/promises";
 import { runJournal } from "../commands/journal/index.mjs";
-import { parsePrNumber } from "./args.mjs";
+import { getFlag, parsePrNumber } from "./args.mjs";
 import { USAGE } from "./help.mjs";
 export async function handleJournal(args) {
     for (const a of args) {
@@ -7,13 +8,29 @@ export async function handleJournal(args) {
             continue;
         if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
             continue;
+        if (a === "--file" || a.startsWith("--file="))
+            continue;
         process.stderr.write(`pr-shepherd: journal: unknown flag: "${a}"\n`);
         process.exitCode = 1;
         return;
     }
     const { prNumber, extra } = parseJournalArgs(args);
-    const rawItem = extra[0];
-    if (!rawItem) {
+    const filePath = getFlag(args, "--file");
+    if (filePath !== null && extra[0]) {
+        process.stderr.write(`pr-shepherd: journal: provide the entry as a positional argument or via --file, not both\n`);
+        process.exitCode = 1;
+        return;
+    }
+    let rawItem;
+    try {
+        rawItem = filePath !== null ? await readItemSource(filePath) : extra[0];
+    }
+    catch (e) {
+        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (rawItem === undefined) {
         process.stderr.write(`${USAGE.journal}\n`);
         process.exitCode = 1;
         return;
@@ -35,11 +52,26 @@ export async function handleJournal(args) {
         process.exitCode = 1;
     }
 }
+/** Reads the journal entry from a file, or from stdin when `filePath` is `-`. */
+async function readItemSource(filePath) {
+    if (filePath === "-")
+        return readStdin();
+    return readFile(filePath, "utf8");
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
 function parseJournalArgs(args) {
     const flagConsumedIndices = new Set();
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === "--format" && i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        if ((a === "--format" || a === "--file") &&
+            i + 1 < args.length &&
+            !args[i + 1].startsWith("--")) {
             flagConsumedIndices.add(i);
             flagConsumedIndices.add(i + 1);
         }

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

@@ -8,6 +8,40 @@ export function buildCrStaleClause(reviews) {
         : "";
     return bot + human;
 }
+/**
+ * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
+ * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in CLAUDE.md); this
+ * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
+ * point of use (rather than at config load) so a malformed rc file value (non-string, or
+ * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or
+ * discarding the rest of the user's config.
+ */
+export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
+    const trimmedHint = typeof hint === "string" ? hint.trim() : "";
+    if (!isBehind || trimmedHint === "")
+        return [];
+    return [`The branch is behind \`origin/${baseBranch}\` — ${trimmedHint} before pushing.`];
+}
+/** Build the `Run the resolve: command` instruction, including its optional substitution hint. */
+export function buildResolveCommandInstruction(resolveCommand) {
+    if (!resolveCommand.hasMutations)
+        return [];
+    const instructions = [];
+    if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
+        instructions.push(`Before running the \`resolve:\` command, remove any thread from \`--reply-thread-ids\` if the latest visible comment in that thread is your own prior Shepherd reply. Do not reply to your own comments.`);
+    }
+    const substituteParts = [];
+    if (resolveCommand.requiresHeadSha) {
+        substituteParts.push(`\`$HEAD_SHA\` with the pushed commit SHA (or \`$(git rev-parse HEAD)\` if you did not push)`);
+    }
+    if (resolveCommand.requiresDismissMessage) {
+        substituteParts.push(`\`$DISMISS_MESSAGE\` with a one-sentence reply/description of what you changed`);
+    }
+    const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
+    instructions.push(`Run the \`resolve:\` command shown above${substituteHint}.`);
+    return instructions;
+}
 export function buildFailingCheckInstructions(checks) {
     if (checks.length === 0)
         return [];
@@ -18,19 +52,19 @@ export function buildFailingCheckInstructions(checks) {
     const hasBare = checks.some((c) => !c.runId && !c.detailsUrl);
     const parts = [];
     if (hasRunId) {
-        parts.push("read any included log excerpt first; fetch the full log with `gh run view <runId> --log-failed` when the excerpt is insufficient; decide whether to rerun with `gh run rerun <runId> --failed` for transient infrastructure failures (network timeout, OOM kill, runner crash), or apply a code fix for real test/build failures; if GitHub omits workflow-evaluation details from API/log output, open the run URL in the GitHub UI");
+        parts.push("read any included log excerpt first; fetch the full log with `gh run view <runId> --log-failed` if insufficient; rerun with `gh run rerun <runId> --failed` for transient infra failures, or apply a code fix for real test/build failures; if API/log output lacks detail, open the run URL in the GitHub UI");
     }
     if (hasCancelled) {
-        parts.push("for `[conclusion: CANCELLED]` entries: these are not concurrency-superseded (superseded CANCELLED checks are excluded from this section and reported under `**superseded**` instead) — rerun with `gh run rerun <runId>` unless you are already pushing new commits this tick for other reasons, in which case the fresh run naturally supersedes it; do not silently treat a required CANCELLED check as resolved — do NOT confuse with IDs under `## Cancelled runs`");
+        parts.push("for `[conclusion: CANCELLED]` entries (not concurrency-superseded — see `**superseded**`): rerun with `gh run rerun <runId>` unless already pushing new commits this tick, in which case the fresh run supersedes it; don't treat as resolved — distinct from `## Cancelled runs`");
     }
     if (hasStartupFailure) {
-        parts.push("for `[conclusion: STARTUP_FAILURE]` entries: inspect with `gh run view <runId>` and rerun with `gh run rerun <runId>` if the workflow should be retried");
+        parts.push("for `[conclusion: STARTUP_FAILURE]` entries: inspect with `gh run view <runId>`, rerun with `gh run rerun <runId>` if warranted");
     }
     if (hasExternal) {
-        parts.push("for `external` entries (no run ID, has URL): open the URL to inspect the failure");
+        parts.push("for `external` entries: open the URL to inspect the failure");
     }
     if (hasBare) {
-        parts.push("for `(no runId)` entries: no log or URL is available — escalate to a human for manual investigation");
+        parts.push("for `(no runId)` entries: no log or URL available — escalate to a human");
     }
     return [`For each failing check under \`## Failing checks\`: ${parts.join("; ")}.`];
 }

package/bin/commands/iterate/classify.mjs

@@ -14,16 +14,21 @@ function dedupeIds(ids) {
 }
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all", botUsernames = new Set(), unresolvedThreads = [], ruleAutoResolveIds = []) {
     const blockedReviewIds = new Set(unresolvedThreads.flatMap((t) => (t.reviewId !== undefined ? [t.reviewId] : [])));
-    // First-look and seen summaries go into the minimize mutation; edited summaries do NOT —
-    // they are already minimized server-side (body changed after minimize was applied).
-    // First-look bodies are rendered so the agent sees them before the minimize happens.
-    const minimizeIds = [...summaries.firstLook, ...summaries.seen]
-        .filter((r) => shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames))
-        .filter((r) => !blockedReviewIds.has(r.id))
-        .map((r) => r.id);
-    // Rule-matched summaries are already suppressed from agent output; bypass normal policy gates.
+    const eligible = (r) => shouldMinimizeAuthor(r.authorType, minimizeComments, r.author, botUsernames) &&
+        !blockedReviewIds.has(r.id);
+    // First-look summaries still need one tick to surface their body to the agent,
+    // so their minimize IDs ride in the agent-facing resolve command. Seen summaries
+    // (already surfaced in a prior tick) have no new content to show — the CLI
+    // self-minimizes them in-process (selfMinimizeIds) instead of routing a
+    // cosmetic-only mutation through fix_code (issue #313). Edited summaries are
+    // excluded entirely: they are already minimized server-side (body changed after
+    // minimize was applied).
+    const minimizeIds = summaries.firstLook.filter(eligible).map((r) => r.id);
+    const selfMinimizeIds = summaries.seen.filter(eligible).map((r) => r.id);
+    // Rule-matched summaries are already suppressed from agent output; bypass normal
+    // policy gates. Keep the two sets disjoint.
     for (const id of ruleAutoResolveIds) {
-        if (!minimizeIds.includes(id))
+        if (!minimizeIds.includes(id) && !selfMinimizeIds.includes(id))
             minimizeIds.push(id);
     }
     if (minimizeApprovals) {
@@ -36,6 +41,7 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
         }
         return {
             minimizeIds,
+            selfMinimizeIds,
             firstLookSummaries: summaries.firstLook,
             editedSummaries: summaries.edited,
             surfacedApprovals,
@@ -43,6 +49,7 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
     }
     return {
         minimizeIds,
+        selfMinimizeIds,
         firstLookSummaries: summaries.firstLook,
         editedSummaries: summaries.edited,
         surfacedApprovals: approvals,

package/bin/commands/iterate/fix-code.mjs

@@ -11,6 +11,7 @@ import { tryCancelRun, buildAutoCancelRunIdsWithOptions, buildInProgressRunIds,
 import { annotationMarkerBody } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
+import { loadConfig } from "../../config/load.mjs";
 function nextFixAttempts(stored, headSha, threads) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};
     const threadBodyHashes = stored?.threadBodyHashes
@@ -91,6 +92,8 @@ export async function handleFixCode(ctx) {
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
+    const isBehind = report.mergeStatus.status === "BEHIND";
+    const { behindBaseHint } = loadConfig().iterate;
     // Only surface in-progress runs when a push is plausible — resolution-only and
     // summary-only iterations have no path to a push, so listing runs would prompt
     // unnecessary cancellation.
@@ -137,7 +140,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind);
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/index.mjs

@@ -10,6 +10,7 @@ import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
+import { autoMinimizeComments } from "../../comments/resolve.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
@@ -35,11 +36,25 @@ export async function runIterate(opts) {
         await clearStallState(stallKey);
         return buildTerminalCancelResult(report);
     }
-    const { minimizeIds: reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = classifyReviewSummaries({
+    const { minimizeIds, selfMinimizeIds, firstLookSummaries, editedSummaries, surfacedApprovals } = classifyReviewSummaries({
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
     }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [...report.threads.actionable, ...report.threads.resolutionOnly], report.ruleAutoResolveReviewSummaryIds);
+    // Already-seen review summaries have no new content to surface — minimize them
+    // in-process so they never register as agent-facing actionable work (#313).
+    // GitHub can still return a null/error/rate-limit result per ID without
+    // throwing (autoMinimizeComments reports this via `errors`, not a rejection);
+    // any ID it did not confirm minimized falls back into the agent-facing set so
+    // the resolve command remains a working fallback instead of silently dropping it.
+    let reviewSummaryIds = minimizeIds;
+    if (selfMinimizeIds.length > 0) {
+        const { minimized } = await autoMinimizeComments(selfMinimizeIds);
+        const minimizedIds = new Set(minimized);
+        const unminimized = selfMinimizeIds.filter((id) => !minimizedIds.has(id));
+        if (unminimized.length > 0)
+            reviewSummaryIds = [...reviewSummaryIds, ...unminimized];
+    }
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.threads.resolutionOnly.length > 0 ||
         report.threads.firstLook.length > 0 ||

package/bin/commands/iterate/render.mjs

@@ -1,5 +1,5 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
-import { buildFailingCheckInstructions, buildCrStaleClause } from "./check-instructions.mjs";
+import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildResolveCommandInstruction, } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
@@ -10,8 +10,8 @@ export function renderResolveCommand(rc) {
         parts.push("--require-sha", "$HEAD_SHA");
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, _baseBranch, // retained for call-site stability; rebase mechanics now defer to the caller
-resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+isBehind = false) {
     const instructions = [];
     const hasNonConflictHints = threads.length > 0 ||
         checks.length > 0 ||
@@ -47,6 +47,7 @@ resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], f
     else if (hasConflicts) {
         instructions.push(`The branch has merge conflicts that must be resolved before merging (see \`**branch**\` above). Resolve them and push.`);
     }
+    instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
     if (inProgressRunIds.length > 0) {
         instructions.push(`If you decide to push new commits: cancel each in-progress run listed under \`## In-progress runs\` before applying code fixes (e.g. \`gh run cancel <id>\`). Runs may complete between the tick and your action; treat cancellation errors on already-finished runs as non-fatal. Skip this step if you are only resolving threads without pushing — the existing runs remain relevant.`);
     }
@@ -54,15 +55,13 @@ resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], f
     if (hasSuggestions)
         instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads", false));
     if (threads.length > 0 || actionableComments.length > 0) {
-        const fixSections = [];
-        if (threads.length > 0)
-            fixSections.push("`## Review threads`");
-        if (actionableComments.length > 0)
-            fixSections.push("`## Actionable comments`");
+        // Actionable comments carry no file/line location (unlike threads), so "referenced above"
+        // is only accurate when threads are present.
+        const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
         const suggestionFallback = hasSuggestions
             ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`commit-suggestion\` run), replace the exact line range shown in the heading (\`path:startLine-endLine\`) with the replacement shown in its \`Replaces lines …\` block verbatim — an empty replacement deletes those lines, a single blank line replaces the range with one blank line.`
             : "";
-        instructions.push(`Apply code fixes: read and edit each file referenced under ${fixSections.join(" and ")} above.${suggestionFallback}`);
+        instructions.push(`Apply code fixes: read and edit ${filesRef}.${suggestionFallback}`);
     }
     if (resolutionOnlyThreads.length > 0) {
         instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`resolve:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
@@ -79,20 +78,7 @@ resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], f
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push(`Run the \`resolve-only:\` command shown above — no substitutions needed.`);
-    if (resolveCommand.hasMutations) {
-        if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
-            instructions.push(`Before running the \`resolve:\` command, remove any thread from \`--reply-thread-ids\` if the latest visible comment in that thread is your own prior Shepherd reply. Do not reply to your own comments.`);
-        }
-        const substituteParts = [];
-        if (resolveCommand.requiresHeadSha) {
-            substituteParts.push(`\`$HEAD_SHA\` with the pushed commit SHA (or \`$(git rev-parse HEAD)\` if you did not push)`);
-        }
-        if (resolveCommand.requiresDismissMessage) {
-            substituteParts.push(`\`$DISMISS_MESSAGE\` with a one-sentence reply/description of what you changed`);
-        }
-        const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
-        instructions.push(`Run the \`resolve:\` command shown above${substituteHint}.`);
-    }
+    instructions.push(...buildResolveCommandInstruction(resolveCommand));
     if (cancelledCount > 0) {
         instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — those runs were already cancelled by the CLI before this turn.`);
     }

package/bin/commands/mark-files-as-viewed.mjs

@@ -153,9 +153,7 @@ async function bulkMarkFilesAsViewedChunk(pullRequestId, paths, result, hasPendi
     let suppressCurrentChunkErrors = false;
     let rateLimitStop;
     try {
-        const resp = await graphqlWithRateLimit(buildBulkMutation(paths), {
-            pullRequestId,
-        });
+        const resp = await graphqlWithRateLimit(buildBulkMutation(paths), { pullRequestId }, { allowPartialData: true });
         data = resp.data;
         graphQlErrors = (resp.errors ?? []);
         const messages = graphQlErrors.map((e) => e.message);

package/bin/comments/resolve.mjs

@@ -128,7 +128,9 @@ async function bulkApplyChunk(resolveIds, replyIds, minimizeIds, dismissIds, dis
     let rateLimitStop;
     let suppressCurrentChunkErrors = false;
     try {
-        const resp = await graphqlWithRateLimit(doc, {});
+        const resp = await graphqlWithRateLimit(doc, {}, {
+            allowPartialData: true,
+        });
         data = resp.data;
         graphQlErrors = (resp.errors ?? []);
         const graphQlErrorMessages = graphQlErrors.map((e) => e.message);

package/bin/config.json

@@ -18,7 +18,8 @@
     "fixAttemptsPerThread": 3,
     "stallTimeoutMinutes": 60,
     "minimizeApprovals": false,
-    "minimizeComments": "all"
+    "minimizeComments": "all",
+    "behindBaseHint": ""
   },
   "watch": {
     "readyDelayMinutes": 10

package/bin/github/batch-response.mjs

@@ -0,0 +1,16 @@
+import { GitHubRequestError } from "./errors.mjs";
+export function requireRawPr(response, pr, repo) {
+    if (!response?.repository) {
+        throw new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
+    }
+    if (!response.repository.pullRequest)
+        throw new Error(`PR #${pr} not found`);
+    return response.repository.pullRequest;
+}
+export function requireContextNodes(nodes) {
+    const nullIndex = nodes.findIndex((node) => node === null);
+    if (nullIndex !== -1) {
+        throw new GitHubRequestError(`Malformed GitHub GraphQL response: null check context at repository.pullRequest.commits.nodes.0.commit.statusCheckRollup.contexts.nodes.${nullIndex}`, { status: 200 });
+    }
+    return nodes;
+}

package/bin/github/batch.mjs

@@ -3,6 +3,7 @@ import { paginateForward, paginateBackward } from "./pagination.mjs";
 import { hydrateThreadCommentPages } from "./thread-comments.mjs";
 import { BATCH_PR_QUERY } from "./queries.mjs";
 import { parseRawPr } from "./batch-parsers.mjs";
+import { requireContextNodes, requireRawPr } from "./batch-response.mjs";
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
  */
@@ -13,10 +14,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
         repo: repo.name,
         pr,
     });
-    const raw = result.data.repository.pullRequest;
-    if (!raw) {
-        throw new Error(`PR #${pr} not found`);
-    }
+    const raw = requireRawPr(result.data, pr, repo);
     // Paginate reviewThreads backward if the first page is incomplete.
     let rawThreadPages = raw.reviewThreads.nodes;
     if (raw.reviewThreads.pageInfo.hasPreviousPage && raw.reviewThreads.pageInfo.startCursor) {
@@ -29,9 +27,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
                 pr,
                 ...(cursor ? { threadsCursor: cursor } : {}),
             });
-            const pr2 = res.data.repository.pullRequest;
-            if (!pr2)
-                throw new Error(`PR #${pr} not found`);
+            const pr2 = requireRawPr(res.data, pr, repo);
             return pr2.reviewThreads;
         }, raw.reviewThreads.pageInfo.startCursor);
         // extra contains pages before the first page.
@@ -48,9 +44,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
                 pr,
                 ...(cursor ? { commentsCursor: cursor } : {}),
             });
-            const pr2 = res.data.repository.pullRequest;
-            if (!pr2)
-                throw new Error(`PR #${pr} not found`);
+            const pr2 = requireRawPr(res.data, pr, repo);
             return pr2.comments;
         }, raw.comments.pageInfo.startCursor);
         rawCommentNodes = [...extra, ...rawCommentNodes];
@@ -66,9 +60,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
                 pr,
                 ...(cursor ? { changesRequestedCursor: cursor } : {}),
             });
-            const pr2 = res.data.repository.pullRequest;
-            if (!pr2)
-                throw new Error(`PR #${pr} not found`);
+            const pr2 = requireRawPr(res.data, pr, repo);
             return pr2.changesRequestedReviews;
         }, raw.changesRequestedReviews.pageInfo.startCursor);
         rawReviewNodes = [...extra, ...rawReviewNodes];
@@ -83,9 +75,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
                 pr,
                 ...(cursor ? { reviewSummariesCursor: cursor } : {}),
             });
-            const pr2 = res.data.repository.pullRequest;
-            if (!pr2)
-                throw new Error(`PR #${pr} not found`);
+            const pr2 = requireRawPr(res.data, pr, repo);
             return pr2.reviewSummaries;
         }, raw.reviewSummaries.pageInfo.startCursor);
         rawReviewSummaryNodes = [...extra, ...rawReviewSummaryNodes];
@@ -103,15 +93,13 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
                 pr,
                 ...(cursor ? { approvedReviewsCursor: cursor } : {}),
             });
-            const pr2 = res.data.repository.pullRequest;
-            if (!pr2)
-                throw new Error(`PR #${pr} not found`);
+            const pr2 = requireRawPr(res.data, pr, repo);
             return pr2.approvedReviews;
         }, raw.approvedReviews.pageInfo.startCursor);
         rawApprovedReviewNodes = [...extra, ...rawApprovedReviewNodes];
     }
     // Paginate check contexts forward if the first page is incomplete.
-    let rawCheckNodes = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.nodes ?? [];
+    let rawCheckNodes = requireContextNodes(raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.nodes ?? []);
     const checksPageInfo = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.pageInfo;
     const firstOid = raw.commits.nodes[0]?.commit.oid;
     if (checksPageInfo?.hasNextPage && checksPageInfo.endCursor) {
@@ -125,7 +113,7 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
                 pr,
                 ...(cursor ? { checksCursor: cursor } : {}),
             });
-            const pr2 = res.data.repository.pullRequest;
+            const pr2 = requireRawPr(res.data, pr, repo);
             if (!pr2?.commits.nodes[0]?.commit.statusCheckRollup) {
                 throw new Error(`Check-context pagination interrupted: statusCheckRollup disappeared on page ${pageCount + 2} (possible force-push race). Retry after the push stabilizes.`);
             }
@@ -135,7 +123,9 @@ export async function fetchPrBatch(pr, repo, opts = {}) {
             }
             pageCount++;
             const ctxs = pr2.commits.nodes[0]?.commit.statusCheckRollup?.contexts;
-            return ctxs ?? { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
+            if (!ctxs)
+                return { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
+            return { ...ctxs, nodes: requireContextNodes(ctxs.nodes) };
         }, checksPageInfo.endCursor);
         rawCheckNodes = [...rawCheckNodes, ...extra];
     }

package/bin/github/errors.mjs

@@ -2,11 +2,13 @@ export class GitHubRequestError extends Error {
     status;
     rateLimit;
     retryAfterSeconds;
+    graphqlErrors;
     constructor(message, opts) {
         super(message);
         this.name = "GitHubRequestError";
         this.status = opts.status;
         this.rateLimit = opts.rateLimit;
         this.retryAfterSeconds = opts.retryAfterSeconds;
+        this.graphqlErrors = opts.graphqlErrors;
     }
 }

package/bin/github/graphql-http.mjs

@@ -1,11 +1,12 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
+import { formatGraphQlErrors, parseGraphQlPayload } from "./graphql-response.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
 const BASE_URL = "https://api.github.com";
-async function graphqlInner(query, vars) {
+async function graphqlInner(query, vars, opts) {
     const url = `${BASE_URL}/graphql`;
     const n = nextEntry();
     appendEntry(formatRequestEntry({
@@ -38,7 +39,28 @@ async function graphqlInner(query, vars) {
         }));
         throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, { status: res.status, rateLimit: rateLimit ?? undefined, retryAfterSeconds });
     }
-    const parsed = (await res.json());
+    let parsed;
+    try {
+        parsed = await res.json();
+    }
+    catch (err) {
+        const detail = err instanceof Error ? `: ${err.message}` : "";
+        appendEntry(formatResponseEntry({
+            n,
+            kind: "GraphQL",
+            method: "POST",
+            url,
+            status: res.status,
+            durationMs,
+            textBody: `Invalid JSON response${detail}`,
+            attempt: attempt > 1 ? attempt : undefined,
+        }));
+        throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
+            status: res.status,
+            rateLimit: rateLimit ?? undefined,
+            retryAfterSeconds,
+        });
+    }
     appendEntry(formatResponseEntry({
         n,
         kind: "GraphQL",
@@ -49,25 +71,35 @@ async function graphqlInner(query, vars) {
         body: parsed,
         attempt: attempt > 1 ? attempt : undefined,
     }));
-    if (parsed.data == null) {
-        const messages = (parsed.errors ?? []).map((e) => e.message).join("; ");
-        throw new GitHubRequestError(`GitHub GraphQL error (no data): ${messages}`, {
+    const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);
+    if (payload.data == null) {
+        const detail = formatGraphQlErrors(payload.errors);
+        throw new GitHubRequestError(`GitHub GraphQL error (no data)${detail ? `: ${detail}` : ""}`, {
+            status: res.status,
+            rateLimit: rateLimit ?? undefined,
+            retryAfterSeconds,
+            graphqlErrors: payload.errors,
+        });
+    }
+    if (payload.errors?.length && !opts.allowPartialData) {
+        throw new GitHubRequestError(`GitHub GraphQL error: ${formatGraphQlErrors(payload.errors)}`, {
             status: res.status,
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
+            graphqlErrors: payload.errors,
         });
     }
-    if (parsed.errors?.length) {
-        const messages = parsed.errors.map((e) => e.message).join("; ");
+    if (payload.errors?.length) {
+        const messages = payload.errors.map((e) => e.message).join("; ");
         process.stderr.write(`pr-shepherd: GraphQL non-fatal errors: ${messages}\n`);
     }
-    return { data: parsed.data, rateLimit, retryAfterSeconds, errors: parsed.errors };
+    return { data: payload.data, rateLimit, retryAfterSeconds, errors: payload.errors };
 }
-export async function graphql(query, vars = {}) {
-    const { data } = await graphqlInner(query, vars);
-    return { data };
+export async function graphql(query, vars = {}, opts = {}) {
+    const { data, errors } = await graphqlInner(query, vars, opts);
+    return { data, errors };
 }
-export async function graphqlWithRateLimit(query, vars = {}) {
-    const { data, rateLimit, retryAfterSeconds, errors } = await graphqlInner(query, vars);
+export async function graphqlWithRateLimit(query, vars = {}, opts = {}) {
+    const { data, rateLimit, retryAfterSeconds, errors } = await graphqlInner(query, vars, opts);
     return { data, rateLimit: rateLimit ?? undefined, retryAfterSeconds, errors };
 }

package/bin/github/graphql-response.mjs

@@ -0,0 +1,42 @@
+import { GitHubRequestError } from "./errors.mjs";
+export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds) {
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw malformedGraphQlResponse("expected a JSON object", status, rateLimit, retryAfterSeconds);
+    }
+    const record = parsed;
+    let errors;
+    if (record["errors"] !== undefined) {
+        if (!Array.isArray(record["errors"]) ||
+            !record["errors"].every((error) => typeof error === "object" &&
+                error !== null &&
+                typeof error["message"] === "string")) {
+            throw malformedGraphQlResponse("errors field is not an array of GraphQL errors", status, rateLimit, retryAfterSeconds);
+        }
+        errors = record["errors"];
+    }
+    if (!("data" in record)) {
+        if (errors?.length)
+            return { data: null, errors };
+        throw malformedGraphQlResponse("missing data field", status, rateLimit, retryAfterSeconds);
+    }
+    if (record["data"] !== null &&
+        (typeof record["data"] !== "object" || Array.isArray(record["data"]))) {
+        throw malformedGraphQlResponse("data field is not an object or null", status, rateLimit, retryAfterSeconds);
+    }
+    return { data: record["data"] ?? null, errors };
+}
+export function formatGraphQlErrors(errors) {
+    return (errors ?? [])
+        .map((error) => {
+        const path = Array.isArray(error.path) ? error.path.map(String).join(".") : "";
+        return path ? `${error.message} (path: ${path})` : error.message;
+    })
+        .join("; ");
+}
+function malformedGraphQlResponse(detail, status, rateLimit, retryAfterSeconds) {
+    return new GitHubRequestError(`Malformed GitHub GraphQL response: ${detail}`, {
+        status,
+        rateLimit: rateLimit ?? undefined,
+        retryAfterSeconds,
+    });
+}

package/package.json

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