pr-shepherd 0.33.0 → 0.35.0

package/bin/exit-codes.d.mts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+import type { IterateResult } from "./types.mts";
+export declare const EXIT: Readonly<{
+    /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
+    readonly OK: 0;
+    /** Nothing to do yet; CI still in progress. */
+    readonly WAIT: 10;
+    /** Draft PR converted to ready for review. */
+    readonly MARK_READY: 11;
+    /** Agent work required. */
+    readonly FIX_CODE: 12;
+    /** Human attention required. */
+    readonly ESCALATE: 13;
+    /** `cancel` + `closed` — PR closed without merging. */
+    readonly CLOSED: 14;
+    /** Bad/unknown flag, unknown subcommand, missing required arg, invalid duration. */
+    readonly USAGE: 64;
+    /** Malformed caller data: bad `--require-sha`, `PRRC_*` IDs, bad repo string. */
+    readonly DATAERR: 65;
+    /** Input file/stdin could not be read. */
+    readonly NOINPUT: 66;
+    /** Precondition unmet: no open PR for branch, thread not eligible, unclassified 4xx. */
+    readonly UNAVAILABLE: 69;
+    /** Unexpected/unclassified internal error — the fallback. */
+    readonly SOFTWARE: 70;
+    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, `Retry-After` present. */
+    readonly TEMPFAIL: 75;
+    /** GitHub 401/403 — missing token or insufficient PAT scopes. */
+    readonly NOPERM: 77;
+    /** `.pr-shepherdrc.yml` validation failure. */
+    readonly CONFIG: 78;
+}>;
+/** An error that carries its own exit code, so the top-level handler doesn't have to guess. */
+export declare class ShepherdError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode: number, opts?: {
+        cause?: unknown;
+    });
+}
+export declare function iterateResultToExitCode(result: IterateResult): number;
+export declare function errorToExitCode(err: unknown): number;

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/activity.d.mts

@@ -0,0 +1,3 @@
+import type { PrActivitySummary, PrComment, Review, ReviewThread } from "../types.mts";
+import type { RawPr } from "./batch-raw-types.mts";
+export declare function buildPrActivitySummary(raw: RawPr, comments: PrComment[], reviewThreads: ReviewThread[], reviewSummaries: Review[], changesRequestedReviews: Review[], approvedReviews: Review[]): PrActivitySummary;

package/bin/github/activity.mjs

@@ -8,6 +8,7 @@ function reviewActivityItems(reviews, latestCommitCommittedAtUnix, kind) {
         id: r.id,
         author: r.author,
         authorType: r.authorType,
+        ...(r.authorAssociation !== undefined && { authorAssociation: r.authorAssociation }),
         body: r.body,
         createdAtUnix: r.createdAtUnix ?? 0,
     }));
@@ -26,6 +27,9 @@ export function buildPrActivitySummary(raw, comments, reviewThreads, reviewSumma
                 id: c.id,
                 author: c.author,
                 authorType: c.authorType,
+                ...(c.authorAssociation !== undefined && {
+                    authorAssociation: c.authorAssociation,
+                }),
                 body: c.body,
                 url: c.url,
                 createdAtUnix: c.createdAtUnix,
@@ -37,6 +41,9 @@ export function buildPrActivitySummary(raw, comments, reviewThreads, reviewSumma
                 id: c.id,
                 author: c.author,
                 authorType: c.authorType,
+                ...(c.authorAssociation !== undefined && {
+                    authorAssociation: c.authorAssociation,
+                }),
                 body: c.body,
                 url: c.url,
                 createdAtUnix: c.createdAtUnix,

package/bin/github/batch-parser-helpers.d.mts

@@ -0,0 +1,22 @@
+import type { AuthorType, CheckConclusion, CheckRun, CheckStatus, Review, ReviewThread } from "../types.mts";
+import type { RawContextNode } from "./batch-raw-types.mts";
+export declare function mapAuthorType(typeName: string | undefined | null, login?: string | undefined | null): AuthorType;
+export declare function parseCreatedAt(iso: string): number;
+/** Map a GraphQL CheckRun context node to a CheckRun. */
+export declare function mapCheckRunNode(node: Extract<RawContextNode, {
+    __typename: "CheckRun";
+}>): CheckRun;
+export declare function latestApprovedLogins(latest: Array<{
+    login: string;
+    state: string;
+}>): Set<string>;
+/**
+ * A CR review is stale when its commit.oid differs from the PR head AND every
+ * associated review thread is resolved or outdated. Reviews with no associated
+ * threads are treated conservatively (not marked stale).
+ */
+export declare function isReviewStale(review: Review, headRefOid: string, reviewThreads: ReviewThread[]): boolean;
+export declare function mapStatusContextState(state: string): {
+    status: CheckStatus;
+    conclusion: CheckConclusion;
+};

package/bin/github/batch-parsers.d.mts

@@ -0,0 +1,3 @@
+import type { BatchPrData } from "../types.mts";
+import type { RawPr, RawThread, RawComment, RawReview, RawReviewSummary, RawContextNode } from "./batch-raw-types.mts";
+export declare function parseRawPr(raw: RawPr, rawThreadPages: RawThread[], rawCommentNodes: RawComment[], rawReviewNodes: RawReview[], rawReviewSummaryNodes: RawReviewSummary[], rawApprovedReviewNodes: RawReviewSummary[], rawCheckNodes: RawContextNode[]): BatchPrData;

package/bin/github/batch-parsers.mjs

@@ -6,6 +6,7 @@ function parseReviewNode(r) {
         id: r.id,
         author: r.author?.login ?? "unknown",
         authorType: mapAuthorType(r.author?.__typename, r.author?.login),
+        ...(r.authorAssociation !== undefined && { authorAssociation: r.authorAssociation }),
         body: r.body,
         createdAtUnix: r.createdAt ? parseCreatedAt(r.createdAt) : 0,
     };
@@ -32,6 +33,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             ...(c.pullRequestReview?.id ? { reviewId: c.pullRequestReview.id } : undefined),
             author: c.author?.login ?? "unknown",
             authorType: mapAuthorType(c.author?.__typename, c.author?.login),
+            ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
             body: c.body,
             url: c.url,
             createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,
@@ -47,6 +49,9 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             ...(comment?.pullRequestReview?.id ? { reviewId: comment.pullRequestReview.id } : undefined),
             author: comment?.author?.login ?? "unknown",
             authorType: mapAuthorType(comment?.author?.__typename, comment?.author?.login),
+            ...(comment?.authorAssociation !== undefined && {
+                authorAssociation: comment.authorAssociation,
+            }),
             body: comment?.body ?? "",
             url: comment?.url ?? "",
             createdAtUnix: comment?.createdAt ? parseCreatedAt(comment.createdAt) : 0,
@@ -58,6 +63,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         isMinimized: c.isMinimized,
         author: c.author?.login ?? "unknown",
         authorType: mapAuthorType(c.author?.__typename, c.author?.login),
+        ...(c.authorAssociation !== undefined && { authorAssociation: c.authorAssociation }),
         body: c.body,
         url: c.url,
         createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,

package/bin/github/batch-raw-types.d.mts

@@ -0,0 +1,207 @@
+import type { CommentAuthorAssociation } from "../types/github.mts";
+export interface RawBatchResponse {
+    repository: {
+        pullRequest: RawPr | null;
+    } | null;
+}
+export interface RawPr {
+    id: string;
+    number: number;
+    state: string;
+    isDraft: boolean;
+    mergeable: string;
+    mergeStateStatus: string;
+    reviewDecision: string | null;
+    headRefOid: string;
+    headRefName: string;
+    headRepository: {
+        nameWithOwner: string;
+    } | null;
+    baseRefName: string;
+    baseRef: {
+        branchProtectionRule: RawBranchProtectionRule | null;
+    } | null;
+    reviewRequests: {
+        nodes: Array<{
+            requestedReviewer: {
+                login?: string;
+                name?: string;
+            } | null;
+        }>;
+    };
+    latestReviews: {
+        nodes: Array<{
+            author: RawAuthor | null;
+            state: string;
+        }>;
+    };
+    reviewThreads: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawThread[];
+    };
+    comments: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawComment[];
+    };
+    changesRequestedReviews: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawReview[];
+    };
+    reviewSummaries: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawReviewSummary[];
+    };
+    allReviews?: {
+        totalCount: number;
+    };
+    approvedReviews: {
+        pageInfo: {
+            hasPreviousPage: boolean;
+            startCursor: string | null;
+        };
+        nodes: RawReviewSummary[];
+    };
+    commits: {
+        totalCount?: number;
+        nodes: Array<{
+            commit: {
+                oid: string;
+                committedDate?: string;
+                statusCheckRollup: {
+                    contexts: {
+                        pageInfo: {
+                            hasNextPage: boolean;
+                            endCursor: string | null;
+                        };
+                        nodes: Array<RawContextNode | null>;
+                    };
+                } | null;
+            };
+        }>;
+    };
+}
+interface RawAuthor {
+    __typename?: string;
+    login: string;
+}
+export interface RawThreadComment {
+    id: string;
+    isMinimized: boolean;
+    url: string;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    pullRequestReview?: {
+        id: string;
+    } | null;
+    body: string;
+    path: string | null;
+    line: number | null;
+    startLine: number | null;
+    createdAt?: string;
+}
+export interface RawThread {
+    id: string;
+    isResolved: boolean;
+    isOutdated: boolean;
+    path?: string | null;
+    line?: number | null;
+    startLine?: number | null;
+    comments: {
+        pageInfo?: {
+            hasNextPage: boolean;
+            endCursor: string | null;
+        };
+        nodes: RawThreadComment[];
+    };
+}
+export interface RawReviewThreadCommentsResponse {
+    node: {
+        __typename?: string;
+        comments: {
+            pageInfo: {
+                hasNextPage: boolean;
+                endCursor: string | null;
+            };
+            nodes: RawThreadComment[];
+        } | null;
+    } | null;
+}
+export interface RawComment {
+    id: string;
+    isMinimized: boolean;
+    url: string;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    body: string;
+    createdAt?: string;
+}
+export interface RawReview {
+    id: string;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    body: string;
+    createdAt?: string;
+    commit?: {
+        oid: string;
+    };
+}
+export interface RawReviewSummary {
+    id: string;
+    isMinimized: boolean;
+    authorAssociation?: CommentAuthorAssociation;
+    author: RawAuthor | null;
+    body: string;
+    createdAt?: string;
+}
+interface RawBranchProtectionRule {
+    requiresApprovingReviews: boolean;
+    requiredApprovingReviewCount: number;
+    requiresConversationResolution: boolean;
+    requiresStatusChecks: boolean;
+    requiredStatusCheckContexts: string[] | null;
+}
+export type RawContextNode = {
+    __typename: "CheckRun";
+    id: string;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    detailsUrl: string | null;
+    completedAt?: string | null;
+    startedAt?: string | null;
+    title: string | null;
+    summary: string | null;
+    checkSuite: {
+        createdAt?: string;
+        updatedAt?: string;
+        workflowRun: {
+            event: string;
+            createdAt?: string;
+            updatedAt?: string;
+            workflow?: {
+                name: string;
+                databaseId?: number | null;
+            } | null;
+        } | null;
+    } | null;
+} | {
+    __typename: "StatusContext";
+    context: string;
+    state: string;
+    createdAt?: string;
+    targetUrl: string | null;
+    description: string | null;
+};
+export {};

package/bin/github/batch-response.d.mts

@@ -0,0 +1,4 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawBatchResponse, RawContextNode, RawPr } from "./batch-raw-types.mts";
+export declare function requireRawPr(response: RawBatchResponse | null | undefined, pr: number, repo: RepoInfo): RawPr;
+export declare function requireContextNodes(nodes: Array<RawContextNode | null>): RawContextNode[];

package/bin/github/batch-response.mjs

@@ -1,16 +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 Error(`PR #${pr} not found`);
+    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) {
-        throw new GitHubRequestError(`Malformed GitHub GraphQL response: null check context at repository.pullRequest.commits.nodes.0.commit.statusCheckRollup.contexts.nodes.${nullIndex}`, { status: 200 });
+        // 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.d.mts

@@ -0,0 +1,22 @@
+import { type RateLimitInfo, type RepoInfo } from "./client.mts";
+import type { BatchPrData } from "../types.mts";
+interface BatchResult {
+    data: BatchPrData;
+    rateLimit?: RateLimitInfo;
+}
+interface FetchPrBatchOptions {
+    /**
+     * When false (default), the first-page approvedReviews are returned but
+     * backward pagination is skipped. Iterate's approvals-minimize flow sets this
+     * to true only when the user opts in, so long-lived PRs with > 50 approvals
+     * don't pay extra GraphQL round-trips per iterate call for data no consumer
+     * currently uses. The first page is free — already inside the one batch
+     * request — so there's no need to conditionally omit the field itself.
+     */
+    paginateApprovedReviews?: boolean;
+}
+/**
+ * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
+ */
+export declare function fetchPrBatch(pr: number, repo: RepoInfo, opts?: FetchPrBatchOptions): Promise<BatchResult>;
+export {};

package/bin/github/branch-protection.d.mts

@@ -0,0 +1,3 @@
+import type { BatchPrData } from "../types.mts";
+import type { RawPr } from "./batch-raw-types.mts";
+export declare function parseBranchProtection(raw: RawPr): BatchPrData["branchProtection"];

package/bin/github/check-annotations.d.mts

@@ -0,0 +1,2 @@
+import type { CheckAnnotation } from "../types.mts";
+export declare function fetchCheckRunAnnotations(checkRunId: string): Promise<CheckAnnotation[]>;

package/bin/github/client.d.mts

@@ -0,0 +1,46 @@
+/**
+ * High-level GitHub client — wraps http.mts for application-level concerns.
+ *
+ * All GitHub I/O goes through native fetch (via http.mts); the `gh` CLI is no
+ * longer used for GitHub API calls, but may be invoked as an auth-token
+ * fallback via `gh auth token` when neither GH_TOKEN nor GITHUB_TOKEN is set.
+ */
+import type { MergeableState, MergeStateStatus } from "../types.mts";
+export type { RateLimitInfo } from "./http.mts";
+export { graphql, graphqlWithRateLimit } from "./http.mts";
+export interface RepoInfo {
+    owner: string;
+    name: string;
+}
+/**
+ * Returns the current repo's owner and name by parsing `git remote get-url origin`.
+ * Handles https://, git@, and ssh:// remote URL formats.
+ */
+export declare function getRepoInfo(): Promise<RepoInfo>;
+/**
+ * Derives the PR number for the current HEAD branch.
+ * Returns null if no open PR is found.
+ */
+export declare function getCurrentPrNumber(): Promise<number | null>;
+/** Returns the PR number for a given branch, or null if no open PR is found. */
+export declare function getPrNumberForBranch(branch: string, owner: string, repo: string): Promise<number | null>;
+/** Returns the `headRefOid` (commit SHA) of the given PR as reported by GitHub. */
+export declare function getPrHeadSha(pr: number, owner: string, name: string): Promise<string>;
+/** Fetches the node ID and body text for a PR. GitHub returns null body for empty bodies — coerced to "". */
+export declare function getPullRequestBody(pr: number, owner: string, name: string): Promise<{
+    nodeId: string;
+    body: string;
+}>;
+/** Overwrites the PR body. */
+export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;
+/**
+ * Fetches `mergeable` and `mergeStateStatus` via the REST API.
+ *
+ * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
+ * a known GitHub quirk where GraphQL lags behind the REST layer.
+ */
+export declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+}>;
+export declare function getCurrentBranch(): Promise<string>;

package/bin/github/client.mjs

@@ -9,6 +9,7 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { graphql as httpGraphql, rest } from "./http.mjs";
 import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY, GET_PR_BODY_QUERY, UPDATE_PR_BODY_MUTATION, } from "./queries.mjs";
+import { getExecutionCwd } from "../execution-context.mjs";
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
 // GraphQL — thin re-exports so callers don't need to import http.mts directly
@@ -19,7 +20,9 @@ export { graphql, graphqlWithRateLimit } from "./http.mjs";
  * Handles https://, git@, and ssh:// remote URL formats.
  */
 export async function getRepoInfo() {
-    const { stdout } = await execFile("git", ["remote", "get-url", "origin"]);
+    const { stdout } = await execFile("git", ["remote", "get-url", "origin"], {
+        cwd: getExecutionCwd(),
+    });
     const url = stdout.trim();
     return parseRemoteUrl(url);
 }
@@ -95,7 +98,9 @@ export async function getMergeableState(pr, owner, repo) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 export async function getCurrentBranch() {
-    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: getExecutionCwd(),
+    });
     return stdout.trim();
 }
 function parseRemoteUrl(url) {

package/bin/github/errors.d.mts

@@ -0,0 +1,25 @@
+import { ShepherdError } from "../exit-codes.mts";
+import type { RateLimitInfo } from "./http.mts";
+export interface GitHubGraphQlError {
+    message: string;
+    path?: unknown;
+}
+export declare class GitHubRequestError extends ShepherdError {
+    readonly status: number;
+    readonly rateLimit?: RateLimitInfo;
+    readonly retryAfterSeconds?: number;
+    readonly graphqlErrors?: GitHubGraphQlError[];
+    constructor(message: string, opts: {
+        status: number;
+        rateLimit?: RateLimitInfo;
+        retryAfterSeconds?: number;
+        graphqlErrors?: GitHubGraphQlError[];
+        /**
+         * Bypasses status-based classification entirely — for callers that already
+         * know the failure kind better than the HTTP status can express (e.g. a
+         * response that failed to parse at all, which is an internal failure, not
+         * an availability or permission problem).
+         */
+        exitCodeOverride?: number;
+    });
+}

package/bin/github/errors.mjs

@@ -1,10 +1,34 @@
-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;

package/bin/github/gql/batch-pr.gql

@@ -82,6 +82,7 @@ query BatchPr(
               id
               isMinimized
               url
+              authorAssociation
               author {
                 __typename
                 login
@@ -107,6 +108,7 @@ query BatchPr(
           id
           isMinimized
           url
+          authorAssociation
           author {
             __typename
             login
@@ -126,6 +128,7 @@ query BatchPr(
         }
         nodes {
           id
+          authorAssociation
           author {
             __typename
             login
@@ -145,6 +148,7 @@ query BatchPr(
         nodes {
           id
           isMinimized
+          authorAssociation
           author {
             __typename
             login
@@ -164,6 +168,7 @@ query BatchPr(
         nodes {
           id
           isMinimized
+          authorAssociation
           author {
             __typename
             login