pr-shepherd 0.13.1 → 0.14.1

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.13.1",
+  "version": "0.14.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -20,9 +20,9 @@ Example Workflow:
 
 `pr-shepherd` optimizes token management, rate limits, and agentic orchestration by moving **ALL** deterministic logic and prompts to code via a CLI tool, enshrining what would be a large skill or command prompt (of which the agent would inevitably make mistakes) into the code and returning a clear, actionable prompt.
 
-The CLI adapts monitor instructions to the calling agent. Claude Code gets `/loop` bootstrap instructions. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`; it gets a reusable `npx pr-shepherd <PR>` command and explicit goal-friendly iterate instructions because Codex does not provide `/loop` scheduling in this workflow.
+The CLI adapts monitor instructions to the calling agent. Claude Code gets `/loop` bootstrap instructions. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`; it gets a reusable pr-shepherd command and explicit goal-friendly iterate instructions because Codex does not provide `/loop` scheduling in this workflow. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, or `yarn`.
 
-At a high level, to start the monitor, the skill/command invokes a CLI that returns a prompt to be ingested by the agent _(schematic — paraphrased for brevity; actual output is more detailed)_:
+At a high level, to start the monitor, the skill/command invokes a CLI that returns a prompt to be ingested by the agent _(schematic — paraphrased for brevity; actual output is more detailed; examples use `npx` as the default spelling — a pnpm or yarn repo would emit `pnpm exec` or `yarn run` instead)_:
 
 ```
 /pr-shepherd:monitor
@@ -32,14 +32,14 @@ At a high level, to start the monitor, the skill/command invokes a CLI that retu
 # PR #123 [MONITOR]
 
 Loop tag: `#pr-shepherd-loop:pr=123:`
-Loop args: `4m`
 
 ## Loop prompt
 
 #pr-shepherd-loop:pr=123:
 
-**IMPORTANT — recurrence rules:** Do not call ScheduleWakeup or /loop. End the turn
-after completing the actions below. The cron job handles the next fire.
+**IMPORTANT — dynamic recurrence rules:** Do not invoke `/loop` again from inside
+this prompt. For nonterminal iterations, call `ScheduleWakeup` with `delaySeconds`
+between 60 and 240 and this same prompt body.
 
 Run in a single Bash call:
   npx pr-shepherd 123
@@ -48,11 +48,10 @@ Run in a single Bash call:
 
 ## Instructions
 
-1. Run `CronList`. If any job's prompt contains the loop tag, run the ## Loop prompt inline then stop.
-2. Otherwise, invoke the /loop skill with Loop args and the full ## Loop prompt body.
+1. Invoke the /loop skill with the full ## Loop prompt body and no fixed interval.
 ```
 
-Each iteration calls `npx pr-shepherd <PR>`, which provides actionable feedback directly to the agent:
+Each iteration calls `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
 
 ```
 > npx pr-shepherd 123
@@ -127,7 +126,7 @@ Some other workflow improvements:
 
 Recommendations:
 
-- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable `npx pr-shepherd <PR>` command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
 - Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
@@ -144,16 +143,15 @@ Recommendations:
 
 ### Monitor a PR
 
-In Claude Code, creates a cron loop that fires every 4 minutes, checks CI and review comments, fixes issues, and marks the PR ready for review when clean. The loop cancels automatically when the PR is merged or closed.
+In Claude Code, creates a fixed-interval loop (default every 4 minutes, configurable via `watch.interval`) that checks CI and review comments, fixes issues, and marks the PR ready for review when clean. The loop runs as a cron job that fires on schedule — agents end each turn cleanly and the cron fires again automatically. The loop stops automatically when the PR is merged or closed (auto-expires after 7 days).
 
-In Codex, run `npx pr-shepherd monitor <PR>` once to emit the goal-friendly recurrence prompt, then follow that prompt. Its reusable follow-up command is `npx pr-shepherd <PR>`.
+In Codex, run `pr-shepherd monitor <PR>` once through the repo package runner to emit the goal-friendly recurrence prompt, then follow that prompt. Its reusable follow-up command is emitted by the CLI.
 
 Claude Code:
 
 ```
 /pr-shepherd:monitor                     # infer PR from current branch
 /pr-shepherd:monitor 42
-/pr-shepherd:monitor 42 every 8m
 /pr-shepherd:monitor 42 --ready-delay 15m
 ```
 
@@ -193,13 +191,15 @@ See [docs/skills.md](docs/skills.md) for full argument reference.
 
 ## Iterate decision loop
 
-On each tick (4-minute default, tunable via `watch.interval`): fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, `wait`, or `cooldown`). See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
+On each dynamic tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, `wait`, or `cooldown`). Claude and Codex both choose a fresh wait between 1 and 4 minutes for each nonterminal recurrence. See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
 
 ## Install
 
-> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `npx pr-shepherd`, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so `npx` resolves it without prompting:
+> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `pr-shepherd` through the repo package runner, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so the selected runner resolves it without prompting:
 >
 > ```bash
+> pnpm add -D pr-shepherd      # pnpm repos
+> yarn add -D pr-shepherd      # yarn repos
 > npm install --save-dev pr-shepherd
 > ```
 >
@@ -252,6 +252,8 @@ After adding the marketplace, open the Codex plugin directory, choose the `jonat
 Install the CLI where Codex will run it:
 
 ```bash
+pnpm add -D pr-shepherd      # pnpm repos
+yarn add -D pr-shepherd      # yarn repos
 npm install --save-dev pr-shepherd
 ```
 
@@ -263,19 +265,21 @@ If your Codex environment does not already set `CODEX_CI=1`, set `AGENT=codex` s
 export AGENT=codex
 ```
 
-Then start a PR monitor from Codex:
+Then start a PR monitor from Codex with the target repository's package runner:
 
 ```bash
-npx pr-shepherd monitor 42
+<runner> pr-shepherd monitor 42
 ```
 
+For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd monitor 42`. For npm repos, use `npx --no-install pr-shepherd monitor 42`.
+
 Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. The monitor bootstrap runs one tick and prints the reusable follow-up command, usually:
 
 ```bash
-npx pr-shepherd 42
+<runner> pr-shepherd 42
 ```
 
-For an active Codex goal, rerun that command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `npx pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
+For an active Codex goal, rerun that command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
 
 ### Without the plugin
 

package/bin/cli/fix-formatter.mjs

@@ -7,6 +7,7 @@ export function formatFixCodeResult(header, result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
+    const runner = opts?.runner;
     const sections = [header];
     if (result.fix.threads.length > 0) {
         sections.push("## Review threads");
@@ -117,7 +118,7 @@ export function formatFixCodeResult(header, result, opts) {
     }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
-    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval)));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/formatters.mjs

@@ -108,7 +108,32 @@ export function formatMutateResult(result) {
         lines.push(`Minimized comments (${result.minimizedComments.length}): ${result.minimizedComments.join(", ")}`);
     if (result.dismissedReviews.length)
         lines.push(`Dismissed reviews (${result.dismissedReviews.length}): ${result.dismissedReviews.join(", ")}`);
-    if (result.errors.length)
-        lines.push(`Errors:\n  ${result.errors.join("\n  ")}`);
+    if (result.rateLimit) {
+        const details = [
+            result.rateLimit.retryAfterSeconds !== undefined
+                ? `retry after ${result.rateLimit.retryAfterSeconds}s`
+                : null,
+            result.rateLimit.remaining !== undefined && result.rateLimit.limit !== undefined
+                ? `remaining ${result.rateLimit.remaining}/${result.rateLimit.limit}`
+                : null,
+            result.rateLimit.resetAt !== undefined
+                ? `reset at ${new Date(result.rateLimit.resetAt * 1000).toISOString()}`
+                : null,
+        ]
+            .filter(Boolean)
+            .join(", ");
+        lines.push(`Stopped: GitHub rate limit hit — ${result.rateLimit.message}${details ? ` (${details})` : ""}`);
+    }
+    if (result.unresolvedThreads?.length)
+        lines.push(`Not resolved due to rate limit (${result.unresolvedThreads.length}): ${result.unresolvedThreads.join(", ")}`);
+    if (result.unminimizedComments?.length)
+        lines.push(`Not minimized due to rate limit (${result.unminimizedComments.length}): ${result.unminimizedComments.join(", ")}`);
+    if (result.undismissedReviews?.length)
+        lines.push(`Not dismissed due to rate limit (${result.undismissedReviews.length}): ${result.undismissedReviews.join(", ")}`);
+    const errors = result.rateLimit
+        ? result.errors.filter((e) => !e.startsWith("rate limit:"))
+        : result.errors;
+    if (errors.length)
+        lines.push(`Errors:\n  ${errors.join("\n  ")}`);
     return lines.join("\n");
 }

package/bin/cli/handlers.mjs

@@ -63,7 +63,12 @@ export async function handleIterate(args) {
         noAutoMarkReady,
         noAutoCancelActionable,
     });
-    const projectionOpts = { runtime, readyDelaySuffix, retryInterval: cfg.watch.interval };
+    const projectionOpts = {
+        runtime,
+        readyDelaySuffix,
+        retryInterval: cfg.watch.interval,
+        runner: cfg.cli?.runner,
+    };
     if (globalOpts.format === "json") {
         const output = globalOpts.verbose
             ? projectIterateVerbose(result, projectionOpts)
@@ -71,10 +76,8 @@ export async function handleIterate(args) {
         process.stdout.write(`${JSON.stringify(output)}\n`);
     }
     else {
-        process.stdout.write(`${formatIterateResult(result, {
-            verbose: globalOpts.verbose,
-            ...projectionOpts,
-        })}\n`);
+        const text = formatIterateResult(result, { verbose: globalOpts.verbose, ...projectionOpts });
+        process.stdout.write(`${text}\n`);
     }
     process.exitCode = iterateActionToExitCode(result.action);
 }

package/bin/cli/iterate-formatter.mjs

@@ -21,6 +21,7 @@ export function formatIterateResult(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
+    const runner = opts?.runner;
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
@@ -56,33 +57,38 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 verbose ? header : heading,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "wait":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "cancel":
             return joinSections([
                 [`${heading} — ${result.reason}`, "", baseLine, summaryLine].join("\n"),
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "escalate":
             return joinSections([
                 header,
                 result.escalate.humanMessage,
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
             ]);
         case "fix_code":
-            return formatFixCodeResult(header, result, { runtime, readyDelaySuffix, retryInterval });
+            return formatFixCodeResult(header, result, {
+                runtime,
+                readyDelaySuffix,
+                retryInterval,
+                runner,
+            });
     }
 }

package/bin/cli/iterate-instructions.mjs

@@ -1,48 +1,50 @@
 import { FIX_INSTRUCTION_END_ITERATION, FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
+import { buildPrShepherdCommand } from "./runner.mjs";
 const DEFAULT_CODEX_RETRY_INTERVAL = "4m";
 const VALID_RETRY_INTERVAL = /^\d+[smhd]$/;
-export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval) {
-    const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix);
+const CLAUDE_DYNAMIC_WAKEUP = "Schedule the next dynamic wakeup with `ScheduleWakeup` using `delaySeconds` between 60 and 240 and the same loop prompt (skip if running under a fixed-interval cron loop — the next scheduled fire handles it), then end this iteration.";
+export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner) {
+    const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix, runner);
     const retryDelay = buildCodexRetryDelay(retryInterval);
     switch (result.action) {
         case "cooldown":
             return [
                 runtime === "codex"
                     ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` after CI starts reporting.`
-                    : "End this iteration — the next cron fire will recheck once CI starts reporting.",
+                    : `CI still needs time to start reporting. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "wait":
             return [
                 runtime === "codex"
                     ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
-                    : "End this iteration — the next cron fire will recheck.",
+                    : CLAUDE_DYNAMIC_WAKEUP,
             ];
         case "mark_ready":
             return [
                 runtime === "codex"
                     ? `The CLI already marked the PR ready for review. Continue the active Codex goal until the ready-delay completes — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
-                    : "The CLI already marked the PR ready for review — end this iteration.",
+                    : `The CLI already marked the PR ready for review. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "cancel":
             return [
                 runtime === "codex"
                     ? "Stop — no recurring Codex monitor is running to cancel."
-                    : "Invoke `/loop cancel` via the Skill tool.",
+                    : `Stop — do not schedule another dynamic wakeup. If this loop was started with a fixed-interval \`/loop\` schedule, call \`CronList\`, find the job whose prompt contains \`#pr-shepherd-loop:pr=${result.pr}:\`, and cancel it with \`CronDelete\`.`,
                 "Stop.",
             ];
         case "escalate":
             return [
                 runtime === "codex"
                     ? "Stop — no recurring Codex monitor is running to cancel."
-                    : "Invoke `/loop cancel` via the Skill tool.",
+                    : `Stop — do not schedule another dynamic wakeup. If this loop was started with a fixed-interval \`/loop\` schedule, call \`CronList\`, find the job whose prompt contains \`#pr-shepherd-loop:pr=${result.pr}:\`, and cancel it with \`CronDelete\`.`,
                 "Stop — the PR needs human direction before monitoring can resume.",
             ];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, retryInterval) {
+export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, retryInterval, runner) {
     if (runtime !== "codex")
         return instructions;
-    const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix);
+    const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix, runner);
     const retryDelay = buildCodexRetryDelay(retryInterval);
     return instructions.map((instruction) => {
         if (instruction === FIX_INSTRUCTION_STOP_AFTER_PUSH) {
@@ -60,9 +62,11 @@ export function adaptIterateLog(log, runtime) {
         return log;
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
-export function buildCodexIterateCommand(pr, readyDelaySuffix) {
+export function buildCodexIterateCommand(pr, readyDelaySuffix, runner) {
     const suffix = readyDelaySuffix?.trim();
-    return `npx pr-shepherd ${pr}${suffix ? ` --ready-delay ${suffix}` : ""}`;
+    return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])], {
+        runner,
+    }).text;
 }
 export function buildCodexRetryDelay(retryInterval) {
     const interval = typeof retryInterval === "string" ? retryInterval.trim() : "";

package/bin/cli/iterate-lean.mjs

@@ -8,7 +8,8 @@ export function projectIterateLean(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
-    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, retryInterval);
+    const runner = opts?.runner;
+    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, retryInterval, runner);
     const base = {
         action: result.action,
         pr: result.pr,
@@ -101,7 +102,7 @@ export function projectIterateLean(result, opts) {
                     }),
                     resolveCommand: result.fix.resolveCommand,
                     ...(result.fix.instructions.length > 0 && {
-                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval),
+                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
                     }),
                 },
             };
@@ -134,12 +135,13 @@ export function projectIterateVerbose(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const retryInterval = opts?.retryInterval;
+    const runner = opts?.runner;
     if (result.action === "fix_code") {
         return {
             ...result,
             fix: {
                 ...result.fix,
-                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval),
+                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
             },
         };
     }
@@ -149,6 +151,6 @@ export function projectIterateVerbose(result, opts) {
     return {
         ...result,
         ...log,
-        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval),
+        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner),
     };
 }

package/bin/cli/runner.mjs

@@ -0,0 +1,109 @@
+import { readFileSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export function buildPrShepherdCommand(args, opts) {
+    const runner = resolveCliRunner(opts.runner, opts.cwd);
+    const argv = baseArgvForRunner(runner).concat(args);
+    return { argv, text: renderShellCommand(argv) };
+}
+export function resolveCliRunner(runner, cwd = process.cwd()) {
+    const configured = parseCliRunner(runner);
+    return configured === "auto" ? detectPackageRunner(cwd) : configured;
+}
+export function parseCliRunner(runner) {
+    if (runner === undefined)
+        return "auto";
+    if (typeof runner !== "string") {
+        throw new Error(`Invalid config: cli.runner must be one of "auto", "npx", "pnpm", or "yarn", got ${JSON.stringify(runner)}`);
+    }
+    const value = runner.trim();
+    if (value === "auto" || value === "npx" || value === "pnpm" || value === "yarn")
+        return value;
+    throw new Error(`Invalid config: cli.runner must be one of "auto", "npx", "pnpm", or "yarn", got ${JSON.stringify(runner)}`);
+}
+export function renderShellCommand(argv) {
+    return argv.map(renderShellArg).join(" ");
+}
+function baseArgvForRunner(runner) {
+    switch (runner) {
+        case "npx":
+            return ["npx", "pr-shepherd"];
+        case "pnpm":
+            return ["pnpm", "exec", "pr-shepherd"];
+        case "yarn":
+            return ["yarn", "run", "pr-shepherd"];
+    }
+}
+const runnerCache = new Map();
+export function __resetRunnerCache() {
+    runnerCache.clear();
+}
+function detectPackageRunner(startDir) {
+    const cached = runnerCache.get(startDir);
+    if (cached)
+        return cached;
+    const home = homedir();
+    const repoRoot = findRepoRoot(startDir);
+    let current = startDir;
+    while (true) {
+        const atBoundary = current === repoRoot || current === home || current === dirname(current);
+        // Read signals for this directory unless it is home without being the repo root.
+        // This lets dotfiles repos (repoRoot === home) detect their own package manager
+        // while still preventing home's lockfiles from influencing unrelated projects.
+        if (!atBoundary || current === repoRoot) {
+            const packageManager = readPackageManager(current);
+            if (packageManager?.startsWith("pnpm@"))
+                return cacheRunner(startDir, "pnpm");
+            if (packageManager?.startsWith("yarn@"))
+                return cacheRunner(startDir, "yarn");
+            if (packageManager?.startsWith("npm@"))
+                return cacheRunner(startDir, "npx");
+            if (isFile(join(current, "pnpm-lock.yaml")))
+                return cacheRunner(startDir, "pnpm");
+            if (isFile(join(current, "yarn.lock")))
+                return cacheRunner(startDir, "yarn");
+            if (isFile(join(current, "package-lock.json")))
+                return cacheRunner(startDir, "npx");
+        }
+        if (atBoundary)
+            return cacheRunner(startDir, "npx");
+        current = dirname(current);
+    }
+}
+function cacheRunner(startDir, runner) {
+    runnerCache.set(startDir, runner);
+    return runner;
+}
+function readPackageManager(packageDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+        return typeof parsed.packageManager === "string" ? parsed.packageManager.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+function findRepoRoot(startDir) {
+    let current = startDir;
+    while (true) {
+        if (statSync(join(current, ".git"), { throwIfNoEntry: false }))
+            return current;
+        if (current === dirname(current))
+            return null;
+        current = dirname(current);
+    }
+}
+function isFile(path) {
+    return statSync(path, { throwIfNoEntry: false })?.isFile() === true;
+}
+function renderShellArg(arg) {
+    if (/^\$[A-Z_][A-Z0-9_]*$/.test(arg))
+        return `"${arg}"`;
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg))
+        return arg;
+    if (!/["$`\\]/.test(arg))
+        return `"${arg}"`;
+    if (!arg.includes("'"))
+        return `'${arg}'`;
+    throw new Error(`Unexpected character in shell arg: ${JSON.stringify(arg)}`);
+}

package/bin/cli-parser.mjs

@@ -31,6 +31,7 @@ import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
 import { handleCommitSuggestion, handleIterate, handleMonitor, handleStatus, } from "./cli/handlers.mjs";
 import { setupLog } from "./log/setup.mjs";
 import { detectAgentRuntime } from "./agent-runtime.mjs";
+import { loadConfig } from "./config/load.mjs";
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
@@ -92,10 +93,11 @@ function readVersion() {
 async function handleCheck(args) {
     const { prNumber, global: globalOpts } = parseCommonArgs(args);
     const runtime = detectAgentRuntime();
+    const cfg = loadConfig();
     const report = await runCheck({ ...globalOpts, prNumber, autoResolve: false });
     const output = globalOpts.format === "json"
-        ? formatJson(report, { runtime })
-        : formatText(report, { runtime });
+        ? formatJson(report, { runtime, runner: cfg.cli?.runner })
+        : formatText(report, { runtime, runner: cfg.cli?.runner });
     process.stdout.write(`${output}\n`);
     process.exitCode = statusToExitCode(report.status);
 }

package/bin/commands/commit-suggestion.mjs

@@ -5,6 +5,8 @@ import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/cli
 import { fetchPrBatch } from "../github/batch.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
 const execFile = promisify(execFileCb);
 export async function runCommitSuggestion(opts) {
     if (!opts.threadId) {
@@ -91,11 +93,12 @@ export async function runCommitSuggestion(opts) {
         `-m ${sq(commitMessageArg)}`,
         ...commitBodyArg.split("\n\n").map((p) => `-m ${sq(p)}`),
     ].join(" ");
+    const resolveCommand = buildPrShepherdCommand(["resolve", String(prNumber), "--resolve-thread-ids", opts.threadId], { runner: loadConfig().cli?.runner }).text;
     const postActionInstructions = [
         `Apply the patch to \`${filePath}\`: run \`git apply\` with the diff shown above, or edit the file directly using the line range (${range}).`,
         `Stage the file: \`git add -- ${quotedPath}\``,
         `Commit: \`${commitCmd}\``,
-        `Resolve the thread on GitHub: \`npx pr-shepherd resolve ${prNumber} --resolve-thread-ids ${opts.threadId}\``,
+        `Resolve the thread on GitHub: \`${resolveCommand}\``,
         `Push when ready: \`git push\` (or \`git push --force-with-lease\` after rebasing).`,
     ];
     return {

package/bin/commands/iterate/classify.mjs

@@ -1,3 +1,4 @@
+import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
     // First-look and seen summaries go into the minimize mutation; edited summaries do NOT —
     // they are already minimized server-side (body changed after minimize was applied).
@@ -20,8 +21,8 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals)
         surfacedApprovals: approvals,
     };
 }
-export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber) {
-    const argv = ["npx", "pr-shepherd", "resolve", String(prNumber)];
+export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, reviews, checks, prNumber, runner) {
+    const argv = buildPrShepherdCommand(["resolve", String(prNumber)], { runner }).argv;
     const threadIds = [...threads.map((t) => t.id), ...resolutionOnlyThreads.map((t) => t.id)];
     if (threadIds.length > 0) {
         argv.push("--resolve-thread-ids", threadIds.join(","));

package/bin/commands/iterate/fix-code.mjs

@@ -6,7 +6,7 @@ import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildInProgressRunIds } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, cliRunner, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
@@ -57,7 +57,7 @@ export async function handleFixCode(ctx) {
         ? buildInProgressRunIds(report, cancelledSet)
         : [];
     const allCommentIds = [...actionableComments.map((c) => c.id), ...reviewSummaryIds];
-    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber);
+    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, cliRunner);
     if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
@@ -77,7 +77,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, cliRunner);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/index.mjs

@@ -117,6 +117,7 @@ export async function runIterate(opts) {
             firstLookSummaries,
             editedSummaries,
             surfacedApprovals,
+            cliRunner: config.cli?.runner,
         });
     }
     const canMarkReady = report.status === "READY" &&