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

package/README.md

@@ -228,6 +228,11 @@ Ready-to-use examples for common patterns are in [`examples/classification/`](ex
 
 Full reference: [docs/README.md](docs/README.md).
 
-## License
+## Harness Ecosystem
 
-[MIT](LICENSE)
+This is part of the following harness ecosystem:
+
+- [auto-harness](https://github.com/jonathanong/auto-harness) - non-interactive agent CLI orchestration across sandboxes
+- [agent-blackboard](https://github.com/jonathanong/agent-blackboard) - session-scoped telemetry for autonomous agents
+- [pr-shepherd](https://github.com/jonathanong/pr-shepherd) - autonomous pull request shepherd
+- [no-mistakes](https://github.com/jonathanong/no-mistakes) - deterministic AST-based codebase intelligence, test selection, and linting for agents

package/bin/cli/default-poll.mjs

@@ -1,3 +1,4 @@
+import { EXIT } from "../exit-codes.mjs";
 import { parsePrNumber } from "./args.mjs";
 import { validateDefaultArgs } from "./validate-default-args.mjs";
 import { USAGE } from "./help.mjs";
@@ -30,5 +31,5 @@ function isDefaultPollFlag(arg) {
 function writeDefaultUsageError(arg) {
     process.stderr.write(`Unknown subcommand: ${arg}\n`);
     process.stderr.write(`${USAGE.top}\n`);
-    process.exitCode = 1;
+    process.exitCode = EXIT.USAGE;
 }

package/bin/cli/duration-flag.mjs

@@ -1,11 +1,12 @@
-import { parseSecondsDurationParts } from "./exit-codes.mjs";
+import { EXIT } from "../exit-codes.mjs";
+import { parseSecondsDurationParts } from "./duration.mjs";
 export function validateSecondsDurationFlag(command, flag, value, presentAsSeparateArg, opts = {}) {
     const bareUnit = opts.defaultUnit === "m" ? "minutes" : "seconds";
     const example = opts.defaultUnit === "m" ? "15m" : "30s";
     if (value === null) {
         if (presentAsSeparateArg) {
             process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} ${example})\n`);
-            process.exitCode = 1;
+            process.exitCode = EXIT.USAGE;
             return null;
         }
         return undefined;
@@ -13,12 +14,12 @@ export function validateSecondsDurationFlag(command, flag, value, presentAsSepar
     const trimmed = value.trim();
     if (trimmed.startsWith("--")) {
         process.stderr.write(`${command}: ${flag} requires a value (e.g. ${flag} ${example})\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return null;
     }
     if (!parseSecondsDurationParts(trimmed, opts)) {
         process.stderr.write(`${command}: invalid ${flag}: ${value}. Expected a duration like 30s, 4.5m, 1h, or a bare number (${bareUnit}).\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return null;
     }
     return trimmed;

package/bin/cli/{exit-codes.mjs → duration.mjs}

@@ -40,29 +40,3 @@ export function parseDurationToSeconds(s, defaultSeconds, opts = {}) {
         return parsed.value * 60;
     return parsed.value;
 }
-export function statusToExitCode(status) {
-    switch (status) {
-        case "MERGED":
-        case "CLOSED":
-        case "READY":
-            return 0;
-        case "IN_PROGRESS":
-            return 2;
-        case "UNRESOLVED_COMMENTS":
-            return 3;
-        default:
-            return 1;
-    }
-}
-export function iterateActionToExitCode(action) {
-    switch (action) {
-        case "fix_code":
-            return 1;
-        case "cancel":
-            return 2;
-        case "escalate":
-            return 3;
-        default:
-            return 0;
-    }
-}

package/bin/cli/handlers.mjs

@@ -3,6 +3,7 @@ import { runMarkFilesAsViewed } from "../commands/mark-files-as-viewed.mjs";
 import { runIterate } from "../commands/iterate/index.mjs";
 import { runClean } from "../commands/clean.mjs";
 import { loadConfig } from "../config/load.mjs";
+import { EXIT } from "../exit-codes.mjs";
 import { parseCommonArgs, getFlag } from "./args.mjs";
 import { USAGE } from "./help.mjs";
 import { formatCommitSuggestionResult, formatCleanResult, formatMarkFilesAsViewedResult, } from "./formatters.mjs";
@@ -14,7 +15,7 @@ export async function handleClean(args) {
     const variant = args[0];
     if (!variant || !CLEAN_VARIANTS.has(variant)) {
         process.stderr.write(`${USAGE.clean}\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const rest = args.slice(1);
@@ -24,7 +25,7 @@ export async function handleClean(args) {
         if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
             continue;
         process.stderr.write(`pr-shepherd: clean: unknown flag: "${a}"\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const fmtIdx = rest.indexOf("--format");
@@ -38,7 +39,7 @@ export async function handleClean(args) {
     }
     if (formatValue !== undefined && formatValue !== "text" && formatValue !== "json") {
         process.stderr.write(`pr-shepherd: clean: invalid --format value: "${formatValue}". Expected "text" or "json".\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const jsonOut = formatValue === "json";
@@ -52,14 +53,14 @@ export async function handleClean(args) {
     const positionals = rest.filter((a, i) => !flagConsumedIndices.has(i) && !a.startsWith("--"));
     if (positionals.length > 1) {
         process.stderr.write(`pr-shepherd: clean: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const value = positionals[0];
     const result = await runClean({ variant: variant, value, dryRun });
     if (!result.ok) {
         process.stderr.write(`pr-shepherd: clean: ${result.error}\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.SOFTWARE;
         return;
     }
     process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${formatCleanResult(result)}\n`);
@@ -69,13 +70,13 @@ export async function handleCommitSuggestion(args) {
     const threadId = getFlag(extra, "--thread-id");
     if (!threadId) {
         process.stderr.write(`${USAGE["commit-suggestion"]}\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const message = getFlag(extra, "--message") ?? undefined;
     if (!message || message.trim() === "") {
         process.stderr.write("--message is required and must be non-empty\n");
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const description = getFlag(extra, "--description") ?? undefined;
@@ -115,7 +116,7 @@ export async function handleMarkFilesAsViewed(args) {
     const parsed = parseMarkFilesAsViewedArgs(extra);
     if (!parsed.ok) {
         process.stderr.write(`pr-shepherd: mark-files-as-viewed: ${parsed.error}\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const result = await runMarkFilesAsViewed({

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

@@ -1,4 +1,5 @@
 import { LOG_FILE_USAGE } from "./help-log-file-page.mjs";
+import { ITERATE_USAGE, POLL_USAGE } from "./help-iterate-poll-pages.mjs";
 export const COMMAND_USAGE = {
     resolve: `pr-shepherd resolve
 
@@ -28,7 +29,7 @@ At least one non-empty action flag is required:
   --reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids.
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
-Exit code: 0 on success; 1 on validation, lookup, or mutation failure.`,
+Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`,
     "commit-suggestion": `pr-shepherd commit-suggestion
 
 Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
@@ -49,8 +50,10 @@ Preconditions:
   The current branch must match the PR head ref, and local HEAD must match the PR head SHA.
 
 Exit codes:
-  0  suggestion patch and instructions produced
-  1  validation, lookup, precondition, or suggestion parsing failure`,
+  0   suggestion patch and instructions produced
+  64  usage error (missing/invalid flag)
+  69  precondition unmet (thread ineligible, branch/SHA mismatch, no open PR)
+  See docs/exit-codes.md for the full sysexits.h table.`,
     "mark-files-as-viewed": `pr-shepherd mark-files-as-viewed
 
 Mark changed files as viewed in the GitHub pull request diff.
@@ -70,73 +73,9 @@ Flags:
   --help, -h          Print this help and exit before GitHub I/O.
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
-Exit code: 0 on success; 1 on validation or lookup failure.`,
-    iterate: `pr-shepherd iterate
-
-Run one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.
-The output contains one action and an action-specific ## Instructions section.
-
-Usage:
-  pr-shepherd iterate [PR] [iterate-flags]
-
-Iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
-  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
-  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
-  --format text|json             Output Markdown text or JSON. Default: text.
-  --verbose                      Include verbose iterate fields.
-  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
-
-Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).
-
-Actions:
-  WAIT        No immediate code action; recheck later or use pr-shepherd poll.
-  MARK_READY  Draft PR was marked ready for review.
-  FIX_CODE    Apply fixes, commit, push, and run the printed resolve command.
-  CANCEL      Terminal state: merged/closed or ready-delay elapsed.
-  ESCALATE    Terminal state requiring human direction.
-
-Exit codes:
-  0  WAIT or MARK_READY
-  1  FIX_CODE, or a command/validation error
-  2  CANCEL
-  3  ESCALATE`,
-    poll: `pr-shepherd poll
-
-Run iterate repeatedly while the action is WAIT. Print only the final tick to stdout.
-Poll exits as soon as iterate returns MARK_READY, FIX_CODE, CANCEL, or ESCALATE, or when timeout
-returns the last WAIT result. With --until-terminal, poll also continues through MARK_READY.
-
-Usage:
-  pr-shepherd poll [PR] [poll-flags] [iterate-flags]
-
-Poll flags:
-  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.
-  --timeout <duration>           Maximum wall-clock wait. Bare number = seconds. Default: 4.5m.
-  --quiet-status                 During WAIT polling, print only changed status snapshots.
-  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
-
-Forwarded iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
-  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
-  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
-  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
-  --format text|json             Output Markdown text or JSON. Default: text.
-  --verbose                      Include verbose iterate fields and detailed per-tick lines.
-  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
-
-Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
-for --interval/--timeout, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
-an explicit unit (4.5m).
-Each WAIT tick writes a single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
-With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
-
-Exit codes:
-  0  WAIT timeout or MARK_READY
-  1  FIX_CODE, or a command/validation error
-  2  CANCEL
-  3  ESCALATE`,
+Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`,
+    iterate: ITERATE_USAGE,
+    poll: POLL_USAGE,
     clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
@@ -161,7 +100,7 @@ Flags:
   --format text|json   Output format. Default: text.
   --help, -h           Print this help and exit before any cleanup.
 
-Exit code: 0 on success; 1 on validation or cleanup failure.`,
+Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`,
     journal: `pr-shepherd journal
 
 Append a list item to the ## Shepherd Journal section of a PR body.
@@ -185,6 +124,6 @@ Flags:
   --format text|json   Output format. Default: text.
   --help, -h           Print this help and exit before any GitHub I/O.
 
-Exit code: 0 on success (including no-change no-op); 1 on validation, lookup, or mutation failure.`,
+Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`,
     "log-file": LOG_FILE_USAGE,
 };

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

@@ -0,0 +1,72 @@
+export const ITERATE_USAGE = `pr-shepherd iterate
+
+Run one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.
+The output contains one action and an action-specific ## Instructions section.
+
+Usage:
+  pr-shepherd iterate [PR] [iterate-flags]
+
+Iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
+  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --format text|json             Output Markdown text or JSON. Default: text.
+  --verbose                      Include verbose iterate fields.
+  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
+
+Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).
+
+Actions:
+  WAIT        No immediate code action; recheck later or use pr-shepherd poll.
+  MARK_READY  Draft PR was marked ready for review.
+  FIX_CODE    Apply fixes, commit, push, and run the printed resolve command.
+  CANCEL      Terminal state: merged/closed or ready-delay elapsed.
+  ESCALATE    Terminal state requiring human direction.
+
+Exit codes:
+  0   CANCEL (merged or ready-delay elapsed)
+  10  WAIT
+  11  MARK_READY
+  12  FIX_CODE
+  13  ESCALATE
+  14  CANCEL (closed without merging)
+  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
+export const POLL_USAGE = `pr-shepherd poll
+
+Run iterate repeatedly while the action is WAIT. Print only the final tick to stdout.
+Poll exits as soon as iterate returns MARK_READY, FIX_CODE, CANCEL, or ESCALATE, or when timeout
+returns the last WAIT result. With --until-terminal, poll also continues through MARK_READY.
+
+Usage:
+  pr-shepherd poll [PR] [poll-flags] [iterate-flags]
+
+Poll flags:
+  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.
+  --timeout <duration>           Maximum wall-clock wait. Bare number = seconds. Default: 4.5m.
+  --quiet-status                 During WAIT polling, print only changed status snapshots.
+  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.
+
+Forwarded iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
+  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --format text|json             Output Markdown text or JSON. Default: text.
+  --verbose                      Include verbose iterate fields and detailed per-tick lines.
+  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
+
+Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
+for --interval/--timeout, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
+an explicit unit (4.5m).
+Each WAIT tick writes a single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
+With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
+
+Exit codes: same as iterate (the final tick's action/reason decides the code).
+  0   CANCEL (merged or ready-delay elapsed)
+  10  WAIT (including a WAIT returned by --timeout)
+  11  MARK_READY
+  12  FIX_CODE
+  13  ESCALATE
+  14  CANCEL (closed without merging)
+  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;

package/bin/cli/help-top-page.mjs

@@ -54,11 +54,14 @@ Clean variants:
   repo                 Remove all state for the current repository.
   all                  Remove all pr-shepherd state.
 
-Exit codes for iterate and poll:
-  0  WAIT or MARK_READY
-  1  FIX_CODE, or a command/validation error
-  2  CANCEL
-  3  ESCALATE
+Exit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).
+  0   CANCEL (merged or ready-delay elapsed)
+  10  WAIT
+  11  MARK_READY
+  12  FIX_CODE
+  13  ESCALATE
+  14  CANCEL (closed without merging)
+See docs/exit-codes.md for the full sysexits.h error-code table.
 
 Duration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).
 

package/bin/cli/iterate-emitter.mjs

@@ -1,4 +1,4 @@
-import { iterateActionToExitCode } from "./exit-codes.mjs";
+import { iterateResultToExitCode } from "../exit-codes.mjs";
 import { formatIterateResult, projectIterateLean, projectIterateVerbose } from "./formatters.mjs";
 export function emitIterateResult(result, opts) {
     const projectionOpts = {
@@ -14,5 +14,5 @@ export function emitIterateResult(result, opts) {
         const text = formatIterateResult(result, { verbose: opts.verbose, ...projectionOpts });
         process.stdout.write(`${text}\n`);
     }
-    process.exitCode = iterateActionToExitCode(result.action);
+    process.exitCode = iterateResultToExitCode(result);
 }

package/bin/cli/iterate-flags.mjs

@@ -1,5 +1,5 @@
 import { getFlag, hasFlag } from "./args.mjs";
-import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { parseDurationToSeconds } from "./duration.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 // --ready-delay and --stall-timeout are minute-family flags: a bare number means minutes, and 0 is a
 // valid value (it disables the ready-delay settle window / stall-timeout escalation, respectively).

package/bin/cli/journal-handler.mjs

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { EXIT, errorToExitCode } from "../exit-codes.mjs";
 import { runJournal } from "../commands/journal/index.mjs";
 import { getFlag, parsePrNumber } from "./args.mjs";
 import { USAGE } from "./help.mjs";
@@ -11,14 +12,14 @@ export async function handleJournal(args) {
         if (a === "--file" || a.startsWith("--file="))
             continue;
         process.stderr.write(`pr-shepherd: journal: unknown flag: "${a}"\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const { prNumber, extra } = parseJournalArgs(args);
     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;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     let rawItem;
@@ -27,12 +28,12 @@ export async function handleJournal(args) {
     }
     catch (e) {
         process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.NOINPUT;
         return;
     }
     if (rawItem === undefined) {
         process.stderr.write(`${USAGE.journal}\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const dryRun = args.includes("--dry-run");
@@ -49,7 +50,7 @@ export async function handleJournal(args) {
     }
     catch (e) {
         process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
-        process.exitCode = 1;
+        process.exitCode = errorToExitCode(e);
     }
 }
 /** Reads the journal entry from a file, or from stdin when `filePath` is `-`. */

package/bin/cli/poll-handler.mjs

@@ -1,7 +1,7 @@
 import { runPoll } from "../commands/poll.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
-import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { parseDurationToSeconds } from "./duration.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";

package/bin/cli/resolve-validators.mjs

@@ -1,8 +1,9 @@
+import { EXIT } from "../exit-codes.mjs";
 export function rejectPrrcMinimizeIds(ids) {
     const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
     if (prrcIds.length > 0) {
         process.stderr.write(`pr-shepherd: resolve: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.DATAERR;
     }
     return prrcIds;
 }
@@ -19,6 +20,6 @@ export function validateRequireSha(sha) {
     if (/^[0-9a-f]{40}$/.test(sha))
         return true;
     process.stderr.write(`pr-shepherd: resolve: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
-    process.exitCode = 1;
+    process.exitCode = EXIT.DATAERR;
     return false;
 }

package/bin/cli-parser.mjs

@@ -1,5 +1,6 @@
 /** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
+import { EXIT, errorToExitCode } from "./exit-codes.mjs";
 import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
@@ -76,7 +77,7 @@ export async function main(argv) {
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
             process.stderr.write(`${USAGE.top}\n`);
-            process.exitCode = 1;
+            process.exitCode = EXIT.USAGE;
             return;
     }
 }
@@ -102,7 +103,7 @@ async function handleLogFile(args) {
     }
     catch (e) {
         process.stderr.write(`pr-shepherd: log-file: ${String(e)}\n`);
-        process.exitCode = 1;
+        process.exitCode = errorToExitCode(e);
     }
 }
 async function handleResolve(args) {
@@ -120,7 +121,7 @@ async function handleResolve(args) {
         return;
     if (hasFlag(extra, "--fetch")) {
         process.stderr.write("pr-shepherd: resolve: --fetch has been removed; run pr-shepherd iterate or poll to fetch the next action.\n");
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const hasAction = resolveThreadIds.length > 0 ||
@@ -129,7 +130,7 @@ async function handleResolve(args) {
         dismissReviewIds.length > 0;
     if (!hasAction) {
         process.stderr.write("pr-shepherd: resolve: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n");
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const result = await runResolveMutate({

package/bin/commands/check.mjs

@@ -19,11 +19,12 @@ import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers
 import { normalizeBotUsernames } from "../comments/authors.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 export async function runCheck(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 config = loadConfig();
     const paginateApprovedReviews = config.iterate.minimizeApprovals;

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

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

@@ -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/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/graphql-response.mjs

@@ -1,3 +1,4 @@
+import { EXIT } from "../exit-codes.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 export function parseGraphQlPayload(parsed, status, rateLimit, retryAfterSeconds) {
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
@@ -34,9 +35,13 @@ export function formatGraphQlErrors(errors) {
         .join("; ");
 }
 function malformedGraphQlResponse(detail, status, rateLimit, retryAfterSeconds) {
+    // A response that fails to parse as valid GraphQL shape is an internal/unexpected
+    // failure, not a precondition or permission problem — force EX_SOFTWARE rather
+    // than letting the (likely 200) status fall through to EX_UNAVAILABLE.
     return new GitHubRequestError(`Malformed GitHub GraphQL response: ${detail}`, {
         status,
         rateLimit: rateLimit ?? undefined,
         retryAfterSeconds,
+        exitCodeOverride: EXIT.SOFTWARE,
     });
 }

package/bin/github/http-auth.mjs

@@ -1,5 +1,6 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
 const execFile = promisify(execFileCb);
 let _token;
 export function _resetTokenCache() {
@@ -35,7 +36,7 @@ async function resolveToken() {
         _token = codexToken;
         return _token;
     }
-    throw new Error("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.");
+    throw new ShepherdError("No GitHub token found. Set GH_TOKEN, GITHUB_TOKEN, or GITHUB_PERSONAL_ACCESS_TOKEN, or run `gh auth login`.", EXIT.NOPERM);
 }
 export async function makeHeaders() {
     return {

package/bin/github/rest-http.mjs

@@ -1,8 +1,9 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { GitHubRequestError } from "./errors.mjs";
 import { makeHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
-import { redactToken, redactUrl, sanitizeBody } from "./http-utils.mjs";
+import { parseRateLimit, parseRetryAfter, redactToken, redactUrl, sanitizeBody, } from "./http-utils.mjs";
 const BASE_URL = "https://api.github.com";
 export async function rest(method, path, body) {
     const url = `${BASE_URL}${path}`;
@@ -28,7 +29,11 @@ export async function rest(method, path, body) {
             textBody: redactToken(text),
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        throw new Error(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`);
+        throw new GitHubRequestError(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
     }
     if (ct.includes("application/json")) {
         const json = (await res.json());
@@ -80,7 +85,11 @@ export async function restText(path) {
             durationMs,
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        throw new Error(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`);
+        throw new GitHubRequestError(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`, {
+            status: res.status,
+            rateLimit: parseRateLimit(res.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(res.headers),
+        });
     }
     appendEntry(formatResponseEntry({
         n,
@@ -121,8 +130,13 @@ async function followRestTextRedirect(res, entry) {
         durationMs: Math.round(performance.now() - t1),
         contentLength: parseContentLength(redirectRes.headers),
     }));
-    if (!redirectRes.ok)
-        throw new Error(`redirect target ${location} failed: ${redirectRes.status}`);
+    if (!redirectRes.ok) {
+        throw new GitHubRequestError(`redirect target ${location} failed: ${redirectRes.status}`, {
+            status: redirectRes.status,
+            rateLimit: parseRateLimit(redirectRes.headers) ?? undefined,
+            retryAfterSeconds: parseRetryAfter(redirectRes.headers),
+        });
+    }
     return redirectRes.text();
 }
 function parseContentLength(headers) {

package/bin/index.mjs

@@ -8,6 +8,7 @@
  *   pr-shepherd iterate [PR]
  */
 import { main } from "./cli-parser.mjs";
+import { errorToExitCode } from "./exit-codes.mjs";
 function formatCause(cause, seen = new Set(), depth = 0) {
     if (depth > 5 || seen.has(cause))
         return "[circular or deep cause chain]";
@@ -23,5 +24,5 @@ main(process.argv).catch((err) => {
     const msg = err instanceof Error ? err.message : String(err);
     const causeStr = err instanceof Error && err.cause != null ? formatCause(err.cause) : null;
     process.stderr.write(`pr-shepherd error: ${msg}${causeStr !== null ? ` (cause: ${causeStr})` : ""}\n`);
-    process.exit(1);
+    process.exit(errorToExitCode(err));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -38,9 +38,9 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.57.0",
+    "oxfmt": "^0.60.0",
     "oxlint": "^1.60.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.4"
   },
   "scripts": {

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -20,7 +20,7 @@ Poll dispatcher for iterating a PR to completion.
 
 3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. `[FIX_CODE]` is non-terminal: do its instructions, then poll again. The poll already waits between ticks via `--interval`; do not add manual `sleep`s between ticks.
 
-4. **Nonzero exit codes:** Treat a nonzero poll exit as PR state only when the output contains a matching `# PR #$N [ACTION]` heading. Exit `1` can also mean a command or validation failure; if there is no `[ACTION]` heading, surface the error and stop instead of looping.
+4. **Exit codes:** an exit code of `64` or higher means the `pr-shepherd` command itself failed (bad flag, GitHub auth/permission error, transient failure, etc.) — surface the error and stop instead of looping. Any other exit code (`0` or `10`–`19`) means the command ran and the output above is real PR state — proceed to step 5.
 
 5. **Terminal states (stop):**
    - `[CANCEL]` — ready-delay completed, or PR merged/closed.