pr-shepherd 0.32.5 → 0.34.0

package/bin/commands/commit-suggestion.mjs

@@ -5,50 +5,51 @@ import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/cli
 import { fetchPrBatch } from "../github/batch.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 const execFile = promisify(execFileCb);
 export async function runCommitSuggestion(opts) {
     if (!opts.threadId) {
-        throw new Error("--thread-id is required");
+        throw new ShepherdError("--thread-id is required", EXIT.USAGE);
     }
     if (!opts.message || opts.message.trim() === "") {
-        throw new Error("--message is required and must be non-empty");
+        throw new ShepherdError("--message is required and must be non-empty", EXIT.USAGE);
     }
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const currentBranch = await getCurrentBranch();
     const { stdout: localHeadOut } = await execFile("git", ["rev-parse", "HEAD"]);
     const localHeadSha = localHeadOut.trim();
     const { data } = await fetchPrBatch(prNumber, repo);
     if (!data.headRepoWithOwner) {
-        throw new Error(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`);
+        throw new ShepherdError(`PR #${prNumber} head repository is unavailable (fork may have been deleted).`, EXIT.UNAVAILABLE);
     }
     if (currentBranch !== data.headRefName) {
-        throw new Error(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
-            `Check out "${data.headRefName}" before applying suggestions.`);
+        throw new ShepherdError(`Current branch "${currentBranch}" does not match PR head branch "${data.headRefName}". ` +
+            `Check out "${data.headRefName}" before applying suggestions.`, EXIT.UNAVAILABLE);
     }
     if (localHeadSha !== data.headRefOid) {
-        throw new Error(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
-            `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`);
+        throw new ShepherdError(`Local HEAD ${localHeadSha} does not match PR head ${data.headRefOid}. ` +
+            `Pull/rebase "${data.headRefName}" to the latest PR head and try again.`, EXIT.UNAVAILABLE);
     }
     const thread = data.reviewThreads.find((t) => t.id === opts.threadId);
     if (!thread) {
-        throw new Error(`Thread ${opts.threadId} not found on PR #${prNumber}.`);
+        throw new ShepherdError(`Thread ${opts.threadId} not found on PR #${prNumber}.`, EXIT.UNAVAILABLE);
     }
     if (thread.isResolved) {
-        throw new Error(`Thread ${opts.threadId} is already resolved.`);
+        throw new ShepherdError(`Thread ${opts.threadId} is already resolved.`, EXIT.UNAVAILABLE);
     }
     if (thread.isOutdated) {
-        throw new Error(`Thread ${opts.threadId} is outdated.`);
+        throw new ShepherdError(`Thread ${opts.threadId} is outdated.`, EXIT.UNAVAILABLE);
     }
     if (thread.isMinimized) {
-        throw new Error(`Thread ${opts.threadId} is minimized.`);
+        throw new ShepherdError(`Thread ${opts.threadId} is minimized.`, EXIT.UNAVAILABLE);
     }
     if (!thread.path || thread.line === null) {
-        throw new Error(`Thread ${opts.threadId} has no file/line anchor.`);
+        throw new ShepherdError(`Thread ${opts.threadId} has no file/line anchor.`, EXIT.UNAVAILABLE);
     }
     // Validate the target file is clean before generating the patch, so the emitted
     // `git add -- <file>` instruction cannot accidentally stage unrelated local edits.
@@ -59,15 +60,15 @@ export async function runCommitSuggestion(opts) {
         thread.path,
     ]);
     if (fileStatus.trim() !== "") {
-        throw new Error(`${thread.path} has uncommitted changes. Commit or stash them before running commit-suggestion.`);
+        throw new ShepherdError(`${thread.path} has uncommitted changes. Commit or stash them before running commit-suggestion.`, EXIT.UNAVAILABLE);
     }
     const parsed = parseSuggestion(thread.body);
     if (!parsed) {
-        throw new Error(`Thread ${opts.threadId} has no suggestion block in the comment body.`);
+        throw new ShepherdError(`Thread ${opts.threadId} has no suggestion block in the comment body.`, EXIT.UNAVAILABLE);
     }
     if (!isCommittableSuggestion(parsed)) {
-        throw new Error(`Thread ${opts.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
-            `3+ backtick fences — refusing to apply (could silently truncate).`);
+        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion body contains nested suggestion fencing or unbalanced ` +
+            `3+ backtick fences — refusing to apply (could silently truncate).`, EXIT.UNAVAILABLE);
     }
     const startLine = thread.startLine ?? thread.line;
     const endLine = thread.line;

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/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

@@ -4,6 +4,7 @@ import { getCurrentPrNumber } from "../../github/client.mjs";
 import { graphql } from "../../github/http.mjs";
 import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
 import { loadConfig } from "../../config/load.mjs";
+import { EXIT, ShepherdError } from "../../exit-codes.mjs";
 import { getCurrentHeadSha, buildSummary, buildRelevantChecks, buildActiveChecks, buildWaitLog, buildSuppressedCheckFields, buildTerminalCancelResult, } from "./helpers.mjs";
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
@@ -17,8 +18,9 @@ export async function runIterate(opts) {
     const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
     const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (prNumber === null)
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+    if (prNumber === null) {
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
+    }
     const neverCancelRuns = opts.neverCancelRuns ?? config.actions.neverCancelRuns;
     const report = await runCheck({
         ...opts,
@@ -28,7 +30,7 @@ export async function runIterate(opts) {
     });
     const [repoOwner, repoName] = report.repo.split("/");
     if (!repoOwner || !repoName) {
-        throw new Error(`Unexpected repo format: "${report.repo}" (expected "owner/name")`);
+        throw new ShepherdError(`Unexpected repo format: "${report.repo}" (expected "owner/name")`, EXIT.DATAERR);
     }
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
     if (report.mergeStatus.state !== "OPEN") {

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

@@ -2,6 +2,7 @@
 import { graphql, graphqlWithRateLimit, getCurrentPrNumber, getRepoInfo, } from "../github/client.mjs";
 import { paginateForward } from "../github/pagination.mjs";
 import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "../comments/rate-limit.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const FILES_QUERY = `query PullRequestFiles($owner: String!, $repo: String!, $pr: Int!, $filesCursor: String) {
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
@@ -25,8 +26,9 @@ const BULK_CHUNK_SIZE = 10;
 export async function runMarkFilesAsViewed(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (!prNumber)
-        throw new Error("No PR number provided and no current branch PR found");
+    if (!prNumber) {
+        throw new ShepherdError("No PR number provided and no current branch PR found", EXIT.UNAVAILABLE);
+    }
     const matchPatterns = opts.matchPatterns ?? [];
     const matchRegexes = matchPatterns.map((pattern) => compilePattern(pattern));
     const fetched = await fetchPullRequestFiles(prNumber, repo);
@@ -61,7 +63,7 @@ async function fetchPullRequestFiles(pr, repo) {
     });
     const raw = first.data.repository?.pullRequest;
     if (!raw)
-        throw new Error(`PR #${pr} not found`);
+        throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
     let files = raw.files.nodes;
     if (raw.files.pageInfo.hasNextPage && raw.files.pageInfo.endCursor) {
         const extra = await paginateForward(async (cursor) => {
@@ -73,7 +75,7 @@ async function fetchPullRequestFiles(pr, repo) {
             });
             const pr2 = res.data.repository?.pullRequest;
             if (!pr2)
-                throw new Error(`PR #${pr} not found`);
+                throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
             return pr2.files;
         }, raw.files.pageInfo.endCursor);
         files = [...files, ...extra];
@@ -86,7 +88,7 @@ function compilePattern(pattern) {
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        throw new Error(`Invalid --match regex ${JSON.stringify(pattern)}: ${msg}`);
+        throw new ShepherdError(`Invalid --match regex ${JSON.stringify(pattern)}: ${msg}`, EXIT.USAGE);
     }
 }
 function selectChangedFiles(changedFiles, opts) {
@@ -153,9 +155,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/commands/resolve-mutate.mjs

@@ -6,11 +6,12 @@ import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "..
 import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { addPrShepherdMarker } from "../comments/marker.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+        throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const { data } = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true });
     const config = loadConfig();

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/exit-codes.mjs

@@ -0,0 +1,74 @@
+/**
+ * Process exit codes for the pr-shepherd CLI.
+ *
+ * Three bands:
+ *   0        done — shepherd finished and the PR is in a good terminal state
+ *   10-19    shepherd RAN successfully; the code reports PR state
+ *   64-78    shepherd FAILED (BSD `sysexits.h` codes)
+ *
+ * Caller rule: `$? >= 64` means shepherd itself failed. `0` or `10-19` means it
+ * ran to completion and is reporting PR state. See docs/exit-codes.md.
+ */
+export const EXIT = Object.freeze({
+    /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
+    OK: 0,
+    /** Nothing to do yet; CI still in progress. */
+    WAIT: 10,
+    /** Draft PR converted to ready for review. */
+    MARK_READY: 11,
+    /** Agent work required. */
+    FIX_CODE: 12,
+    /** Human attention required. */
+    ESCALATE: 13,
+    /** `cancel` + `closed` — PR closed without merging. */
+    CLOSED: 14,
+    /** Bad/unknown flag, unknown subcommand, missing required arg, invalid duration. */
+    USAGE: 64,
+    /** Malformed caller data: bad `--require-sha`, `PRRC_*` IDs, bad repo string. */
+    DATAERR: 65,
+    /** Input file/stdin could not be read. */
+    NOINPUT: 66,
+    /** Precondition unmet: no open PR for branch, thread not eligible, unclassified 4xx. */
+    UNAVAILABLE: 69,
+    /** Unexpected/unclassified internal error — the fallback. */
+    SOFTWARE: 70,
+    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, `Retry-After` present. */
+    TEMPFAIL: 75,
+    /** GitHub 401/403 — missing token or insufficient PAT scopes. */
+    NOPERM: 77,
+    /** `.pr-shepherdrc.yml` validation failure. */
+    CONFIG: 78,
+});
+/** An error that carries its own exit code, so the top-level handler doesn't have to guess. */
+export class ShepherdError extends Error {
+    exitCode;
+    constructor(message, exitCode, opts) {
+        super(message, opts);
+        this.name = "ShepherdError";
+        this.exitCode = exitCode;
+    }
+}
+const CANCEL_REASON_EXIT_CODE = {
+    merged: EXIT.OK,
+    "ready-delay-elapsed": EXIT.OK,
+    closed: EXIT.CLOSED,
+};
+export function iterateResultToExitCode(result) {
+    switch (result.action) {
+        case "cancel":
+            return CANCEL_REASON_EXIT_CODE[result.reason];
+        case "wait":
+            return EXIT.WAIT;
+        case "mark_ready":
+            return EXIT.MARK_READY;
+        case "fix_code":
+            return EXIT.FIX_CODE;
+        case "escalate":
+            return EXIT.ESCALATE;
+    }
+}
+export function errorToExitCode(err) {
+    if (err instanceof ShepherdError)
+        return err.exitCode;
+    return EXIT.SOFTWARE;
+}

package/bin/github/batch-response.mjs

@@ -0,0 +1,21 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+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 ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
+    }
+    return response.repository.pullRequest;
+}
+export function requireContextNodes(nodes) {
+    const nullIndex = nodes.findIndex((node) => node === null);
+    if (nullIndex !== -1) {
+        // A null context node is an unexpected/malformed shape, not a precondition or
+        // permission problem — force EX_SOFTWARE rather than falling through to the
+        // (200-status-derived) EX_UNAVAILABLE default.
+        throw new GitHubRequestError(`Malformed GitHub GraphQL response: null check context at repository.pullRequest.commits.nodes.0.commit.statusCheckRollup.contexts.nodes.${nullIndex}`, { status: 200, exitCodeOverride: EXIT.SOFTWARE });
+    }
+    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

@@ -1,12 +1,38 @@
-export class GitHubRequestError extends Error {
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+// GitHub's GraphQL API reports field-level permission failures (e.g. a fine-grained
+// PAT missing a scope) as an `errors[].message` entry at HTTP 200, not as an HTTP
+// 401/403 — the transport-level request succeeded even though one field could not
+// be resolved. Status alone can't see this, so classification must also inspect the
+// GraphQL error messages themselves.
+const GRAPHQL_PERMISSION_ERROR = /resource not accessible/i;
+function hasPermissionError(graphqlErrors) {
+    return graphqlErrors?.some((e) => GRAPHQL_PERMISSION_ERROR.test(e.message)) ?? false;
+}
+function classifyStatus(status, rateLimit, retryAfterSeconds, graphqlErrors) {
+    // Retry signals take priority over everything else: GitHub's secondary rate limit
+    // returns 403 with a Retry-After header, which is a transient throttle — not the
+    // permission-denied 403 a bad/missing token produces. Treat any retry signal as
+    // TEMPFAIL first so it isn't shadowed by the checks below.
+    const rateLimitExhausted = rateLimit !== undefined && rateLimit.remaining <= 0;
+    if (status === 429 || status >= 500 || retryAfterSeconds !== undefined || rateLimitExhausted) {
+        return EXIT.TEMPFAIL;
+    }
+    if (status === 401 || status === 403 || hasPermissionError(graphqlErrors))
+        return EXIT.NOPERM;
+    return EXIT.UNAVAILABLE;
+}
+export class GitHubRequestError extends ShepherdError {
     status;
     rateLimit;
     retryAfterSeconds;
+    graphqlErrors;
     constructor(message, opts) {
-        super(message);
+        super(message, opts.exitCodeOverride ??
+            classifyStatus(opts.status, opts.rateLimit, opts.retryAfterSeconds, opts.graphqlErrors));
         this.name = "GitHubRequestError";
         this.status = opts.status;
         this.rateLimit = opts.rateLimit;
         this.retryAfterSeconds = opts.retryAfterSeconds;
+        this.graphqlErrors = opts.graphqlErrors;
     }
 }