pr-shepherd 0.16.3 → 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.3",
+  "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/checks/triage.test-support.mjs

@@ -0,0 +1,61 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach } from "vitest";
+// ---------------------------------------------------------------------------
+// Stub fetch globally so http.mts uses our mock.
+// ---------------------------------------------------------------------------
+const mockFetch = vi.fn();
+vi.stubGlobal("fetch", mockFetch);
+import { fetchStartupFailureChecks, triageFailingChecks } from "./triage.mjs";
+import { mergeStartupFailureChecks } from "./startup-failures.mjs";
+const REPO = { owner: "owner", name: "repo" };
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeCheck(overrides = {}) {
+    return {
+        name: "tests",
+        status: "COMPLETED",
+        conclusion: "FAILURE",
+        detailsUrl: "https://github.com/owner/repo/actions/runs/99/jobs/1",
+        event: "pull_request",
+        runId: "run-99",
+        category: "failing",
+        ...overrides,
+    };
+}
+function makeJobsResponse(jobs) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve({ jobs }),
+        text: () => Promise.resolve(JSON.stringify({ jobs })),
+    };
+}
+function makeErrorResponse(status) {
+    return {
+        ok: false,
+        status,
+        headers: new Headers(),
+        text: () => Promise.resolve("error"),
+    };
+}
+function makeWorkflowRunsResponse(runs) {
+    return {
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve({ workflow_runs: runs }),
+        text: () => Promise.resolve(JSON.stringify({ workflow_runs: runs })),
+    };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+export function registerHooks() {
+    beforeEach(() => {
+        mockFetch.mockReset();
+        process.env["GH_TOKEN"] = "test-token";
+    });
+}
+export { REPO, fetchStartupFailureChecks, makeCheck, makeErrorResponse, makeJobsResponse, makeWorkflowRunsResponse, mergeStartupFailureChecks, mockFetch, triageFailingChecks, };

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/iterate-lean.test-support.mjs

@@ -0,0 +1,5 @@
+// @ts-nocheck
+import { describe, it, expect } from "vitest";
+import { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
+import { makeIterateResult } from "../cli-parser.iterate-fixtures.mjs";
+export { makeIterateResult, projectIterateLean, projectIterateVerbose };

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.commit-suggestion.test-support.mjs

@@ -0,0 +1,66 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
+vi.mock("./commands/resolve.mts", () => ({
+    runResolveFetch: vi.fn(),
+    runResolveMutate: 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() };
+});
+vi.mock("./github/client.mts", () => ({
+    getRepoInfo: vi.fn().mockResolvedValue({ owner: "owner", name: "repo" }),
+}));
+import { main } from "./cli-parser.mjs";
+import { runCommitSuggestion } from "./commands/commit-suggestion.mjs";
+const mockRunCommitSuggestion = vi.mocked(runCommitSuggestion);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let stdoutSpy;
+let stderrSpy;
+function getStdout() {
+    return stdoutSpy.mock.calls.map((c) => c[0]).join("");
+}
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+const SUGGESTION_RESULT = {
+    pr: 42,
+    repo: "owner/repo",
+    threadId: "t1",
+    path: "a.ts",
+    startLine: 5,
+    endLine: 5,
+    author: "alice",
+    patch: "--- a/a.ts\n+++ b/a.ts\n@@ -5,1 +5,1 @@\n-old\n+new\n",
+    commitMessage: "apply fix",
+    commitBody: "Co-authored-by: alice <alice@users.noreply.github.com>",
+    filesToStage: ["a.ts"],
+    postActionInstructions: [
+        "Apply the patch to `a.ts`: run `git apply` with the diff shown above.",
+        "Stage the file: `git add -- a.ts`",
+        'Commit: `git commit -m "apply fix" -m "Co-authored-by: alice <alice@users.noreply.github.com>"`',
+        "Resolve the thread on GitHub: `npx pr-shepherd resolve 42 --resolve-thread-ids t1`",
+        "Push when ready: `git push` (or `git push --force-with-lease` after rebasing).",
+    ],
+};
+// ---------------------------------------------------------------------------
+// commit-suggestion dispatch
+// ---------------------------------------------------------------------------
+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 { SUGGESTION_RESULT, getStdout, main, mockRunCommitSuggestion, runCommitSuggestion, stderrSpy, stdoutSpy, };

package/bin/cli-parser.iterate-fix.test-support.mjs

@@ -0,0 +1,48 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
+vi.mock("./commands/resolve.mts", () => ({
+    runResolveFetch: vi.fn(),
+    runResolveMutate: 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() };
+});
+vi.mock("./github/client.mts", () => ({
+    getRepoInfo: vi.fn().mockResolvedValue({ owner: "owner", name: "repo" }),
+}));
+import { main } from "./cli-parser.mjs";
+import { runIterate } from "./commands/iterate/index.mjs";
+import { makeIterateResult } from "./cli-parser.iterate-fixtures.mjs";
+const mockRunIterate = vi.mocked(runIterate);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let stdoutSpy;
+let stderrSpy;
+function getStdout() {
+    return stdoutSpy.mock.calls.map((c) => c[0]).join("");
+}
+// ---------------------------------------------------------------------------
+// formatIterateResult — fix_code actions and ## Checks section
+// ---------------------------------------------------------------------------
+export function registerHooks() {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+        delete process.env.AGENT;
+        delete process.env.CODEX_CI;
+        stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    });
+    afterEach(() => {
+        process.exitCode = undefined;
+        delete process.env.AGENT;
+        delete process.env.CODEX_CI;
+        stdoutSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+}
+export { getStdout, main, makeIterateResult, mockRunIterate, runIterate, 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.iterate.test-support.mjs

@@ -0,0 +1,49 @@
+// @ts-nocheck
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+vi.mock("./commands/check.mts", () => ({ runCheck: vi.fn() }));
+vi.mock("./commands/resolve.mts", () => ({
+    runResolveFetch: vi.fn(),
+    runResolveMutate: 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 { runIterate } from "./commands/iterate/index.mjs";
+import { formatIterateResult } from "./cli/iterate-formatter.mjs";
+import { makeIterateResult } from "./cli-parser.iterate-fixtures.mjs";
+const mockRunIterate = vi.mocked(runIterate);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let stdoutSpy;
+let stderrSpy;
+function getStdout() {
+    return stdoutSpy.mock.calls.map((c) => c[0]).join("");
+}
+function getStderr() {
+    return stderrSpy.mock.calls.map((c) => c[0]).join("");
+}
+// ---------------------------------------------------------------------------
+// iterate dispatch
+// ---------------------------------------------------------------------------
+export function registerHooks() {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        process.exitCode = undefined;
+        delete process.env.AGENT;
+        delete process.env.CODEX_CI;
+        stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+        stderrSpy = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    });
+    afterEach(() => {
+        process.exitCode = undefined;
+        delete process.env.AGENT;
+        delete process.env.CODEX_CI;
+        stdoutSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+}
+export { formatIterateResult, getStderr, getStdout, main, makeIterateResult, mockRunIterate, runIterate, stderrSpy, stdoutSpy, };

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;