pr-shepherd 0.45.0 → 0.46.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.45.0",
+  "version": "0.46.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -31,8 +31,8 @@ Each tick returns exactly one action:
 
 - `WAIT` — no immediate action; continue with the next poll.
 - `MARK_READY` — the CLI converted an eligible draft PR to ready; continue polling.
-- `FIX_CODE` — agent work is required; complete it, then continue polling.
-- `MERGE` — run the emitted auto-merge command only when GitHub reports `viewerCanEnableAutoMerge`; queue enrollment otherwise hands off for authorization.
+- `FIX_CODE` — agent work is required; complete it, push when needed, then continue polling. Push access to the PR head branch is a usage precondition.
+- `MERGE` — run the emitted auto-merge command only when GitHub reports `viewerCanEnableAutoMerge`; missing authorization returns `ESCALATE`.
 - `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
 - `ESCALATE` — stop polling until a human provides direction.
 
@@ -77,18 +77,18 @@ Conversations Resolved: No [Not Required]
 9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate again with the same options; without code changes, complete the authorized review mutations and iterate again.
 ```
 
-See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
+See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
 
 ## Workflow Assumptions
 
 This system is opinionated and works best with PRs that use required status checks and conversation resolution.
 
 - A human inline thread whose original comment has `viewerDidAuthor: true` is replied to and resolved when its latest comment is unmarked. An unmarked other-human inline thread remains reply-only; a marker-ended other-human thread is already acknowledged and receives no further mutation. Human items are never minimized.
-- Detected bots and configured `botUsernames` review threads are returned until resolved; bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
+- Detected bots and configured `botUsernames` review threads are returned until resolved when the required mutation is authorized and the thread has a source location. Unauthorized or unlocated items are surfaced once and then marker-gated until edited. Bot/non-human threads, PR comments, and review summaries can be resolved or minimized when eligible. Review summaries are not minimized while known inline child threads from that review remain unresolved.
 - Shepherd identifies its own latest reply only when that comment begins `<!-- pr-shepherd -->`, not from author equality. A marked viewer-authored thread can be resolved without another reply as a retry.
 - Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
-- The CLI never performs git mutations itself — it only emits commit/push instructions for the agent to run. It recommends pushing autonomously (own-repo PRs, and fork PRs where the viewer has push access to the fork) unless GitHub's viewer fields affirmatively report no head-branch push access, in which case it hands the push off to a human instead.
+- The CLI never performs git mutations itself — it only emits commit/push instructions for the agent to run. Push access to the PR head is a usage precondition; GitHub viewer fields do not create a separate push-authorization handoff.
 - Every GitHub mutation is permission-aware. Shepherd uses raw viewer capability fields, omits unauthorized commands, and repeats authorization checks in direct `apply` commands. Missing capability data fails closed.
 - `build_suggestion_patches` turns one or more ordered GitHub suggestion threads into checked patches and commit metadata, but never edits the working tree or git history. Local HEAD may be ahead when the live PR head is its ancestor.
 
@@ -156,6 +156,17 @@ complete Markdown list item with LF line endings. It fails closed for malformed
 containers and ignores journal-shaped examples hidden in Markdown constructs. The full journal API,
 including append and reconciliation helpers, is documented in [docs/api.md](docs/api.md).
 
+For shell automation that already has a PR body, use the equivalent local-only command:
+
+```sh
+pr-shepherd journal extract --body-file pr-body.md
+```
+
+It writes one JSON line containing the typed extraction result. It never reads GitHub credentials,
+configuration, or Shepherd logs. On POSIX, its final body-file path entry must be a readable regular
+file in a trusted parent directory; symlinks, FIFOs, and devices are rejected with exit code 66.
+Unsupported platforms fail closed with that same exit code.
+
 ### Clean Local State
 
 `pr-shepherd` stores seen markers, fix-attempt counters, stall fingerprints, ready-delay markers, and logs under `$PR_SHEPHERD_STATE_DIR` (default `$TMPDIR/pr-shepherd-state`).

package/bin/checks/conclusions.d.mts

@@ -6,22 +6,6 @@ import type { CheckConclusion, ViewerAuthorization } from "../types.mts";
  * which covers fork push access — is the right field to gate on.
  */
 export declare function canRerunWorkflows(auth: ViewerAuthorization | undefined): boolean;
-/**
- * True when the viewer can push commits to the PR head branch — the fork, for a fork PR
- * (own-fork PRs report `headRepositoryPermission: "ADMIN"`), or the base repo otherwise.
- * `viewerCanEditFiles` is GitHub's direct "can the viewer commit to this PR" signal (true
- * for fork authors and for maintainers with "allow edits from maintainers" enabled) and
- * takes priority when present.
- *
- * pr-shepherd's premise is that the caller has push access to the PR it's iterating, so
- * this defaults to pushable: it withholds the autonomous push only when GitHub
- * affirmatively reports no head-branch access (`viewerCanEditFiles === false` and
- * `headRepositoryPermission` in `NONE`/`READ`/`TRIAGE`). An unverifiable/unknown signal —
- * matching the residual risk already accepted for CI reruns (see `canRerunWorkflows`) —
- * is treated as pushable rather than pre-emptively handed off; a push without access
- * simply fails when attempted.
- */
-export declare function canPushToHead(auth: ViewerAuthorization | undefined): boolean;
 /** Failing-check rows for formatter/instructions — excludes annotation-only carriers. */
 export declare function isFailingAgentCheck(check: {
     conclusion: CheckConclusion;

package/bin/checks/conclusions.mjs

@@ -11,33 +11,6 @@ export function canRerunWorkflows(auth) {
     const permission = auth?.repositoryPermission;
     return permission != null && RERUN_CAPABLE_PERMISSIONS.has(permission);
 }
-/** Repository roles that carry push access to the head branch. */
-const PUSH_CAPABLE_PERMISSIONS = new Set(["WRITE", "MAINTAIN", "ADMIN"]);
-/**
- * True when the viewer can push commits to the PR head branch — the fork, for a fork PR
- * (own-fork PRs report `headRepositoryPermission: "ADMIN"`), or the base repo otherwise.
- * `viewerCanEditFiles` is GitHub's direct "can the viewer commit to this PR" signal (true
- * for fork authors and for maintainers with "allow edits from maintainers" enabled) and
- * takes priority when present.
- *
- * pr-shepherd's premise is that the caller has push access to the PR it's iterating, so
- * this defaults to pushable: it withholds the autonomous push only when GitHub
- * affirmatively reports no head-branch access (`viewerCanEditFiles === false` and
- * `headRepositoryPermission` in `NONE`/`READ`/`TRIAGE`). An unverifiable/unknown signal —
- * matching the residual risk already accepted for CI reruns (see `canRerunWorkflows`) —
- * is treated as pushable rather than pre-emptively handed off; a push without access
- * simply fails when attempted.
- */
-export function canPushToHead(auth) {
-    if (auth === undefined)
-        return true;
-    if (auth.viewerCanEditFiles === true)
-        return true;
-    const permission = auth.headRepositoryPermission;
-    if (permission != null && !PUSH_CAPABLE_PERMISSIONS.has(permission))
-        return false;
-    return true;
-}
 /** True for conclusions that belong under `## Failing checks` (not success/skipped/neutral). */
 function isFailingCheckConclusion(conclusion) {
     return conclusion == null || !NON_FAILING_CONCLUSIONS.has(conclusion);

package/bin/cli/fix-formatter.mjs

@@ -9,9 +9,11 @@ import { isFailingAgentCheck } from "../checks/conclusions.mjs";
 import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 export function formatFixCodeResult(header, result) {
     const sections = [header];
-    if (result.fix.threads.length > 0) {
-        sections.push("## Review threads");
-        for (const t of result.fix.threads) {
+    const renderThreads = (heading, threads) => {
+        if (threads.length === 0)
+            return;
+        sections.push(heading);
+        for (const t of threads) {
             const lineLabel = renderLineRange(t.startLine, t.line);
             const loc = t.path ? `\`${t.path}:${lineLabel}\`` : "(no location)";
             const heading = t.url ? `[threadId=${t.id}](${t.url})` : `\`threadId=${t.id}\``;
@@ -24,7 +26,11 @@ export function formatFixCodeResult(header, result) {
                 sections.push(renderSuggestionBlock(t.suggestion, ""));
             }
         }
-    }
+    };
+    const locatedThreads = result.fix.threads.filter((thread) => thread.path !== null && thread.line !== null);
+    const unlocatedThreads = result.fix.threads.filter((thread) => thread.path === null || thread.line === null);
+    renderThreads("## Review threads", locatedThreads);
+    renderThreads("## Unlocated review threads (logged once — no mutation)", unlocatedThreads);
     if (result.fix.resolutionOnlyThreads.length > 0) {
         sections.push("## Review threads to resolve");
         sections.push(result.fix.resolutionOnlyThreads

package/bin/cli/help-command-pages.d.mts

@@ -246,5 +246,18 @@ Flags:
   --help, -h           Print this help and exit before any GitHub I/O.
 
 Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
+    readonly "journal extract": `pr-shepherd journal extract
+
+Extract one visible, structurally valid Shepherd Journal from a local PR-body file.
+This command performs no GitHub, configuration, or log I/O.
+
+Usage:
+  pr-shepherd journal extract --body-file <path>
+
+The output is exactly one JSON line: the typed result from extractShepherdJournal.
+Malformed or unrecognized journal content is returned as {"ok":false,...} with exit code 0.
+On POSIX, the final body-file path entry must be a readable regular file in a trusted parent directory;
+symlinks, FIFOs, devices, and unreadable paths exit 66. Unsupported platforms fail closed with exit 66.
+--help, -h                      Print this help and exit before any I/O.`;
     readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
 };

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

@@ -249,5 +249,18 @@ Flags:
   --help, -h           Print this help and exit before any GitHub I/O.
 
 Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`,
+    "journal extract": `pr-shepherd journal extract
+
+Extract one visible, structurally valid Shepherd Journal from a local PR-body file.
+This command performs no GitHub, configuration, or log I/O.
+
+Usage:
+  pr-shepherd journal extract --body-file <path>
+
+The output is exactly one JSON line: the typed result from extractShepherdJournal.
+Malformed or unrecognized journal content is returned as {"ok":false,...} with exit code 0.
+On POSIX, the final body-file path entry must be a readable regular file in a trusted parent directory;
+symlinks, FIFOs, devices, and unreadable paths exit 66. Unsupported platforms fail closed with exit 66.
+--help, -h                      Print this help and exit before any I/O.`,
     "log-file": LOG_FILE_USAGE,
 };

package/bin/cli/help-top-page.d.mts

@@ -1 +1 @@
-export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Select changed files; no viewed-state mutation is attempted.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration 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).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Select changed files; no viewed-state mutation is attempted.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration 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).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";

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

@@ -10,6 +10,7 @@ Usage:
   pr-shepherd apply review [PR] [review-flags]
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
+  pr-shepherd journal extract --body-file <path>
   pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]
   pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]
   pr-shepherd admin log-file [--format text|json]
@@ -20,6 +21,7 @@ Commands:
   apply review         Apply review-state mutations after fixes.
   apply files          Select changed files; no viewed-state mutation is attempted.
   apply journal        Append a list item to the Shepherd Journal details block of a PR body.
+  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.
   build-suggestion-patches
                        Convert ordered GitHub suggestion threads into patches and commit instructions.
   admin clean          Remove pr-shepherd state files.

package/bin/cli/help.d.mts

@@ -246,8 +246,21 @@ Flags:
   --help, -h           Print this help and exit before any GitHub I/O.
 
 Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
+    readonly "journal extract": `pr-shepherd journal extract
+
+Extract one visible, structurally valid Shepherd Journal from a local PR-body file.
+This command performs no GitHub, configuration, or log I/O.
+
+Usage:
+  pr-shepherd journal extract --body-file <path>
+
+The output is exactly one JSON line: the typed result from extractShepherdJournal.
+Malformed or unrecognized journal content is returned as {"ok":false,...} with exit code 0.
+On POSIX, the final body-file path entry must be a readable regular file in a trusted parent directory;
+symlinks, FIFOs, devices, and unreadable paths exit 66. Unsupported platforms fail closed with exit 66.
+--help, -h                      Print this help and exit before any I/O.`;
     readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
-    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Select changed files; no viewed-state mutation is attempted.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration 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).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Select changed files; no viewed-state mutation is attempted.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration 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).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
 };
 /** Resolve help keys for nested public commands before any command I/O. */
 export declare function helpKeyForArgs(args: string[]): keyof typeof USAGE;

package/bin/cli/help.mjs

@@ -13,6 +13,8 @@ export function helpKeyForArgs(args) {
         return "apply files";
     if (args[0] === "apply" && args[1] === "journal")
         return "apply journal";
+    if (args[0] === "journal" && args[1] === "extract")
+        return "journal extract";
     if (args[0] === "admin" && args[1] === "clean")
         return "admin clean";
     if (args[0] === "admin" && args[1] === "log-file")

package/bin/cli/iterate-checks-formatter.d.mts

@@ -0,0 +1,2 @@
+import type { RelevantCheck } from "../types.mts";
+export declare function formatRelevantChecks(checks: RelevantCheck[]): string | null;

package/bin/cli/iterate-checks-formatter.mjs

@@ -0,0 +1,55 @@
+import { renderCheckAnnotation } from "./fix-formatter-extra.mjs";
+export function formatRelevantChecks(checks) {
+    if (checks.length === 0)
+        return null;
+    const lines = ["## Checks", ""];
+    for (const check of checks) {
+        lines.push(...formatRelevantCheck(check));
+    }
+    return lines.join("\n");
+}
+function formatRelevantCheck(check) {
+    const workflow = check.workflowName ? `${check.workflowName} › ` : "";
+    const job = check.jobName ?? check.name;
+    const lines = [`- \`${workflow}${job}\` [conclusion: ${check.conclusion}]`];
+    appendCheckFields(lines, check);
+    appendLogExcerpt(lines, check.logExcerpt);
+    appendAnnotations(lines, check.annotations);
+    return lines;
+}
+function appendCheckFields(lines, check) {
+    const codeFields = [
+        ["run", check.runId],
+        ["URL", check.detailsUrl],
+        ["scope", check.scope],
+        ["commit", check.commitOid],
+    ];
+    for (const [label, value] of codeFields) {
+        if (value)
+            lines.push(`  - ${label}: \`${value}\``);
+    }
+    const textFields = [
+        ["failed step", check.failedStep],
+        ["summary", check.summary],
+    ];
+    for (const [label, value] of textFields) {
+        if (value)
+            lines.push(`  - ${label}: ${value}`);
+    }
+}
+function appendLogExcerpt(lines, logExcerpt) {
+    if (!logExcerpt)
+        return;
+    for (const line of logExcerpt.split("\n"))
+        lines.push(`  > ${line}`);
+}
+function appendAnnotations(lines, annotations) {
+    if (!annotations || annotations.length === 0)
+        return;
+    lines.push("  - annotations:");
+    for (const annotation of annotations) {
+        for (const line of renderCheckAnnotation(annotation).split("\n")) {
+            lines.push(`    ${line}`);
+        }
+    }
+}

package/bin/cli/iterate-formatter.mjs

@@ -1,4 +1,5 @@
 import { formatFixCodeResult } from "./fix-formatter.mjs";
+import { formatRelevantChecks } from "./iterate-checks-formatter.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, } from "./iterate-instructions.mjs";
 import { formatMergeRequirementLines } from "../merge-status/requirements-format.mjs";
@@ -26,7 +27,8 @@ export function formatIterateResult(result, opts) {
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
         : "";
-    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\``;
+    const baseBranchSeg = verbose && result.baseBranch ? ` · **baseBranch** \`${result.baseBranch}\`` : "";
+    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\`${baseBranchSeg}`;
     let summaryLine;
     if (verbose) {
         let verboseBranch = "";
@@ -110,7 +112,8 @@ export function formatIterateResult(result, opts) {
     const header = headerLines.join("\n");
     const quotaWarning = formatQuotaWarning(result.quotaWarning);
     const apiUsage = verbose ? formatApiUsage(result.apiUsage) : null;
-    const telemetrySections = [quotaWarning, apiUsage];
+    const verboseChecks = verbose ? formatRelevantChecks(result.checks) : null;
+    const telemetrySections = [quotaWarning, apiUsage, verboseChecks];
     switch (result.action) {
         case "wait":
             return joinSections([
@@ -149,6 +152,7 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 cancelHeaderLines.join("\n"),
                 ...(apiUsage ? [apiUsage] : []),
+                ...(verboseChecks ? [verboseChecks] : []),
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);
@@ -157,6 +161,7 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 header,
                 ...(apiUsage ? [apiUsage] : []),
+                ...(verboseChecks ? [verboseChecks] : []),
                 result.escalate.humanMessage,
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]);

package/bin/cli/iterate-lean.mjs

@@ -158,6 +158,10 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.escalate.changesRequestedReviews,
                     }),
+                    ...(result.escalate.checks &&
+                        result.escalate.checks.length > 0 && {
+                        checks: result.escalate.checks,
+                    }),
                     ...(result.escalate.stalledChecks &&
                         result.escalate.stalledChecks.length > 0 && {
                         stalledChecks: result.escalate.stalledChecks,

package/bin/cli/journal-extract-handler.d.mts

@@ -0,0 +1,2 @@
+/** Extracts a checked Shepherd Journal from a local PR-body file without external I/O. */
+export declare function handleJournalExtract(args: string[]): Promise<void>;

package/bin/cli/journal-extract-handler.mjs

@@ -0,0 +1,48 @@
+import { extractShepherdJournal } from "../journal/index.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { USAGE, maybePrintHelp } from "./help.mjs";
+import { readSafeBodyFile } from "./safe-body-file.mjs";
+/** Extracts a checked Shepherd Journal from a local PR-body file without external I/O. */
+export async function handleJournalExtract(args) {
+    if (maybePrintHelp(args, "journal extract"))
+        return;
+    const bodyFile = parseBodyFile(args);
+    if (bodyFile === null)
+        return;
+    try {
+        const body = await readSafeBodyFile(bodyFile);
+        process.stdout.write(`${JSON.stringify(extractShepherdJournal(body))}\n`);
+    }
+    catch (error) {
+        process.stderr.write(`pr-shepherd: journal extract: ${String(error)}\n`);
+        process.exitCode = error instanceof ShepherdError ? error.exitCode : EXIT.NOINPUT;
+    }
+}
+function parseBodyFile(args) {
+    let bodyFile;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--body-file") {
+            const value = args[++index];
+            if (value === undefined || bodyFile !== undefined) {
+                return printUsage();
+            }
+            bodyFile = value;
+            continue;
+        }
+        if (arg.startsWith("--body-file=")) {
+            const value = arg.slice("--body-file=".length);
+            if (value === "" || bodyFile !== undefined)
+                return printUsage();
+            bodyFile = value;
+            continue;
+        }
+        return printUsage();
+    }
+    return bodyFile ?? printUsage();
+}
+function printUsage() {
+    process.stderr.write(`${USAGE["journal extract"]}\n`);
+    process.exitCode = EXIT.USAGE;
+    return null;
+}

package/bin/cli/safe-body-file.d.mts

@@ -0,0 +1,14 @@
+import { open } from "node:fs/promises";
+type FileHandle = Awaited<ReturnType<typeof open>>;
+export interface SafeBodyFileReaderDependencies {
+    platform: NodeJS.Platform;
+    noFollow: number | undefined;
+    nonBlock: number | undefined;
+    open: (filePath: string, flags: number) => Promise<FileHandle>;
+}
+/**
+ * Reads a regular file after rejecting unsafe final path entries without exposing its contents.
+ * Callers must trust parent directories: O_NOFOLLOW only protects the final path entry.
+ */
+export declare function readSafeBodyFile(filePath: string, dependencies?: SafeBodyFileReaderDependencies): Promise<string>;
+export {};

package/bin/cli/safe-body-file.mjs

@@ -0,0 +1,42 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+const DEFAULT_DEPENDENCIES = {
+    platform: process.platform,
+    noFollow: constants.O_NOFOLLOW,
+    nonBlock: constants.O_NONBLOCK,
+    open,
+};
+/**
+ * Reads a regular file after rejecting unsafe final path entries without exposing its contents.
+ * Callers must trust parent directories: O_NOFOLLOW only protects the final path entry.
+ */
+export async function readSafeBodyFile(filePath, dependencies = DEFAULT_DEPENDENCIES) {
+    const flags = safeOpenFlags(dependencies);
+    if (flags === null)
+        throw noInput();
+    let handle;
+    try {
+        handle = await dependencies.open(filePath, flags);
+        if (!(await handle.stat()).isFile())
+            throw new Error("not a regular file");
+        return await handle.readFile({ encoding: "utf8" });
+    }
+    catch {
+        throw noInput();
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function safeOpenFlags(dependencies) {
+    if (dependencies.platform === "win32" ||
+        dependencies.noFollow === undefined ||
+        dependencies.nonBlock === undefined) {
+        return null;
+    }
+    return constants.O_RDONLY | dependencies.noFollow | dependencies.nonBlock;
+}
+function noInput() {
+    return new ShepherdError("body file could not be read safely", EXIT.NOINPUT);
+}

package/bin/cli-parser.mjs

@@ -10,6 +10,7 @@ import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
+import { handleJournalExtract } from "./cli/journal-extract-handler.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { setupLog } from "./log/setup.mjs";
@@ -32,6 +33,12 @@ export async function main(argv) {
         await handleLogFile(args.slice(1));
         return;
     }
+    // Extraction deliberately precedes legacy warnings and logging: it is a local,
+    // GitHub/config/log-free read path for automation that already has a PR body.
+    if (subcommand === "journal" && args[1] === "extract") {
+        await handleJournalExtract(args.slice(2));
+        return;
+    }
     // The public command groups keep admin diagnostics out of the normal
     // command namespace. Keep this before setupLog because log-file reads the
     // log path and must not initialize/tee the log it is reporting.

package/bin/commands/check-status.mjs

@@ -9,15 +9,15 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
         return "FAILING";
     if (verdict.anyInProgress)
         return "IN_PROGRESS";
-    // BLOCKED with no remaining shepherd work — hand off via ready-delay regardless of why GitHub
+    // BLOCKED with no remaining shepherd work — enter ready-delay regardless of why GitHub
     // is BLOCKED (review pending, insufficient approvals, branch-protection rule, etc.).
     // Requires hasChecks so that a PR with zero relevant checks (CI never started, or all
     // filtered/skipped) doesn't prematurely trigger READY before any check has reported.
     // Exception: UNSTABLE with ignored checks — UNSTABLE means only non-required checks are
-    // pending/failing, and if those are all ignored the handoff is safe even with no other checks.
+    // pending/failing, and if those are all ignored the ready state is safe even with no other checks.
     // BLOCKED is excluded from the ignoredNames extension: BLOCKED can mean required checks haven't
-    // started, and handing off prematurely there risks a broken merge attempt.
-    // blockingBotReviewInProgress is still excluded — a bot review is shepherd's problem, not a hand-off.
+    // started, and entering READY prematurely there risks a broken merge attempt.
+    // blockingBotReviewInProgress is still excluded — a bot review is Shepherd work, not a READY state.
     const hasRelevantPassingChecks = verdict.hasChecks || (mergeStatus.status === "UNSTABLE" && verdict.ignoredNames.length > 0);
     if (verdict.allPassed &&
         hasRelevantPassingChecks &&

package/bin/commands/check.mjs

@@ -16,7 +16,8 @@ import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
-import { normalizeBotUsernames } from "../comments/authors.mjs";
+import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
+import { buildThreadMutationRouting } from "./iterate/thread-mutation-routing.mjs";
 import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
@@ -80,7 +81,17 @@ export async function runCheck(opts) {
     const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize !== true));
     const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
     const deniedRuleAutoResolveThreadIds = new Set(partition.ruleAutoResolveThreadIds.filter((id) => batchData.reviewThreads.find((thread) => thread.id === id)?.viewerCanResolve !== true));
-    const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id)), seenMap, botUsernames);
+    const visibleThreadCandidates = batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id));
+    const threadMutationRouting = buildThreadMutationRouting(visibleThreadCandidates, botUsernames, partition.ruleAutoResolveThreadIds);
+    const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
+    const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
+    const repeatableThreadIds = new Set(visibleThreadCandidates
+        .filter((thread) => thread.path !== null &&
+        thread.line !== null &&
+        (!replyThreadIds.has(thread.id) || thread.viewerCanReply === true) &&
+        (!resolveThreadIds.has(thread.id) || thread.viewerCanResolve === true))
+        .map((thread) => thread.id));
+    const threadVisibility = classifyThreadVisibility(visibleThreadCandidates, seenMap, botUsernames, repeatableThreadIds);
     const firstLookComments = minimizedCommentCandidates.flatMap((c) => {
         const cls = classifyItem(c.id, c.body, seenMap);
         if (cls === "unchanged")
@@ -103,7 +114,7 @@ export async function runCheck(opts) {
         else
             seenSummaries.push(r);
     }
-    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
+    const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames, batchData.viewerAuthorization?.viewerCanAdminister === true);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     if (opts.persistSeen !== false) {
         const successfulAnnotations = [
@@ -145,12 +156,21 @@ export async function runCheck(opts) {
         ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
     };
     const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(authorizedPartition, opts.autoMinimizeSuppressed);
+    const visibleMutationThreadIds = new Set([...threadVisibility.activeThreads, ...threadVisibility.resolutionOnlyThreads].map((thread) => thread.id));
     const ruleAutoResolveThreadIds = [
         ...authorizedRuleAutoResolveThreadIds,
-        ...deniedRuleAutoResolveThreadIds,
+        ...[...deniedRuleAutoResolveThreadIds].filter((id) => visibleMutationThreadIds.has(id)),
     ];
     const changesRequestedReviews = changesRequestedReviewVisibility.visible;
-    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)).length;
+    const visibleChangesRequestedIds = new Set(changesRequestedReviews.map((review) => review.id));
+    const changesRequestedReviewCount = batchData.changesRequestedReviews.filter((review) => {
+        if (partition.suppressedChangesRequestedIds.has(review.id))
+            return false;
+        const isBot = !isHumanAuthor(review) || isConfiguredBotAuthor(review, botUsernames);
+        return (!isBot ||
+            batchData.viewerAuthorization?.viewerCanAdminister === true ||
+            visibleChangesRequestedIds.has(review.id));
+    }).length;
     const approvedReviews = approvedReviewVisibility.visible;
     let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
     if (status === "READY" && !didRefreshMergeability) {