pr-shepherd 0.7.1 → 0.8.0

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

@@ -0,0 +1,97 @@
+import { readFixAttempts, writeFixAttempts } from "../../state/fix-attempts.mjs";
+import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
+import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
+import { classifyComments, buildResolveCommand } from "./classify.mjs";
+import { buildFixInstructions } from "./render.mjs";
+import { applyStallGuard } from "./stall.mjs";
+import { tryCancelRun } from "./helpers.mjs";
+export async function handleFixCode(ctx) {
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, surfacedSummaries, } = ctx;
+    const actionableChecks = report.checks.failing.filter((f) => f.failureKind === "actionable");
+    const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
+    const isNewSha = stored?.headSha !== headSha;
+    // Accumulate across shas — only increment when a push is detected (sha changed)
+    const currentAttempts = stored ? { ...stored.threadAttempts } : {};
+    if (isNewSha) {
+        for (const t of report.threads.actionable) {
+            currentAttempts[t.id] = (currentAttempts[t.id] ?? 0) + 1;
+        }
+    }
+    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, report.comments.actionable, report.changesRequestedReviews, actionableChecks, currentAttempts, report.mergeStatus.status === "CONFLICTS");
+    if (escalateTriggers.triggers.length > 0) {
+        const escalateBase = {
+            triggers: escalateTriggers.triggers,
+            unresolvedThreads: report.threads.actionable.map(toAgentThread),
+            ambiguousComments: report.comments.actionable.map(toAgentComment),
+            changesRequestedReviews: report.changesRequestedReviews,
+            attemptHistory: escalateTriggers.thrashHistory,
+            suggestion: buildEscalateSuggestion(escalateTriggers.triggers),
+        };
+        return {
+            ...base,
+            action: "escalate",
+            escalate: {
+                ...escalateBase,
+                humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+            },
+        };
+    }
+    // Save updated state (only incremented on sha change)
+    await writeFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber }, { headSha, threadAttempts: currentAttempts });
+    let cancelled = [];
+    if (!opts.noAutoCancelActionable) {
+        const uniqueRunIds = [
+            ...new Set(actionableChecks.map((c) => c.runId).filter((id) => id !== null)),
+        ];
+        const results = await Promise.all(uniqueRunIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
+        cancelled = results.filter((id) => id !== null);
+    }
+    const baseLookup = validateBaseBranch(report.baseBranch);
+    const threads = report.threads.actionable.map(toAgentThread);
+    const { actionable: actionableComments, noiseIds: noiseCommentIds } = classifyComments(report.comments.actionable.map(toAgentComment));
+    const checks = toAgentChecks(actionableChecks);
+    const { changesRequestedReviews } = report;
+    const hasConflicts = report.mergeStatus.status === "CONFLICTS";
+    const allCommentIds = [
+        ...actionableComments.map((c) => c.id),
+        ...noiseCommentIds,
+        ...reviewSummaryIds,
+    ];
+    const resolveCommand = buildResolveCommand(threads, actionableComments, allCommentIds, changesRequestedReviews, checks, prNumber);
+    if (baseLookup.isFallback && (resolveCommand.requiresHeadSha || hasConflicts)) {
+        const fallbackEscalateBase = {
+            triggers: ["base-branch-unknown"],
+            unresolvedThreads: threads,
+            ambiguousComments: actionableComments,
+            changesRequestedReviews,
+            suggestion: buildEscalateSuggestion(["base-branch-unknown"], baseLookup.failureReason),
+        };
+        return {
+            ...base,
+            action: "escalate",
+            escalate: {
+                ...fallbackEscalateBase,
+                humanMessage: buildEscalateHumanMessage(fallbackEscalateBase, prNumber),
+            },
+        };
+    }
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length);
+    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
+        ...base,
+        baseBranch: baseLookup.branch,
+        action: "fix_code",
+        fix: {
+            mode: "rebase-and-push",
+            threads,
+            actionableComments,
+            noiseCommentIds,
+            reviewSummaryIds,
+            surfacedSummaries,
+            checks,
+            changesRequestedReviews,
+            resolveCommand,
+            instructions,
+        },
+        cancelled,
+    }, report, reviewSummaryIds);
+}

package/bin/commands/iterate/helpers.mjs

@@ -0,0 +1,103 @@
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { rest } from "../../github/http.mjs";
+const execFile = promisify(execFileCb);
+export function buildSummary(report) {
+    return {
+        passing: report.checks.passing.length,
+        skipped: report.checks.skipped.length,
+        filtered: report.checks.filtered.length,
+        inProgress: report.checks.inProgress.length,
+    };
+}
+/**
+ * Build the full list of CI checks relevant to PR readiness: triggered by a PR
+ * event (or StatusContext with null event), completed, and not skipped/neutral.
+ * Includes both passing and failing. Failing entries carry failureKind + errorExcerpt.
+ */
+export function buildRelevantChecks(report) {
+    const excluded = new Set([null, "SKIPPED", "NEUTRAL"]);
+    const passing = report.checks.passing.flatMap((c) => {
+        if (excluded.has(c.conclusion))
+            return [];
+        const conclusion = c.conclusion;
+        return [
+            {
+                name: c.name,
+                conclusion,
+                runId: c.runId,
+                detailsUrl: c.detailsUrl || null,
+                summary: c.summary,
+            },
+        ];
+    });
+    const failing = report.checks.failing.flatMap((c) => {
+        if (excluded.has(c.conclusion))
+            return [];
+        const conclusion = c.conclusion;
+        return [
+            {
+                name: c.name,
+                conclusion,
+                runId: c.runId,
+                detailsUrl: c.detailsUrl || null,
+                failureKind: c.failureKind,
+                workflowName: c.workflowName,
+                failedStep: c.failedStep,
+                summary: c.summary,
+            },
+        ];
+    });
+    return [...passing, ...failing];
+}
+export async function getLastCommitTime() {
+    try {
+        const { stdout } = await execFile("git", ["log", "-1", "--format=%ct", "HEAD"]);
+        return parseInt(stdout.trim(), 10);
+    }
+    catch {
+        return null;
+    }
+}
+// Best-effort: cancelling a completed run is a no-op, not an error.
+export async function tryCancelRun(runId, owner, repo) {
+    try {
+        await rest("POST", `/repos/${owner}/${repo}/actions/runs/${runId}/cancel`);
+        return runId;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // GitHub returns 409 when the run reached a terminal state — expected, not worth logging.
+        if (/409|already completed|cannot cancel a workflow run that is completed/i.test(msg))
+            return null;
+        process.stderr.write(`pr-shepherd: cancel run ${runId} failed (ignored): ${msg}\n`);
+        return null;
+    }
+}
+export async function getCurrentHeadSha() {
+    try {
+        const { stdout } = await execFile("git", ["rev-parse", "HEAD"]);
+        return stdout.trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function buildCooldownResult(prNumber, readyDelaySeconds) {
+    return {
+        action: "cooldown",
+        pr: prNumber,
+        repo: "",
+        status: "UNKNOWN",
+        state: "UNKNOWN",
+        mergeStateStatus: "UNKNOWN",
+        copilotReviewInProgress: false,
+        isDraft: false,
+        shouldCancel: false,
+        remainingSeconds: readyDelaySeconds,
+        summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 0 },
+        baseBranch: "",
+        checks: [],
+        log: "SKIP: CI still starting — waiting for first check to appear",
+    };
+}

package/bin/commands/iterate/index.mjs

@@ -0,0 +1,122 @@
+import { runCheck } from "../check.mjs";
+import { updateReadyDelay } from "../ready-delay.mjs";
+import { getCurrentPrNumber } from "../../github/client.mjs";
+import { graphql } from "../../github/http.mjs";
+import { MARK_PR_READY_MUTATION } from "../../github/queries.mjs";
+import { loadConfig } from "../../config/load.mjs";
+import { getLastCommitTime, getCurrentHeadSha, buildSummary, buildRelevantChecks, buildCooldownResult, } from "./helpers.mjs";
+import { classifyReviewSummaries } from "./classify.mjs";
+import { applyStallGuard } from "./stall.mjs";
+import { buildWaitLog } from "./render.mjs";
+import { handleFixCode } from "./fix-code.mjs";
+import { buildRerunCiResult } from "./steps.mjs";
+export async function runIterate(opts) {
+    const config = loadConfig();
+    const cooldownSeconds = opts.cooldownSeconds ?? config.iterate.cooldownSeconds;
+    const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
+    const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
+    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
+    if (prNumber === null) {
+        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+    }
+    const optsWithPr = { ...opts, prNumber };
+    const lastCommitTime = await getLastCommitTime();
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (lastCommitTime !== null && nowSeconds - lastCommitTime < cooldownSeconds) {
+        return buildCooldownResult(prNumber, readyDelaySeconds);
+    }
+    const report = await runCheck({
+        ...optsWithPr,
+        autoResolve: config.actions.autoResolveOutdated,
+    });
+    if (report.mergeStatus.state !== "OPEN") {
+        const state = report.mergeStatus.state.toLowerCase();
+        return {
+            pr: report.pr,
+            repo: report.repo,
+            status: report.status,
+            mergeStateStatus: report.mergeStatus.mergeStateStatus,
+            copilotReviewInProgress: report.mergeStatus.copilotReviewInProgress,
+            isDraft: report.mergeStatus.isDraft,
+            shouldCancel: true,
+            remainingSeconds: 0,
+            state: report.mergeStatus.state,
+            summary: buildSummary(report),
+            baseBranch: report.baseBranch,
+            checks: buildRelevantChecks(report),
+            action: "cancel",
+            log: `CANCEL: PR #${report.pr} is ${state} — stopping monitor`,
+        };
+    }
+    const [repoOwner, repoName] = report.repo.split("/");
+    if (!repoOwner || !repoName) {
+        throw new Error(`Unexpected repo format: "${report.repo}" (expected "owner/name")`);
+    }
+    const isReady = report.status === "READY";
+    const readyState = await updateReadyDelay(report.pr, isReady, readyDelaySeconds, repoOwner, repoName);
+    const base = {
+        pr: report.pr,
+        repo: report.repo,
+        status: report.status,
+        state: report.mergeStatus.state,
+        mergeStateStatus: report.mergeStatus.mergeStateStatus,
+        copilotReviewInProgress: report.mergeStatus.copilotReviewInProgress,
+        isDraft: report.mergeStatus.isDraft,
+        shouldCancel: readyState.shouldCancel,
+        remainingSeconds: readyState.remainingSeconds,
+        summary: buildSummary(report),
+        baseBranch: report.baseBranch,
+        checks: buildRelevantChecks(report),
+    };
+    if (readyState.shouldCancel) {
+        return {
+            ...base,
+            action: "cancel",
+            log: `CANCEL: PR #${base.pr} has been ready for review — ready-delay elapsed, stopping monitor`,
+        };
+    }
+    const headSha = (await getCurrentHeadSha()) ?? "unknown";
+    const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
+    const { minimizeIds: reviewSummaryIds, surfacedSummaries } = classifyReviewSummaries(report.reviewSummaries, report.approvedReviews, config.iterate.minimizeReviewSummaries);
+    const actionableChecks = report.checks.failing.filter((f) => f.failureKind === "actionable");
+    const hasActionableWork = report.threads.actionable.length > 0 ||
+        report.comments.actionable.length > 0 ||
+        report.changesRequestedReviews.length > 0 ||
+        actionableChecks.length > 0 ||
+        report.mergeStatus.status === "CONFLICTS" ||
+        reviewSummaryIds.length > 0 ||
+        surfacedSummaries.length > 0;
+    if (hasActionableWork) {
+        return handleFixCode({
+            base,
+            report,
+            opts,
+            headSha,
+            stallKey,
+            prNumber,
+            stallTimeoutSeconds,
+            repoOwner,
+            repoName,
+            reviewSummaryIds,
+            surfacedSummaries,
+        });
+    }
+    const transientChecks = report.checks.failing.filter((f) => (f.failureKind === "timeout" || f.failureKind === "cancelled") && f.runId !== null);
+    if (transientChecks.length > 0) {
+        return buildRerunCiResult(transientChecks, base, prNumber, stallKey, stallTimeoutSeconds, headSha, report, reviewSummaryIds);
+    }
+    const canMarkReady = report.status === "READY" &&
+        report.mergeStatus.isDraft &&
+        !report.mergeStatus.copilotReviewInProgress &&
+        !readyState.shouldCancel;
+    if (canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady) {
+        await graphql(MARK_PR_READY_MUTATION, { pullRequestId: report.nodeId });
+        return {
+            ...base,
+            action: "mark_ready",
+            markedReady: true,
+            log: `MARKED READY: PR #${report.pr} converted from draft to ready for review`,
+        };
+    }
+    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, { ...base, action: "wait", log: buildWaitLog(base) }, report, reviewSummaryIds);
+}

package/bin/commands/iterate/render.mjs

@@ -0,0 +1,119 @@
+/**
+ * Render a ResolveCommand as a single-line command string for the monitor loop
+ * to print or execute. This is NOT a general-purpose POSIX escaper — it wraps
+ * the two known placeholders ($DISMISS_MESSAGE, $HEAD_SHA) and any whitespace-
+ * bearing arg in double quotes so multi-word values don't split across flags.
+ *
+ * Contract for callers substituting placeholders: replace the entire quoted
+ * token (including the surrounding `"`) with a properly shell-quoted literal.
+ * Do not splice raw text inside the existing quotes — the output would then
+ * re-expand `$…` / `$(…)` / embedded `"` and break.
+ */
+export function renderResolveCommand(rc) {
+    // `$HEAD_SHA` is never in `rc.argv` — it is appended pre-quoted below when
+    // `requiresHeadSha`. Only `$DISMISS_MESSAGE` (or whitespace-bearing values)
+    // need quoting here.
+    const needsQuoting = (arg) => {
+        if (arg === "$DISMISS_MESSAGE")
+            return true;
+        // Assert no characters that would break the naive escaper are present in arg
+        if (/["$`\\]/.test(arg)) {
+            throw new Error(`Unexpected character in argv arg that needsQuoting can't handle: ${JSON.stringify(arg)}`);
+        }
+        return /\s/.test(arg);
+    };
+    const parts = rc.argv.map((a) => (needsQuoting(a) ? `"${a}"` : a));
+    if (rc.requiresHeadSha) {
+        parts.push("--require-sha", '"$HEAD_SHA"');
+    }
+    return parts.join(" ");
+}
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount) {
+    const instructions = [];
+    if (threads.length > 0 || actionableComments.length > 0) {
+        instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.`);
+    }
+    // Mirror the truthiness checks in `formatIterateResult` (cli/iterate-formatter.mts) so each
+    // AgentCheck maps to the same bullet shape here as there: runId → runId
+    // bullet, else detailsUrl → external bullet, else `(no runId)` bullet.
+    const checksWithRunId = checks.filter((c) => c.runId);
+    const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
+    const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
+    if (checksWithRunId.length > 0) {
+        instructions.push(`For each bullet in \`## Failing checks\` whose backticked locator is a numeric runId (GitHub Actions): run \`gh run view <runId> --log-failed\`, identify the failure, and apply the fix.`);
+    }
+    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 — \`gh run view\` cannot fetch logs for external checks.`);
+    }
+    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 (reviews.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 || actionableComments.length > 0 || checks.length > 0 || reviews.length > 0;
+    const needsPush = hasCodeChanges || hasConflicts;
+    if (hasCodeChanges) {
+        instructions.push(`Commit changed files: \`git add <files> && git commit -m "<descriptive message>"\``);
+        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) {
+        const captureHint = resolveCommand.requiresHeadSha
+            ? ` — capture \`HEAD_SHA=$(git rev-parse HEAD)\``
+            : "";
+        if (hasConflicts) {
+            instructions.push(`Rebase with conflict resolution: run \`git fetch origin && git rebase origin/${baseBranch}\`. If the rebase halts with conflicts, edit the conflicted files to resolve them, \`git add <files>\`, then \`git rebase --continue\`. Repeat until the rebase completes, then \`git push --force-with-lease\`${captureHint}.`);
+        }
+        else {
+            instructions.push(`Rebase and push: \`git fetch origin && git rebase origin/${baseBranch} && git push --force-with-lease\`${captureHint}`);
+        }
+    }
+    // Only tell the agent to run `resolve:` if the command actually mutates
+    // GitHub state. A CONFLICTS-only flow has nothing to mutate on GitHub.
+    if (resolveCommand.hasMutations) {
+        const substituteParts = [];
+        if (resolveCommand.requiresHeadSha) {
+            substituteParts.push(`"$HEAD_SHA" with the pushed commit SHA`);
+        }
+        if (resolveCommand.requiresDismissMessage) {
+            substituteParts.push(`$DISMISS_MESSAGE with a one-sentence description of what you changed`);
+        }
+        const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
+        instructions.push(`Run the \`resolve:\` command shown above${substituteHint}.`);
+    }
+    if (needsPush && cancelledCount > 0) {
+        instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — the CLI cancelled those runs before your push, and your push has already triggered new runs with different IDs.`);
+    }
+    if (needsPush) {
+        instructions.push(`Stop this iteration — CI needs time to run on the new push before the next tick.`);
+    }
+    else if (resolveCommand.hasMutations) {
+        instructions.push(`Stop this iteration before the next tick.`);
+    }
+    else {
+        instructions.push(`End this iteration.`);
+    }
+    return instructions;
+}
+export function buildWaitLog(base) {
+    const { summary, mergeStateStatus, remainingSeconds } = base;
+    const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
+    switch (mergeStateStatus) {
+        case "BEHIND":
+            parts.push("branch is behind base");
+            break;
+        case "BLOCKED":
+            parts.push("blocked by pending reviews or required status checks");
+            break;
+        case "DRAFT":
+            parts.push("PR is a draft");
+            break;
+        case "UNSTABLE":
+            parts.push("some checks are unstable");
+            break;
+    }
+    if (remainingSeconds > 0) {
+        parts.push(`${remainingSeconds}s until auto-cancel`);
+    }
+    return parts.join(" — ");
+}

package/bin/commands/iterate/stall.mjs

@@ -0,0 +1,65 @@
+import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
+import { toAgentThread, toAgentComment } from "../../reporters/agent.mjs";
+import { buildEscalateSuggestion, buildEscalateHumanMessage } from "./escalate.mjs";
+export function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
+    const checks = [
+        ...report.checks.failing.map((f) => `failing:${f.name}:${f.failureKind ?? ""}`),
+        ...report.checks.inProgress.map((p) => `inProgress:${p.name}`),
+    ].sort();
+    const threads = report.threads.actionable.map((t) => t.id).sort();
+    const comments = report.comments.actionable.map((c) => c.id).sort();
+    const reviews = report.changesRequestedReviews.map((r) => r.id).sort();
+    const summaries = [...reviewSummaryIds].sort();
+    return JSON.stringify({
+        action,
+        headSha,
+        status: base.status,
+        mergeStateStatus: base.mergeStateStatus,
+        state: base.state,
+        isDraft: base.isDraft,
+        checks,
+        threads,
+        comments,
+        reviews,
+        summaries,
+    });
+}
+export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {
+    const fingerprint = computeStallFingerprint(prospectiveResult.action, headSha, base, report, reviewSummaryIds);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const stored = await readStallState(stallKey);
+    if (stored && stored.fingerprint === fingerprint) {
+        const ageSeconds = nowSeconds - stored.firstSeenAt;
+        if (ageSeconds < 0) {
+            // Clock skew: stored timestamp is in the future. Reset to avoid perpetually negative age.
+            await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
+        }
+        else if (stallTimeoutSeconds <= 0) {
+            // Stall detection disabled: refresh so re-enabling starts a fresh timer.
+            await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
+        }
+        else if (ageSeconds >= stallTimeoutSeconds) {
+            const stalledMinutes = Math.floor(ageSeconds / 60);
+            const escalateBase = {
+                triggers: ["stall-timeout"],
+                unresolvedThreads: report.threads.actionable.map(toAgentThread),
+                ambiguousComments: report.comments.actionable.map(toAgentComment),
+                changesRequestedReviews: report.changesRequestedReviews,
+                suggestion: buildEscalateSuggestion(["stall-timeout"], String(stalledMinutes)),
+            };
+            return {
+                ...base,
+                action: "escalate",
+                escalate: {
+                    ...escalateBase,
+                    humanMessage: buildEscalateHumanMessage(escalateBase, prNumber),
+                },
+            };
+        }
+        // Within threshold: preserve firstSeenAt, emit the original result.
+        return prospectiveResult;
+    }
+    // Fingerprint changed or no prior state — reset the stall timer.
+    await writeStallState(stallKey, { fingerprint, firstSeenAt: nowSeconds });
+    return prospectiveResult;
+}

package/bin/commands/iterate/steps.mjs

@@ -0,0 +1,31 @@
+import { applyStallGuard } from "./stall.mjs";
+export async function buildRerunCiResult(transientChecks, base, prNumber, stallKey, stallTimeoutSeconds, headSha, report, reviewSummaryIds) {
+    const runMap = new Map();
+    for (const c of transientChecks) {
+        if (c.runId === null)
+            continue;
+        const existing = runMap.get(c.runId);
+        if (existing) {
+            existing.checkNames.push(c.name);
+        }
+        else {
+            runMap.set(c.runId, {
+                runId: c.runId,
+                checkNames: [c.name],
+                failureKind: c.failureKind,
+                workflowName: c.workflowName,
+            });
+        }
+    }
+    const reran = [...runMap.values()];
+    const runSummaries = reran.map(({ runId, checkNames, failureKind, workflowName }) => {
+        const prefix = workflowName ? `${workflowName} › ` : "";
+        return `${runId} (${prefix}${checkNames.join(", ")} — ${failureKind})`;
+    });
+    return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
+        ...base,
+        action: "rerun_ci",
+        reran,
+        log: `RERUN NEEDED — ${reran.length} CI run${reran.length === 1 ? "" : "s"}: ${runSummaries.join(", ")}`,
+    }, report, reviewSummaryIds);
+}