pr-shepherd 0.2.0 → 0.3.0

package/dist/commands/iterate.mjs

@@ -0,0 +1,295 @@
+/**
+ * `shepherd iterate [PR]`
+ *
+ * One-shot iteration that rolls cooldown + sweep + deterministic dispatch
+ * into a single call, emitting compact JSON.
+ *
+ * Decision order:
+ *   1. cooldown   — last commit is < cooldownSeconds old
+ *   2. sweep      — fetch CI + comments + merge status, auto-resolve outdated
+ *   2.5 cancel    — state !== OPEN (PR merged or closed)
+ *   3. cancel     — readyState.shouldCancel
+ *   4. fix_code   — actionable threads, comments, CI failures, CHANGES_REQUESTED, or CONFLICTS
+ *                   (fix_code handler does fetch+rebase+push — all actionable work in one push)
+ *   5. rerun_ci   — timeout / infrastructure failures only (no actionable work, no conflicts)
+ *   6. rebase     — flaky failure + branch BEHIND
+ *   7. mark_ready — READY + CLEAN + draft + not shouldCancel (converts draft to ready)
+ *   8. wait       — nothing to do
+ *
+ * Exit codes:
+ *   0  wait / cooldown / rerun_ci / mark_ready
+ *   1  fix_code / rebase
+ *   2  cancel
+ */
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { runCheck } from "./check.mjs";
+import { triageFailingChecks } from "../checks/triage.mjs";
+import { updateReadyDelay } from "./ready-delay.mjs";
+import { getCurrentPrNumber } from "../github/client.mjs";
+import { readFixAttempts, writeFixAttempts } from "../cache/fix-attempts.mjs";
+import { toAgentThread, toAgentComment, toAgentChecks } from "../reporters/agent.mjs";
+import { loadConfig } from "../config/load.mjs";
+const execFile = promisify(execFileCb);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export async function runIterate(opts) {
+    const config = loadConfig();
+    const cooldownSeconds = opts.cooldownSeconds ?? config.iterate.cooldownSeconds;
+    const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
+    // Resolve prNumber early so the cooldown result carries a valid PR number.
+    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 };
+    // Step 1: Cooldown — skip if last commit is too fresh.
+    const lastCommitTime = await getLastCommitTime();
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (nowSeconds - lastCommitTime < cooldownSeconds) {
+        // We don't have a report yet — return a minimal cooldown result.
+        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 },
+        };
+    }
+    // Step 2: Sweep — fetch CI + comments + merge status, auto-resolve outdated.
+    // skipTriage defers log fetching until we know we'll need failureKind (steps 4–6).
+    let report = await runCheck({
+        ...optsWithPr,
+        autoResolve: config.actions.autoResolveOutdated,
+        skipTriage: true,
+    });
+    // Step 2.5: Cancel if PR is merged or closed — no longer actionable.
+    if (report.mergeStatus.state !== "OPEN") {
+        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),
+            action: "cancel",
+        };
+    }
+    // Step 3: Ready-delay state machine.
+    const [repoOwner, repoName] = report.repo.split("/");
+    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),
+    };
+    // Step 3 cont.: cancel if ready-delay elapsed.
+    if (readyState.shouldCancel) {
+        return { ...base, action: "cancel" };
+    }
+    // Triage failing checks now that we know we need failureKind for steps 4–6.
+    if (report.checks.failing.length > 0) {
+        const triaged = await triageFailingChecks(report.checks.failing);
+        report = { ...report, checks: { ...report.checks, failing: triaged } };
+    }
+    // Step 4: Actionable work — fix comments, review requests, CI failures, and merge
+    // conflicts all in one push. CONFLICTS is included here because the fix_code handler
+    // already runs fetch+rebase+push, so conflicts are resolved as part of that flow.
+    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";
+    if (hasActionableWork) {
+        // Load fix-attempt counts, resetting if HEAD SHA changed (new commit pushed).
+        const headSha = await getCurrentHeadSha();
+        const attemptsKey = { owner: repoOwner, repo: repoName, pr: prNumber };
+        const stored = await readFixAttempts(attemptsKey);
+        const attempts = stored?.headSha === headSha
+            ? stored
+            : { headSha, threadAttempts: {} };
+        // Escalation checks — surface ambiguous situations instead of looping forever.
+        const escalateTriggers = checkEscalateTriggers(report.threads.actionable, report.comments.actionable, report.changesRequestedReviews, actionableChecks, attempts.threadAttempts, report.mergeStatus.status === "CONFLICTS");
+        if (escalateTriggers.triggers.length > 0) {
+            return {
+                ...base,
+                action: "escalate",
+                escalate: {
+                    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),
+                },
+            };
+        }
+        // Increment attempt counts for this dispatch cycle.
+        const newThreadAttempts = { ...attempts.threadAttempts };
+        for (const t of report.threads.actionable) {
+            newThreadAttempts[t.id] = (newThreadAttempts[t.id] ?? 0) + 1;
+        }
+        await writeFixAttempts(attemptsKey, { headSha, threadAttempts: newThreadAttempts });
+        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)));
+            cancelled = results.filter((id) => id !== null);
+        }
+        return {
+            ...base,
+            action: "fix_code",
+            fix: {
+                threads: report.threads.actionable.map(toAgentThread),
+                comments: report.comments.actionable.map(toAgentComment),
+                checks: toAgentChecks(actionableChecks),
+                changesRequestedReviews: report.changesRequestedReviews,
+            },
+            cancelled,
+        };
+    }
+    // Step 5: Transient failures (timeout / infrastructure) — no actionable work, no conflicts.
+    const transientChecks = report.checks.failing.filter((f) => f.failureKind === "timeout" || f.failureKind === "infrastructure");
+    if (transientChecks.length > 0 && !opts.noAutoRerun) {
+        // Deduplicate runIds — multiple failed steps can share the same runId.
+        const uniqueRunIds = [
+            ...new Set(transientChecks.map((c) => c.runId).filter((id) => id !== null)),
+        ];
+        await Promise.all(uniqueRunIds.map((runId) => runGhCommand(["run", "rerun", runId, "--failed"])));
+        return { ...base, action: "rerun_ci", reran: uniqueRunIds };
+    }
+    // Step 6: Flaky + behind — rebase needed.
+    const hasFlaky = report.checks.failing.some((f) => f.failureKind === "flaky");
+    if (hasFlaky && report.mergeStatus.status === "BEHIND" && config.actions.autoRebase) {
+        return { ...base, action: "rebase" };
+    }
+    // Step 7: Mark ready for review.
+    // Draft PRs often report mergeStateStatus === 'DRAFT' rather than 'CLEAN' until
+    // they're explicitly marked ready, so we allow either state when isDraft is true.
+    const mergeStateAllowsMarkReady = report.mergeStatus.mergeStateStatus === "CLEAN" ||
+        (report.mergeStatus.mergeStateStatus === "DRAFT" && report.mergeStatus.isDraft);
+    const canMarkReady = report.status === "READY" &&
+        mergeStateAllowsMarkReady &&
+        !report.mergeStatus.copilotReviewInProgress &&
+        !readyState.shouldCancel &&
+        report.mergeStatus.isDraft;
+    if (canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady) {
+        await runGhCommand(["pr", "ready", String(report.pr)]);
+        return { ...base, action: "mark_ready", markedReady: true };
+    }
+    // Step 8: Nothing to do.
+    return { ...base, action: "wait" };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildSummary(report) {
+    return {
+        passing: report.checks.passing.length,
+        skipped: report.checks.skipped.length,
+        filtered: report.checks.filtered.length,
+        inProgress: report.checks.inProgress.length,
+    };
+}
+async function getLastCommitTime() {
+    try {
+        const { stdout } = await execFile("git", ["log", "-1", "--format=%ct", "HEAD"]);
+        return parseInt(stdout.trim(), 10);
+    }
+    catch {
+        return 0;
+    }
+}
+async function runGhCommand(args) {
+    try {
+        await execFile("gh", args);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`gh ${args.join(" ")} failed: ${msg}`, { cause: err });
+    }
+}
+// Best-effort: cancelling a completed run is a no-op, not an error.
+async function tryCancelRun(runId) {
+    try {
+        await execFile("gh", ["run", "cancel", runId]);
+        return runId;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`pr-shepherd: gh run cancel ${runId} failed (ignored): ${msg}\n`);
+        return null;
+    }
+}
+async function getCurrentHeadSha() {
+    try {
+        const { stdout } = await execFile("git", ["rev-parse", "HEAD"]);
+        return stdout.trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+function checkEscalateTriggers(actionableThreads, actionableComments, changesRequestedReviews, actionableChecks, threadAttempts, hasConflicts) {
+    const triggers = [];
+    const maxAttempts = loadConfig().iterate.fixAttemptsPerThread;
+    // Trigger 1: fix thrash — same thread dispatched too many times without resolving.
+    const thrashThreads = actionableThreads.filter((t) => (threadAttempts[t.id] ?? 0) >= maxAttempts);
+    if (thrashThreads.length > 0) {
+        triggers.push("fix-thrash");
+    }
+    // Trigger 2: PR-level CHANGES_REQUESTED with no inline threads/comments/CI to act on.
+    // Skip when there are merge conflicts — fix_code handles conflict resolution, not escalation.
+    if (changesRequestedReviews.length > 0 &&
+        actionableThreads.length === 0 &&
+        actionableComments.length === 0 &&
+        actionableChecks.length === 0 &&
+        !hasConflicts) {
+        triggers.push("pr-level-changes-requested");
+    }
+    // Trigger 3: actionable thread has no file/line — cannot locate code to edit.
+    const unlocatable = actionableThreads.filter((t) => t.path === null || t.line === null);
+    if (unlocatable.length > 0) {
+        triggers.push("thread-missing-location");
+    }
+    return {
+        triggers,
+        thrashHistory: thrashThreads.length > 0
+            ? thrashThreads.map((t) => ({ threadId: t.id, attempts: threadAttempts[t.id] ?? 0 }))
+            : undefined,
+    };
+}
+function buildEscalateSuggestion(triggers) {
+    if (triggers.includes("fix-thrash")) {
+        return "Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:monitor";
+    }
+    if (triggers.includes("pr-level-changes-requested")) {
+        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 "Ambiguous state — inspect the PR and act manually";
+}

package/dist/commands/ready-delay.mjs

@@ -0,0 +1,87 @@
+/**
+ * Ready-delay state machine for the shepherd iterate loop.
+ *
+ * When all READY conditions hold, shepherd writes a `ready-since.txt` marker
+ * to the cache dir. The loop continues until the PR has been READY for
+ * `readyDelaySeconds` consecutively. Any not-READY result resets the timer.
+ */
+import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+/**
+ * Update the ready-delay state machine and return the current decision.
+ *
+ * Call this at the end of each sweep iteration:
+ *   - If `isReady == true`: start or continue the ready timer.
+ *   - If `isReady == false`: reset the timer.
+ *
+ * When `shouldCancel == true`, the slash command should invoke `/loop cancel`.
+ */
+export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo) {
+    const markerPath = readySincePath(prNumber, owner, repo);
+    if (!isReady) {
+        // Reset the timer.
+        await safeUnlink(markerPath);
+        return { isReady: false, shouldCancel: false, remainingSeconds: readyDelaySeconds };
+    }
+    // PR is READY — check or create the marker.
+    const now = Math.floor(Date.now() / 1000);
+    let readySince;
+    try {
+        const raw = await readFile(markerPath, "utf8");
+        readySince = parseInt(raw.trim(), 10);
+        // Reset if the stored value is not finite or is in the future (clock skew,
+        // corrupted file, or manual edit). A future timestamp would produce a
+        // negative elapsed value and an inflated remainingSeconds.
+        if (!Number.isFinite(readySince) || readySince > now) {
+            readySince = now;
+            await safeWriteFile(markerPath, String(now));
+        }
+    }
+    catch {
+        // Marker doesn't exist yet — create it.
+        readySince = now;
+        await safeWriteFile(markerPath, String(now));
+    }
+    const elapsed = now - readySince;
+    const remaining = readyDelaySeconds - elapsed;
+    if (remaining <= 0) {
+        // Leave the marker in place so future sweeps also return shouldCancel:true
+        // until the PR drops out of READY state (which resets via safeUnlink above).
+        return { isReady: true, shouldCancel: true, remainingSeconds: 0 };
+    }
+    return { isReady: true, shouldCancel: false, remainingSeconds: remaining };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function readySincePath(pr, owner, repo) {
+    for (const [field, value] of [
+        ["owner", owner],
+        ["repo", repo],
+    ]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`Invalid path segment "${field}": ${value}`);
+        }
+    }
+    const base = process.env["PR_SHEPHERD_CACHE_DIR"] ?? join(tmpdir(), "pr-shepherd-cache");
+    return join(base, `${owner}-${repo}`, String(pr), "ready-since.txt");
+}
+async function safeUnlink(path) {
+    try {
+        await unlink(path);
+    }
+    catch {
+        // Ignore — file may not exist.
+    }
+}
+async function safeWriteFile(path, content) {
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, content, "utf8");
+    }
+    catch {
+        // Best-effort.
+    }
+}

package/dist/commands/resolve.mjs

@@ -0,0 +1,64 @@
+/**
+ * `shepherd resolve [PR] [flags]`
+ *
+ * Two modes:
+ *
+ *   Fetch mode (--fetch or no mutation flags):
+ *     Auto-resolves outdated threads and returns all active threads,
+ *     visible comments, and CHANGES_REQUESTED reviews for LLM triage.
+ *     Sonnet reads this output, applies code fixes, pushes, then calls
+ *     resolve in mutation mode to resolve/minimize/dismiss by ID.
+ *
+ *   Mutation mode (--resolve-thread-ids, --minimize-comment-ids, --dismiss-review-ids):
+ *     Resolves/minimizes/dismisses by ID. Optionally verifies the push
+ *     has landed on GitHub before mutating (--require-sha).
+ */
+import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
+import { fetchPrBatch } from "../github/batch.mjs";
+import { getOutdatedThreads } from "../comments/outdated.mjs";
+import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mjs";
+/**
+ * Fetch mode: auto-resolve outdated threads and return all active items for LLM triage.
+ */
+export async function runResolveFetch(opts) {
+    const repo = await getRepoInfo();
+    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
+    if (prNumber === null) {
+        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+    }
+    // Always bypass cache for resolve — we need fresh data before mutating.
+    const { data } = await fetchPrBatch(prNumber, repo);
+    const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved);
+    const visibleComments = data.comments.filter((c) => !c.isMinimized);
+    // Auto-resolve outdated.
+    const outdated = getOutdatedThreads(unresolvedThreads);
+    let autoResolved = [];
+    if (outdated.length > 0) {
+        const { resolved: resolvedIds } = await autoResolveOutdated(outdated.map((t) => t.id));
+        autoResolved = outdated.filter((t) => resolvedIds.includes(t.id));
+    }
+    const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
+    return {
+        autoResolved,
+        actionableThreads: activeThreads,
+        actionableComments: visibleComments,
+        changesRequestedReviews: data.changesRequestedReviews,
+    };
+}
+/**
+ * Mutation mode: resolve/minimize/dismiss by ID.
+ */
+export async function runResolveMutate(opts) {
+    const repo = await getRepoInfo();
+    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
+    if (prNumber === null) {
+        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+    }
+    return applyResolveOptions(prNumber, repo, {
+        resolveThreadIds: opts.resolveThreadIds,
+        minimizeCommentIds: opts.minimizeCommentIds,
+        dismissReviewIds: opts.dismissReviewIds,
+        dismissMessage: opts.dismissMessage,
+        requireSha: opts.requireSha,
+    });
+}

package/dist/commands/status.mjs

@@ -0,0 +1,107 @@
+/**
+ * `shepherd status PR1 [PR2 PR3 …]`
+ *
+ * Fetches readiness status for one or more PRs and prints a table.
+ * Uses a separate lightweight GraphQL query (MULTI_PR_STATUS_QUERY) per PR
+ * rather than the heavy batch query, since we only need summary data.
+ *
+ * Exit code: 0 if all PRs are READY, non-zero otherwise.
+ */
+import { graphql, getRepoInfo } from "../github/client.mjs";
+import { MULTI_PR_STATUS_QUERY, MULTI_PR_STATUS_QUERY_WITH_CURSOR } from "../github/queries.mjs";
+export async function runStatus(opts) {
+    const repo = await getRepoInfo();
+    const summaries = await Promise.all(opts.prNumbers.map((pr) => fetchSummary(pr, repo.owner, repo.name)));
+    return summaries;
+}
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+async function fetchSummary(pr, owner, repo) {
+    const result = await graphql(MULTI_PR_STATUS_QUERY, {
+        owner,
+        repo,
+        pr,
+    });
+    const p = result.data.repository.pullRequest;
+    if (!p) {
+        throw new Error(`PR #${pr} not found in ${owner}/${repo}`);
+    }
+    let allNodes = p.reviewThreads.nodes;
+    // If the response was truncated, fetch additional pages to get the full count.
+    if (p.reviewThreads.totalCount > p.reviewThreads.nodes.length) {
+        // Fetch additional pages backward until we have all threads.
+        let cursor = p.reviewThreads.pageInfo?.startCursor ?? null;
+        while (cursor !== null) {
+            // eslint-disable-next-line no-await-in-loop
+            const extra = await graphql(MULTI_PR_STATUS_QUERY_WITH_CURSOR, {
+                owner,
+                repo,
+                pr,
+                cursor,
+            });
+            const p2 = extra.data.repository.pullRequest;
+            if (!p2)
+                break;
+            allNodes = [...p2.reviewThreads.nodes, ...allNodes];
+            if (!p2.reviewThreads.pageInfo?.hasPreviousPage || !p2.reviewThreads.pageInfo.startCursor) {
+                break;
+            }
+            cursor = p2.reviewThreads.pageInfo.startCursor;
+        }
+    }
+    const unresolvedThreads = allNodes.filter((n) => !n.isResolved).length;
+    const ciState = p.commits.nodes[0]?.commit.statusCheckRollup?.state ?? null;
+    // If we still have fewer nodes than totalCount, report truncation.
+    const threadsTruncated = p.reviewThreads.totalCount > allNodes.length;
+    return {
+        number: p.number,
+        title: p.title,
+        state: p.state,
+        isDraft: p.isDraft,
+        mergeStateStatus: p.mergeStateStatus,
+        reviewDecision: p.reviewDecision,
+        unresolvedThreads,
+        ciState,
+        threadsTruncated,
+    };
+}
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+export function formatStatusTable(summaries, repoFull) {
+    const lines = [`\n# ${repoFull} — PR status (${summaries.length})\n`];
+    for (const s of summaries) {
+        const verdict = deriveVerdict(s);
+        const ciLabel = s.ciState ?? "—";
+        const title = s.title.slice(0, 50);
+        const truncNote = s.threadsTruncated
+            ? " (threads truncated — run shepherd check for full count)"
+            : "";
+        lines.push(`PR #${String(s.number).padEnd(5)} ${title.padEnd(52)} ${verdict.padEnd(12)} ${ciLabel}${truncNote}`);
+    }
+    return lines.join("\n");
+}
+export function deriveVerdict(s) {
+    if (s.state === "MERGED")
+        return "MERGED";
+    if (s.state === "CLOSED")
+        return "CLOSED";
+    if (s.isDraft)
+        return "DRAFT";
+    if (s.mergeStateStatus === "CLEAN" &&
+        s.unresolvedThreads === 0 &&
+        s.ciState === "SUCCESS" &&
+        s.reviewDecision !== "CHANGES_REQUESTED") {
+        return "READY";
+    }
+    if (s.mergeStateStatus === "BLOCKED")
+        return "BLOCKED";
+    if (s.mergeStateStatus === "DIRTY")
+        return "CONFLICTS";
+    if (s.ciState === "PENDING" || s.ciState === "EXPECTED")
+        return "IN PROGRESS";
+    if (s.ciState === "FAILURE" || s.ciState === "ERROR")
+        return "FAILING";
+    return s.mergeStateStatus;
+}

package/{src/comments/outdated.mts → dist/comments/outdated.mjs}

@@ -9,10 +9,7 @@
  * enough that the comment no longer points to a live diff line. These threads
  * are visually collapsed on GitHub and are safe to resolve programmatically.
  */
-
-import type { ReviewThread } from "../types.mts";
-
 /** Returns the subset of threads that should be auto-resolved as outdated. */
-export function getOutdatedThreads(threads: ReviewThread[]): ReviewThread[] {
-  return threads.filter((t) => t.isOutdated && !t.isResolved);
+export function getOutdatedThreads(threads) {
+    return threads.filter((t) => t.isOutdated && !t.isResolved);
 }

package/dist/comments/resolve.mjs

@@ -0,0 +1,113 @@
+/**
+ * Batched mutations for resolving threads, minimizing comments, and dismissing reviews.
+ *
+ * The three mutation types (resolve / minimize / dismiss) are run sequentially so total
+ * in-flight mutations never exceed CONCURRENCY at once, keeping us well within GitHub's
+ * secondary rate-limit window.
+ *
+ * Push-before-resolve safety:
+ *   When `requireSha` is set, shepherd verifies that GitHub has received that
+ *   commit before issuing any resolve/dismiss mutations. It polls up to 20 seconds.
+ *   If the push hasn't landed, shepherd throws rather than resolving prematurely
+ *   (which could allow auto-merge before reviewers see the fix).
+ */
+import { graphql, getPrHeadSha } from "../github/client.mjs";
+import { RESOLVE_THREAD_MUTATION, MINIMIZE_COMMENT_MUTATION, DISMISS_REVIEW_MUTATION, } from "../github/queries.mjs";
+import { loadConfig } from "../config/load.mjs";
+const config = loadConfig();
+const CONCURRENCY = config.resolve.concurrency;
+const SHA_POLL_INTERVAL_MS = config.resolve.shaPoll.intervalMs;
+const SHA_POLL_MAX_ATTEMPTS = config.resolve.shaPoll.maxAttempts;
+/**
+ * Execute all requested resolve/minimize/dismiss mutations.
+ *
+ * @throws Error if `requireSha` is set and GitHub hasn't received that commit
+ *              within the polling window.
+ */
+export async function applyResolveOptions(pr, repo, opts) {
+    // Require --message when dismissing reviews.
+    if ((opts.dismissReviewIds?.length ?? 0) > 0 && !opts.dismissMessage) {
+        throw new Error("--message is required when dismissing reviews");
+    }
+    // Safety check: verify the push landed before resolving.
+    if (opts.requireSha) {
+        await waitForSha(pr, repo, opts.requireSha);
+    }
+    const result = {
+        resolvedThreads: [],
+        minimizedComments: [],
+        dismissedReviews: [],
+        errors: [],
+    };
+    await runBatched(opts.resolveThreadIds ?? [], (id) => resolveThread(id), result.resolvedThreads, result.errors);
+    await runBatched(opts.minimizeCommentIds ?? [], (id) => minimizeComment(id, "RESOLVED"), result.minimizedComments, result.errors);
+    await runBatched(opts.dismissReviewIds ?? [], (id) => dismissReview(id, opts.dismissMessage), result.dismissedReviews, result.errors);
+    return result;
+}
+/**
+ * Auto-resolve a batch of outdated threads via the resolveReviewThread mutation.
+ */
+export async function autoResolveOutdated(threadIds) {
+    const resolved = [];
+    const errors = [];
+    await runBatched(threadIds, (id) => resolveThread(id), resolved, errors);
+    return { resolved, errors };
+}
+// ---------------------------------------------------------------------------
+// Mutation helpers
+// ---------------------------------------------------------------------------
+async function resolveThread(threadId) {
+    await graphql(RESOLVE_THREAD_MUTATION, { threadId });
+}
+async function minimizeComment(commentId, classifier) {
+    await graphql(MINIMIZE_COMMENT_MUTATION, { commentId, classifier });
+}
+async function dismissReview(reviewId, message) {
+    await graphql(DISMISS_REVIEW_MUTATION, { reviewId, message });
+}
+// ---------------------------------------------------------------------------
+// Concurrency helper
+// ---------------------------------------------------------------------------
+async function runBatched(ids, fn, successList, errorList) {
+    // Process in chunks of CONCURRENCY.
+    for (let i = 0; i < ids.length; i += CONCURRENCY) {
+        const chunk = ids.slice(i, i + CONCURRENCY);
+        // eslint-disable-next-line no-await-in-loop
+        await Promise.all(chunk.map(async (id) => {
+            try {
+                await fn(id);
+                successList.push(id);
+            }
+            catch (err) {
+                errorList.push(`${id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }));
+    }
+}
+// ---------------------------------------------------------------------------
+// SHA polling
+// ---------------------------------------------------------------------------
+async function waitForSha(pr, repo, expectedSha) {
+    for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            const currentSha = await getPrHeadSha(pr, repo.owner, repo.name);
+            if (currentSha === expectedSha)
+                return;
+        }
+        catch (err) {
+            // Transient network / 5xx error — keep polling unless this is the last attempt.
+            if (attempt === SHA_POLL_MAX_ATTEMPTS - 1)
+                throw err;
+        }
+        if (attempt < SHA_POLL_MAX_ATTEMPTS - 1) {
+            // eslint-disable-next-line no-await-in-loop
+            await sleep(SHA_POLL_INTERVAL_MS);
+        }
+    }
+    // Total actual wait = (SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS (no sleep after last poll).
+    throw new Error(`Timeout: GitHub PR #${pr} head SHA has not updated to ${expectedSha} after ${((SHA_POLL_MAX_ATTEMPTS - 1) * SHA_POLL_INTERVAL_MS) / 1000}s. Push may still be in transit — retry shortly.`);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}