pr-shepherd 0.2.0

package/src/commands/iterate.mts

@@ -0,0 +1,371 @@
+/**
+ * `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.mts";
+import { triageFailingChecks } from "../checks/triage.mts";
+import { updateReadyDelay } from "./ready-delay.mts";
+import { getCurrentPrNumber } from "../github/client.mts";
+import { readFixAttempts, writeFixAttempts } from "../cache/fix-attempts.mts";
+import type {
+  EscalateDetails,
+  IterateCommandOptions,
+  IterateResult,
+  IterateResultBase,
+  IterateResultSummary,
+  PrComment,
+  ReviewThread,
+  Review,
+  TriagedCheck,
+} from "../types.mts";
+import { loadConfig } from "../config/load.mts";
+
+const execFile = promisify(execFileCb);
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export async function runIterate(opts: IterateCommandOptions): Promise<IterateResult> {
+  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" as const,
+      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: IterateResultBase = {
+    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: {} as Record<string, number> };
+
+    // 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,
+          ambiguousComments: report.comments.actionable,
+          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: string[] = [];
+    if (!opts.noAutoCancelActionable) {
+      const uniqueRunIds = [
+        ...new Set(actionableChecks.map((c) => c.runId).filter((id): id is string => id !== null)),
+      ];
+      const results = await Promise.all(uniqueRunIds.map((id) => tryCancelRun(id)));
+      cancelled = results.filter((id): id is string => id !== null);
+    }
+    return {
+      ...base,
+      action: "fix_code",
+      fix: {
+        threads: report.threads.actionable,
+        comments: report.comments.actionable,
+        checks: 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: Awaited<ReturnType<typeof runCheck>>): IterateResultSummary {
+  return {
+    passing: report.checks.passing.length,
+    skipped: report.checks.skipped.length,
+    filtered: report.checks.filtered.length,
+    inProgress: report.checks.inProgress.length,
+  };
+}
+
+async function getLastCommitTime(): Promise<number> {
+  try {
+    const { stdout } = await execFile("git", ["log", "-1", "--format=%ct", "HEAD"]);
+    return parseInt(stdout.trim(), 10);
+  } catch {
+    return 0;
+  }
+}
+
+async function runGhCommand(args: string[]): Promise<void> {
+  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: string): Promise<string | null> {
+  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(): Promise<string> {
+  try {
+    const { stdout } = await execFile("git", ["rev-parse", "HEAD"]);
+    return stdout.trim();
+  } catch {
+    return "unknown";
+  }
+}
+
+interface EscalateCheck {
+  triggers: string[];
+  thrashHistory?: EscalateDetails["attemptHistory"];
+}
+
+function checkEscalateTriggers(
+  actionableThreads: ReviewThread[],
+  actionableComments: PrComment[],
+  changesRequestedReviews: Review[],
+  actionableChecks: TriagedCheck[],
+  threadAttempts: Record<string, number>,
+  hasConflicts: boolean,
+): EscalateCheck {
+  const triggers: string[] = [];
+  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: string[]): string {
+  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/src/commands/ready-delay.mts

@@ -0,0 +1,117 @@
+/**
+ * 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.mts";
+
+// ---------------------------------------------------------------------------
+// Ready-delay state machine
+// ---------------------------------------------------------------------------
+
+export interface ReadyDelayState {
+  isReady: boolean;
+  /**
+   * When true, the loop should cancel itself — the PR has been READY for
+   * longer than the configured ready-delay.
+   */
+  shouldCancel: boolean;
+  /** How many seconds remain in the ready-delay cooldown. */
+  remainingSeconds: number;
+}
+
+/**
+ * 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: number,
+  isReady: boolean,
+  readyDelaySeconds: number,
+  owner: string,
+  repo: string,
+): Promise<ReadyDelayState> {
+  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: number;
+
+  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: number, owner: string, repo: string): string {
+  for (const [field, value] of [
+    ["owner", owner],
+    ["repo", repo],
+  ] as const) {
+    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: string): Promise<void> {
+  try {
+    await unlink(path);
+  } catch {
+    // Ignore — file may not exist.
+  }
+}
+
+async function safeWriteFile(path: string, content: string): Promise<void> {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+  } catch {
+    // Best-effort.
+  }
+}

package/src/commands/ready-delay.test.mts

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { join } from "node:path";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { updateReadyDelay } from "./ready-delay.mts";
+
+const OWNER = "test-owner";
+const REPO = "test-repo";
+const PR = 42;
+const DELAY = 600; // 10 minutes
+
+let cacheDir: string;
+
+beforeEach(async () => {
+  cacheDir = await mkdtemp(join(tmpdir(), "shepherd-watch-test-"));
+  process.env["PR_SHEPHERD_CACHE_DIR"] = cacheDir;
+});
+
+afterEach(async () => {
+  delete process.env["PR_SHEPHERD_CACHE_DIR"];
+  await rm(cacheDir, { recursive: true, force: true });
+});
+
+describe("updateReadyDelay", () => {
+  it("returns isReady:false and resets remainingSeconds when not ready", async () => {
+    const state = await updateReadyDelay(PR, false, DELAY, OWNER, REPO);
+    expect(state.isReady).toBe(false);
+    expect(state.shouldCancel).toBe(false);
+    expect(state.remainingSeconds).toBe(DELAY);
+  });
+
+  it("starts a fresh countdown on first READY call", async () => {
+    const state = await updateReadyDelay(PR, true, DELAY, OWNER, REPO);
+    expect(state.isReady).toBe(true);
+    expect(state.shouldCancel).toBe(false);
+    expect(state.remainingSeconds).toBeGreaterThan(0);
+    expect(state.remainingSeconds).toBeLessThanOrEqual(DELAY);
+  });
+
+  it("fires shouldCancel when delay has elapsed", async () => {
+    // Write a marker from the past (delay + 5 seconds ago)
+    const past = Math.floor(Date.now() / 1000) - DELAY - 5;
+    const markerPath = join(cacheDir, `${OWNER}-${REPO}`, String(PR), "ready-since.txt");
+    const { mkdir, writeFile } = await import("node:fs/promises");
+    await mkdir(join(cacheDir, `${OWNER}-${REPO}`, String(PR)), { recursive: true });
+    await writeFile(markerPath, String(past), "utf8");
+
+    const state = await updateReadyDelay(PR, true, DELAY, OWNER, REPO);
+    expect(state.isReady).toBe(true);
+    expect(state.shouldCancel).toBe(true);
+    expect(state.remainingSeconds).toBe(0);
+  });
+
+  it("keeps the marker file after shouldCancel fires so subsequent calls also return shouldCancel:true", async () => {
+    // Write a past marker
+    const past = Math.floor(Date.now() / 1000) - DELAY - 5;
+    const markerPath = join(cacheDir, `${OWNER}-${REPO}`, String(PR), "ready-since.txt");
+    const { mkdir, writeFile } = await import("node:fs/promises");
+    await mkdir(join(cacheDir, `${OWNER}-${REPO}`, String(PR)), { recursive: true });
+    await writeFile(markerPath, String(past), "utf8");
+
+    // First call fires shouldCancel
+    const first = await updateReadyDelay(PR, true, DELAY, OWNER, REPO);
+    expect(first.shouldCancel).toBe(true);
+
+    // Marker file must still exist
+    const contents = await readFile(markerPath, "utf8");
+    expect(contents).toBe(String(past));
+
+    // Second call (simulating next cron tick) also returns shouldCancel:true
+    const second = await updateReadyDelay(PR, true, DELAY, OWNER, REPO);
+    expect(second.shouldCancel).toBe(true);
+  });
+
+  it("resets the countdown when ready-since.txt contains a future timestamp (clock skew)", async () => {
+    // Write a marker far in the future (simulating clock skew or manual corruption).
+    const future = Math.floor(Date.now() / 1000) + 9999;
+    const markerPath = join(cacheDir, `${OWNER}-${REPO}`, String(PR), "ready-since.txt");
+    const { mkdir, writeFile } = await import("node:fs/promises");
+    await mkdir(join(cacheDir, `${OWNER}-${REPO}`, String(PR)), { recursive: true });
+    await writeFile(markerPath, String(future), "utf8");
+
+    const state = await updateReadyDelay(PR, true, DELAY, OWNER, REPO);
+    // Future timestamp must be reset to "now" — remaining should be ~DELAY.
+    expect(state.isReady).toBe(true);
+    expect(state.shouldCancel).toBe(false);
+    expect(state.remainingSeconds).toBeGreaterThan(0);
+    expect(state.remainingSeconds).toBeLessThanOrEqual(DELAY);
+  });
+
+  it("resets the timer when PR drops out of READY state after shouldCancel", async () => {
+    const past = Math.floor(Date.now() / 1000) - DELAY - 5;
+    const markerPath = join(cacheDir, `${OWNER}-${REPO}`, String(PR), "ready-since.txt");
+    const { mkdir, writeFile, access } = await import("node:fs/promises");
+    await mkdir(join(cacheDir, `${OWNER}-${REPO}`, String(PR)), { recursive: true });
+    await writeFile(markerPath, String(past), "utf8");
+
+    // shouldCancel fires
+    await updateReadyDelay(PR, true, DELAY, OWNER, REPO);
+
+    // PR becomes not-ready (e.g. new review comment) — timer must reset
+    const reset = await updateReadyDelay(PR, false, DELAY, OWNER, REPO);
+    expect(reset.isReady).toBe(false);
+    expect(reset.shouldCancel).toBe(false);
+
+    // Marker file must be gone
+    await expect(access(markerPath)).rejects.toThrow();
+  });
+
+  it("rejects when owner contains an invalid path segment character", async () => {
+    // owner contains '/' which is not in the allowed SAFE_SEGMENT charset.
+    await expect(updateReadyDelay(PR, true, DELAY, "owner/bad", "repo")).rejects.toThrow(
+      "Invalid path segment",
+    );
+  });
+});

package/src/commands/resolve.mts

@@ -0,0 +1,92 @@
+/**
+ * `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.mts";
+import { fetchPrBatch } from "../github/batch.mts";
+import { getOutdatedThreads } from "../comments/outdated.mts";
+import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mts";
+import type { GlobalOptions, ResolveOptions, ReviewThread, PrComment, Review } from "../types.mts";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface FetchResult {
+  autoResolved: ReviewThread[];
+  actionableThreads: ReviewThread[];
+  actionableComments: PrComment[];
+  changesRequestedReviews: Review[];
+}
+
+export interface ResolveCommandOptions extends GlobalOptions {
+  /** When true, run in fetch mode regardless of other flags. */
+  fetch?: boolean;
+}
+
+/**
+ * Fetch mode: auto-resolve outdated threads and return all active items for LLM triage.
+ */
+export async function runResolveFetch(opts: ResolveCommandOptions): Promise<FetchResult> {
+  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: ReviewThread[] = [];
+  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: ResolveCommandOptions & ResolveOptions,
+): Promise<import("../comments/resolve.mts").ResolveResult> {
+  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,
+  });
+}