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

package/README.md

@@ -190,7 +190,7 @@ actions:
 
 Environment variables:
 
-- `GH_TOKEN` / `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` for auth; `gh auth token` is used as a fallback.
+- `GH_TOKEN` / `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` for auth; `gh auth token` is used as a fallback. See [GitHub authentication and token access](docs/authentication.md) for required PAT permissions.
 - `PR_SHEPHERD_STATE_DIR` to override state and log location.
 - `PR_SHEPHERD_LOG_DISABLED=1` to disable per-worktree debug logging.
 
@@ -221,13 +221,18 @@ Ready-to-use examples for common patterns are in [`examples/classification/`](ex
 ## Requirements
 
 - Node.js >= 22.18.0, Bun, or Deno
-- A GitHub token or authenticated `gh` CLI; private repositories require `repo` scope.
+- A GitHub token or authenticated `gh` CLI with the [required repository access](docs/authentication.md). A classic PAT needs the `repo` scope for complete operation.
 - `git`
 
 ## Docs
 
 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.
@@ -169,16 +108,22 @@ Creates the section at the end if absent. Idempotent — duplicate items are ski
 
 Usage:
   pr-shepherd journal [PR] <item> [--dry-run] [--format text|json]
+  pr-shepherd journal [PR] --file <path> [--dry-run] [--format text|json]
+  pr-shepherd journal [PR] --file - [--dry-run] [--format text|json]
 
   PR     PR number or GitHub pull request URL. Defaults to current branch PR.
   item   Markdown list item: must start with "- " followed by non-whitespace text.
          Example: '- Rejected suggestion: kept existing pattern for consistency.'
+         Provide it as a positional argument, or via --file to avoid shell-escaping
+         backticks and multi-line Markdown. Exactly one of the two is required.
 
 Flags:
+  --file <path>        Read the entry from a file instead of a positional argument.
+                        Pass --file - to read from stdin.
   --dry-run            Preview the new PR body without writing it to GitHub.
   --format text|json   Output format. Default: text.
   --help, -h           Print this help and exit before any GitHub I/O.
 
-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,5 +1,7 @@
+import { readFile } from "node:fs/promises";
+import { EXIT, errorToExitCode } from "../exit-codes.mjs";
 import { runJournal } from "../commands/journal/index.mjs";
-import { parsePrNumber } from "./args.mjs";
+import { getFlag, parsePrNumber } from "./args.mjs";
 import { USAGE } from "./help.mjs";
 export async function handleJournal(args) {
     for (const a of args) {
@@ -7,15 +9,31 @@ export async function handleJournal(args) {
             continue;
         if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
             continue;
+        if (a === "--file" || a.startsWith("--file="))
+            continue;
         process.stderr.write(`pr-shepherd: journal: unknown flag: "${a}"\n`);
-        process.exitCode = 1;
+        process.exitCode = EXIT.USAGE;
         return;
     }
     const { prNumber, extra } = parseJournalArgs(args);
-    const rawItem = extra[0];
-    if (!rawItem) {
+    const filePath = getFlag(args, "--file");
+    if (filePath !== null && extra[0]) {
+        process.stderr.write(`pr-shepherd: journal: provide the entry as a positional argument or via --file, not both\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    let rawItem;
+    try {
+        rawItem = filePath !== null ? await readItemSource(filePath) : extra[0];
+    }
+    catch (e) {
+        process.stderr.write(`pr-shepherd: journal: ${String(e)}\n`);
+        process.exitCode = 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");
@@ -32,14 +50,29 @@ 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 `-`. */
+async function readItemSource(filePath) {
+    if (filePath === "-")
+        return readStdin();
+    return readFile(filePath, "utf8");
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
     }
+    return Buffer.concat(chunks).toString("utf8");
 }
 function parseJournalArgs(args) {
     const flagConsumedIndices = new Set();
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
-        if (a === "--format" && i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        if ((a === "--format" || a === "--file") &&
+            i + 1 < args.length &&
+            !args[i + 1].startsWith("--")) {
             flagConsumedIndices.add(i);
             flagConsumedIndices.add(i + 1);
         }

package/bin/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;