pr-shepherd 0.16.4 → 0.18.0

package/bin/cli/iterate-lean.mjs

@@ -5,10 +5,9 @@ import { adaptIterateLog, adaptFixCodeInstructions, buildSimpleIterateInstructio
  * outside the state where they are meaningful.
  */
 export function projectIterateLean(result, opts) {
-    const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const runner = opts?.runner;
-    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, runner);
+    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, readyDelaySuffix, runner);
     const base = {
         action: result.action,
         pr: result.pr,
@@ -32,26 +31,27 @@ export function projectIterateLean(result, opts) {
             remainingSeconds: result.remainingSeconds,
         }),
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
+        ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
     };
     switch (result.action) {
         case "wait":
             return {
                 ...base,
-                log: adaptIterateLog(result.log, runtime),
+                log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
         case "cancel":
             return {
                 ...base,
                 reason: result.reason,
-                log: adaptIterateLog(result.log, runtime),
+                log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
         case "mark_ready":
             // drop markedReady — always true, redundant with action discriminator
             return {
                 ...base,
-                log: adaptIterateLog(result.log, runtime),
+                log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };
         case "fix_code":
@@ -94,7 +94,7 @@ export function projectIterateLean(result, opts) {
                     }),
                     resolveCommand: result.fix.resolveCommand,
                     ...(result.fix.instructions.length > 0 && {
-                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
+                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner),
                     }),
                 },
             };
@@ -124,7 +124,6 @@ export function projectIterateLean(result, opts) {
     }
 }
 export function projectIterateVerbose(result, opts) {
-    const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const runner = opts?.runner;
     if (result.action === "fix_code") {
@@ -132,16 +131,14 @@ export function projectIterateVerbose(result, opts) {
             ...result,
             fix: {
                 ...result.fix,
-                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
+                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner),
             },
         };
     }
-    const log = "log" in result && typeof result.log === "string"
-        ? { log: adaptIterateLog(result.log, runtime) }
-        : {};
+    const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
     return {
         ...result,
         ...log,
-        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner),
+        instructions: buildSimpleIterateInstructions(result, 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/poll-handler.mjs

@@ -0,0 +1,42 @@
+import { runPoll } from "../commands/poll.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
+import { parseDurationToSeconds } from "./exit-codes.mjs";
+import { validateSecondsDurationFlag } from "./duration-flag.mjs";
+import { parseIterateFlags } from "./iterate-flags.mjs";
+import { emitIterateResult } from "./iterate-emitter.mjs";
+const DEFAULT_POLL_INTERVAL_SECONDS = 30;
+const DEFAULT_POLL_TIMEOUT_SECONDS = 300;
+export async function handlePoll(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const cfg = loadConfig();
+    const flags = parseIterateFlags(extra, cfg);
+    if (flags.readyDelaySuffix === null)
+        return;
+    const intervalStr = getFlag(extra, "--interval");
+    const intervalSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--interval", intervalStr, hasFlag(extra, "--interval"));
+    if (intervalSuffix === null)
+        return;
+    const intervalSeconds = parseDurationToSeconds(intervalSuffix ?? "", DEFAULT_POLL_INTERVAL_SECONDS);
+    const timeoutStr = getFlag(extra, "--timeout");
+    const timeoutSuffix = validateSecondsDurationFlag("pr-shepherd poll", "--timeout", timeoutStr, hasFlag(extra, "--timeout"));
+    if (timeoutSuffix === null)
+        return;
+    const timeoutSeconds = parseDurationToSeconds(timeoutSuffix ?? "", DEFAULT_POLL_TIMEOUT_SECONDS);
+    const result = await runPoll({
+        ...globalOpts,
+        prNumber,
+        readyDelaySeconds: flags.readyDelaySeconds,
+        stallTimeoutSeconds: flags.stallTimeoutSeconds,
+        noAutoMarkReady: flags.noAutoMarkReady,
+        noAutoCancelActionable: flags.noAutoCancelActionable,
+        intervalSeconds,
+        timeoutSeconds,
+    });
+    emitIterateResult(result, {
+        format: globalOpts.format,
+        verbose: globalOpts.verbose ?? false,
+        readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
+        runner: cfg.cli?.runner,
+    });
+}

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

@@ -32,15 +32,11 @@ 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();
     });

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

@@ -13,6 +13,7 @@ export function makeIterateResult(action = "wait") {
         remainingSeconds: 60,
         summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 1 },
         baseBranch: "main",
+        branchProtection: null,
         checks: [],
     };
     if (action === "wait")
@@ -39,7 +40,9 @@ export function makeIterateResult(action = "wait") {
                     requiresDismissMessage: false,
                     hasMutations: false,
                 },
-                instructions: ["Stop this iteration before the next tick."],
+                instructions: [
+                    "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.",
+                ],
                 firstLookThreads: [],
                 firstLookComments: [],
                 inProgressRunIds: [],
@@ -64,7 +67,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

@@ -33,15 +33,11 @@ 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();
     });

package/bin/cli-parser.mjs

@@ -14,6 +14,10 @@
  *   pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]
  *                              [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                              [--no-auto-cancel-actionable]
+ *   pr-shepherd poll [PR] [--interval 30s] [--timeout 5m] [--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 +25,8 @@ 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 { handlePoll } from "./cli/poll-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
 // Entry
@@ -56,9 +61,15 @@ export async function main(argv) {
         case "iterate":
             await handleIterate(args.slice(1));
             break;
+        case "poll":
+            await handlePoll(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|poll|log-file|clean> [options]\n" +
                 "       pr-shepherd --version | -v\n");
             process.exitCode = 1;
             return;

package/bin/commands/check-terminal-report.mjs

@@ -31,5 +31,6 @@ export function buildTerminalReport(prNumber, repo, batchData, mergeStatus, stat
         firstLookSummaries: [],
         editedSummaries: [],
         approvedReviews: [],
+        branchProtection: batchData.branchProtection,
     };
 }

package/bin/commands/check.mjs

@@ -151,5 +151,6 @@ export async function runCheck(opts) {
         firstLookSummaries,
         editedSummaries,
         approvedReviews: batchData.approvedReviews,
+        branchProtection: batchData.branchProtection,
     };
 }

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

@@ -94,6 +94,7 @@ function makeBatchData(overrides = {}) {
         changesRequestedReviews: [],
         reviewSummaries: [],
         approvedReviews: [],
+        branchProtection: null,
         checks: [makeCheck()],
         ...overrides,
     };

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

@@ -68,6 +68,7 @@ function makeBatch(threads) {
         changesRequestedReviews: [],
         reviewSummaries: [],
         approvedReviews: [],
+        branchProtection: null,
     };
 }
 const FILE_CONTENT = "line1\n" +

package/bin/commands/commit-suggestion.test-support.mjs

@@ -76,6 +76,7 @@ function makeBatch(threads, headRepoWithOwner = "owner/repo") {
         changesRequestedReviews: [],
         reviewSummaries: [],
         approvedReviews: [],
+        branchProtection: null,
     };
 }
 const FILE_CONTENT = "line1\n" +

package/bin/commands/iterate/check-instructions.mjs

@@ -1,24 +1,26 @@
 export function buildFailingCheckInstructions(checks) {
-    const instructions = [];
-    const failedRunIdChecks = checks.filter((c) => c.runId && c.conclusion !== "CANCELLED" && c.conclusion !== "STARTUP_FAILURE");
-    const cancelledRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "CANCELLED");
-    const startupFailureRunIdChecks = checks.filter((c) => c.runId && c.conclusion === "STARTUP_FAILURE");
-    const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
-    const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
-    if (failedRunIdChecks.length > 0) {
-        instructions.push(`For each failing check under \`## Failing checks\` with a run ID and no \`[conclusion: CANCELLED]\` or \`[conclusion: STARTUP_FAILURE]\` tag: run \`gh run view <runId> --log-failed\` to fetch the failing job's log. If the log shows a transient infrastructure failure (network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\`. If the log shows a real test/build failure, apply a code fix.`);
+    if (checks.length === 0)
+        return [];
+    const hasRunId = checks.some((c) => c.runId && c.conclusion !== "CANCELLED" && c.conclusion !== "STARTUP_FAILURE");
+    const hasCancelled = checks.some((c) => c.runId && c.conclusion === "CANCELLED");
+    const hasStartupFailure = checks.some((c) => c.runId && c.conclusion === "STARTUP_FAILURE");
+    const hasExternal = checks.some((c) => !c.runId && c.detailsUrl);
+    const hasBare = checks.some((c) => !c.runId && !c.detailsUrl);
+    const parts = [];
+    if (hasRunId) {
+        parts.push("fetch the log with `gh run view <runId> --log-failed` and decide: rerun with `gh run rerun <runId> --failed` for transient infrastructure failures (network timeout, OOM kill, runner crash), or apply a code fix for real test/build failures");
     }
-    if (cancelledRunIdChecks.length > 0) {
-        instructions.push(`For each \`[conclusion: CANCELLED]\` bullet under \`## Failing checks\`: the run was cancelled outside Shepherd's control (manual cancel, newer push, concurrency-group eviction). Run \`gh run rerun <runId>\` only if the cancellation looks unintended; otherwise treat it as resolved by the superseding run. Do NOT confuse these with IDs under \`## Cancelled runs\` — those were cancelled by Shepherd itself.`);
+    if (hasCancelled) {
+        parts.push("for `[conclusion: CANCELLED]` entries: rerun with `gh run rerun <runId>` if the cancellation looks unintended (not superseded by a newer push or concurrency-group eviction); otherwise treat as resolved — do NOT confuse with IDs under `## Cancelled runs`");
     }
-    if (startupFailureRunIdChecks.length > 0) {
-        instructions.push(`For each \`[conclusion: STARTUP_FAILURE]\` bullet under \`## Failing checks\`: the workflow failed before jobs/logs were created. Run \`gh run view <runId>\` to inspect the run metadata, then run \`gh run rerun <runId>\` if the workflow should be attempted again.`);
+    if (hasStartupFailure) {
+        parts.push("for `[conclusion: STARTUP_FAILURE]` entries: inspect with `gh run view <runId>` and rerun with `gh run rerun <runId>` if the workflow should be retried");
     }
-    if (externalChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
+    if (hasExternal) {
+        parts.push("for `external` entries (no run ID, has URL): open the URL to inspect the failure");
     }
-    if (bareChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`(no runId)\`: there is no run or details URL to inspect. Escalate these to a human — they require manual investigation outside the pr-shepherd flow.`);
+    if (hasBare) {
+        parts.push("for `(no runId)` entries: no log or URL is available — escalate to a human for manual investigation");
     }
-    return instructions;
+    return [`For each failing check under \`## Failing checks\`: ${parts.join("; ")}.`];
 }