pr-shepherd 0.56.5 → 0.57.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.56.5",
+  "version": "0.57.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -15,7 +15,7 @@ An agent finishing a PR should think about code, not reconstruct GitHub state or
 
 Highlights:
 
-- Batched GraphQL reads and writes (plus REST where GraphQL cannot) so one poll replaces a tool-call fan-out. MCP `iterate` is one tick and the client owns recurrence; `--debounce` is a poll-dispatcher settle window, not an MCP tool.
+- GraphQL by default, with a supported REST transport for Claude Code cloud sessions and narrowly defined automatic fallback. REST may expose less context; missing fields remain unknown. MCP `iterate` is one tick and the client owns recurrence; `--debounce` is a poll-dispatcher settle window, not an MCP tool.
 - CI summaries include failed checks, and the failed job/step plus a log excerpt when triage can fetch them. Job and log details are omitted for `STARTUP_FAILURE` and `CANCELLED`; agents may still inspect logs.
 - Handles GitHub comment types (comments, threads, replies) and their states, including first-look, outdated, resolved, minimized, and edited.
 - `apply` batches resolve / reply / minimize / dismiss. `build_suggestion_patches` validates and returns ordered diffs without mutating git.
@@ -34,8 +34,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, push when needed, then continue polling. Push access to the PR head branch is a usage precondition.
-- `MERGE` — run the emitted head-pinned auto-merge or queue command. Ordinary merges include a plain-merge fallback; queue merges include a GraphQL enqueue fallback. GitHub is authoritative for the result and reports any authorization failure.
-- `CANCEL` — stop polling this pull request because it merged, closed, or completed its ready-delay. Continue any remaining pull requests or issues from the original request.
+- `MERGE` — run the emitted head-pinned merge or queue command for the selected transport. GitHub is authoritative for the result and reports any authorization failure. Queue operations can use REST.
+- `CANCEL` — stop polling this pull request because it merged, closed, or completed its ready-delay. It prints no instructions; continue any remaining pull requests or issues from the original request.
 - `ESCALATE` — stop polling until a human provides direction. Native stacks reach this only after their autonomous one-PR sessions are exhausted.
 
 Native-stack summaries additionally use stack-level `SHEPHERD`: run the listed one-PR sessions,
@@ -48,14 +48,12 @@ Example shape:
 
 # PR #123 [FIX_CODE]
 
-**status** `UNRESOLVED_COMMENTS` · **merge** `CLEAN` · **state** `OPEN` · **repo** `owner/repo`
+**status** `UNRESOLVED_COMMENTS` · **repo** `owner/repo`
 **summary** 3 passing
-Approvals: None [Not Required]
-Conversations Resolved: No [Not Required]
 
 ## Review threads
 
-### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice · User · MEMBER)
+### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice · MEMBER)
 
 > The variable name is misleading.
 
@@ -64,21 +62,14 @@ Conversations Resolved: No [Not Required]
 - `24697658766` — `CI › lint / typecheck / test (22.x)` [conclusion: FAILURE]
   > oxfmt
 
-## Post-fix actions
-
-- base: `main`
-- apply review: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
-
 ## Instructions
 
-1. Review each item under `## Review threads` and `## Failing checks` and decide whether it needs a code change.
-2. Apply every warranted review fix in each file referenced above.
-3. Triage `## Failing checks`. Playbook: "CI failure triage".
-4. If you changed code, commit any remaining changes and push to the PR head branch. If you did not, do not commit.
-5. If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)` (it must equal the remote PR head). If you did, use the pushed SHA.
-6. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
-7. Run the `apply review:` command above. Playbook: "Review-mutation mechanics".
-8. `[FIX_CODE]` is non-terminal. Iterate immediately with the same options.
+1. Fix each warranted item.
+2. Triage `## Failing checks`. Playbook: "CI failure triage".
+3. Commit and push any changes.
+4. Journal key decisions or rejections with URLs or IDs: `pr-shepherd apply journal 123 '- <decision>'`
+5. `$DISMISS_MESSAGE`: one sentence on what changed. Run even if no code changed: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha HEAD`
+6. Rerun Shepherd now.
 ```
 
 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`–`16`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
@@ -94,7 +85,7 @@ This system is opinionated and works best with PRs that use required status chec
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
 - With `--merge`, actionable review threads/comments/reviews/summaries are held back (`WAIT`, with raw deferred-work counts) while a PR sits in the merge queue, since a Shepherd-initiated push would eject it; set `actions.workWhileQueued: true` to act on them immediately instead. Failing checks and merge conflicts are never deferred.
 - 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.
-- Generated iterate mutations and automatic actions are capability-aware and omit unauthorized commands. Explicit `apply` operations forward the caller's requested IDs without iterate's author or capability policy and surface GitHub's result.
+- Generated iterate mutations use capability fields when the transport supplies them. With REST, capability is unknown and otherwise eligible mutations are attempted; GitHub's response is authoritative. Explicit `apply` operations forward the caller's requested IDs and surface GitHub's result.
 - `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.
 
 ## Usage
@@ -135,6 +126,9 @@ pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE or stack S
 pr-shepherd 42 --ready-delay 15m
 pr-shepherd 42 --merge                  # request head-pinned auto-merge/queue; GitHub reports the result
 pr-shepherd iterate 42                 # single tick
+pr-shepherd 42 --instructions playbook # fold invariant fix_code steps into a playbook pointer (default: inline)
+pr-shepherd 42 --poll-mode event       # one tick, no sleeping; prints nextCheck (default under CLAUDE_CODE_REMOTE=true)
+pr-shepherd playbook "Fix-code loop"   # print a bundled skill playbook (no name lists them)
 pr-shepherd owner/repo#42              # poll a PR in an explicit repository
 pr-shepherd https://github.com/owner/repo/pull/42
 pr-shepherd 42 43 44                   # summarize an explicit same-repository set
@@ -144,13 +138,16 @@ pr-shepherd --stack 43                 # summarize every PR in a native GitHub s
 A user-supplied `--merge` authorizes the agent to run the emitted merge/enqueue commands for the
 selected PRs or stack without another conversational confirmation. Host permission checks still apply.
 
-Multi-PR and `--stack` polling use compact, read-only GraphQL summaries. They return when work is
+Multi-PR and `--stack` polling use compact, read-only summaries from the selected transport.
+GraphQL mode uses GraphQL summaries; REST mode preserves unavailable fields as unknown. They return when work is
 needed, every selected PR is complete, the bounded timeout expires, or `--until-terminal` crosses a
 configured GraphQL quota-warning band. Explicit PR sets give each actionable row an exact single-PR
 `pollCommand`, so independent rows can proceed before the next aggregate poll.
 
 Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself. Every
-layer that still has work gets its own one-PR session on the same tick, including a clean draft
+row marks ownership by comparing its author with the authenticated viewer; REST reads `/user`
+for that identity without inferring viewer permissions. Sessions act only on rows marked `owned`. Every
+owned layer that still has work gets its own one-PR session on the same tick, including a clean draft
 whose session marks it ready. Layers do not wait for a lower layer's READY receipt, so their
 ready-delays overlap. With automatic mark-ready disabled, the instructions ask the agent to mark
 a clean draft ready after its probe. A queued stack, or one whose remaining layers can only wait,
@@ -161,14 +158,20 @@ until then, `SHEPHERD` remains the immediate action and lists the human blockers
 
 With `--stack --merge`, the highest open layer whose open lower layers all have current READY
 receipts, and whose bottom open layer GitHub has retargeted onto the stack base, returns `MERGE`
-with `gh stack merge <that PR number> --yes` and the allowed method flag (`--squash` unless config or the repository selects another). That lands the named layer and every
+with the transport-specific stack merge command and allowed method. GraphQL mode uses
+`gh stack merge <that PR number> --yes`; REST mode uses the SHA-pinned
+`pr-shepherd apply merge` command, using the trunk's known queue policy even when the named layer
+targets its parent branch. The command binds the observed stack, trunk, and ordered prefix with
+`--expected-stack` and rejects a changed stack before submission. Unknown REST queue policy uses
+`default` without a merge method. Known queue requests omit the configured direct merge method.
+That lands the named layer and every
 unmerged layer below it. When the base uses a merge queue, the same command queues the prefix
 together and GitHub evaluates each layer from the bottom; a failure ejects that layer and those
 above it. For a `failed_checks` removal on the layer's first ejection, the one-PR session emits a head-, queue-commit-, and timestamp-pinned local acknowledgment command; run it only when the failure does not reproduce after updating from the latest base, the head did not change, and no source changes or other blockers remain. Fresh source checks and a new READY receipt then let the aggregate selector recover the eligible prefix. Manual or stale removals cannot use this path. Layers above the prefix keep their one-PR sessions. After the merge, GitHub retargets
 the next layer, so the rerun continues until the stack returns `CANCEL`. API and MCP aggregate
 calls perform one summary tick and leave recurrence to the caller.
 
-Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds` (built-in 60 for one PR), `stackIntervalFactor` (built-in 2, so `--stack` and multi-PR polls wait 120s), `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit `--interval` overrides either period for that invocation and is not multiplied. Other explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default. Quota-warning bands stay multiples of `intervalSeconds`; the dispatcher sleeps the slower of the effective interval and the active band, so a default stack waits 120s until a tighter band is slower than that.
+Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds` (built-in 60 for one PR), `stackIntervalFactor` (built-in 2, so `--stack` and multi-PR polls wait 120s), `timeoutSeconds`, `debounceSeconds`, `quietStatus`, and `reconcileSeconds` (built-in 900; the longest an idle GraphQL wait replays its last snapshot while REST change detectors are unchanged). Explicit `--interval` overrides either period for that invocation and is not multiplied. Other explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default. Quota-warning bands stay multiples of `intervalSeconds`; the dispatcher sleeps the slower of the effective interval and the active band, so a default stack waits 120s until a tighter band is slower than that.
 
 ### Apply Review And Journal Changes, Or Select Files
 
@@ -193,7 +196,8 @@ containers and ignores journal-shaped examples hidden in Markdown constructs. Th
 including append and reconciliation helpers, is documented in [docs/api.md](docs/api.md).
 
 MCP clients can call `extract_journal({ body: prBody })` for the same pure result without writing a
-file, or `get_journal({ pr: "owner/repo#123" })` to fetch a PR body through GraphQL and extract it.
+file, or `get_journal({ pr: "owner/repo#123" })` to fetch a PR body through the selected
+transport and extract it.
 Both return the typed extraction JSON in `structuredContent` and `content`; neither mutates the PR.
 
 For shell automation that already has a PR body, use the equivalent local-only command:
@@ -209,6 +213,8 @@ Unsupported platforms fail closed with that same exit code.
 
 ### Clean Local State
 
+In Claude Code cloud sessions, [event mode](docs/cloud.md) runs one tick per event or wake-up instead of sleeping, and the default state directory moves into the repository's common directory.
+
 `pr-shepherd` stores seen markers, fix-attempt counters, stall fingerprints, ready-delay markers, and logs under `$PR_SHEPHERD_STATE_DIR` (default: `pr-shepherd-state` in the per-user temp dir; see [configuration](docs/configuration.md#environment-variables)).
 
 ```sh
@@ -314,6 +320,17 @@ For guided noise reduction, use the plugin's `reduce-pr-noise` skill. It loads f
 
 ### Classification rules
 
+For common vendor bot noise (CodeRabbit and Gemini rate-limit notices, Codex usage-limit and review boilerplate, Codecov reports, and more), enable the bundled rules instead of writing your own:
+
+```yaml
+# .pr-shepherdrc.yml
+classify:
+  standard:
+    all: true
+```
+
+See [`classify.standard`](docs/configuration.md#classifystandard--default-) for the rule list and per-rule overrides. Write custom rules for repository-specific policy.
+
 Drop `.ts` / `.mts` / `.mjs` / `.js` files under `.pr-shepherd/classification/` to suppress and/or auto-resolve specific bot comments — useful for silencing repetitive noise like rate-limit notices from `gemini-code-assist` or "Reviews paused" from `coderabbitai`.
 
 ```ts
@@ -328,7 +345,7 @@ const rule: ClassifyRule = (item) => {
 export default rule;
 ```
 
-`suppress: true` hides the item from agent output. `autoResolve: true` queues it for the minimize/resolve mutation. `reason` is an optional note. When both flags apply together and `actions.autoMinimizeSuppressed` is `true` (the default), Shepherd resolves the thread or minimizes the comment or review summary during `iterate` only when GitHub reports the exact per-object capability. Confirmed successes are recorded on `threads.autoResolved` and `comments.autoMinimized`, printed once as `## Classification auto-resolve` before `## Instructions` (the same `ruleAutoResolve` object in JSON), and appended as one Shepherd Journal list item attributed to the token login. Distinct rule reasons are included. Failed IDs stay on the generated `apply review` command, and each failure is an extra bullet in that section. A journal write failure is reported the same way and does not undo the GitHub resolve or minimize. `actions.autoMinimizeSuppressed: false` leaves the IDs on that command and does not mutate, journal, or print the line. Denied or unverifiable items return to the normal first-look/edit visibility gate and produce no mutation recommendation.
+`suppress: true` hides the item from agent output. `autoResolve: true` queues it for the minimize/resolve mutation. `reason` is an optional note. When both flags apply together and `actions.autoMinimizeSuppressed` is `true` (the default), Shepherd attempts supported operations and relies on GitHub's response when capability is unknown. Confirmed successes are recorded on `threads.autoResolved` and `comments.autoMinimized`, printed once as `## Classification auto-resolve` before `## Instructions` (the same `ruleAutoResolve` object in JSON), and appended as one Shepherd Journal list item attributed to the token login. Distinct rule reasons are included. Failed IDs stay on the generated `apply review` command, and each failure is an extra bullet in that section. A journal write failure is reported the same way and does not undo the GitHub resolve or minimize. `actions.autoMinimizeSuppressed: false` leaves the IDs on that command and does not mutate, journal, or print the line. Denied review mutations are surfaced once then skipped; REST comment minimization is unsupported and is surfaced as a one-look skip. See [transport behavior](docs/rest.md).
 
 TypeScript rules are loaded by the runtime's native TypeScript support; keep them to erasable syntax such as type annotations and `import type`. Runtime TypeScript features that need transpilation, such as enums, namespaces, parameter properties, and decorators, are not supported. Use `.mts` for portable ESM rules across Node, Bun, and Deno.
 

package/bin/api.d.mts

@@ -1,3 +1,9 @@
+import { type GithubTransport } from "./github/transport.mts";
+export type { GithubTransport } from "./github/transport.mts";
+import { type ApplyMergeResult } from "./commands/apply-merge.mts";
+import type { RestMergeAction, RestMergeStackGuard } from "./github/rest-merge.mts";
+export type { RestMergeStackGuard } from "./github/rest-merge.mts";
+import type { MergeMethod } from "./config/merge-method.mts";
 import { type JournalResult } from "./commands/journal/index.mts";
 import { type MarkFilesAsViewedResult } from "./commands/mark-files-as-viewed.mts";
 import { type ApplyQueueRemovalResult } from "./commands/apply-queue-removal.mts";
@@ -5,12 +11,14 @@ import type { ResolveResult } from "./comments/resolve.mts";
 import type { BuildSuggestionPatchesResult, CommitSuggestionResult, IterateCommandOptions, IterateResult, PollSummaryResult } from "./types.mts";
 import { type ShepherdJournalExtraction } from "./journal/index.mts";
 export interface CreatePrShepherdOptions {
+    /** GitHub transport retained for this client; individual calls may override it. */
+    transport?: GithubTransport;
     /** Working directory used for git, config, and classification-rule lookups. */
     cwd?: string;
 }
 /** A positive PR number, GitHub pull-request URL, or owner/repo#number reference. */
 export type PrReference = number | string;
-type IterateOptions = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "fingerprintCache" | "deferQuotaWarning" | "quotaWarningMinimumPollIntervalMinutes">;
+type IterateOptions = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "fingerprintCache" | "stallDeadlineSink" | "deferQuotaWarning" | "quotaWarningMinimumPollIntervalMinutes">;
 export type SingleIterateInput = IterateOptions & {
     pr?: PrReference;
     prs?: never;
@@ -34,6 +42,7 @@ export interface ReviewMutationsOperation {
     dismissReviewIds?: string[];
     /** Required when replying to a thread or dismissing a review. */
     message?: string;
+    /** `HEAD` (this checkout's commit) or a full SHA the PR head must match before mutating. */
     requireSha?: string;
 }
 export interface MarkFilesViewedOperation {
@@ -54,14 +63,25 @@ export interface AcknowledgeQueueRemovalOperation {
     queueCommitOid: string;
     removedAtUnix: number;
 }
+export interface MergeOperation {
+    type: "merge";
+    requireSha: string;
+    mergeAction: RestMergeAction;
+    mergeMethod?: MergeMethod;
+    expectedStack?: RestMergeStackGuard;
+}
 /** Operations run in this exact list order after validation. */
-export type ApplyOperation = ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation | AcknowledgeQueueRemovalOperation;
+export type ApplyOperation = MergeOperation | ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation | AcknowledgeQueueRemovalOperation;
 export interface ApplyInput {
+    transport?: GithubTransport;
     /** PR shared by every operation in this ordered apply request. */
     pr?: PrReference;
     operations: ApplyOperation[];
 }
 export type ApplyOperationResult = {
+    type: "merge";
+    result: ApplyMergeResult;
+} | {
     type: "review_mutations";
     result: ResolveResult;
 } | {
@@ -78,6 +98,7 @@ export interface ApplyResult {
     operations: ApplyOperationResult[];
 }
 export interface BuildSuggestionPatchInput {
+    transport?: GithubTransport;
     pr?: PrReference;
     threadId: string;
     message: string;
@@ -89,10 +110,12 @@ export interface SuggestionPatchInput {
     description?: string;
 }
 export interface BuildSuggestionPatchesInput {
+    transport?: GithubTransport;
     pr?: PrReference;
     suggestions: SuggestionPatchInput[];
 }
 export interface GetJournalInput {
+    transport?: GithubTransport;
     pr: PrReference;
 }
 export interface PrShepherd {
@@ -120,4 +143,3 @@ export declare class PartialApplyError extends Error {
  * read/plan, ordered apply, and suggestion-patch operations.
  */
 export declare function createPrShepherd(options?: CreatePrShepherdOptions): PrShepherd;
-export {};

package/bin/api.mjs

@@ -1,9 +1,10 @@
 /* eslint-disable max-lines */
 import { resolve } from "node:path";
+import { createGithubTransportRunner } from "./github/transport.mjs";
+import { runApplyMerge, validateApplyMergeOptions, } from "./commands/apply-merge.mjs";
 import { runCommitSuggestion } from "./commands/commit-suggestion.mjs";
 import { runSuggestionPatches } from "./commands/suggestion-patches.mjs";
-import { runIterate } from "./commands/iterate/index.mjs";
-import { runPollSummary } from "./commands/poll-summary.mjs";
+import { runIterateForMode, runPollSummaryForMode } from "./commands/event-mode.mjs";
 import { runJournal } from "./commands/journal/index.mjs";
 import { validateJournalItem } from "./commands/journal/transform.mjs";
 import { runMarkFilesAsViewed, } from "./commands/mark-files-as-viewed.mjs";
@@ -12,6 +13,7 @@ import { applyQueueRemovalAck, } from "./commands/apply-queue-removal.mjs";
 import { runWithExecutionCwd } from "./execution-context.mjs";
 import { parsePrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "./pr-reference.mjs";
 import { getPullRequestBody, getRepoInfo } from "./github/client.mjs";
+import { getLocalHeadSha } from "./commands/suggestion-patch-git.mjs";
 import { extractShepherdJournal } from "./journal/index.mjs";
 /** Raised before any API mutation when an input cannot be validated. */
 export class PrShepherdValidationError extends Error {
@@ -38,22 +40,26 @@ export class PartialApplyError extends Error {
  */
 export function createPrShepherd(options = {}) {
     const cwd = options.cwd === undefined ? undefined : resolve(options.cwd);
+    const transportRunner = createGithubTransportRunner(options.transport);
+    function runInClient(input, work) {
+        return runWithExecutionCwd(cwd, () => transportRunner(work, input?.transport));
+    }
     function iterate(input = {}) {
-        return runWithExecutionCwd(cwd, async () => {
+        return runInClient(input, async () => {
             validateIterateSelectors(input);
             if ("prs" in input || "stack" in input) {
                 const target = await resolveAggregateIterateInput(input);
-                return runPollSummary(target);
+                return runPollSummaryForMode(target);
             }
             const { pr: _pr, ...iterateOptions } = input;
             const target = resolvePrReference(input.pr);
-            return runIterate({ ...iterateOptions, ...target, format: "json" });
+            return runIterateForMode({ ...iterateOptions, ...target, format: "json" });
         });
     }
     return Object.freeze({
         iterate,
         getJournal(input) {
-            return runWithExecutionCwd(cwd, async () => {
+            return runInClient(input, async () => {
                 const { prNumber, targetRepository } = resolvePrReference(input.pr);
                 if (!prNumber)
                     throw new PrShepherdValidationError("getJournal requires a PR reference");
@@ -63,7 +69,7 @@ export function createPrShepherd(options = {}) {
             });
         },
         apply(input) {
-            return runWithExecutionCwd(cwd, async () => {
+            return runInClient(input, async () => {
                 validateApplyInput(input);
                 const { prNumber, targetRepository } = resolvePrReference(input.pr);
                 const results = [];
@@ -71,16 +77,32 @@ export function createPrShepherd(options = {}) {
                     const operation = input.operations[index];
                     try {
                         switch (operation.type) {
+                            case "merge": {
+                                const result = await runApplyMerge({
+                                    prNumber,
+                                    targetRepository,
+                                    requireSha: operation.requireSha,
+                                    mergeAction: operation.mergeAction,
+                                    mergeMethod: operation.mergeMethod,
+                                    expectedStack: operation.expectedStack,
+                                });
+                                results.push({ type: operation.type, result });
+                                break;
+                            }
                             case "review_mutations": {
                                 const { type: _type, message, ...options } = operation;
                                 const result = await runResolveMutate({
                                     ...options,
+                                    // `HEAD` names this checkout's commit, the same form the printed CLI command uses.
+                                    requireSha: options.requireSha === "HEAD" ? await getLocalHeadSha() : options.requireSha,
                                     prNumber,
                                     targetRepository,
                                     dismissMessage: message,
                                     format: "json",
                                 });
                                 results.push({ type: operation.type, result });
+                                if (result.sessionRefusal)
+                                    return { operations: results };
                                 break;
                             }
                             case "mark_files_viewed": {
@@ -130,7 +152,7 @@ export function createPrShepherd(options = {}) {
         buildSuggestionPatch(input) {
             validateSuggestionPatchInput(input);
             const { pr: _pr, ...options } = input;
-            return runWithExecutionCwd(cwd, async () => {
+            return runInClient(input, async () => {
                 const target = resolvePrReference(input.pr);
                 return runCommitSuggestion({ ...options, ...target, format: "json" });
             });
@@ -138,7 +160,7 @@ export function createPrShepherd(options = {}) {
         buildSuggestionPatches(input) {
             validateSuggestionPatchesInput(input);
             const { pr: _pr, ...options } = input;
-            return runWithExecutionCwd(cwd, async () => {
+            return runInClient(input, async () => {
                 const target = resolvePrReference(input.pr);
                 return runSuggestionPatches({ ...options, ...target, format: "json" });
             });
@@ -190,15 +212,29 @@ function validateApplyInput(input) {
     if (!input || !Array.isArray(input.operations) || input.operations.length === 0) {
         throw new PrShepherdValidationError("apply requires a non-empty operations array");
     }
-    for (const operation of input.operations)
+    const parsed = validatePrReference(input.pr);
+    for (const operation of input.operations) {
         validateOperation(operation);
-    validatePrReference(input.pr);
+        if (operation.type === "merge" &&
+            operation.expectedStack !== undefined &&
+            parsed.number !== undefined &&
+            operation.expectedStack.prefix.at(-1)?.pr !== parsed.number)
+            throw new PrShepherdValidationError("expectedStack prefix must end at the requested PR");
+    }
 }
 function validateOperation(operation) {
     if (!operation || typeof operation !== "object") {
         throw new PrShepherdValidationError("apply operation must be an object");
     }
     switch (operation.type) {
+        case "merge":
+            try {
+                validateApplyMergeOptions(operation);
+            }
+            catch (error) {
+                throw new PrShepherdValidationError(error instanceof Error ? error.message : String(error));
+            }
+            return;
         case "review_mutations":
             validateReviewMutations(operation);
             return;
@@ -254,8 +290,10 @@ function validateReviewMutations(operation) {
     if (operation.message !== undefined && typeof operation.message !== "string") {
         throw new PrShepherdValidationError("review_mutations.message must be a string");
     }
-    if (operation.requireSha !== undefined && !/^[0-9a-f]{40}$/.test(operation.requireSha)) {
-        throw new PrShepherdValidationError("review_mutations.requireSha must be a full 40-character lowercase hex SHA");
+    if (operation.requireSha !== undefined &&
+        operation.requireSha !== "HEAD" &&
+        !/^[0-9a-f]{40}$/.test(operation.requireSha)) {
+        throw new PrShepherdValidationError("review_mutations.requireSha must be HEAD or a full 40-character lowercase hex SHA");
     }
 }
 function validateMarkFilesViewed(operation) {

package/bin/checks/classify.d.mts

@@ -21,6 +21,7 @@ import type { CheckRun, ClassifiedCheck } from "../types.mts";
  */
 export declare function classifyChecks(checks: CheckRun[], opts?: {
     additionalRelevantEvents?: string[];
+    requiredContexts?: readonly string[];
 }): ClassifiedCheck[];
 export interface CiVerdict {
     /** True when all relevant (non-filtered, non-skipped, non-ignored) checks passed. */

package/bin/checks/classify.mjs

@@ -30,7 +30,7 @@ export function classifyChecks(checks, opts = {}) {
     const isIgnored = buildMatcher(config.ignoreChecks ?? []);
     const isProtected = buildMatcher(config.actions.neverCancelRuns ?? []);
     const protectedRunIds = buildProtectedRunIds(checks, isProtected);
-    const supersededIndices = buildSupersededIndices(checks);
+    const supersededIndices = buildSupersededIndices(checks, opts.requiredContexts);
     return checks.map((c, index) => {
         if (isIgnored(c.name) && !isProtectedCheck(c, protectedRunIds)) {
             return { ...c, category: "ignored" };

package/bin/checks/conclusions.d.mts

@@ -4,8 +4,12 @@ import type { CheckConclusion, ViewerAuthorization } from "../types.mts";
  * (`actions: write`, which rides with push access). The rerun runs against the base
  * repo where the run lives, so `repositoryPermission` — not `headRepositoryPermission`,
  * which covers fork push access — is the right field to gate on.
+ *
+ * REST exposes no viewer capability fields, so on a REST snapshot an unknown role does not deny
+ * the rerun: the recommended `gh run rerun` is attempted and GitHub's response decides. A role
+ * GitHub did report still gates the rerun.
  */
-export declare function canRerunWorkflows(auth: ViewerAuthorization | undefined): boolean;
+export declare function canRerunWorkflows(auth: ViewerAuthorization | undefined, transport?: "rest"): boolean;
 /** Failing-check rows for formatter/instructions — excludes annotation-only carriers. */
 export declare function isFailingAgentCheck(check: {
     conclusion: CheckConclusion;

package/bin/checks/conclusions.mjs

@@ -6,10 +6,16 @@ const RERUN_CAPABLE_PERMISSIONS = new Set(["WRITE", "MAINTAIN", "ADMIN"]);
  * (`actions: write`, which rides with push access). The rerun runs against the base
  * repo where the run lives, so `repositoryPermission` — not `headRepositoryPermission`,
  * which covers fork push access — is the right field to gate on.
+ *
+ * REST exposes no viewer capability fields, so on a REST snapshot an unknown role does not deny
+ * the rerun: the recommended `gh run rerun` is attempted and GitHub's response decides. A role
+ * GitHub did report still gates the rerun.
  */
-export function canRerunWorkflows(auth) {
+export function canRerunWorkflows(auth, transport) {
     const permission = auth?.repositoryPermission;
-    return permission != null && RERUN_CAPABLE_PERMISSIONS.has(permission);
+    if (permission === undefined)
+        return transport === "rest";
+    return permission !== null && RERUN_CAPABLE_PERMISSIONS.has(permission);
 }
 /** True for conclusions that belong under `## Failing checks` (not success/skipped/neutral). */
 function isFailingCheckConclusion(conclusion) {

package/bin/checks/superseded.d.mts

@@ -3,6 +3,12 @@ import type { CheckRun } from "../types.mts";
 /**
  * A later-created run supersedes an older cancellation as before. GitHub can start
  * check jobs out of run-ID order, so a lower-ID run can also cover a cancellation
- * when its matching successful job actually started and completed later.
+ * when its matching successful job actually started and completed later. Cancelled
+ * wrappers can report completion before start; compare both observed boundaries
+ * without treating that reversed interval as a successful execution.
+ *
+ * The lower-ID form never covers a required context: GitHub's required gate reads the
+ * latest (highest-ID) run, so that cancellation still fails it (github/gh-stack#466).
+ * Neither does a newer run that lacks the context, for the same reason.
  */
-export declare function buildSupersededIndices(checks: CheckRun[]): Set<number>;
+export declare function buildSupersededIndices(checks: CheckRun[], requiredContexts?: readonly string[]): Set<number>;

package/bin/checks/superseded.mjs

@@ -17,7 +17,7 @@ function numericRunId(check) {
     const id = Number(check.runId);
     return Number.isSafeInteger(id) ? id : undefined;
 }
-function validTimes(check) {
+function validTimes(check, requireOrdered = true) {
     const { startedAtUnix: start, completedAtUnix: completion } = check;
     return (typeof start === "number" &&
         Number.isFinite(start) &&
@@ -25,14 +25,21 @@ function validTimes(check) {
         typeof completion === "number" &&
         Number.isFinite(completion) &&
         completion > 0 &&
-        completion >= start);
+        (!requireOrdered || completion >= start));
 }
 /**
  * A later-created run supersedes an older cancellation as before. GitHub can start
  * check jobs out of run-ID order, so a lower-ID run can also cover a cancellation
- * when its matching successful job actually started and completed later.
+ * when its matching successful job actually started and completed later. Cancelled
+ * wrappers can report completion before start; compare both observed boundaries
+ * without treating that reversed interval as a successful execution.
+ *
+ * The lower-ID form never covers a required context: GitHub's required gate reads the
+ * latest (highest-ID) run, so that cancellation still fails it (github/gh-stack#466).
+ * Neither does a newer run that lacks the context, for the same reason.
  */
-export function buildSupersededIndices(checks) {
+export function buildSupersededIndices(checks, requiredContexts = []) {
+    const required = new Set(requiredContexts.map((context) => context.trim()));
     const maxRunIdByGroup = new Map();
     const runIds = checks.map(numericRunId);
     checks.forEach((check, index) => {
@@ -52,14 +59,18 @@ export function buildSupersededIndices(checks) {
         const runId = runIds[index];
         if (group === undefined || runId === undefined)
             return;
+        const isRequired = required.has(cancelled.name.trim());
         if (maxRunIdByGroup.get(group) > runId) {
-            superseded.add(index);
+            // A required context is covered only by a newer run of the same context.
+            if (!isRequired || hasNewerSameName(checks, runIds, cancelled, group, runId))
+                superseded.add(index);
             return;
         }
-        if (cancelled.status !== "COMPLETED" ||
+        if (isRequired ||
+            cancelled.status !== "COMPLETED" ||
             !cancelled.workflowId ||
             cancelled.event === null ||
-            !validTimes(cancelled))
+            !validTimes(cancelled, false))
             return;
         const covered = checks.some((success, candidateIndex) => {
             const candidateRunId = runIds[candidateIndex];
@@ -81,3 +92,9 @@ export function buildSupersededIndices(checks) {
     });
     return superseded;
 }
+function hasNewerSameName(checks, runIds, cancelled, group, runId) {
+    return checks.some((check, index) => runIds[index] !== undefined &&
+        runIds[index] > runId &&
+        check.name.trim() === cancelled.name.trim() &&
+        groupKeyOf(check) === group);
+}

package/bin/classify/loader.d.mts

@@ -6,5 +6,7 @@ export interface LoadedRule {
 }
 export declare function discoverRuleFiles(cwd: string): string[];
 export declare function loadRules(files: string[]): Promise<LoadedRule[]>;
+/** Local `.pr-shepherd/classification/` rules followed by the enabled bundled rules. */
+export declare function loadClassifyRules(cwd: string, standardRuleNames?: readonly string[]): Promise<LoadedRule[]>;
 /** Reset the rule cache — for use in tests. */
 export declare function _resetRuleCache(): void;

package/bin/classify/loader.mjs

@@ -10,6 +10,7 @@ import { readdirSync, statSync } from "node:fs";
 import { join, dirname, extname, basename } from "node:path";
 import { homedir } from "node:os";
 import { pathToFileURL } from "node:url";
+import { STANDARD_RULES } from "./standard/index.mjs";
 const CLASSIFICATION_DIR = ".pr-shepherd/classification";
 const VALID_EXTENSIONS = new Set([".ts", ".mts", ".mjs", ".js"]);
 export function discoverRuleFiles(cwd) {
@@ -60,6 +61,20 @@ export async function loadRules(files) {
     ruleCache.set(cacheKey, rules);
     return rules;
 }
+/** Bundled rules enabled by `classify.standard`, named `standard:<rule>`. */
+function standardRules(names) {
+    return names.flatMap((name) => {
+        const rule = STANDARD_RULES[name];
+        return rule === undefined
+            ? []
+            : [{ name: `standard:${name}`, file: `pr-shepherd:standard/${name}`, rule }];
+    });
+}
+/** Local `.pr-shepherd/classification/` rules followed by the enabled bundled rules. */
+export async function loadClassifyRules(cwd, standardRuleNames = []) {
+    const local = await loadRules(discoverRuleFiles(cwd));
+    return [...local, ...standardRules(standardRuleNames)];
+}
 /** Reset the rule cache — for use in tests. */
 export function _resetRuleCache() {
     ruleCache.clear();

package/bin/classify/standard/author.d.mts

@@ -0,0 +1,3 @@
+import type { ClassifyItem, ClassifyItemKind } from "../types.mts";
+/** True when GitHub reports a bot author whose normalized login is one of `logins`. */
+export declare function isBotItem(item: ClassifyItem, logins: readonly string[], kinds: readonly ClassifyItemKind[]): boolean;

package/bin/classify/standard/author.mjs

@@ -0,0 +1,10 @@
+/** Lowercased login without the REST `[bot]` suffix, so GraphQL and REST logins compare equal. */
+function normalizeLogin(login) {
+    return login.toLowerCase().replace(/\[bot\]$/, "");
+}
+/** True when GitHub reports a bot author whose normalized login is one of `logins`. */
+export function isBotItem(item, logins, kinds) {
+    return (item.authorType === "Bot" &&
+        kinds.includes(item.kind) &&
+        logins.includes(normalizeLogin(item.author)));
+}

package/bin/classify/standard/codecov-report.d.mts

@@ -0,0 +1,4 @@
+import type { ClassifyRule } from "../types.mts";
+/** Codecov's coverage report comment. Coverage gates still report through their status checks. */
+declare const rule: ClassifyRule;
+export default rule;