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

package/README.md

@@ -198,6 +198,8 @@ On each dynamic tick: fetch PR state in one GraphQL batch → classify CI, comme
 > **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
 > ```
 >
@@ -250,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
 ```
 
@@ -261,16 +265,18 @@ 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). `pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

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

@@ -30,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.14.0",
+  "version": "0.14.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr-shepherd
-description: 'Codex-only skill for checking, updating, monitoring, or resolving a GitHub pull request with pr-shepherd. Use for requests like "check this PR", "use pr-shepherd", "iterate PR #123", "resolve this PR''s comments", or "run pr-shepherd until this PR is ready". For open-ended requests, create a Codex goal and run explicit `npx --no-install pr-shepherd PR_NUMBER` cycles, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` including repeated unchanged CI failures.'
+description: 'Codex-only skill for checking, updating, monitoring, or resolving a GitHub pull request with pr-shepherd. Use for requests like "check this PR", "use pr-shepherd", "iterate PR #123", "resolve this PR''s comments", or "run pr-shepherd until this PR is ready". For open-ended requests, create a Codex goal and run explicit pr-shepherd cycles through the target repo package runner, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` including repeated unchanged CI failures.'
 ---
 
 # pr-shepherd
@@ -19,32 +19,37 @@ Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
 2. Decide whether this is one cycle or an open-ended goal.
    - For one-off requests such as "check this PR", "run pr-shepherd once", or "resolve this PR's comments", run one explicit CLI command.
    - For requests such as "continue", "until ready", "until this PR is ready", or "keep iterating", create a Codex goal before the first recurring cycle with this objective:
-     `Run npx --no-install pr-shepherd PR_NUMBER cycles, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun, until Shepherd emits [CANCEL] for ready-delay completion or PR #PR_NUMBER is merged/closed, or pr-shepherd escalates, including repeated unchanged CI failures.`
+     `Run pr-shepherd PR_NUMBER cycles through the target repo package runner, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun, until Shepherd emits [CANCEL] for ready-delay completion or PR #PR_NUMBER is merged/closed, or pr-shepherd escalates, including repeated unchanged CI failures.`
 
-3. Verify the CLI is available.
-   - In the pr-shepherd source checkout, before any `npx --no-install pr-shepherd` invocation, verify `bin/` and `node_modules/` exist. If either is missing, run:
+3. Select the package runner from the target repository root.
+   - Prefer `package.json` `packageManager`: `pnpm@...` -> `pnpm exec`, `yarn@...` -> `yarn run`, `npm@...` -> `npx --no-install`.
+   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` -> `pnpm exec`, `yarn.lock` -> `yarn run`, `package-lock.json` or no signal -> `npx --no-install`.
+   - Example: in `~/filaments`, use `pnpm exec pr-shepherd ...` because the root package declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml`.
+
+4. Verify the CLI is available.
+   - Only when the target repository itself is the pr-shepherd source checkout, verify `bin/` and `node_modules/` exist before any local CLI invocation. If either is missing, run the source checkout's package-manager install command. This repository currently uses npm, so run:
      `npm install`
-   - In other repositories, use `npx --no-install pr-shepherd` so Codex does not install packages implicitly. If that fails because the package is missing, tell the user to install `pr-shepherd` in the target repo with `npm install --save-dev pr-shepherd`.
+   - In other repositories, run through the selected package runner so Codex does not install packages implicitly. If the package is missing, tell the user to install `pr-shepherd` with the matching dev-dependency command: `pnpm add -D pr-shepherd`, `yarn add -D pr-shepherd`, or `npm install --save-dev pr-shepherd`.
 
-4. Run the appropriate command from the repository root.
+5. Run the appropriate command from the repository root.
    - For a status check:
-     `npx --no-install pr-shepherd check PR_NUMBER`
+     `<runner> pr-shepherd check PR_NUMBER`
    - For review comment resolution:
-     `npx --no-install pr-shepherd resolve PR_NUMBER --fetch`
+     `<runner> pr-shepherd resolve PR_NUMBER --fetch`
    - For a monitor bootstrap:
-     `npx --no-install pr-shepherd monitor PR_NUMBER`
+     `<runner> pr-shepherd monitor PR_NUMBER`
    - For the recurring explicit monitor tick:
-     `npx --no-install pr-shepherd PR_NUMBER`
-   - `npx --no-install pr-shepherd iterate PR_NUMBER` remains supported as a legacy alias, but use the default `pr-shepherd PR_NUMBER` form for recurring Codex cycles.
+     `<runner> pr-shepherd PR_NUMBER`
+   - `pr-shepherd iterate PR_NUMBER` remains supported as a legacy alias, but use the default `pr-shepherd PR_NUMBER` form for recurring Codex cycles.
 
-5. Print or summarize the important status, then follow the output's `## Instructions` exactly.
+6. Print or summarize the important status, then follow the output's `## Instructions` exactly.
 
-6. Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `npx pr-shepherd monitor` for recurrence. Codex does explicit `pr-shepherd PR_NUMBER` cycles.
+7. Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `pr-shepherd monitor` for recurrence. Codex does explicit `pr-shepherd PR_NUMBER` cycles.
 
-7. For open-ended goal requests, complete the CLI-provided instructions for the current cycle. If the output says to continue the active Codex goal, pick a fresh sleep/timeout between 1 and 4 minutes, wait that long, and run another explicit `pr-shepherd PR_NUMBER` cycle.
+8. For open-ended goal requests, complete the CLI-provided instructions for the current cycle. If the output says to continue the active Codex goal, pick a fresh sleep/timeout between 1 and 4 minutes, wait that long, and run another explicit `pr-shepherd PR_NUMBER` cycle through the same runner.
 
-8. Do not stop an open-ended goal only because the output is `[WAIT]`, `[COOLDOWN]`, `[MARK_READY]`, or a post-fix CI wait. These are nonterminal Codex recurrence states.
+9. Do not stop an open-ended goal only because the output is `[WAIT]`, `[COOLDOWN]`, `[MARK_READY]`, or a post-fix CI wait. These are nonterminal Codex recurrence states.
 
-9. Stop only when Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or when it emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures. If a Codex goal is active, mark it complete only when one of those terminal conditions is actually satisfied.
+10. Stop only when Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or when it emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures. If a Codex goal is active, mark it complete only when one of those terminal conditions is actually satisfied.
 
-10. If the output includes fixes, pushes, rebases, or resolve commands, perform only the instructed scoped actions. Do not resolve, minimize, or dismiss comments until the CLI-provided post-push and `--require-sha` instructions are satisfied.
+11. If the output includes fixes, pushes, rebases, or resolve commands, perform only the instructed scoped actions. Do not resolve, minimize, or dismiss comments until the CLI-provided post-push and `--require-sha` instructions are satisfied.