pr-shepherd 0.13.1 → 0.14.1

package/bin/commands/iterate/render.mjs

@@ -1,34 +1,36 @@
+import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
 export const FIX_INSTRUCTION_STOP_AFTER_PUSH = "Stop this iteration — CI needs time to run on the new push before the next tick.";
 export const FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK = "Stop this iteration before the next tick.";
 export const FIX_INSTRUCTION_END_ITERATION = "End this iteration.";
 /**
- * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE` and whitespace-bearing
- * argv entries in double quotes for placeholder substitution. Throws if argv contains `"`, `$`,
- * `` ` ``, or `\`. `$HEAD_SHA` is appended separately when `requiresHeadSha` is set.
+ * Render a resolve command as a shell snippet. Wraps `$DISMISS_MESSAGE`, `$HEAD_SHA`, and
+ * whitespace-bearing argv entries for placeholder substitution. `$HEAD_SHA` is appended separately
+ * when `requiresHeadSha` is set.
  */
 export function renderResolveCommand(rc) {
-    const needsQuoting = (arg) => {
-        if (arg === "$DISMISS_MESSAGE")
-            return true;
-        if (/["$`\\]/.test(arg)) {
-            throw new Error(`Unexpected character in argv arg that needsQuoting can't handle: ${JSON.stringify(arg)}`);
-        }
-        return /\s/.test(arg);
-    };
-    const parts = rc.argv.map((a) => (needsQuoting(a) ? `"${a}"` : a));
+    const parts = [...rc.argv];
     if (rc.requiresHeadSha) {
-        parts.push("--require-sha", '"$HEAD_SHA"');
+        parts.push("--require-sha", "$HEAD_SHA");
     }
-    return parts.join(" ");
+    return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
     const instructions = [];
     if (inProgressRunIds.length > 0) {
         instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\`. Do this before applying any code fixes — the push at the end of this iteration will supersede those runs anyway, so letting them continue burns CI minutes for results no one will read. If \`gh\` reports a run is already completed, ignore it and continue with the next ID.`);
     }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
-        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the \`resolve:\` command below (the thread is not auto-resolved). If the patch fails to apply, fall through to the manual-edit step. Do not retry the same command.`);
+        const commitSuggestionCommand = buildPrShepherdCommand([
+            "commit-suggestion",
+            String(prNumber),
+            "--thread-id",
+            "<id>",
+            "--message",
+            "<one-sentence headline>",
+            "--format=json",
+        ], { runner }).text;
+        instructions.push(`For each thread marked \`[suggestion]\` under \`## Review threads\`: run \`${commitSuggestionCommand}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the \`resolve:\` command below (the thread is not auto-resolved). If the patch fails to apply, fall through to the manual-edit step. Do not retry the same command.`);
     }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions

package/bin/commands/monitor.mjs

@@ -1,6 +1,7 @@
 import { getCurrentPrNumber } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { joinSections } from "../util/markdown.mjs";
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 export async function runMonitor(opts) {
     const config = loadConfig();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -18,8 +19,8 @@ export async function runMonitor(opts) {
     // block depend on this exact string — don't change the format.
     const loopTag = `#pr-shepherd-loop:pr=${prNumber}:`;
     const loopArgs = interval;
-    const reusableCommand = buildIterateCommand(prNumber, opts.readyDelaySuffix);
-    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, loopArgs, opts.runtime ?? "claude");
+    const reusableCommand = buildIterateCommand(prNumber, opts.readyDelaySuffix, config.cli?.runner);
+    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, loopArgs, opts.runtime ?? "claude", config.cli?.runner);
     return {
         prNumber,
         loopTag,
@@ -72,11 +73,11 @@ function validateReadyDelaySuffix(readyDelaySuffix) {
     }
     return trimmed;
 }
-function buildIterateCommand(prNumber, readyDelaySuffix) {
+function buildIterateCommand(prNumber, readyDelaySuffix, runner) {
     const validatedDelay = validateReadyDelaySuffix(readyDelaySuffix);
-    return `npx pr-shepherd ${prNumber}${validatedDelay ? ` --ready-delay ${validatedDelay}` : ""}`;
+    return buildPrShepherdCommand([String(prNumber), ...(validatedDelay ? ["--ready-delay", validatedDelay] : [])], { runner }).text;
 }
-function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "claude") {
+function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "claude", runner) {
     if (runtime === "codex") {
         return [
             loopTag,
@@ -85,7 +86,7 @@ function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "cla
             "- Run the command below once and follow its `## Instructions` exactly.",
             `- If the output tells you to continue the active Codex goal, wait about the configured interval (${loopArgs}) and rerun the reusable command from the monitor output.`,
             "- Stop only when Shepherd emits `[CANCEL]` because the ready-delay completed or the PR was merged/closed, or when Shepherd emits `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).",
-            "- Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `npx pr-shepherd monitor`; Codex recurrence is explicit `iterate` command cycles.",
+            `- Do not call \`/loop\`, \`ScheduleWakeup\`, \`CronCreate\`, or \`${buildPrShepherdCommand(["monitor", String(prNumber)], { runner }).text}\`; Codex recurrence is explicit \`iterate\` command cycles.`,
             "",
             "Run in a single Bash call:",
             `  ${iterateCmd}`,

package/bin/commands/resolve-instructions.mjs

@@ -1,9 +1,10 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
  * Build the numbered triage/fix/resolve instruction steps for the agent to follow.
  * Steps are conditionally emitted based on what the fetch returned (mirrors
  * `buildFixInstructions` in `commands/iterate/render.mts`).
  */
-export function buildFetchInstructions(prNumber, result) {
+export function buildFetchInstructions(prNumber, result, runner) {
     const { actionableThreads, resolutionOnlyThreads, firstLookThreads, actionableComments, firstLookComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     const total = actionableThreads.length +
@@ -30,7 +31,16 @@ export function buildFetchInstructions(prNumber, result) {
         instructions.push(`First-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
     }
     if (hasSuggestions) {
-        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
+        const commitSuggestionCommand = buildPrShepherdCommand([
+            "commit-suggestion",
+            String(prNumber),
+            "--thread-id",
+            "<id>",
+            "--message",
+            "<one-sentence headline>",
+            "--format=json",
+        ], { runner }).text;
+        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`${commitSuggestionCommand}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
     }
     if (hasCodeItems) {
         instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);
@@ -50,7 +60,10 @@ export function buildFetchInstructions(prNumber, result) {
         : reviewSummaries.length > 0
             ? ` Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`.`
             : "";
-    instructions.push(`Run \`npx pr-shepherd resolve ${prNumber} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
+    const resolveCommand = `${buildPrShepherdCommand(["resolve", String(prNumber)], {
+        runner,
+    }).text} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]`;
+    instructions.push(`Run \`${resolveCommand}\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
     instructions.push(`For any large decisions or rejections you made this iteration, add or update a \`## Shepherd Journal\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision. For threads and comments, use the markdown link shown in each item's bullet above; for reviews, reference the review ID.`);
     instructions.push(`Report: echo the CLI's mutation output, then one line per Acknowledged item: \`Acknowledged <id> (@<author>): <reason>\`. If any fetched item was neither resolved nor acknowledged, stop and escalate: "<N> item(s) fetched but not acted on or acknowledged — need human direction before closing".`);
     return instructions;

package/bin/commands/resolve.mjs

@@ -126,7 +126,7 @@ export async function runResolveFetch(opts) {
         reviewSummaries: cfg.resolve.fetchReviewSummaries ? data.reviewSummaries : [],
         commitSuggestionsEnabled: cfg.actions.commitSuggestions,
     };
-    return { ...result, instructions: buildFetchInstructions(prNumber, result) };
+    return { ...result, instructions: buildFetchInstructions(prNumber, result, cfg.cli?.runner) };
 }
 export async function runResolveMutate(opts) {
     const repo = await getRepoInfo();

package/bin/comments/pending-ops.mjs

@@ -0,0 +1,20 @@
+export function setPendingOps(result, ops) {
+    const resolved = new Set(result.resolvedThreads);
+    const minimized = new Set(result.minimizedComments);
+    const dismissed = new Set(result.dismissedReviews);
+    const unresolvedThreads = ops
+        .filter((op) => op.kind === "r" && !resolved.has(op.id))
+        .map((op) => op.id);
+    const unminimizedComments = ops
+        .filter((op) => op.kind === "m" && !minimized.has(op.id))
+        .map((op) => op.id);
+    const undismissedReviews = ops
+        .filter((op) => op.kind === "d" && !dismissed.has(op.id))
+        .map((op) => op.id);
+    if (unresolvedThreads.length > 0)
+        result.unresolvedThreads = unresolvedThreads;
+    if (unminimizedComments.length > 0)
+        result.unminimizedComments = unminimizedComments;
+    if (undismissedReviews.length > 0)
+        result.undismissedReviews = undismissedReviews;
+}

package/bin/comments/rate-limit.mjs

@@ -0,0 +1,45 @@
+export function rateLimitFromError(err, fallbackMessage) {
+    const maybe = err;
+    const message = err instanceof Error ? err.message : fallbackMessage;
+    const status = finiteNumber(maybe.status);
+    const hasRateLimitStatus = status === 403 || status === 429;
+    if (!isRateLimitMessage(message) &&
+        !(hasRateLimitStatus && maybe.retryAfterSeconds !== undefined) &&
+        maybe.rateLimit?.remaining !== 0)
+        return null;
+    return buildRateLimitStop(message, {
+        rateLimit: maybe.rateLimit,
+        retryAfterSeconds: maybe.retryAfterSeconds,
+    });
+}
+export function rateLimitFromGraphQlResult(messages, meta) {
+    const message = messages.find(isRateLimitMessage);
+    if (message)
+        return buildRateLimitStop(message, meta);
+    if (meta.stopOnZeroRemaining === true && meta.rateLimit?.remaining === 0) {
+        return buildRateLimitStop("GitHub GraphQL rate limit remaining is 0", meta);
+    }
+    return undefined;
+}
+function buildRateLimitStop(message, meta) {
+    const stop = { message };
+    const retryAfterSeconds = finiteNumber(meta.retryAfterSeconds);
+    const remaining = finiteNumber(meta.rateLimit?.remaining);
+    const limit = finiteNumber(meta.rateLimit?.limit);
+    const resetAt = finiteNumber(meta.rateLimit?.resetAt);
+    if (retryAfterSeconds !== undefined)
+        stop.retryAfterSeconds = retryAfterSeconds;
+    if (limit !== undefined)
+        stop.limit = limit;
+    if (remaining !== undefined)
+        stop.remaining = remaining;
+    if (resetAt !== undefined)
+        stop.resetAt = resetAt;
+    return stop;
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+export function isRateLimitMessage(message) {
+    return /rate limit|rate-limit|secondary limit|secondary rate/i.test(message);
+}

package/bin/comments/resolve.mjs

@@ -1,5 +1,7 @@
-import { graphql, getPrHeadSha } from "../github/client.mjs";
-import { loadConfig } from "../config/load.mjs";
+import { graphqlWithRateLimit } from "../github/client.mjs";
+import { isRateLimitMessage, rateLimitFromError, rateLimitFromGraphQlResult, } from "./rate-limit.mjs";
+import { setPendingOps } from "./pending-ops.mjs";
+import { waitForSha } from "./sha-poll.mjs";
 export async function applyResolveOptions(pr, repo, opts) {
     if ((opts.dismissReviewIds?.length ?? 0) > 0 && !opts.dismissMessage) {
         throw new Error("--message is required when dismissing reviews");
@@ -28,8 +30,8 @@ export async function autoResolveOutdated(threadIds) {
     await bulkApply(threadIds, [], [], "", result);
     return { resolved: result.resolvedThreads, errors: result.errors };
 }
-// Chunk at 50 so a single oversized list never fails the entire call.
-const BULK_CHUNK_SIZE = 50;
+// Keep mutation batches small so rate-limit stops leave a precise pending list.
+const BULK_CHUNK_SIZE = 10;
 function buildBulkMutation(resolveIds, minimizeIds, dismissIds, dismissMessage) {
     const ops = [];
     for (let i = 0; i < resolveIds.length; i++) {
@@ -52,70 +54,72 @@ async function bulkApply(resolveIds, minimizeIds, dismissIds, dismissMessage, re
     for (let i = 0; i < allOps.length; i += BULK_CHUNK_SIZE) {
         const chunk = allOps.slice(i, i + BULK_CHUNK_SIZE);
         // eslint-disable-next-line no-await-in-loop
-        await bulkApplyChunk(chunk.filter((o) => o.kind === "r").map((o) => o.id), chunk.filter((o) => o.kind === "m").map((o) => o.id), chunk.filter((o) => o.kind === "d").map((o) => o.id), dismissMessage, result);
+        const stopped = await bulkApplyChunk(chunk.filter((o) => o.kind === "r").map((o) => o.id), chunk.filter((o) => o.kind === "m").map((o) => o.id), chunk.filter((o) => o.kind === "d").map((o) => o.id), dismissMessage, result, i + BULK_CHUNK_SIZE < allOps.length);
+        if (stopped) {
+            setPendingOps(result, allOps.slice(i));
+            return;
+        }
     }
 }
-async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessage, result) {
+async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessage, result, hasPendingAfter) {
     if (resolveIds.length === 0 && minimizeIds.length === 0 && dismissIds.length === 0)
-        return;
+        return false;
     const doc = buildBulkMutation(resolveIds, minimizeIds, dismissIds, dismissMessage);
     let data;
+    let rateLimitStop;
+    let suppressCurrentChunkErrors = false;
     try {
-        const resp = await graphql(doc, {});
+        const resp = await graphqlWithRateLimit(doc, {});
         data = resp.data;
+        const graphQlErrorMessages = resp.errors?.map((e) => e.message) ?? [];
+        suppressCurrentChunkErrors = graphQlErrorMessages.some(isRateLimitMessage);
+        rateLimitStop = rateLimitFromGraphQlResult(graphQlErrorMessages, {
+            rateLimit: resp.rateLimit,
+            retryAfterSeconds: resp.retryAfterSeconds,
+            stopOnZeroRemaining: hasPendingAfter,
+        });
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        const stop = rateLimitFromError(err, msg);
+        if (stop) {
+            result.errors.push(`rate limit: ${stop.message}`);
+            result.rateLimit = stop;
+            return true;
+        }
         for (const id of resolveIds)
             result.errors.push(`${id}: ${msg}`);
         for (const id of minimizeIds)
             result.errors.push(`${id}: ${msg}`);
         for (const id of dismissIds)
             result.errors.push(`${id}: ${msg}`);
-        return;
+        return false;
     }
     for (let i = 0; i < resolveIds.length; i++) {
         const r = data[`r${i}`];
         if (r?.thread?.isResolved === true)
             result.resolvedThreads.push(resolveIds[i]);
-        else
+        else if (!suppressCurrentChunkErrors)
             result.errors.push(`${resolveIds[i]}: resolve returned null or thread not resolved`);
     }
     for (let i = 0; i < minimizeIds.length; i++) {
         const m = data[`m${i}`];
         if (m?.minimizedComment?.isMinimized === true)
             result.minimizedComments.push(minimizeIds[i]);
-        else
+        else if (!suppressCurrentChunkErrors)
             result.errors.push(`${minimizeIds[i]}: minimize returned null or comment not minimized`);
     }
     for (let i = 0; i < dismissIds.length; i++) {
         const d = data[`d${i}`];
         if (d?.pullRequestReview != null)
             result.dismissedReviews.push(dismissIds[i]);
-        else
+        else if (!suppressCurrentChunkErrors)
             result.errors.push(`${dismissIds[i]}: dismiss returned null`);
     }
-}
-async function waitForSha(pr, repo, expectedSha) {
-    const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
-    for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
-        try {
-            // eslint-disable-next-line no-await-in-loop
-            const currentSha = await getPrHeadSha(pr, repo.owner, repo.name);
-            if (currentSha === expectedSha)
-                return;
-        }
-        catch (err) {
-            if (attempt === SHA_POLL_MAX_ATTEMPTS - 1)
-                throw err;
-        }
-        if (attempt < SHA_POLL_MAX_ATTEMPTS - 1) {
-            // eslint-disable-next-line no-await-in-loop
-            await sleep(SHA_POLL_INTERVAL_MS);
-        }
+    if (rateLimitStop) {
+        result.errors.push(`rate limit: ${rateLimitStop.message}`);
+        result.rateLimit = rateLimitStop;
+        return true;
     }
-    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return false;
 }

package/bin/comments/sha-poll.mjs

@@ -0,0 +1,25 @@
+import { getPrHeadSha } from "../github/client.mjs";
+import { loadConfig } from "../config/load.mjs";
+export async function waitForSha(pr, repo, expectedSha) {
+    const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
+    for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const currentSha = await getPrHeadSha(pr, repo.owner, repo.name);
+            if (currentSha === expectedSha)
+                return;
+        }
+        catch (err) {
+            if (attempt === SHA_POLL_MAX_ATTEMPTS - 1)
+                throw err;
+        }
+        if (attempt < SHA_POLL_MAX_ATTEMPTS - 1) {
+            // eslint-disable-next-line no-await-in-loop
+            await sleep(SHA_POLL_INTERVAL_MS);
+        }
+    }
+    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/bin/config/load.mjs

@@ -3,6 +3,7 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
+import { parseCliRunner } from "../cli/runner.mjs";
 const RC_FILENAME = ".pr-shepherdrc.yml";
 function findRcFile(startDir) {
     const home = homedir();
@@ -51,6 +52,15 @@ export function loadConfig() {
         const raw = readFileSync(rcPath, "utf8");
         const parsed = (parse(raw) ?? {});
         const config = deepMerge(defaults, parsed);
+        // Validate cli and watch at load time so misconfigurations are caught once
+        // with the rc file path in context, rather than during instruction rendering.
+        if (config.cli === null || Array.isArray(config.cli) || typeof config.cli !== "object") {
+            throw new Error(`Invalid config: cli must be a plain object, got ${JSON.stringify(config.cli)}`);
+        }
+        config.cli.runner = parseCliRunner(config.cli.runner);
+        if (typeof config.watch?.interval !== "string" || !/^\d+[smhd]$/.test(config.watch.interval)) {
+            throw new Error(`Invalid config: watch.interval must be a duration string like "4m" or "1h", got ${JSON.stringify(config.watch?.interval)}`);
+        }
         configCache.set(cwd, config);
         return config;
     }

package/bin/config.json

@@ -1,4 +1,7 @@
 {
+  "cli": {
+    "runner": "auto"
+  },
   "iterate": {
     "cooldownSeconds": 30,
     "fixAttemptsPerThread": 3,

package/bin/github/client.mjs

@@ -7,8 +7,9 @@
  */
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
-import { graphql as httpGraphql, rest } from "./http.mjs";
+import { graphql as httpGraphql, rest, GitHubRequestError, } from "./http.mjs";
 import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY } from "./queries.mjs";
+export { GitHubRequestError };
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
 // GraphQL — thin re-exports so callers don't need to import http.mts directly

package/bin/github/errors.mjs

@@ -0,0 +1,12 @@
+export class GitHubRequestError extends Error {
+    status;
+    rateLimit;
+    retryAfterSeconds;
+    constructor(message, opts) {
+        super(message);
+        this.name = "GitHubRequestError";
+        this.status = opts.status;
+        this.rateLimit = opts.rateLimit;
+        this.retryAfterSeconds = opts.retryAfterSeconds;
+    }
+}

package/bin/github/http.mjs

@@ -2,6 +2,8 @@ import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+export { GitHubRequestError };
 const execFile = promisify(execFileCb);
 const BASE_URL = "https://api.github.com";
 // ---------------------------------------------------------------------------
@@ -105,6 +107,7 @@ async function graphqlInner(query, vars) {
     });
     const durationMs = Math.round(performance.now() - retryT0);
     const rateLimit = parseRateLimit(res.headers);
+    const retryAfterSeconds = parseRetryAfter(res.headers);
     if (!res.ok) {
         const body = await res.text();
         appendEntry(formatResponseEntry({
@@ -117,7 +120,7 @@ async function graphqlInner(query, vars) {
             textBody: redactToken(body),
             attempt: attempt > 1 ? attempt : undefined,
         }));
-        throw new Error(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`);
+        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, { status: res.status, rateLimit: rateLimit ?? undefined, retryAfterSeconds });
     }
     const parsed = (await res.json());
     appendEntry(formatResponseEntry({
@@ -132,21 +135,25 @@ async function graphqlInner(query, vars) {
     }));
     if (parsed.data == null) {
         const messages = (parsed.errors ?? []).map((e) => e.message).join("; ");
-        throw new Error(`GitHub GraphQL error (no data): ${messages}`);
+        throw new GitHubRequestError(`GitHub GraphQL error (no data): ${messages}`, {
+            status: res.status,
+            rateLimit: rateLimit ?? undefined,
+            retryAfterSeconds,
+        });
     }
     if (parsed.errors?.length) {
         const messages = parsed.errors.map((e) => e.message).join("; ");
         process.stderr.write(`pr-shepherd: GraphQL non-fatal errors: ${messages}\n`);
     }
-    return { data: parsed.data, rateLimit };
+    return { data: parsed.data, rateLimit, retryAfterSeconds, errors: parsed.errors };
 }
 export async function graphql(query, vars = {}) {
     const { data } = await graphqlInner(query, vars);
     return { data };
 }
 export async function graphqlWithRateLimit(query, vars = {}) {
-    const { data, rateLimit } = await graphqlInner(query, vars);
-    return { data, rateLimit: rateLimit ?? undefined };
+    const { data, rateLimit, retryAfterSeconds, errors } = await graphqlInner(query, vars);
+    return { data, rateLimit: rateLimit ?? undefined, retryAfterSeconds, errors };
 }
 // ---------------------------------------------------------------------------
 // REST
@@ -305,3 +312,8 @@ function parseRateLimit(headers) {
     }
     return null;
 }
+function parseRetryAfter(headers) {
+    const raw = headers.get("retry-after");
+    const seconds = Number(raw);
+    return raw !== null && Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
+}

package/bin/reporters/check-instructions.mjs

@@ -1,3 +1,4 @@
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
  * Build the numbered instruction steps for the agent to follow after a `check` run.
  * All rebase policy, CI budget policy, and ready-to-merge gating live here so the
@@ -59,7 +60,7 @@ export function buildCheckInstructions(report, opts) {
     // 5. Continuous monitoring pointer (suppressed only when truly ready to merge)
     if (!isReady) {
         instructions.push(runtime === "codex"
-            ? `This is a one-shot check. For follow-up monitoring, run \`npx pr-shepherd ${report.pr}\`.`
+            ? `This is a one-shot check. For follow-up monitoring, run \`${buildPrShepherdCommand([String(report.pr)], { runner: opts?.runner }).text}\`.`
             : "This is a one-shot check. For continuous monitoring that acts on these signals automatically, use `/pr-shepherd:monitor`.");
     }
     return instructions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -29,7 +29,7 @@
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
-    "oxfmt": "^0.46.0",
+    "oxfmt": "^0.47.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4"

package/plugin/skills/check/SKILL.md

@@ -25,9 +25,11 @@ allowed-tools: ["Bash"]
    If `MERGED`, output: `PR #N is already merged. Nothing to check.` and skip.
 
 3. **Run the check and follow instructions:**
+   Use the repository package runner selected by `packageManager` or lockfile
+   (for example, `pnpm exec`, `yarn run`, or `npx --no-install`).
 
    ```bash
-   npx pr-shepherd check <N>
+   <runner> pr-shepherd check <N>
    ```
 
    Print the full output. Follow the `## Instructions` section exactly.

package/plugin/skills/monitor/SKILL.md

@@ -4,7 +4,18 @@ description: "Start continuous CI monitoring — marks PR ready for review when
 argument-hint: "[PR number or URL]"
 user-invocable: true
 allowed-tools:
-  ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill", "CronCreate", "CronList", "CronDelete"]
+  [
+    "Bash",
+    "Read",
+    "Grep",
+    "Edit",
+    "Write",
+    "Glob",
+    "Skill",
+    "ScheduleWakeup",
+    "CronList",
+    "CronDelete",
+  ]
 ---
 
 # pr-shepherd monitor — Continuous PR Monitor
@@ -19,9 +30,11 @@ allowed-tools:
    - If no PR found, report an error and stop.
 
 2. **Run the bootstrap command and follow its instructions:**
+   Use the repository package runner selected by `packageManager` or lockfile
+   (for example, `pnpm exec`, `yarn run`, or `npx --no-install`).
 
    ```bash
-   npx pr-shepherd monitor <PR_NUMBER>
+   <runner> pr-shepherd monitor <PR_NUMBER>
    ```
 
    Print the full output. Follow the `## Instructions` section exactly.

package/plugin/skills/resolve/SKILL.md

@@ -28,9 +28,11 @@ Resolve unresolved review threads and minimize PR comments on the current PR —
    If `MERGED`, invoke `/loop cancel` via the Skill tool, output a merged message, and stop.
 
 3. **Fetch and follow instructions:**
+   Use the repository package runner selected by `packageManager` or lockfile
+   (for example, `pnpm exec`, `yarn run`, or `npx --no-install`).
 
    ```bash
-   npx pr-shepherd resolve <N> --fetch
+   <runner> pr-shepherd resolve <N> --fetch
    ```
 
    Print the full output. Follow the `## Instructions` section exactly.

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

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