@workit-dev/core 0.0.1 → 1.0.0

package/src/forge/report.ts

@@ -0,0 +1,994 @@
+// `workit pr status` / `ci wait` / `ci rerun` logic (design §2.1, S10): one
+// forge-neutral status document, the `next` priority, the CI-wait verdict,
+// and rerun planning with the rerun-once rule.
+import { aheadBehind, currentBranch, fetchRefs, hasCommit, headSha, resolveRef } from "../git/rev";
+import { appendObserved, readLedger, type LedgerActor } from "../ledger";
+import { loadCheckConfig, gateCheckNames } from "../check-config";
+import { branchLane } from "../core/policy/lane";
+import {
+  checkEvidence,
+  type CheckEvidenceDoc,
+  type CiCheck,
+  localCheckRows,
+} from "../core/policy/check-evidence";
+import type { ResolvedForge } from "./resolve";
+import { rerunCounts, recordReruns, withRerunLock, type RerunRow } from "./reruns";
+import {
+  failure,
+  success,
+  type Forge,
+  type ForgeCheck,
+  type ForgePrStatus,
+  type ForgeResult,
+  type ForgeThread,
+  type PrState,
+  type RefChecks,
+  type RerunTarget,
+} from "./types";
+
+/**
+ * What to do next, in priority order: conflicts > required rebase > threads
+ * > CI > review > draft > merge queue > other merge blockers > READY.
+ */
+export type NextAction =
+  | "MERGED"
+  | "CLOSED"
+  | "RESOLVE_CONFLICTS"
+  | "REBASE"
+  | "RESOLVE_THREADS"
+  | "FIX_CI"
+  | "WAITING_CI"
+  | "ADDRESS_REVIEW"
+  | "REVIEW"
+  | "MARK_READY"
+  | "IN_MERGE_QUEUE"
+  | "NOT_MERGEABLE"
+  | "READY";
+
+/**
+ * The next babysitting step for a `green`/`merged` endpoint, coarser than
+ * `next`: `wait` is CI running (`workit ci wait`); `wait-forge` is CI done
+ * but the forge still deciding (merge queue, mergeability computing);
+ * `ready` means nothing is left for the agent (a human approval may still be
+ * pending); null for a closed, unmerged PR.
+ */
+export type BabysitAction =
+  | "wait"
+  | "wait-forge"
+  | "mark-ready"
+  | "fix-ci"
+  | "address-threads"
+  | "update-branch"
+  | "ready"
+  | "merged";
+
+export type FailingCheck = {
+  name: string;
+  url: string | null;
+  runId: number | null;
+  jobId: number | null;
+  conclusion: string | null;
+  /** Required by branch protection; an optional failure does not block the merge. */
+  required: boolean | null;
+  logTail: string[];
+  logError?: string;
+  rerunsOnHead: number;
+};
+
+export type BehindBase = {
+  behind: number | null;
+  ahead: number | null;
+  baseSha: string | null;
+  upToDate: boolean | null;
+  /** Why the counts are null (fetch failed, commit not available). */
+  error?: string;
+};
+
+export type ChecksState = "failing" | "pending" | "passing" | "none";
+
+export type PrStatusDoc = {
+  forge: "github" | "gitlab";
+  repo: string;
+  /** The push repository when it is a fork of `repo`. */
+  headRepo: string | null;
+  number: number;
+  url: string;
+  state: PrState;
+  draft: boolean;
+  base: string;
+  head: { branch: string; sha: string; localSha: string | null; pushed: boolean | null };
+  mergeable: "yes" | "no" | "unknown";
+  mergeState: string | null;
+  conflicts: boolean;
+  rebaseRequired: boolean;
+  inMergeQueue: boolean;
+  behindBase: BehindBase | null;
+  checks: {
+    /** Over the checks that gate the merge (required ones when protection names them). */
+    state: ChecksState;
+    failing: FailingCheck[];
+    pending: string[];
+    passing: number;
+    /** Required contexts that have not reported on this head; null when unknown. */
+    missingRequired: string[] | null;
+  };
+  /** The configured checks this head's review lane needs and their fresh evidence (#509). */
+  evidence: CheckEvidenceDoc;
+  reviews: { decision: string | null; unresolvedThreads: ForgeThread[] };
+  /** Every reason the PR cannot merge right now (empty when READY). */
+  blockers: string[];
+  identity: { login: string | null; credential: string; note?: string } | null;
+  truncated: boolean;
+  next: NextAction;
+  babysit: BabysitAction | null;
+};
+
+/** Failing checks whose log tail is fetched; the rest list without a tail. */
+export const MAX_LOG_TAILS = 5;
+
+/**
+ * The checks that gate the merge: the required ones when branch protection
+ * names any; otherwise every check (an unprotected or unreadable branch is
+ * treated conservatively).
+ */
+export function gatingChecks(status: ForgePrStatus): {
+  checks: ForgeCheck[];
+  /** True when branch protection decides which checks gate. */
+  protected: boolean;
+} {
+  const required = status.checks.filter((check) => check.required === true);
+  const protectionNamesChecks = (status.requiredContexts?.length ?? 0) > 0;
+  return required.length > 0 || protectionNamesChecks
+    ? { checks: required, protected: true }
+    : { checks: status.checks, protected: false };
+}
+
+export function missingRequired(status: ForgePrStatus): string[] | null {
+  if (status.requiredContexts === null) return null;
+  const seen = new Set(status.checks.map((check) => check.context));
+  return status.requiredContexts.filter((context) => !seen.has(context));
+}
+
+export function checksState(
+  checks: readonly ForgeCheck[],
+  missing: readonly string[] | null = [],
+): ChecksState {
+  if (checks.some((check) => check.state === "failing")) return "failing";
+  if (checks.some((check) => check.state === "pending") || (missing?.length ?? 0) > 0)
+    return "pending";
+  return checks.length > 0 ? "passing" : "none";
+}
+
+// GitLab detailed_merge_status values that mean "mergeable now".
+const GITLAB_MERGEABLE = new Set(["mergeable"]);
+// GitHub mergeStateStatus values that allow a merge (UNSTABLE: only
+// non-required checks fail; HAS_HOOKS: pre-receive hooks will run).
+const GITHUB_MERGEABLE = new Set(["clean", "unstable", "has_hooks"]);
+
+export type NextInput = {
+  forge: "github" | "gitlab";
+  state: PrState;
+  draft: boolean;
+  conflicts: boolean;
+  rebaseRequired: boolean;
+  mergeable: "yes" | "no" | "unknown";
+  mergeState: string | null;
+  inMergeQueue: boolean;
+  reviewDecision: string | null;
+  threads: number;
+  checks: ChecksState;
+  /** Branch protection names the gating checks (else every check gates). */
+  checksRequired?: boolean;
+};
+
+/** The ordered merge blockers; the first one is `next`. */
+export function blockersOf(input: NextInput): Array<{ next: NextAction; reason: string }> {
+  if (input.state === "merged") return [{ next: "MERGED", reason: "merged" }];
+  if (input.state === "closed") return [{ next: "CLOSED", reason: "closed" }];
+  const out: Array<{ next: NextAction; reason: string }> = [];
+  const ms = input.mergeState ?? "";
+  if (input.conflicts) out.push({ next: "RESOLVE_CONFLICTS", reason: "conflicts" });
+  if (input.rebaseRequired) out.push({ next: "REBASE", reason: "behind_base_required" });
+  if (input.threads > 0 || ms === "discussions_not_resolved")
+    out.push({ next: "RESOLVE_THREADS", reason: "unresolved_threads" });
+  if (input.checks === "failing")
+    out.push({
+      next: "FIX_CI",
+      reason: input.checksRequired ? "required_checks_failing" : "checks_failing",
+    });
+  else if (
+    input.checks === "pending" ||
+    ms === "ci_still_running" ||
+    (ms === "ci_must_pass" && input.checks !== "passing")
+  )
+    out.push({ next: "WAITING_CI", reason: "checks_pending" });
+  if (input.reviewDecision === "changes_requested" || ms === "requested_changes")
+    out.push({ next: "ADDRESS_REVIEW", reason: "changes_requested" });
+  else if (input.reviewDecision === "review_required" || ms === "not_approved")
+    out.push({ next: "REVIEW", reason: "review_required" });
+  if (input.draft || ms === "draft" || ms === "draft_status")
+    out.push({ next: "MARK_READY", reason: "draft" });
+  if (input.inMergeQueue) out.push({ next: "IN_MERGE_QUEUE", reason: "in_merge_queue" });
+  if (out.length === 0) {
+    const allowed = input.forge === "github" ? GITHUB_MERGEABLE.has(ms) : GITLAB_MERGEABLE.has(ms);
+    if (input.mergeable === "unknown")
+      out.push({ next: "NOT_MERGEABLE", reason: "mergeability_unknown" });
+    else if (!allowed)
+      out.push({ next: "NOT_MERGEABLE", reason: `merge_state_${ms || "unknown"}` });
+  }
+  return out;
+}
+
+export function nextAction(input: NextInput): NextAction {
+  return blockersOf(input)[0]?.next ?? "READY";
+}
+
+/**
+ * Map `next` (plus the first blocker's reason) to one babysitting step. The
+ * branch is updated only when the forge requires it (conflicts, a required
+ * rebase): merely behind its base is still `ready`, so a busy base never
+ * starts a rebase/CI loop or drops approvals. A draft reads `mark-ready` once
+ * nothing else is open, even when a review is also pending.
+ */
+export function babysitAction(
+  next: NextAction,
+  reason: string | null,
+  draft: boolean,
+): BabysitAction | null {
+  switch (next) {
+    case "MERGED":
+      return "merged";
+    case "CLOSED":
+      return null;
+    case "RESOLVE_CONFLICTS":
+    case "REBASE":
+      return "update-branch";
+    case "RESOLVE_THREADS":
+    case "ADDRESS_REVIEW":
+      return "address-threads";
+    case "FIX_CI":
+      return "fix-ci";
+    case "WAITING_CI":
+      return "wait";
+    case "IN_MERGE_QUEUE":
+      return "wait-forge";
+    default:
+      if (draft) return "mark-ready";
+      if (next === "NOT_MERGEABLE" && reason === "mergeability_unknown") return "wait-forge";
+      return "ready";
+  }
+}
+
+/**
+ * Count head against the base tip the API reported, locally. A pure read:
+ * missing commits are fetched by id (no destination ref, no FETCH_HEAD), so
+ * no ref in the shared repository moves.
+ */
+export function computeBehindBase(
+  cwd: string,
+  remotes: { base: string; head: string },
+  baseSha: string | null,
+  headSha_: string,
+  options: { timeoutMs?: number } = {},
+): ForgeResult<BehindBase> {
+  const empty = { behind: null, ahead: null, upToDate: null };
+  if (!baseSha)
+    return success({ ...empty, baseSha: null, error: "the forge reported no base tip" });
+  for (const [sha, remote] of [
+    [baseSha, remotes.base],
+    [headSha_, remotes.head],
+  ] as const) {
+    if (hasCommit(cwd, sha)) continue;
+    const fetched = fetchRefs(cwd, remote, [sha], options);
+    if (!fetched.ok && remote !== remotes.base) fetchRefs(cwd, remotes.base, [sha], options);
+    if (!hasCommit(cwd, sha))
+      return success({
+        ...empty,
+        baseSha,
+        error: fetched.ok ? `${sha.slice(0, 12)} is not available locally` : fetched.error,
+      });
+  }
+  const counts = aheadBehind(cwd, baseSha, headSha_);
+  return success(
+    counts ? { ...counts, baseSha } : { ...empty, baseSha, error: "ahead/behind did not resolve" },
+  );
+}
+
+export type ReportOptions = {
+  pr?: number | null;
+  branch?: string | null;
+  logLines?: number;
+  /** Skip the behind-base count (ci wait polls). */
+  behind?: boolean;
+};
+
+/** The PR/MR number for `--pr`, `--branch`, or the current branch. */
+export function selectPr(
+  cwd: string,
+  resolved: ResolvedForge,
+  options: ReportOptions,
+): ForgeResult<number> {
+  if (options.pr) return success(options.pr);
+  const branch = options.branch ?? currentBranch(cwd);
+  if (!branch)
+    return failure("invalid_input", "HEAD is detached; pass --pr <n> or --branch <name>");
+  const localSha = resolveRef(cwd, `refs/heads/${branch}`);
+  const found = resolved.forge.findPr(branch, {
+    owner: resolved.headRepo.split("/")[0] ?? null,
+    projectId: resolved.headProjectId,
+    sha: localSha,
+  });
+  if (!found.ok) return found;
+  if (!found.data) {
+    const noun = resolved.forge.kind === "github" ? "pull request" : "merge request";
+    return failure(
+      "not_found",
+      `no ${noun} for branch ${branch} from ${resolved.headRepo} in ${resolved.forge.repo}`,
+      "workit git push && workit pr create --fill  # or pass --pr <n>",
+    );
+  }
+  return success(found.data.number);
+}
+
+/** Local runs observed on this branch, and CI's checks, folded into the lane's evidence doc. */
+export function evidenceFor(
+  cwd: string,
+  status: ForgePrStatus,
+  ci: readonly ForgeCheck[] = status.checks,
+): CheckEvidenceDoc {
+  const lane = branchLane(cwd, { base: status.base, head: status.head.sha });
+  const configured = gateCheckNames(loadCheckConfig(cwd), "verification");
+  const read = readLedger(cwd);
+  const local = read.ok ? localCheckRows(read.value.rows) : [];
+  const ciChecks: CiCheck[] = ci.flatMap((check) =>
+    check.state === "skipped" ? [] : [{ name: check.name, state: check.state }],
+  );
+  return checkEvidence({ lane: lane.lane, head: status.head.sha, configured, local, ci: ciChecks });
+}
+
+export function buildStatusDoc(
+  cwd: string,
+  resolved: ResolvedForge,
+  status: ForgePrStatus,
+  options: {
+    logLines: number;
+    behind: boolean;
+    behindTimeoutMs?: number;
+    identity?: PrStatusDoc["identity"];
+  },
+): ForgeResult<PrStatusDoc> {
+  const { forge } = resolved;
+  const reruns = rerunCounts(cwd, { repo: forge.repo, head: status.head.sha });
+  const gating = gatingChecks(status);
+  const missing = missingRequired(status);
+  const failing = status.checks.filter((check) => check.state === "failing");
+  const failingDocs = failing.map((check, index): FailingCheck => {
+    const doc: FailingCheck = {
+      name: check.name,
+      url: check.url,
+      runId: check.runId,
+      jobId: check.jobId,
+      conclusion: check.conclusion,
+      required: check.required,
+      logTail: [],
+      rerunsOnHead: reruns.get(check.name) ?? 0,
+    };
+    if (check.jobId !== null && options.logLines > 0 && index < MAX_LOG_TAILS) {
+      const tail = forge.jobLogTail({ jobId: check.jobId, scope: check.scope }, options.logLines);
+      if (tail.ok) doc.logTail = tail.data;
+      else doc.logError = tail.error;
+    }
+    return doc;
+  });
+  const local =
+    currentBranch(cwd) === status.head.branch
+      ? headSha(cwd)
+      : resolveRef(cwd, `refs/heads/${status.head.branch}`);
+  let behindBase: BehindBase | null = null;
+  if (options.behind && status.state === "open") {
+    const counted = computeBehindBase(
+      cwd,
+      { base: resolved.baseRemote, head: resolved.remote },
+      status.baseSha,
+      status.head.sha,
+      options.behindTimeoutMs === undefined ? {} : { timeoutMs: options.behindTimeoutMs },
+    );
+    if (!counted.ok) return counted;
+    behindBase = counted.data;
+  }
+  const state = checksState(gating.checks, missing);
+  const blockers = blockersOf({
+    forge: forge.kind,
+    state: status.state,
+    draft: status.draft,
+    conflicts: status.conflicts,
+    rebaseRequired: status.rebaseRequired,
+    mergeable: status.mergeable,
+    mergeState: status.mergeState,
+    inMergeQueue: status.inMergeQueue,
+    reviewDecision: status.reviewDecision,
+    threads: status.threads.length,
+    checks: state,
+    checksRequired: gating.protected,
+  });
+  return success({
+    forge: forge.kind,
+    repo: forge.repo,
+    headRepo: resolved.fork ? resolved.headRepo : null,
+    number: status.number,
+    url: status.url,
+    state: status.state,
+    draft: status.draft,
+    base: status.base,
+    head: {
+      branch: status.head.branch,
+      sha: status.head.sha,
+      localSha: local,
+      pushed: local === null ? null : local === status.head.sha,
+    },
+    mergeable: status.mergeable,
+    mergeState: status.mergeState,
+    conflicts: status.conflicts,
+    rebaseRequired: status.rebaseRequired,
+    inMergeQueue: status.inMergeQueue,
+    behindBase,
+    checks: {
+      state,
+      failing: failingDocs,
+      pending: status.checks
+        .filter((check) => check.state === "pending")
+        .map((check) => check.name),
+      passing: status.checks.filter((check) => check.state === "passing").length,
+      missingRequired: missing,
+    },
+    evidence: evidenceFor(cwd, status),
+    reviews: { decision: status.reviewDecision, unresolvedThreads: status.threads },
+    blockers: status.state === "open" ? blockers.map((blocker) => blocker.reason) : [],
+    identity: options.identity ?? null,
+    truncated: status.truncated,
+    next: blockers[0]?.next ?? "READY",
+    babysit: babysitAction(
+      blockers[0]?.next ?? "READY",
+      blockers[0]?.reason ?? null,
+      status.draft || blockers.some((blocker) => blocker.next === "MARK_READY"),
+    ),
+  });
+}
+
+/**
+ * Record what the forge said about a PR as a CLI-observed `pr.status` row
+ * (pr, branch, head, base, state: open|merged|closed, checks), only when it
+ * differs from the newest row for that PR, so polling never floods the
+ * ledger. Hooks read it without calling the forge: an open PR's checks
+ * (passing|failing|pending; one without gating checks is not recorded), and
+ * a PR merged or closed outside workit (the forge UI). Never fails the verb:
+ * a ledger error only loses the row.
+ */
+export function recordPrStatus(cwd: string, doc: PrStatusDoc, actor: LedgerActor): void {
+  const checks = doc.checks.state;
+  const state = doc.state;
+  if (state !== "open" && state !== "merged" && state !== "closed") return;
+  if (state === "open" && checks !== "passing" && checks !== "failing" && checks !== "pending")
+    return;
+  try {
+    const ledger = readLedger(cwd);
+    if (!ledger.ok) return;
+    const last = ledger.value.rows.findLast(
+      (row) =>
+        row.type === "pr.status" &&
+        row.observer === "workit_cli" &&
+        row.pr === doc.number &&
+        row.repo === doc.repo,
+    );
+    if (
+      last &&
+      last.head === doc.head.sha &&
+      last.checks === checks &&
+      (last.state ?? "open") === state &&
+      (last.base ?? null) === (doc.base ?? null)
+    )
+      return;
+    appendObserved(cwd, {
+      type: "pr.status",
+      actor,
+      branch: doc.head.branch,
+      head: doc.head.sha,
+      pr: doc.number,
+      repo: doc.repo,
+      forge: doc.forge,
+      state,
+      checks,
+      base: doc.base,
+    });
+  } catch {
+    // The row is an observation for hooks; the verb's answer stands without it.
+  }
+}
+
+/** Select, read and document one PR/MR (recorded as a `pr.status` row when `actor` is given). */
+export function prStatusReport(
+  cwd: string,
+  resolved: ResolvedForge,
+  options: ReportOptions & { identity?: PrStatusDoc["identity"]; actor?: LedgerActor } = {},
+): ForgeResult<{ doc: PrStatusDoc; raw: ForgePrStatus }> {
+  const number = selectPr(cwd, resolved, options);
+  if (!number.ok) return number;
+  const status = resolved.forge.prStatus(number.data);
+  if (!status.ok) return status;
+  const doc = buildStatusDoc(cwd, resolved, status.data, {
+    logLines: options.logLines ?? 60,
+    behind: options.behind ?? true,
+    identity: options.identity,
+  });
+  if (!doc.ok) return doc;
+  if (options.actor) recordPrStatus(cwd, doc.data, options.actor);
+  return success({ doc: doc.data, raw: status.data });
+}
+
+// ---------------------------------------------------------------------------
+// ci wait
+
+export type WaitState = "ready" | "waiting" | "failed" | "blocked";
+
+export type WaitVerdict = { state: WaitState; reason: string; unblock?: string };
+
+/**
+ * Checks never appeared: after this grace a PR with no missing required check
+ * reads "none" (no CI configured). A forge is slow to register the runs of a
+ * freshly pushed head, so the grace is generous (#510).
+ */
+export const NO_CHECKS_GRACE_MS = 120_000;
+
+/**
+ * CI verdict for the PR head. Only gating checks count; a closed or merged
+ * PR is never "ready". No checks at all is ready only after the grace and
+ * only when the forge says nothing is required.
+ */
+export function waitVerdict(
+  doc: PrStatusDoc,
+  options: {
+    head?: string | null;
+    elapsedMs: number;
+    noChecksGraceMs?: number;
+    /**
+     * Checks the base branch ran that this head has not registered yet. Only
+     * set when branch protection is unreadable, so required names are unknown (#510).
+     */
+    expectedMissing?: readonly string[];
+  },
+): WaitVerdict {
+  if (doc.state !== "open")
+    return {
+      state: "blocked",
+      reason: `pr_${doc.state}`,
+      unblock: `the ${doc.forge === "github" ? "PR" : "MR"} is ${doc.state}; nothing to wait for`,
+    };
+  if (options.head && !doc.head.sha.startsWith(options.head))
+    return { state: "waiting", reason: "head_mismatch" };
+  const checks = doc.checks.state;
+  // Fail-fast on purpose: a failing gating check ends the wait even while
+  // other checks still run (`checks.pending` in the payload lists them).
+  if (checks === "failing") return { state: "failed", reason: "checks_failing" };
+  // Before "pending": CI never runs on a conflicting PR, so waiting cannot help (M8).
+  if (doc.conflicts && checks !== "passing")
+    return {
+      state: "blocked",
+      reason: "conflicts",
+      unblock: `rebase onto ${doc.base} and push; CI does not run on a conflicting PR`,
+    };
+  if (checks === "pending") return { state: "waiting", reason: "checks_pending" };
+  // Gating checks passed but another check on the head is still queued or
+  // running (a non-required workflow): never green while anything runs (#440).
+  if (doc.checks.pending.length > 0) return { state: "waiting", reason: "checks_pending" };
+  // Small workflows register and pass in seconds while the main CI registers
+  // later: a head still missing a check the base ran is not done within the grace.
+  const grace = options.noChecksGraceMs ?? NO_CHECKS_GRACE_MS;
+  if ((options.expectedMissing?.length ?? 0) > 0 && options.elapsedMs < grace)
+    return { state: "waiting", reason: "checks_not_registered" };
+  if (checks === "passing") return { state: "ready", reason: "checks_passing" };
+  // Unknown protection (null) is not "required": the grace bounds the wait.
+  const ciRequired =
+    (doc.checks.missingRequired?.length ?? 0) > 0 ||
+    doc.mergeState === "ci_must_pass" ||
+    doc.mergeState === "ci_still_running";
+  if (ciRequired) return { state: "waiting", reason: "no_checks_yet" };
+  if (options.elapsedMs < grace) return { state: "waiting", reason: "no_checks_yet" };
+  return { state: "ready", reason: "no_checks" };
+}
+
+/**
+ * Poll delays: `interval`, growing 1.5x per poll up to max(interval, 2 min).
+ * Deterministic, so a wait's poll count is predictable from its timeout.
+ */
+export function pollDelay(intervalMs: number, poll: number): number {
+  const cap = Math.max(intervalMs, 120_000);
+  return Math.min(cap, Math.round(intervalMs * 1.5 ** poll));
+}
+
+// ---------------------------------------------------------------------------
+// ci rerun
+
+export type RerunPlan = {
+  checks: ForgeCheck[];
+  targets: RerunTarget[];
+  /** Selected checks the forge cannot rerun (external statuses). */
+  skipped: string[];
+};
+
+export function planRerun(
+  status: ForgePrStatus,
+  selection: { failed: boolean; names: readonly string[] },
+): ForgeResult<RerunPlan> {
+  return planRerunChecks(status.checks, status.head.sha, selection);
+}
+
+function planRerunChecks(
+  all: readonly ForgeCheck[],
+  head: string,
+  selection: { failed: boolean; names: readonly string[] },
+): ForgeResult<RerunPlan> {
+  let checks: ForgeCheck[];
+  if (selection.names.length > 0) {
+    const unknown = selection.names.filter((name) => !all.some((check) => check.name === name));
+    if (unknown.length)
+      return failure(
+        "invalid_input",
+        `unknown check ${unknown.map((name) => JSON.stringify(name)).join(", ")}; known: ${all.map((check) => check.name).join(", ") || "none"}`,
+      );
+    checks = all.filter((check) => selection.names.includes(check.name));
+    const running = checks.filter((check) => check.state === "pending");
+    if (running.length)
+      return failure(
+        "busy",
+        `still running: ${running.map((check) => check.name).join(", ")}`,
+        "workit ci wait",
+      );
+  } else {
+    checks = all.filter((check) => check.state === "failing");
+  }
+  if (checks.length === 0)
+    return failure("not_found", `no failing checks on head ${head.slice(0, 12)}`);
+  const rerunnable = checks.filter((check) => check.jobId !== null && check.runId !== null);
+  const skipped = checks.filter((check) => !rerunnable.includes(check)).map((check) => check.name);
+  const targets: RerunTarget[] = [];
+  if (selection.names.length === 0) {
+    // One "rerun failed jobs" per workflow run / pipeline. The forge refuses
+    // it while the run still has jobs in progress (GitHub: HTTP 403).
+    const busy = all.filter(
+      (check) =>
+        check.state === "pending" &&
+        check.runId !== null &&
+        rerunnable.some((failing) => failing.runId === check.runId),
+    );
+    if (busy.length)
+      return failure(
+        "busy",
+        `the failed jobs' run is still in progress (${busy.map((check) => check.name).join(", ")})`,
+        "workit ci wait, then rerun",
+      );
+    const seen = new Set<number>();
+    for (const check of rerunnable)
+      if (!seen.has(check.runId!)) {
+        seen.add(check.runId!);
+        targets.push({ kind: "failed_in_run", runId: check.runId!, scope: check.scope });
+      }
+  } else {
+    for (const check of rerunnable)
+      targets.push({ kind: "job", jobId: check.jobId!, scope: check.scope });
+  }
+  if (targets.length === 0)
+    return failure(
+      "unavailable",
+      `${skipped.join(", ")} cannot be rerun from here (not a CI job); rerun it on the forge`,
+    );
+  return success({ checks: rerunnable, targets, skipped });
+}
+
+export type RerunOutcome = {
+  /** The PR rerun; null for a branch rerun. */
+  pr: number | null;
+  /** The branch whose latest run was rerun; null for a PR rerun. */
+  branch: string | null;
+  head: string;
+  reason: string;
+  forced: boolean;
+  rerun: Array<{ name: string; runId: number | null; jobId: number | null }>;
+  skipped: string[];
+  recorded: boolean;
+};
+
+type RerunOptions = { failed: boolean; names: readonly string[]; reason: string; force: boolean };
+
+/** What a rerun acts on: a PR head, or the head of a branch (a red base). */
+type RerunSubject = { pr: number | null; branch: string | null; head: string };
+
+/**
+ * Apply the rerun-once rule, trigger the reruns, and record one row per check
+ * whose rerun the forge accepted.
+ */
+export function executeRerun(
+  cwd: string,
+  resolved: ResolvedForge,
+  status: ForgePrStatus,
+  options: RerunOptions,
+): ForgeResult<RerunOutcome> {
+  if (status.state !== "open")
+    return failure("blocked", `${status.state} PR: CI cannot be rerun`, "nothing to do");
+  const plan = planRerun(status, options);
+  if (!plan.ok) return plan;
+  return lockedRerun(
+    cwd,
+    resolved,
+    { pr: status.number, branch: null, head: status.head.sha },
+    plan.data,
+    options,
+  );
+}
+
+/**
+ * `ci rerun --ref`: the same rule for the latest CI run on a branch's head
+ * (GitHub: its workflow runs; GitLab: its latest pipeline), so a base that
+ * went red on a flake can be rerun without a PR.
+ */
+export function executeBranchRerun(
+  cwd: string,
+  resolved: ResolvedForge,
+  branch: string,
+  ref: RefChecks,
+  options: RerunOptions,
+): ForgeResult<RerunOutcome> {
+  if (!ref.sha)
+    return failure("unavailable", `the forge did not report the head commit of ${branch}`);
+  if (ref.checks.length === 0)
+    return failure("not_found", `no CI has reported for ${branch} at ${ref.sha.slice(0, 12)}`);
+  const plan = planRerunChecks(ref.checks, ref.sha, options);
+  if (!plan.ok) return plan;
+  return lockedRerun(cwd, resolved, { pr: null, branch, head: ref.sha }, plan.data, options);
+}
+
+function lockedRerun(
+  cwd: string,
+  resolved: ResolvedForge,
+  subject: RerunSubject,
+  plan: RerunPlan,
+  options: RerunOptions,
+): ForgeResult<RerunOutcome> {
+  const locked = withRerunLock(cwd, () => rerunLocked(cwd, resolved, subject, plan, options));
+  return (
+    locked ??
+    failure("busy", "another ci rerun is in progress for this repository", "retry in a moment")
+  );
+}
+
+function rerunLocked(
+  cwd: string,
+  resolved: ResolvedForge,
+  subject: RerunSubject,
+  plan: RerunPlan,
+  options: RerunOptions,
+): ForgeResult<RerunOutcome> {
+  const { forge } = resolved;
+  const counts = rerunCounts(cwd, { repo: forge.repo, head: subject.head });
+  const repeated = plan.checks.filter((check) => (counts.get(check.name) ?? 0) > 0);
+  if (repeated.length && !options.force)
+    return failure(
+      "blocked",
+      `rerun_limit: ${repeated.map((check) => check.name).join(", ")} already rerun once on head ${subject.head.slice(0, 12)}`,
+      "treat it as a real failure and fix it; if it is a confirmed flake, rerun with --force",
+    );
+  const accepted: ForgeCheck[] = [];
+  for (const target of plan.targets) {
+    const done = forge.rerun(target);
+    if (!done.ok) {
+      recordAccepted(cwd, resolved, subject, accepted, options);
+      return failure(
+        done.code,
+        accepted.length
+          ? `${done.error} (already rerun: ${accepted.map((check) => check.name).join(", ")})`
+          : done.error,
+        done.unblock,
+      );
+    }
+    accepted.push(
+      ...plan.checks.filter((check) =>
+        target.kind === "failed_in_run"
+          ? check.runId === target.runId
+          : check.jobId === target.jobId,
+      ),
+    );
+  }
+  const recorded = recordAccepted(cwd, resolved, subject, accepted, options);
+  return success({
+    pr: subject.pr,
+    branch: subject.branch,
+    head: subject.head,
+    reason: options.reason,
+    forced: options.force,
+    rerun: accepted.map((check) => ({ name: check.name, runId: check.runId, jobId: check.jobId })),
+    skipped: plan.skipped,
+    recorded,
+  });
+}
+
+function recordAccepted(
+  cwd: string,
+  resolved: ResolvedForge,
+  subject: RerunSubject,
+  accepted: readonly ForgeCheck[],
+  options: { reason: string; force: boolean },
+): boolean {
+  const at = new Date().toISOString();
+  const rows: RerunRow[] = accepted.map((check) => ({
+    v: 1,
+    at,
+    type: "ci.rerun",
+    forge: resolved.forge.kind,
+    repo: resolved.forge.repo,
+    pr: subject.pr,
+    branch: subject.branch,
+    head: subject.head,
+    runId: check.runId,
+    check: check.name,
+    reason: options.reason,
+    forced: options.force,
+  }));
+  return recordReruns(cwd, rows);
+}
+
+// ---------------------------------------------------------------------------
+// merge gate: optional-check waivers (#269 D1) and transient mergeability (D2)
+
+/** `pr merge --allow-failing <check>… --reason <why>`. */
+export type CheckWaiver = { checks: readonly string[]; reason: string };
+
+/** A check a waiver passed on a merged PR: its `merge.waived` row, or why it could not be written. */
+export type WaivedCheck = { check: string; recorded: string } | { check: string; error: string };
+
+/**
+ * `status` with the failing checks `waiver` names marked waived (state
+ * `skipped`, conclusion `waived_<conclusion>`), so the merge gate reads them
+ * as not gating. A required check is never waived: naming one refuses, and
+ * so does one whose required flag the forge could not read. A name that
+ * matches no check on the head is a usage error (a typo never merges).
+ */
+export function waiveChecks(
+  status: ForgePrStatus,
+  waiver: CheckWaiver,
+  /** `stack land` (#739): a name this head does not run is skipped, not refused. */
+  options: { perPr?: boolean } = {},
+): ForgeResult<{ status: ForgePrStatus; waived: ForgeCheck[] }> {
+  const required = (check: ForgeCheck): boolean | null =>
+    check.required === true || status.requiredContexts?.includes(check.context) === true
+      ? true
+      : check.required === false
+        ? false
+        : null;
+  const named = new Set<ForgeCheck>();
+  for (const name of waiver.checks) {
+    const matches = status.checks.filter((check) => check.name === name || check.context === name);
+    if (!matches.length && options.perPr) continue;
+    if (!matches.length)
+      return failure(
+        "invalid_input",
+        `unknown_check: --allow-failing ${JSON.stringify(name)} matches no check on the head; checks: ${status.checks.map((check) => check.name).join(", ") || "none"}`,
+        "workit pr status  # copy the check name exactly",
+      );
+    for (const check of matches) named.add(check);
+  }
+  const hard = [...named].filter((check) => required(check) !== false);
+  if (hard.length)
+    return failure(
+      "blocked",
+      `waiver_refused: ${hard.map((check) => `${check.name} (${required(check) ? "required by branch protection" : "the forge cannot say it is optional"})`).join(", ")}; --allow-failing only passes a check branch protection does not require`,
+      "fix the check (workit pr status shows its log tail), push, then workit ci wait",
+    );
+  const waived = [...named].filter((check) => check.state === "failing");
+  return success({
+    status: {
+      ...status,
+      checks: status.checks.map((check) =>
+        waived.includes(check)
+          ? { ...check, state: "skipped", conclusion: `waived_${check.conclusion ?? "failure"}` }
+          : check,
+      ),
+    },
+    waived,
+  });
+}
+
+/** Waits between re-reads while the forge reports mergeability UNKNOWN (3.5 s in all). */
+export const MERGEABILITY_RETRY_MS: readonly number[] = [500, 1000, 2000];
+
+/** Tests replace `sleep` (the forge reads are synchronous). */
+export const mergeGateDeps = {
+  sleep: (ms: number): void => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  },
+};
+
+/**
+ * `forge` as `pr merge` and `stack land` read it until the merge call: an
+ * open PR whose mergeability is UNKNOWN (the forge still computing it) is
+ * re-read with backoff, `MERGEABILITY_RETRY_MS`, before the gate decides (it
+ * stops at `wait-forge` when it stays unknown); and a waiver passes the
+ * failing optional checks it names. Each waived check is recorded as a
+ * `merge.waived` row only once the forge accepts the merge: a refusal before
+ * the merge call (another author, a verdict, a dry run) or a failed merge
+ * records nothing. After the merge call the forge is read as is. `waived`
+ * lists the checks a waiver passed on the merged PR, each with its row id,
+ * or the error when the row could not be written after the merge.
+ *
+ * `perPr` (`stack land`, #739): the waiver applies to each PR whose head runs
+ * the named check, and a PR without it is not refused for it. `matched` then
+ * collects the names some read head ran, so the caller can refuse a name no
+ * PR runs (`unknown_check`); `waives(n)` names the failing checks the waiver
+ * passes at PR n's latest read.
+ */
+export function mergeGateForge(
+  forge: Forge,
+  cwd: string,
+  options: { waiver: CheckWaiver | null; actor: LedgerActor; perPr?: boolean },
+): Forge & {
+  waived: WaivedCheck[];
+  matched: Set<string>;
+  waives: (number: number) => string[];
+} {
+  const waivedRows: WaivedCheck[] = [];
+  const matched = new Set<string>();
+  let merging = false;
+  // The waiver decided at the latest read of each PR; recorded on its merge.
+  const pending = new Map<number, { status: ForgePrStatus; checks: ForgeCheck[] }>();
+  const read = (number: number): ForgeResult<ForgePrStatus> => {
+    let status = forge.prStatus(number);
+    for (const delay of MERGEABILITY_RETRY_MS) {
+      if (!status.ok || status.data.state !== "open" || status.data.mergeable !== "unknown") break;
+      mergeGateDeps.sleep(delay);
+      status = forge.prStatus(number);
+    }
+    return status;
+  };
+  const record = (status: ForgePrStatus, check: ForgeCheck, reason: string): WaivedCheck => {
+    const row = appendObserved(cwd, {
+      type: "merge.waived",
+      actor: options.actor,
+      branch: status.head.branch,
+      head: status.head.sha,
+      pr: status.number,
+      base: status.base,
+      check: check.name,
+      conclusion: check.conclusion,
+      reason,
+      what: `#${status.number} failing optional check ${check.name} waived at ${status.head.sha.slice(0, 12)} (reason: ${reason})`,
+    });
+    return row.ok
+      ? { check: check.name, recorded: String(row.value.id) }
+      : { check: check.name, error: row.error };
+  };
+  return {
+    ...forge,
+    prStatus(number) {
+      if (merging) return forge.prStatus(number);
+      const status = read(number);
+      if (!status.ok || !options.waiver || status.data.state !== "open") return status;
+      for (const name of options.waiver.checks)
+        if (status.data.checks.some((check) => check.name === name || check.context === name))
+          matched.add(name);
+      const waived = waiveChecks(status.data, options.waiver, { perPr: options.perPr });
+      if (!waived.ok) return waived;
+      pending.set(number, { status: status.data, checks: waived.data.waived });
+      return success(waived.data.status);
+    },
+    merge(number, mergeOptions) {
+      merging = true;
+      const merged = forge.merge(number, mergeOptions);
+      const decided = pending.get(number);
+      if (merged.ok && decided && options.waiver)
+        for (const check of decided.checks)
+          waivedRows.push(record(decided.status, check, options.waiver.reason));
+      return merged;
+    },
+    waived: waivedRows,
+    matched,
+    waives: (number) => pending.get(number)?.checks.map((check) => check.name) ?? [],
+  };
+}