pr-shepherd 0.16.4 → 0.17.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.16.4",
+  "version": "0.17.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -20,7 +20,7 @@ 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 emits runtime-specific retry instructions. Claude-compatible output schedules exactly one next session-only iteration after a fresh delay between 30 seconds and 4 minutes, then ends the turn. Codex-compatible output sleeps inline for that delay, then reruns the configured pr-shepherd command. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, or `yarn`.
+The CLI emits runtime-specific retry instructions. Claude-compatible output schedules exactly one next session-only iteration after a fresh delay between 30 seconds and 4 minutes, then ends the turn. Codex-compatible output sleeps inline for that delay, then reruns the configured pr-shepherd command. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, `yarn`, or `bun`.
 
 At a high level, the skill invokes `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
 
@@ -136,6 +136,18 @@ npx pr-shepherd iterate 42               # legacy-compatible spelling
 
 On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, or `wait`). Claude schedules one next session-only iteration after a fresh 30s-4m delay; Codex sleeps inline for that delay and reruns. 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.
 
+## Cleaning state
+
+`pr-shepherd` accumulates state under `$PR_SHEPHERD_STATE_DIR` (seen markers, fix-attempt counters, stall fingerprints, etc.). To reset it:
+
+```sh
+npx pr-shepherd clean current    # remove state for the current branch's PR
+npx pr-shepherd clean repo       # remove all state for this repo
+npx pr-shepherd clean all        # remove all pr-shepherd state
+```
+
+Add `--dry-run` to preview what would be removed. See [docs/cli-usage.md](docs/cli-usage.md) for the full `clean` reference.
+
 ## Install
 
 > **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:
@@ -143,6 +155,7 @@ On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and
 > ```bash
 > pnpm add -D pr-shepherd      # pnpm repos
 > yarn add -D pr-shepherd      # yarn repos
+> bun add -d pr-shepherd       # bun repos
 > npm install --save-dev pr-shepherd
 > ```
 >
@@ -197,6 +210,7 @@ Install the CLI where Codex will run it:
 ```bash
 pnpm add -D pr-shepherd      # pnpm repos
 yarn add -D pr-shepherd      # yarn repos
+bun add -d pr-shepherd       # bun repos
 npm install --save-dev pr-shepherd
 ```
 
@@ -214,7 +228,7 @@ Then iterate a PR from Codex with the target repository's package runner:
 <runner> pr-shepherd iterate 42
 ```
 
-For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd iterate 42`. For npm repos, use `npx pr-shepherd iterate 42`.
+For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd iterate 42`. For Bun repos (with `bun.lock` or `bun.lockb`), use `bunx pr-shepherd iterate 42`. For npm repos, use `npx pr-shepherd iterate 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 skill runs one tick and Codex-compatible instructions tell you to pick a fresh sleep/timeout between 30 seconds and 4 minutes before the next rerun. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows.
 

package/bin/cli/clean-formatter.mjs

@@ -0,0 +1,20 @@
+import { joinSections } from "../util/markdown.mjs";
+export function formatCleanResult(result) {
+    if (!result.ok) {
+        return `Error: ${result.error ?? "unknown error"}`;
+    }
+    const heading = result.dryRun ? "## Would clean" : "## Cleaned";
+    const paths = result.deleted;
+    if (result.skipped.length > 0) {
+        const label = result.dryRun ? "Nothing to clean (dry-run)" : "Nothing to clean";
+        return `${label} — ${result.target} does not exist.`;
+    }
+    const sections = [
+        heading,
+        paths.map((p) => `- ${p}`).join("\n"),
+        result.dryRun
+            ? `Would remove ${paths.length} item(s) under ${result.target}`
+            : `Removed ${paths.length} item(s) under ${result.target}`,
+    ];
+    return joinSections(sections);
+}

package/bin/cli/fix-formatter.mjs

@@ -1,7 +1,7 @@
 import { renderResolveCommand } from "../commands/iterate/render.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, renderAuthor, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, } from "./list-formatters.mjs";
 import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instructions.mjs";
 export function formatFixCodeResult(header, result, opts) {
     const runtime = opts?.runtime ?? "claude";
@@ -92,15 +92,8 @@ export function formatFixCodeResult(header, result, opts) {
     const firstLookTotal = result.fix.firstLookThreads.length + result.fix.firstLookComments.length;
     if (firstLookTotal > 0) {
         sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
-        const bullets = [];
-        for (const t of result.fix.firstLookThreads) {
-            bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
-        }
-        for (const c of result.fix.firstLookComments) {
-            const editedSuffix = c.edited ? ", edited" : "";
-            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
-        }
-        sections.push(bullets.join("\n"));
+        const resolutionOnlyIds = new Set(result.fix.resolutionOnlyThreads.map((t) => t.id));
+        sections.push(buildFirstLookBullets(result.fix.firstLookThreads, resolutionOnlyIds, result.fix.firstLookComments).join("\n"));
     }
     if (result.fix.inProgressRunIds.length > 0) {
         sections.push("## In-progress runs");

package/bin/cli/formatters.mjs

@@ -1,7 +1,8 @@
 export { formatIterateResult } from "./iterate-formatter.mjs";
 export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
+export { formatCleanResult } from "./clean-formatter.mjs";
 import { safeFence } from "./fence.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, } from "./list-formatters.mjs";
 import { joinSections } from "../util/markdown.mjs";
 export function formatFetchResult(result) {
     const activeTotal = result.actionableThreads.length +
@@ -46,15 +47,8 @@ export function formatFetchResult(result) {
     }
     if (firstLookTotal > 0) {
         sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
-        const bullets = [];
-        for (const t of result.firstLookThreads) {
-            bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
-        }
-        for (const c of result.firstLookComments) {
-            const editedSuffix = c.edited ? ", edited" : "";
-            bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
-        }
-        sections.push(bullets.join("\n"));
+        const resolutionOnlyIds = new Set(result.resolutionOnlyThreads.map((t) => t.id));
+        sections.push(buildFirstLookBullets(result.firstLookThreads, resolutionOnlyIds, result.firstLookComments).join("\n"));
     }
     sections.push("## Summary");
     sections.push(total === 0
@@ -108,6 +102,8 @@ 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.skippedDismissals?.length)
+        lines.push(`Skipped dismissals (${result.skippedDismissals.length}): ${result.skippedDismissals.join(", ")}`);
     if (result.rateLimit) {
         const details = [
             result.rateLimit.retryAfterSeconds !== undefined

package/bin/cli/handlers.mjs

@@ -1,11 +1,67 @@
 import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
 import { runIterate } from "../commands/iterate/index.mjs";
+import { runClean } from "../commands/clean.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { detectAgentRuntime } from "../agent-runtime.mjs";
 import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
 import { parseDurationToMinutes, iterateActionToExitCode } from "./exit-codes.mjs";
-import { formatCommitSuggestionResult, formatIterateResult, projectIterateLean, projectIterateVerbose, } from "./formatters.mjs";
+import { formatCommitSuggestionResult, formatCleanResult, formatIterateResult, projectIterateLean, projectIterateVerbose, } from "./formatters.mjs";
 import { validateDurationFlag } from "./duration-flag.mjs";
+const CLEAN_VARIANTS = new Set(["pr", "branch", "current", "repo", "all"]);
+export async function handleClean(args) {
+    const variant = args[0];
+    if (!variant || !CLEAN_VARIANTS.has(variant)) {
+        process.stderr.write("Usage: pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]\n");
+        process.exitCode = 1;
+        return;
+    }
+    const rest = args.slice(1);
+    for (const a of rest) {
+        if (!a.startsWith("--"))
+            continue;
+        if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
+            continue;
+        process.stderr.write(`pr-shepherd: clean: unknown flag: "${a}"\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const fmtIdx = rest.indexOf("--format");
+    const fmtEqEntry = rest.find((a) => a.startsWith("--format="));
+    let formatValue;
+    if (fmtEqEntry !== undefined) {
+        formatValue = fmtEqEntry.slice("--format=".length);
+    }
+    else if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
+        formatValue = rest[fmtIdx + 1];
+    }
+    if (formatValue !== undefined && formatValue !== "text" && formatValue !== "json") {
+        process.stderr.write(`pr-shepherd: clean: invalid --format value: "${formatValue}". Expected "text" or "json".\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const jsonOut = formatValue === "json";
+    const dryRun = rest.includes("--dry-run");
+    // Skip the value consumed by --format <value> so it isn't mistaken for the positional.
+    const flagConsumedIndices = new Set();
+    if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
+        flagConsumedIndices.add(fmtIdx);
+        flagConsumedIndices.add(fmtIdx + 1);
+    }
+    const positionals = rest.filter((a, i) => !flagConsumedIndices.has(i) && !a.startsWith("--"));
+    if (positionals.length > 1) {
+        process.stderr.write(`pr-shepherd: clean: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const value = positionals[0];
+    const result = await runClean({ variant: variant, value, dryRun });
+    if (!result.ok) {
+        process.stderr.write(`pr-shepherd: clean: ${result.error}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${formatCleanResult(result)}\n`);
+}
 export async function handleCommitSuggestion(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");

package/bin/cli/iterate-instructions.mjs

@@ -4,7 +4,7 @@ function buildRecheckInstruction(runtime, rerunCommand, purpose) {
     if (runtime === "codex") {
         return `Pick a fresh sleep/timeout between 30 seconds and 4 minutes, wait that long, then rerun \`${rerunCommand}\` to ${purpose}.`;
     }
-    return `Schedule one session-only follow-up task to run \`${rerunCommand}\` to ${purpose} once after a fresh delay between 30 seconds and 4 minutes, then end this turn. Do not sleep or rerun inline.`;
+    return `Single-shot continuation: schedule one session-only follow-up task to run \`${rerunCommand}\` to ${purpose} once after a fresh delay between 30 seconds and 4 minutes, then end this turn. Do not sleep or rerun inline.`;
 }
 export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner) {
     const rerunCommand = buildIterateCommand(result.pr, readyDelaySuffix, runner);
@@ -18,7 +18,9 @@ export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix
         case "cancel":
             return ["Stop — the active goal is complete."];
         case "escalate":
-            return ["Stop — the PR needs human direction before iterating can resume."];
+            return [
+                "Stop — the PR needs human direction before iterating can resume. This is a manual handoff; do not continue automated fix attempts.",
+            ];
     }
 }
 export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, runner) {

package/bin/cli/list-formatters.mjs

@@ -27,7 +27,8 @@ export function renderThreadBullet(t, opts = {}) {
         : "`(no location)`";
     const suggestionMarker = t.suggestion ? " [suggestion]" : "";
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
-    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${statusSuffix}: ${renderBodyPreview(t.body)}`;
+    const bodySuffix = opts.noBody ? "" : `: ${renderBodyPreview(t.body)}`;
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}${statusSuffix}${bodySuffix}`;
     if (t.suggestion && opts.renderSuggestion) {
         return `${bulletLine}\n${renderSuggestionBlock(t.suggestion)}`;
     }
@@ -47,3 +48,22 @@ export function renderReviewListSection(heading, items) {
         return null;
     return `## ${heading}\n\n${items.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n")}`;
 }
+/**
+ * Build bullet strings for the `## First-look items` section.
+ * Threads that also appear in resolutionOnlyIds have their body suppressed
+ * (already shown in `## Review threads to resolve`).
+ */
+export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, firstLookComments) {
+    const bullets = [];
+    for (const t of firstLookThreads) {
+        bullets.push(renderThreadBullet(t, {
+            statusTag: renderFirstLookStatusTag(t),
+            noBody: resolutionOnlyIds.has(t.id),
+        }));
+    }
+    for (const c of firstLookComments) {
+        const editedSuffix = c.edited ? ", edited" : "";
+        bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
+    }
+    return bullets;
+}

package/bin/cli/runner.mjs

@@ -10,16 +10,18 @@ export function resolveCliRunner(runner, cwd = process.cwd()) {
     const configured = parseCliRunner(runner);
     return configured === "auto" ? detectPackageRunner(cwd) : configured;
 }
+const VALID_RUNNERS = ["auto", "npx", "pnpm", "yarn", "bun"];
+const VALID_RUNNERS_LIST = VALID_RUNNERS.map((v) => `"${v}"`).join(", ");
 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)}`);
+        throw new Error(`Invalid config: cli.runner must be one of ${VALID_RUNNERS_LIST}, got ${JSON.stringify(runner)}`);
     }
     const value = runner.trim();
-    if (value === "auto" || value === "npx" || value === "pnpm" || value === "yarn")
+    if (VALID_RUNNERS.includes(value))
         return value;
-    throw new Error(`Invalid config: cli.runner must be one of "auto", "npx", "pnpm", or "yarn", got ${JSON.stringify(runner)}`);
+    throw new Error(`Invalid config: cli.runner must be one of ${VALID_RUNNERS_LIST}, got ${JSON.stringify(runner)}`);
 }
 export function renderShellCommand(argv) {
     return argv.map(renderShellArg).join(" ");
@@ -32,6 +34,8 @@ function baseArgvForRunner(runner) {
             return ["pnpm", "exec", "pr-shepherd"];
         case "yarn":
             return ["yarn", "run", "pr-shepherd"];
+        case "bun":
+            return ["bunx", "pr-shepherd"];
     }
 }
 const runnerCache = new Map();
@@ -58,10 +62,16 @@ function detectPackageRunner(startDir) {
                 return cacheRunner(startDir, "yarn");
             if (packageManager?.startsWith("npm@"))
                 return cacheRunner(startDir, "npx");
+            if (packageManager?.startsWith("bun@"))
+                return cacheRunner(startDir, "bun");
             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, "bun.lock")))
+                return cacheRunner(startDir, "bun");
+            if (isFile(join(current, "bun.lockb")))
+                return cacheRunner(startDir, "bun");
             if (isFile(join(current, "package-lock.json")))
                 return cacheRunner(startDir, "npx");
         }

package/bin/cli-parser.clean.test-support.mjs

@@ -0,0 +1,45 @@
+// @ts-nocheck
+import { vi, beforeEach, afterEach } from "vitest";
+vi.mock("./commands/clean.mts", () => ({
+    runClean: vi.fn(),
+}));
+vi.mock("./commands/resolve.mts", () => ({
+    runResolveFetch: vi.fn(),
+    runResolveMutate: vi.fn(),
+}));
+vi.mock("./commands/log-file.mts", () => ({
+    runLogFile: vi.fn(),
+}));
+vi.mock("./commands/commit-suggestion.mts", () => ({
+    runCommitSuggestion: vi.fn(),
+}));
+vi.mock("./commands/iterate/index.mts", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, runIterate: vi.fn() };
+});
+import { main } from "./cli-parser.mjs";
+import { runClean } from "./commands/clean.mjs";
+export const mockRunClean = vi.mocked(runClean);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let stdoutSpy;
+let stderrSpy;
+export function getStdout() {
+    return stdoutSpy.mock.calls.map((c) => c[0]).join("");
+}
+export function getStderr() {
+    return stderrSpy.mock.calls.map((c) => c[0]).join("");
+}
+export function registerHooks() {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+        stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    });
+    afterEach(() => {
+        process.exitCode = undefined;
+        stdoutSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+}
+export { main, stderrSpy, stdoutSpy };

package/bin/cli-parser.iterate-fixtures.mjs

@@ -64,7 +64,7 @@ export function makeIterateResult(action = "wait") {
                 ambiguousComments: [],
                 changesRequestedReviews: [],
                 suggestion: "check manually",
-                humanMessage: "⚠️ /pr-shepherd:pr-shepherd paused — needs human direction",
+                humanMessage: "⚠️ /pr-shepherd:pr-shepherd paused — manual intervention required",
             },
         };
     }

package/bin/cli-parser.mjs

@@ -14,6 +14,7 @@
  *   pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]
  *                              [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                              [--no-auto-cancel-actionable]
+ *   pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]
  */
 import { readFileSync } from "node:fs";
 import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
@@ -21,7 +22,7 @@ import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultIterateInvocation, validateDefaultIterateArgs } from "./cli/default-iterate.mjs";
 import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
-import { handleCommitSuggestion, handleIterate } from "./cli/handlers.mjs";
+import { handleClean, handleCommitSuggestion, handleIterate } from "./cli/handlers.mjs";
 import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
 // Entry
@@ -56,9 +57,12 @@ export async function main(argv) {
         case "iterate":
             await handleIterate(args.slice(1));
             break;
+        case "clean":
+            await handleClean(args.slice(1));
+            break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
-            process.stderr.write("Usage: pr-shepherd <resolve|commit-suggestion|iterate|log-file> [options]\n" +
+            process.stderr.write("Usage: pr-shepherd <resolve|commit-suggestion|iterate|log-file|clean> [options]\n" +
                 "       pr-shepherd --version | -v\n");
             process.exitCode = 1;
             return;

package/bin/commands/clean.mjs

@@ -0,0 +1,156 @@
+import { rm, readdir, realpath, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveStateBase } from "../state/base.mjs";
+import { getRepoInfo, getCurrentPrNumber, getCurrentBranch, getPrNumberForBranch, } from "../github/client.mjs";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+export async function runClean(opts) {
+    const dryRun = opts.dryRun ?? false;
+    const rawBase = resolveStateBase();
+    const base = await realpath(rawBase).catch(() => rawBase);
+    let target;
+    try {
+        target = await resolveTarget(base, opts);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            variant: opts.variant,
+            dryRun,
+            base,
+            target: "",
+            deleted: [],
+            skipped: [],
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+    let targetExists = false;
+    try {
+        await stat(target);
+        targetExists = true;
+    }
+    catch (e) {
+        if (e.code !== "ENOENT") {
+            return {
+                ok: false,
+                variant: opts.variant,
+                dryRun,
+                base,
+                target,
+                deleted: [],
+                skipped: [],
+                error: `Failed to stat target: ${e.message}`,
+            };
+        }
+    }
+    if (!targetExists) {
+        return {
+            ok: true,
+            variant: opts.variant,
+            dryRun,
+            base,
+            target,
+            deleted: [],
+            skipped: [target],
+        };
+    }
+    let entries;
+    try {
+        const names = await readdir(target);
+        entries = names.map((n) => join(target, n));
+    }
+    catch {
+        entries = [target];
+    }
+    if (dryRun) {
+        return {
+            ok: true,
+            variant: opts.variant,
+            dryRun: true,
+            base,
+            target,
+            deleted: entries,
+            skipped: [],
+        };
+    }
+    try {
+        await rm(target, { recursive: true, force: true });
+    }
+    catch (e) {
+        return {
+            ok: false,
+            variant: opts.variant,
+            dryRun: false,
+            base,
+            target,
+            deleted: [],
+            skipped: [],
+            error: `Failed to remove target: ${e.message}`,
+        };
+    }
+    return {
+        ok: true,
+        variant: opts.variant,
+        dryRun: false,
+        base,
+        target,
+        deleted: entries,
+        skipped: [],
+    };
+}
+async function resolveTarget(base, opts) {
+    const { variant, value } = opts;
+    if (variant === "all") {
+        if (value !== undefined) {
+            throw new Error(`"clean all" does not accept a positional argument; got "${value}". Did you mean "clean repo" or "clean pr"?`);
+        }
+        return base;
+    }
+    const repo = await getRepoInfo();
+    const { owner, name } = repo;
+    for (const [field, val] of [
+        ["owner", owner],
+        ["repo", name],
+    ]) {
+        if (!SAFE_SEGMENT.test(val)) {
+            throw new Error(`Invalid repository segment "${field}": ${val}`);
+        }
+    }
+    const ownerRepo = `${owner}-${name}`;
+    if (variant === "repo") {
+        if (value !== undefined) {
+            throw new Error(`"clean repo" does not accept a positional argument; got "${value}". Did you mean "clean pr" or "clean branch"?`);
+        }
+        return join(base, ownerRepo);
+    }
+    let prNumber;
+    if (variant === "pr") {
+        if (value !== undefined) {
+            const n = parseInt(value, 10);
+            if (!Number.isFinite(n) || n <= 0 || String(n) !== value.trim()) {
+                throw new Error(`Invalid PR number: ${value}`);
+            }
+            prNumber = n;
+        }
+        else {
+            const n = await getCurrentPrNumber();
+            if (n === null)
+                throw new Error("No open PR found for current branch");
+            prNumber = n;
+        }
+    }
+    else {
+        // "branch" or "current"
+        if (variant === "current" && value !== undefined) {
+            throw new Error(`"clean current" does not accept a positional argument; got "${value}". Did you mean "clean branch"?`);
+        }
+        const branchName = value ?? (await getCurrentBranch());
+        if (branchName === "HEAD") {
+            throw new Error("Could not resolve current branch (detached HEAD)");
+        }
+        const n = await getPrNumberForBranch(branchName, owner, name);
+        if (n === null)
+            throw new Error(`No open PR found for branch: ${branchName}`);
+        prNumber = n;
+    }
+    return join(base, ownerRepo, String(prNumber));
+}

package/bin/commands/clean.test-support.mjs

@@ -0,0 +1,48 @@
+// @ts-nocheck
+import { vi, beforeEach, afterEach } from "vitest";
+import { join } from "node:path";
+import { mkdtemp, realpath, rm, mkdir, writeFile, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+vi.mock("../github/client.mts", () => ({
+    getRepoInfo: vi.fn().mockResolvedValue({ owner: "acme", name: "widgets" }),
+    getCurrentBranch: vi.fn().mockResolvedValue("feature/test"),
+    getCurrentPrNumber: vi.fn().mockResolvedValue(42),
+    getPrNumberForBranch: vi.fn().mockResolvedValue(42),
+}));
+import { getRepoInfo, getCurrentBranch, getCurrentPrNumber, getPrNumberForBranch, } from "../github/client.mjs";
+export const mockGetRepoInfo = vi.mocked(getRepoInfo);
+export const mockGetCurrentBranch = vi.mocked(getCurrentBranch);
+export const mockGetCurrentPrNumber = vi.mocked(getCurrentPrNumber);
+export const mockGetPrNumberForBranch = vi.mocked(getPrNumberForBranch);
+export let stateDir;
+export function registerHooks() {
+    beforeEach(async () => {
+        const tmpPath = await mkdtemp(join(tmpdir(), "shepherd-clean-test-"));
+        stateDir = await realpath(tmpPath);
+        process.env["PR_SHEPHERD_STATE_DIR"] = stateDir;
+        vi.clearAllMocks();
+        mockGetRepoInfo.mockResolvedValue({ owner: "acme", name: "widgets" });
+        mockGetCurrentBranch.mockResolvedValue("feature/test");
+        mockGetCurrentPrNumber.mockResolvedValue(42);
+        mockGetPrNumberForBranch.mockResolvedValue(42);
+    });
+    afterEach(async () => {
+        delete process.env["PR_SHEPHERD_STATE_DIR"];
+        await rm(stateDir, { recursive: true, force: true });
+    });
+}
+export async function seedPrDir(dir, pr) {
+    const prDir = join(dir, "acme-widgets", String(pr));
+    await mkdir(join(prDir, "seen"), { recursive: true });
+    await writeFile(join(prDir, "fix-attempts.json"), "{}", "utf8");
+    return prDir;
+}
+export async function pathExists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/bin/commands/iterate/classify.mjs

@@ -1,5 +1,16 @@
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { shouldMinimizeAuthor } from "../../comments/minimize-policy.mjs";
+function dedupeIds(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals, minimizeComments = "all") {
     // 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).
@@ -28,26 +39,43 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
 }
 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)];
+    const resolveThreadIds = dedupeIds(threads.map((t) => t.id));
+    const threadIds = dedupeIds([...resolveThreadIds, ...resolutionOnlyThreads.map((t) => t.id)]);
     if (threadIds.length > 0) {
         argv.push("--resolve-thread-ids", threadIds.join(","));
     }
     if (allCommentIds.length > 0) {
         argv.push("--minimize-comment-ids", allCommentIds.join(","));
     }
-    const hasDismiss = reviews.length > 0;
+    const commentIdSet = new Set(allCommentIds);
+    const filteredReviewIds = [];
+    const droppedDismissReviewIds = [];
+    for (const review of reviews) {
+        if (commentIdSet.has(review.id))
+            droppedDismissReviewIds.push(review.id);
+        else
+            filteredReviewIds.push(review.id);
+    }
+    const hasDismiss = filteredReviewIds.length > 0;
     if (hasDismiss) {
-        argv.push("--dismiss-review-ids", reviews.map((r) => r.id).join(","));
+        argv.push("--dismiss-review-ids", filteredReviewIds.join(","));
         argv.push("--message", "$DISMISS_MESSAGE");
     }
-    // A push is required when threads, CI failures, or changes-requested reviews are present — the
-    // CLI knows those imply code edits. Comments are surfaced for the agent to evaluate; the CLI
-    // cannot know whether a given comment will require a push, so comments are excluded here.
-    const requiresHeadSha = threads.length > 0 || checks.length > 0 || reviews.length > 0;
     // hasMutations = we appended at least one of --resolve-thread-ids,
     // --minimize-comment-ids, or --dismiss-review-ids. Returned explicitly
     // (rather than derived from argv.length) so callers don't couple to the
     // base-argv shape.
-    const hasMutations = threadIds.length > 0 || allCommentIds.length > 0 || reviews.length > 0;
-    return { argv, requiresHeadSha, requiresDismissMessage: hasDismiss, hasMutations };
+    const hasMutations = threadIds.length > 0 || allCommentIds.length > 0 || filteredReviewIds.length > 0;
+    // `requiresHeadSha` is only added when this resolve command includes a
+    // mutation that can race with a moving HEAD: resolving actionable threads,
+    // dismissing CHANGES_REQUESTED reviews, or addressing failing checks.
+    const hasCodeMutations = hasMutations && (threads.length > 0 || checks.length > 0 || filteredReviewIds.length > 0);
+    const requiresHeadSha = hasCodeMutations;
+    return {
+        argv,
+        requiresHeadSha,
+        requiresDismissMessage: hasDismiss,
+        ...(droppedDismissReviewIds.length > 0 ? { droppedDismissReviewIds } : undefined),
+        hasMutations,
+    };
 }

package/bin/commands/iterate/escalate.mjs

@@ -55,7 +55,7 @@ export function validateBaseBranch(raw) {
 }
 export function buildEscalateHumanMessage(escalate, pr) {
     const lines = [];
-    lines.push("⚠️ /pr-shepherd:pr-shepherd paused — needs human direction");
+    lines.push("⚠️ /pr-shepherd:pr-shepherd paused — manual intervention required");
     lines.push("");
     lines.push(`**Triggers:** ${escalate.triggers.map((t) => `\`${t}\``).join(", ")}`);
     lines.push("");
@@ -66,6 +66,7 @@ export function buildEscalateHumanMessage(escalate, pr) {
     if (hasItems) {
         lines.push("");
         lines.push("## Items needing attention");
+        lines.push("");
         for (const t of escalate.unresolvedThreads) {
             const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
             const firstLine = t.body.split("\n")[0] ?? "";
@@ -83,6 +84,7 @@ export function buildEscalateHumanMessage(escalate, pr) {
     if (escalate.thrashHistory && escalate.thrashHistory.length > 0) {
         lines.push("");
         lines.push("## Fix attempts");
+        lines.push("");
         for (const a of escalate.thrashHistory) {
             lines.push(`- thread \`${a.threadId}\` attempted ${a.attempts} times`);
         }
@@ -90,26 +92,26 @@ export function buildEscalateHumanMessage(escalate, pr) {
     lines.push("");
     lines.push("---");
     lines.push("");
-    lines.push(`After fixing manually, rerun \`/pr-shepherd:pr-shepherd ${pr}\` to resume.`);
+    lines.push(`After completing manual fixes (and pushing if required), rerun \`/pr-shepherd:pr-shepherd ${pr}\` to resume.`);
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
     if (triggers.includes("stall-timeout")) {
         const mins = detail ?? "30";
-        return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. Inspect the PR and resume manually once the blocking issue is resolved.`;
+        return `No progress detected for ${mins} minute${parseInt(mins, 10) === 1 ? "" : "s"} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
     if (triggers.includes("base-branch-unknown")) {
         const reason = detail ? ` (${detail})` : "";
-        return `Could not determine the PR's base branch${reason} — refusing to emit a rebase that could force-push onto the wrong base. Run the rebase manually against the PR's real target branch.`;
+        return `Could not determine the PR's base branch${reason} — automated rebases are paused because branch safety is unclear. Run the rebase manually against the PR's real target branch.`;
     }
     if (triggers.includes("fix-thrash")) {
-        return "Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:pr-shepherd";
+        return "Same thread(s) reached the automated attempt limit — treat this as a manual handoff. Apply the fix by hand.";
     }
     if (triggers.includes("pr-level-changes-requested")) {
-        return "Reviewer requested changes but left no inline comments — read the review and act manually";
+        return "Reviewer requested changes but left no inline comments — read the review and act manually.";
     }
     if (triggers.includes("thread-missing-location")) {
-        return "Review thread has no file/line reference — cannot locate code to edit automatically";
+        return "Review thread has no file/line reference — automated location routing failed and manual handling is required.";
     }
-    return "Ambiguous state — inspect the PR and act manually";
+    return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }

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

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 import { readFixAttempts, writeFixAttempts } from "../../state/fix-attempts.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
@@ -52,14 +53,24 @@ export async function handleFixCode(ctx) {
     const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
-    const hasGuaranteedSupersedingPush = threads.length > 0 || checks.length > 0 || changesRequestedReviews.length > 0 || hasConflicts;
-    const inProgressRunIds = hasGuaranteedSupersedingPush
-        ? buildInProgressRunIds(report, cancelledSet)
-        : [];
+    const hasReviewRequestedCodeLikeChanges = changesRequestedReviews.length > 0 &&
+        (actionableComments.length > 0 || resolutionOnlyThreads.length > 0);
+    const hasGuaranteedPush = threads.length > 0 || checks.length > 0 || hasConflicts || hasReviewRequestedCodeLikeChanges;
+    const shouldPush = hasGuaranteedPush;
+    // Only cancel in-progress runs for paths that produce a new code commit. A
+    // conflict-only rebase push will supersede any in-progress run on its own.
+    const hasCodeLikePush = threads.length > 0 || checks.length > 0 || hasReviewRequestedCodeLikeChanges;
+    const inProgressRunIds = hasCodeLikePush ? buildInProgressRunIds(report, cancelledSet) : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
     const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, cliRunner);
-    if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
+    const overlappingReviewIds = resolveCommand.droppedDismissReviewIds ?? [];
+    if (overlappingReviewIds.length > 0) {
+        process.stderr.write(`pr-shepherd: resolve command overlap: ${overlappingReviewIds.length} ` +
+            `review IDs were also in minimize/comment IDs and were dropped from --dismiss-review-ids: ` +
+            `${overlappingReviewIds.join(", ")}\n`);
+    }
+    if (baseLookup.isFallback && shouldPush) {
         const fallbackEscalateBase = {
             triggers: ["base-branch-unknown"],
             unresolvedThreads: [...threads, ...resolutionOnlyThreads.map(toAgentThread)],
@@ -78,7 +89,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, cliRunner);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, cliRunner, shouldPush);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/render.mjs

@@ -16,8 +16,10 @@ export function renderResolveCommand(rc) {
     }
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], runner, needsPushInput) {
     const instructions = [];
+    const hasCodeWork = threads.length > 0 || checks.length > 0;
+    const needsPush = needsPushInput ?? (hasCodeWork || hasConflicts);
     if (inProgressRunIds.length > 0) {
         instructions.push(`Cancel in-progress CI runs first: for each ID under \`## In-progress runs\`, run \`gh run cancel <id>\` before applying code fixes. If \`gh\` reports a run is already completed, ignore it and continue with the next ID.`);
     }
@@ -35,15 +37,18 @@ export function buildFixInstructions(threads, actionableComments, checks, review
         instructions.push(`Resolve the threads under \`## Review threads to resolve\` with the \`resolve:\` command shown below. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
     }
     instructions.push(...buildFailingCheckInstructions(checks));
-    if (reviews.length > 0) {
+    if (changesRequestedReviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }
-    const hasCodeChanges = threads.length > 0 || checks.length > 0 || reviews.length > 0;
-    const needsPush = hasCodeChanges || hasConflicts;
-    if (hasCodeChanges) {
+    if (needsPush && (hasCodeWork || changesRequestedReviews.length > 0)) {
         instructions.push(`Commit changed files: \`git add <files> && git commit -m "<descriptive message>"\``);
+    }
+    if (changesRequestedReviews.length > 0) {
         instructions.push(`Keep the PR title and description current: if the changes alter the PR's scope or intent, run \`gh pr edit ${prNumber} --title "<new title>" --body "<new body>"\` to reflect them. Skip if the existing title/body still accurately describe the PR.`);
     }
+    if (!needsPush && resolveCommand.requiresHeadSha) {
+        instructions.push("Capture the current HEAD SHA before resolving with: `HEAD_SHA=$(git rev-parse HEAD)`.");
+    }
     if (needsPush) {
         const captureHint = resolveCommand.requiresHeadSha
             ? ` — capture \`HEAD_SHA=$(git rev-parse HEAD)\``
@@ -71,7 +76,8 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (resolveCommand.hasMutations) {
         const substituteParts = [];
         if (resolveCommand.requiresHeadSha) {
-            substituteParts.push(`"$HEAD_SHA" with the pushed commit SHA`);
+            const shaSource = needsPush ? "pushed commit SHA" : "current HEAD SHA";
+            substituteParts.push(`"$HEAD_SHA" with the ${shaSource}`);
         }
         if (resolveCommand.requiresDismissMessage) {
             substituteParts.push(`$DISMISS_MESSAGE with a one-sentence description of what you changed`);

package/bin/comments/resolve.mjs

@@ -1,9 +1,48 @@
+/* eslint-disable max-lines */
 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";
+const COMMENTED_DISMISS_ERROR_PATTERNS = [
+    /can\s*not\s+dismiss[\s\S]*?commented pull request review/i,
+];
+function dedupeIds(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+function isCommentedDismissError(message) {
+    return COMMENTED_DISMISS_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+function dismissReviewNonDismissibleMessage(id) {
+    return `Not dismissed: ${id} is a COMMENTED review. Use --minimize-comment-ids instead; --dismiss-review-ids is only for CHANGES_REQUESTED reviews.`;
+}
 export async function applyResolveOptions(pr, repo, opts) {
-    if ((opts.dismissReviewIds?.length ?? 0) > 0 && !opts.dismissMessage) {
+    const resolveThreadIds = dedupeIds(opts.resolveThreadIds ?? []);
+    const minimizeCommentIds = opts.minimizeCommentIds ?? [];
+    const dismissReviewIds = dedupeIds(opts.dismissReviewIds ?? []);
+    const minimizeCommentIdSet = new Set(minimizeCommentIds);
+    const filteredDismissReviewIds = dismissReviewIds.filter((id) => !minimizeCommentIdSet.has(id));
+    const overlappingDismissIds = dismissReviewIds.filter((id) => minimizeCommentIdSet.has(id));
+    const result = {
+        resolvedThreads: [],
+        minimizedComments: [],
+        dismissedReviews: [],
+        errors: [],
+    };
+    if (overlappingDismissIds.length > 0) {
+        result.skippedDismissals = [];
+        for (const id of overlappingDismissIds) {
+            result.skippedDismissals.push(id);
+        }
+    }
+    if (filteredDismissReviewIds.length > 0 && !opts.dismissMessage) {
         throw new Error("--message is required when dismissing reviews");
     }
     if (opts.requireSha) {
@@ -11,13 +50,7 @@ export async function applyResolveOptions(pr, repo, opts) {
         // before reviewers see the fix.
         await waitForSha(pr, repo, opts.requireSha);
     }
-    const result = {
-        resolvedThreads: [],
-        minimizedComments: [],
-        dismissedReviews: [],
-        errors: [],
-    };
-    await bulkApply(opts.resolveThreadIds ?? [], opts.minimizeCommentIds ?? [], opts.dismissReviewIds ?? [], opts.dismissMessage ?? "", result);
+    await bulkApply(resolveThreadIds, minimizeCommentIds, filteredDismissReviewIds, opts.dismissMessage ?? "", result);
     return result;
 }
 export async function autoResolveOutdated(threadIds) {
@@ -65,13 +98,15 @@ async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessag
     if (resolveIds.length === 0 && minimizeIds.length === 0 && dismissIds.length === 0)
         return false;
     const doc = buildBulkMutation(resolveIds, minimizeIds, dismissIds, dismissMessage);
-    let data;
+    let data = {};
+    let graphQlErrors = [];
     let rateLimitStop;
     let suppressCurrentChunkErrors = false;
     try {
         const resp = await graphqlWithRateLimit(doc, {});
         data = resp.data;
-        const graphQlErrorMessages = resp.errors?.map((e) => e.message) ?? [];
+        graphQlErrors = (resp.errors ?? []);
+        const graphQlErrorMessages = graphQlErrors.map((e) => e.message);
         suppressCurrentChunkErrors = graphQlErrorMessages.some(isRateLimitMessage);
         rateLimitStop = rateLimitFromGraphQlResult(graphQlErrorMessages, {
             rateLimit: resp.rateLimit,
@@ -109,12 +144,27 @@ async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessag
         else if (!suppressCurrentChunkErrors)
             result.errors.push(`${minimizeIds[i]}: minimize returned null or comment not minimized`);
     }
+    const singleDismiss = dismissIds.length === 1;
+    const commentedDismissErrorIndexes = new Set();
+    let hasUnmappedCommentedDismissError = false;
+    for (const error of graphQlErrors) {
+        if (!isCommentedDismissError(error.message))
+            continue;
+        const alias = dismissErrorAliasIndex(error);
+        if (alias === undefined) {
+            hasUnmappedCommentedDismissError = true;
+            continue;
+        }
+        commentedDismissErrorIndexes.add(alias);
+    }
     for (let i = 0; i < dismissIds.length; i++) {
         const d = data[`d${i}`];
         if (d?.pullRequestReview != null)
             result.dismissedReviews.push(dismissIds[i]);
         else if (!suppressCurrentChunkErrors)
-            result.errors.push(`${dismissIds[i]}: dismiss returned null`);
+            result.errors.push(commentedDismissErrorIndexes.has(i) || (singleDismiss && hasUnmappedCommentedDismissError)
+                ? dismissReviewNonDismissibleMessage(dismissIds[i])
+                : `${dismissIds[i]}: dismiss returned null`);
     }
     if (rateLimitStop) {
         result.errors.push(`rate limit: ${rateLimitStop.message}`);
@@ -123,3 +173,12 @@ async function bulkApplyChunk(resolveIds, minimizeIds, dismissIds, dismissMessag
     }
     return false;
 }
+function dismissErrorAliasIndex(error) {
+    if (!Array.isArray(error.path))
+        return undefined;
+    const alias = error.path.find((part) => typeof part === "string" && /^d\d+$/.test(part));
+    if (typeof alias !== "string")
+        return undefined;
+    const parsed = Number.parseInt(alias.slice(1), 10);
+    return Number.isNaN(parsed) ? undefined : parsed;
+}

package/bin/github/client.mjs

@@ -34,7 +34,16 @@ export async function getCurrentPrNumber() {
         if (branch === "HEAD")
             return null;
         const repo = await getRepoInfo();
-        const result = await httpGraphql(PR_NUMBER_BY_BRANCH_QUERY, { owner: repo.owner, repo: repo.name, branch });
+        return getPrNumberForBranch(branch, repo.owner, repo.name);
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns the PR number for a given branch, or null if no open PR is found. */
+export async function getPrNumberForBranch(branch, owner, repo) {
+    try {
+        const result = await httpGraphql(PR_NUMBER_BY_BRANCH_QUERY, { owner, repo, branch });
         return result.data.repository?.pullRequests.nodes[0]?.number ?? null;
     }
     catch {

package/bin/state/base.mjs

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 export function resolveStateBase() {
-    return process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    const envDir = process.env["PR_SHEPHERD_STATE_DIR"];
+    return envDir ? envDir : join(tmpdir(), "pr-shepherd-state");
 }

package/package.json

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

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

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

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

@@ -29,12 +29,12 @@ One-tick dispatcher for iterating a PR to completion.
    If `MERGED` or `CLOSED`, output: `PR #N is already merged/closed. Nothing to do.` and stop.
 
 3. **Select the package runner** from the target repository root:
-   - Prefer `package.json` `packageManager`: `pnpm@...` → `pnpm exec`, `yarn@...` → `yarn run`, `npm@...` → `npx`.
-   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` → `pnpm exec`, `yarn.lock` → `yarn run`, `package-lock.json` or no signal → `npx`.
+   - Prefer `package.json` `packageManager`: `pnpm@...` → `pnpm exec`, `yarn@...` → `yarn run`, `bun@...` → `bunx`, `npm@...` → `npx`.
+   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` → `pnpm exec`, `yarn.lock` → `yarn run`, `bun.lock` / `bun.lockb` → `bunx`, `package-lock.json` or no signal → `npx`.
 
 4. **Run one iterate tick:**
 
-   If the package is missing in the target repository, 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`.
+   If the package is missing in the target repository, tell the user to install pr-shepherd with the matching dev-dependency command: `pnpm add -D pr-shepherd`, `yarn add -D pr-shepherd`, `bun add -d pr-shepherd`, or `npm install --save-dev pr-shepherd`.
 
    ```bash
    <runner> pr-shepherd <N>
@@ -45,4 +45,4 @@ One-tick dispatcher for iterating a PR to completion.
 5. **Stop conditions:**
    - Stop when the CLI emits `[CANCEL]` (ready-delay completed, or PR merged/closed).
    - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures.
-   - All other actions (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) are non-terminal: follow the `## Instructions`. For Claude, schedule exactly one next session-only iteration and end the turn; do not sleep inline and do not create a recurring cron.
+   - All other actions (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) are non-terminal: follow the `## Instructions`. For Claude, schedule exactly one next session-only iteration and end the turn; do not sleep inline and do not create a recurring cron or polling loop (`while true`, repeated polling, etc.).