@intentius/chant 0.124.40 → 0.124.42

package/src/pr-forge.ts

@@ -361,6 +361,13 @@ export interface PrForge {
   authors(pr: number): Promise<string[]>;
   /** The merged pull request that produced `sha`, or null. */
   pullRequestFor(sha: string): Promise<number | null>;
+  /**
+   * Whether pull request `pr` (merge request `pr` on GitLab) is still open
+   * (#4293): neither merged nor closed. A pull request the forge does not
+   * know reads as not open. Target locks (../lifecycle/target-lock.ts) read
+   * a lock whose holder is not open as released.
+   */
+  pullRequestOpen?(pr: number): Promise<boolean>;
   /**
    * Open a pull request (a merge request on GitLab) from `head` into `base`,
    * or into the default branch when `base` is not given. Over REST on every
@@ -377,6 +384,10 @@ export interface PrForge {
   editPullRequest(pr: number, change: { title?: string; body?: string }): Promise<PullRequest | undefined>;
   /** Add labels to a pull request by name. Forgejo needs them to exist; GitHub and GitLab make them. */
   addLabels(pr: number, labels: readonly string[]): Promise<void>;
+  /** The names of the labels pull request `pr` carries (#4292), for `ci.labels`. */
+  labels?(pr: number): Promise<string[]>;
+  /** Whether pull request `pr` is open, closed unmerged, or merged (#4298), for `pr-env sweep`. */
+  pullRequestState?(pr: number): Promise<"open" | "closed" | "merged">;
   /**
    * Merge pull request `pr` only if its head is still `opts.sha`. A moved
    * head, a conflict or a branch rule the forge enforces comes back as
@@ -391,6 +402,81 @@ export interface PrForge {
   openPullRequests?(base: string): Promise<OpenPullRequest[]>;
   /** GitHub and Forgejo (#4095): the commit `branch` points at, or undefined when there is no such branch. */
   branchHead?(branch: string): Promise<string | undefined>;
+  /**
+   * When a scheduled Op's generated job last ran from its schedule or by hand
+   * (#4289). GitHub reads the workflow `workflow` names and its `schedule` and
+   * `workflow_dispatch` runs. Forgejo reads the repository's runs and keeps
+   * the ones from that workflow file. GitLab reads the active pipeline
+   * schedules whose `CHANT_SCHEDULED_OP` variable is `op` and their last
+   * pipelines. Throws a {@link ForgeApiError} when the forge will not say.
+   */
+  scheduledRuns?(query: ScheduledRunsQuery): Promise<ScheduledRuns>;
+  /**
+   * The four checks an apply before merge requires (#4301, ws-106), each
+   * about pull request `pr` at `head`, the commit the job checked out. Each
+   * fails when the forge's head for `pr` is another commit. `approved`:
+   * someone other than the pull request's authors ({@link authors}) approved
+   * `head`, and no standing review asks for changes. On GitLab an approval
+   * counts when it came after the merge request's latest push, read from its
+   * system notes, and never from the token's own user.
+   */
+  prApproved?(pr: number, head: string): Promise<PrRequireResult>;
+  /** The forge says `pr` merges as it stands: no conflicts, and on GitHub no branch protection blocking it. Pending while the forge works it out. */
+  prMergeable?(pr: number, head: string): Promise<PrRequireResult>;
+  /** `head` contains the tip of the branch `pr` merges into. */
+  prUndiverged?(pr: number, head: string): Promise<PrRequireResult>;
+  /**
+   * Every status and check reported on `head` passed, and at least one did.
+   * Statuses named in `ignore` are left out, such as the apply's own.
+   * Pending while one still runs or none has reported.
+   */
+  prChecksPassed?(pr: number, head: string, ignore?: readonly string[]): Promise<PrRequireResult>;
+}
+
+/** What one of the requires checks (#4301) found. */
+export interface PrRequireResult {
+  passed: boolean;
+  /** Not settled yet: the forge is still working it out, or a check still runs. Asking again may pass. */
+  pending?: boolean;
+  /** One line for a person. */
+  reason: string;
+}
+
+const short = (sha: string | undefined): string => (sha ?? "nothing").slice(0, 8);
+const pass = (reason: string): PrRequireResult => ({ passed: true, reason });
+const refuse = (reason: string, pending = false): PrRequireResult => ({ passed: false, ...(pending ? { pending: true } : {}), reason });
+const moved = (what: string, head: string, now: string | undefined): PrRequireResult => refuse(`${what}'s head is ${short(now)}, not ${short(head)}, the commit this job checked out`);
+
+/** The verdict over statuses and checks: failing and still-running names, and how many reported. */
+function checksVerdict(what: string, head: string, failing: string[], waiting: string[], count: number): PrRequireResult {
+  const names = (l: string[]) => [...new Set(l)].sort().join(", ");
+  if (failing.length > 0) return refuse(`${names(failing)} failed on ${short(head)}`);
+  if (waiting.length > 0) return refuse(`${names(waiting)} still running on ${short(head)}`, true);
+  if (count === 0) return refuse(`no check has reported on ${what}'s head ${short(head)} yet`, true);
+  return pass(`${count} check${count === 1 ? "" : "s"} passed on ${short(head)}`);
+}
+
+/** Which scheduled Op job {@link PrForge.scheduledRuns} asks about. */
+export interface ScheduledRunsQuery {
+  /** The Op's name, the value of GitLab's `CHANT_SCHEDULED_OP` selector. */
+  op: string;
+  /** GitHub and Forgejo: the Op's workflow file name, such as `drift-watch.yml`. */
+  workflow: string;
+}
+
+/** What a forge says about a scheduled Op job's runs (#4289). */
+export interface ScheduledRuns {
+  /** When the job last ran from its schedule or by hand (ISO 8601), if it ever did. */
+  last?: string;
+  /** GitHub: the workflow is off, and why (`disabled_inactivity`, `disabled_manually`). */
+  disabled?: string;
+  /** GitLab: no active pipeline schedule selects the Op. */
+  noSchedule?: boolean;
+}
+
+/** The newest of some ISO 8601 times, ignoring what does not parse. */
+function newestTime(times: readonly (string | undefined)[]): string | undefined {
+  return times.filter((t): t is string => typeof t === "string" && !Number.isNaN(Date.parse(t))).sort((a, b) => Date.parse(b) - Date.parse(a))[0];
 }
 
 /** A GitHub or Forgejo client. */
@@ -581,6 +667,11 @@ export interface GithubForgeOptions {
   fetch?: ForgeFetch;
 }
 
+/** GitLab's merge statuses while it works out whether a merge request can merge (#4301). */
+const GITLAB_CHECKING = new Set(["checking", "unchecked", "preparing", "approvals_syncing", "cannot_be_merged_recheck"]);
+/** GitLab's commit statuses still running. */
+const GITLAB_RUNNING = new Set(["created", "waiting_for_resource", "preparing", "pending", "running", "scheduled"]);
+
 /** GitHub keeps a status description to 140 characters; Forgejo follows. */
 const GITHUB_DESCRIPTION = 140;
 /** GitLab keeps a status description to 255 characters. */
@@ -650,6 +741,33 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       ...(url ? { target_url: url } : {}),
     });
   };
+  const authorsOf = async (pr: number): Promise<string[]> => {
+    const logins = new Set<string>();
+    const add = (v: unknown) => {
+      if (isObject(v) && typeof v.login === "string" && v.login !== "") logins.add(v.login);
+    };
+    const opened = await api.call("GET", `${repo}/pulls/${pr}`);
+    if (isObject(opened)) add(opened.user);
+    for (const c of await api.list(`${repo}/pulls/${pr}/commits`, pageParams, pageSize)) {
+      if (!isObject(c)) continue;
+      add(c.author);
+      add(c.committer);
+    }
+    return [...logins].sort();
+  };
+  const branchTip = async (branch: string): Promise<string | undefined> => {
+    let b: unknown;
+    try {
+      b = await api.call("GET", `${repo}/branches/${branch.split("/").map(encodeURIComponent).join("/")}`);
+    } catch (err) {
+      if (err instanceof ForgeApiError && err.status === 404) return undefined;
+      throw err;
+    }
+    // GitHub names the commit `sha`, Forgejo `id`.
+    const commit = isObject(b) && isObject(b.commit) ? b.commit : undefined;
+    return commit ? str(commit.sha) ?? str(commit.id) : undefined;
+  };
+  const headOf = (v: unknown): string | undefined => (isObject(v) && isObject(v.head) ? str(v.head.sha) : undefined);
   return {
     kind,
     host,
@@ -677,19 +795,93 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       }
       return [...standing].filter(([, state]) => state === "APPROVED").map(([login]) => login).sort();
     },
-    async authors(pr) {
-      const logins = new Set<string>();
-      const add = (v: unknown) => {
-        if (isObject(v) && typeof v.login === "string" && v.login !== "") logins.add(v.login);
-      };
-      const opened = await api.call("GET", `${repo}/pulls/${pr}`);
-      if (isObject(opened)) add(opened.user);
-      for (const c of await api.list(`${repo}/pulls/${pr}/commits`, pageParams, pageSize)) {
-        if (!isObject(c)) continue;
-        add(c.author);
-        add(c.committer);
+    authors: authorsOf,
+    async prApproved(pr, head) {
+      const got = await api.call("GET", `${repo}/pulls/${pr}`);
+      const at = headOf(got);
+      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      // A reviewer's newest deciding review stands, as in approvers; an approval counts only of this head.
+      const standing = new Map<string, { state: string; commit?: string }>();
+      for (const r of await api.list(`${repo}/pulls/${pr}/reviews`, pageParams, pageSize)) {
+        const login = loginOf(r);
+        if (!login || !isObject(r) || typeof r.state !== "string") continue;
+        const state = r.dismissed === true ? "DISMISSED" : r.state.toUpperCase();
+        if (state === "COMMENTED" || state === "COMMENT" || state === "PENDING") continue;
+        const commit = str(r.commit_id);
+        standing.set(login, { state, ...(commit ? { commit } : {}) });
+      }
+      const changes = [...standing].filter(([, r]) => r.state === "CHANGES_REQUESTED" || r.state === "REQUEST_CHANGES").map(([l]) => l).sort();
+      if (changes.length > 0) return refuse(`${changes.join(", ")} asked for changes`);
+      const authors = new Set(await authorsOf(pr));
+      const by = [...standing].filter(([l, r]) => r.state === "APPROVED" && r.commit === head && !authors.has(l)).map(([l]) => l).sort();
+      if (by.length === 0) return refuse(`no reviewer other than its authors approved its head ${short(head)}`);
+      return pass(`approved at ${short(head)} by ${by.join(", ")}`);
+    },
+    async prMergeable(pr, head) {
+      const got = await api.call("GET", `${repo}/pulls/${pr}`);
+      const at = headOf(got);
+      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      const m = isObject(got) ? got : {};
+      const into = isObject(m.base) ? str(m.base.ref) : undefined;
+      if (m.mergeable === false || m.mergeable_state === "dirty") return refuse(`the forge reports conflicts with ${into ?? "its base"}`);
+      if (m.mergeable !== true) return refuse("the forge has not worked out yet whether it can merge", true);
+      if (kind === "github" && m.mergeable_state === "blocked") return refuse(`branch protection on ${into ?? "its base"} blocks its merge`);
+      return pass(`it merges into ${into ?? "its base"} as it stands`);
+    },
+    async prUndiverged(pr, head) {
+      const got = await api.call("GET", `${repo}/pulls/${pr}`);
+      const at = headOf(got);
+      if (at !== head) return moved(`pull request ${pr}`, head, at);
+      const into = isObject(got) && isObject(got.base) ? str(got.base.ref) : undefined;
+      if (!into) return refuse(`the forge names no branch pull request ${pr} merges into`);
+      if (kind === "github") {
+        // behind_by: the commits on the base branch that the head does not contain.
+        const cmp = await api.call("GET", `${repo}/compare/${encodeURIComponent(into)}...${head}`);
+        const behind = isObject(cmp) ? num(cmp.behind_by) : undefined;
+        if (behind === undefined) return refuse(`the forge did not say how far ${short(head)} is behind ${into}`);
+        return behind === 0 ? pass(`${short(head)} contains ${into}`) : refuse(`${short(head)} is ${behind} commit${behind === 1 ? "" : "s"} behind ${into}`);
+      }
+      // Forgejo: the pull request's merge base is the base branch's tip exactly when the head contains it.
+      const tip = await branchTip(into);
+      const base = isObject(got) ? str(got.merge_base) : undefined;
+      if (!tip || !base) return refuse(`the forge did not say where ${into} is or where ${short(head)} left it`);
+      return base === tip ? pass(`${short(head)} contains ${into} at ${short(tip)}`) : refuse(`${short(head)} does not contain ${into} at ${short(tip)}`);
+    },
+    async prChecksPassed(_pr, head, ignore = []) {
+      const skip = new Set(ignore);
+      const failing: string[] = [];
+      const waiting: string[] = [];
+      let count = 0;
+      // The combined status holds each context's newest status.
+      const combined = await api.call("GET", `${repo}/commits/${head}/status`);
+      for (const st of isObject(combined) && Array.isArray(combined.statuses) ? combined.statuses : []) {
+        const context = isObject(st) ? str(st.context) : undefined;
+        if (!context || skip.has(context)) continue;
+        const state = str(st.state) ?? str(st.status) ?? "";
+        count++;
+        if (state === "failure" || state === "error" || state === "failed") failing.push(context);
+        else if (state === "pending" || state === "running" || state === "") waiting.push(context);
+      }
+      if (kind === "github") {
+        const runs = await api.call("GET", `${repo}/commits/${head}/check-runs?per_page=100`);
+        for (const run of isObject(runs) && Array.isArray(runs.check_runs) ? runs.check_runs : []) {
+          const name = (isObject(run) ? str(run.name) : undefined) ?? "a check";
+          if (skip.has(name) || !isObject(run)) continue;
+          count++;
+          if (run.status !== "completed") waiting.push(name);
+          else if (!["success", "neutral", "skipped"].includes(String(run.conclusion))) failing.push(name);
+        }
+      }
+      return checksVerdict(`pull request ${_pr}`, head, failing, waiting, count);
+    },
+    async pullRequestOpen(pr) {
+      try {
+        const got = await api.call("GET", `${repo}/pulls/${pr}`);
+        return isObject(got) && got.state === "open" && got.merged !== true;
+      } catch (err) {
+        if (err instanceof ForgeApiError && err.status === 404) return false;
+        throw err;
       }
-      return [...logins].sort();
     },
     async pullRequestFor(sha) {
       if (kind === "forgejo") {
@@ -765,17 +957,27 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       }
       return out.sort((a, b) => a.number - b.number);
     },
-    async branchHead(branch) {
-      let b: unknown;
-      try {
-        b = await api.call("GET", `${repo}/branches/${branch.split("/").map(encodeURIComponent).join("/")}`);
-      } catch (err) {
-        if (err instanceof ForgeApiError && err.status === 404) return undefined;
-        throw err;
+    branchHead: branchTip,
+    async scheduledRuns(q) {
+      const file = encodeURIComponent(q.workflow);
+      if (kind === "github") {
+        const workflow = await api.call("GET", `${repo}/actions/workflows/${file}`);
+        const runs = await Promise.all(["schedule", "workflow_dispatch"].map((event) => api.call("GET", `${repo}/actions/workflows/${file}/runs?event=${event}&per_page=1`)));
+        const last = newestTime(runs.flatMap((r) => (isObject(r) && Array.isArray(r.workflow_runs) ? r.workflow_runs.map((w) => (isObject(w) ? str(w.created_at) : undefined)) : [])));
+        const state = (isObject(workflow) ? str(workflow.state) : undefined) ?? "active";
+        return { ...(last ? { last } : {}), ...(state.startsWith("disabled") ? { disabled: state } : {}) };
       }
-      // GitHub names the commit `sha`, Forgejo `id`.
-      const commit = isObject(b) && isObject(b.commit) ? b.commit : undefined;
-      return commit ? str(commit.sha) ?? str(commit.id) : undefined;
+      // Forgejo lists a repository's runs newest first; the event and the workflow are read from each run, whatever the query honours.
+      const listed = await api.call("GET", `${repo}/actions/runs?event=schedule&limit=50`);
+      const runs = Array.isArray(listed) ? listed : isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : [];
+      const ours = runs.filter((r): r is Record<string, unknown> => {
+        if (!isObject(r)) return false;
+        const event = str(r.event) ?? str(r.trigger_event);
+        const workflow = str(r.workflow_id) ?? str(r.path);
+        return (event === "schedule" || event === "workflow_dispatch") && (workflow === undefined || workflow.endsWith(q.workflow));
+      });
+      const last = newestTime(ours.map((r) => str(r.created) ?? str(r.created_at) ?? str(r.started)));
+      return last ? { last } : {};
     },
     async editPullRequest(pr, change) {
       return pull(await api.call("PATCH", `${repo}/pulls/${pr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { body: change.body } : {}) }));
@@ -784,6 +986,16 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       if (labels.length === 0) return;
       await api.call("POST", `${repo}/issues/${pr}/labels`, { labels: [...labels] });
     },
+    async labels(pr) {
+      const listed = await api.list(`${repo}/issues/${pr}/labels`, pageParams, pageSize);
+      return listed.map((l) => (isObject(l) ? str(l.name) : undefined)).filter((n): n is string => n !== undefined);
+    },
+    async pullRequestState(pr) {
+      const p = await api.call("GET", `${repo}/pulls/${pr}`);
+      if (!isObject(p)) return "open";
+      if (p.merged === true || (typeof p.merged_at === "string" && p.merged_at !== "")) return "merged";
+      return p.state === "closed" ? "closed" : "open";
+    },
     async mergePullRequest(pr, m) {
       const method = m.method ?? "merge";
       let res: unknown;
@@ -915,6 +1127,22 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       await api.call("PUT", `${project}/issues/${n}`, { state_event: "close" });
     },
   };
+  const authorsOf = async (mr: number): Promise<string[]> => {
+    const logins = new Set<string>();
+    const merge = await api.call("GET", `${notes}/${mr}`);
+    const author = isObject(merge) ? authorOf(merge) : undefined;
+    if (author) logins.add(author);
+    const emails = new Set<string>();
+    for (const c of await api.list(`${notes}/${mr}/commits`, pageParams, 100)) {
+      if (!isObject(c)) continue;
+      for (const email of [str(c.author_email), str(c.committer_email)]) if (email) emails.add(email.toLowerCase());
+    }
+    for (const email of [...emails].sort()) {
+      const users = await api.call("GET", `/users?search=${encodeURIComponent(email)}`);
+      for (const u of Array.isArray(users) ? users : []) if (isObject(u) && typeof u.username === "string") logins.add(u.username);
+    }
+    return [...logins].sort();
+  };
   return {
     kind: "gitlab",
     host,
@@ -946,21 +1174,83 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         .filter((l): l is string => l !== undefined);
       return [...new Set(logins)].sort();
     },
-    async authors(mr) {
-      const logins = new Set<string>();
-      const merge = await api.call("GET", `${notes}/${mr}`);
-      const author = isObject(merge) ? authorOf(merge) : undefined;
-      if (author) logins.add(author);
-      const emails = new Set<string>();
-      for (const c of await api.list(`${notes}/${mr}/commits`, pageParams, 100)) {
-        if (!isObject(c)) continue;
-        for (const email of [str(c.author_email), str(c.committer_email)]) if (email) emails.add(email.toLowerCase());
+    authors: authorsOf,
+    async prApproved(mr, head) {
+      const got = await api.call("GET", `${notes}/${mr}`);
+      const at = isObject(got) ? str(got.sha) : undefined;
+      if (at !== head) return moved(`merge request !${mr}`, head, at);
+      // The token's own user approves for the pipeline, never as a reviewer.
+      const me = await api.call("GET", "/user");
+      const self = isObject(me) ? str(me.username) : undefined;
+      if (!self) return refuse("GitLab did not say which user the job's token acts as, so no approval counts");
+      // An approval counts once it came after the latest push: the newest version of the diff.
+      const versions = await api.call("GET", `${notes}/${mr}/versions`);
+      const since = Math.max(-Infinity, ...(Array.isArray(versions) ? versions : []).map((v) => Date.parse((isObject(v) ? str(v.created_at) : undefined) ?? "")).filter(Number.isFinite));
+      const said = new Map<string, { what: string; at: number }>();
+      for (const n of await api.list(`${notes}/${mr}/notes?sort=asc&order_by=created_at`, pageParams, 100)) {
+        if (!isObject(n) || n.system !== true) continue;
+        const who = authorOf(n);
+        const body = (str(n.body) ?? "").trim();
+        const what = /^approved this merge request/.test(body) ? "approved" : /^unapproved this merge request/.test(body) ? "unapproved" : /^requested changes/.test(body) ? "changes" : undefined;
+        const when = Date.parse(str(n.created_at) ?? "");
+        if (!who || who === self || !what || !Number.isFinite(when)) continue;
+        const before = said.get(who);
+        if (!before || when >= before.at) said.set(who, { what, at: when });
+      }
+      const changes = [...said].filter(([, v]) => v.what === "changes").map(([w]) => w).sort();
+      if (changes.length > 0) return refuse(`${changes.join(", ")} requested changes`);
+      const authors = new Set(await authorsOf(mr));
+      const by = [...said].filter(([w, v]) => v.what === "approved" && v.at > since && !authors.has(w)).map(([w]) => w).sort();
+      if (by.length === 0) return refuse(`no member other than its authors approved it after its latest push, ${short(head)}`);
+      return pass(`approved after ${short(head)} by ${by.join(", ")}`);
+    },
+    async prMergeable(mr, head) {
+      const got = await api.call("GET", `${notes}/${mr}`);
+      const m = isObject(got) ? got : {};
+      if (str(m.sha) !== head) return moved(`merge request !${mr}`, head, str(m.sha));
+      const status = str(m.detailed_merge_status) ?? (m.merge_status === "can_be_merged" ? "mergeable" : (str(m.merge_status) ?? ""));
+      const into = str(m.target_branch) ?? "its target branch";
+      if (status === "conflict" || m.has_conflicts === true) return refuse(`GitLab reports conflicts with ${into}`);
+      if (GITLAB_CHECKING.has(status)) return refuse("GitLab has not worked out yet whether it can merge", true);
+      if (status !== "mergeable") return refuse(`GitLab says ${status || "nothing"} about merging it`);
+      return pass(`it merges into ${into} as it stands`);
+    },
+    async prUndiverged(mr, head) {
+      const got = await api.call("GET", `${notes}/${mr}?include_diverged_commits_count=true`);
+      const m = isObject(got) ? got : {};
+      if (str(m.sha) !== head) return moved(`merge request !${mr}`, head, str(m.sha));
+      const into = str(m.target_branch) ?? "its target branch";
+      const behind = num(m.diverged_commits_count);
+      if (behind === undefined) return refuse(`GitLab did not say how far ${short(head)} is behind ${into}`);
+      return behind === 0 ? pass(`${short(head)} contains ${into}`) : refuse(`${short(head)} is ${behind} commit${behind === 1 ? "" : "s"} behind ${into}`);
+    },
+    async prChecksPassed(mr, head, ignore = []) {
+      const skip = new Set(ignore);
+      // Each name's newest status; a job allowed to fail holds nothing back.
+      const newest = new Map<string, Record<string, unknown>>();
+      for (const st of await api.list(`${project}/repository/commits/${head}/statuses?all=true`, pageParams, 100)) {
+        const name = isObject(st) ? str(st.name) : undefined;
+        if (!name || skip.has(name) || !isObject(st)) continue;
+        const had = newest.get(name);
+        if (!had || (num(st.id) ?? 0) > (num(had.id) ?? 0)) newest.set(name, st);
       }
-      for (const email of [...emails].sort()) {
-        const users = await api.call("GET", `/users?search=${encodeURIComponent(email)}`);
-        for (const u of Array.isArray(users) ? users : []) if (isObject(u) && typeof u.username === "string") logins.add(u.username);
+      const failing: string[] = [];
+      const waiting: string[] = [];
+      for (const [name, st] of newest) {
+        const state = str(st.status) ?? "";
+        if ((state === "failed" || state === "canceled") && st.allow_failure !== true) failing.push(name);
+        else if (GITLAB_RUNNING.has(state)) waiting.push(name);
+      }
+      return checksVerdict(`merge request !${mr}`, head, failing, waiting, newest.size);
+    },
+    async pullRequestOpen(mr) {
+      try {
+        const got = await api.call("GET", `${notes}/${mr}`);
+        return isObject(got) && got.state === "opened";
+      } catch (err) {
+        if (err instanceof ForgeApiError && err.status === 404) return false;
+        throw err;
       }
-      return [...logins].sort();
     },
     async pullRequestFor(sha) {
       const mrs = await api.call("GET", `${project}/repository/commits/${sha}/merge_requests`);
@@ -984,6 +1274,19 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         .filter((m): m is PullRequest => m !== undefined)
         .sort((a, b) => a.number - b.number)[0];
     },
+    async scheduledRuns(q) {
+      // The variable the gitlab lexicon's generated Op file selects a scheduled job by.
+      const selects = (d: unknown): boolean =>
+        isObject(d) && Array.isArray(d.variables) && d.variables.some((v) => isObject(v) && v.key === "CHANT_SCHEDULED_OP" && v.value === q.op);
+      const schedules = await api.list(`${project}/pipeline_schedules?scope=active`, pageParams, 100);
+      // A schedule's variables are on each schedule, not the list.
+      const details = await Promise.all(schedules.map((s) => api.call("GET", `${project}/pipeline_schedules/${isObject(s) ? num(s.id) : ""}`)));
+      const ours = details.filter(selects);
+      const ids = ours.map((d) => (isObject(d) && isObject(d.last_pipeline) ? num(d.last_pipeline.id) : undefined)).filter((n): n is number => n !== undefined && n > 0);
+      const pipelines = await Promise.all(ids.map((id) => api.call("GET", `${project}/pipelines/${id}`)));
+      const last = newestTime(pipelines.map((p) => (isObject(p) ? str(p.created_at) : undefined)));
+      return { ...(last ? { last } : {}), ...(ours.length === 0 ? { noSchedule: true } : {}) };
+    },
     async editPullRequest(mr, change) {
       return mergeRequest(await api.call("PUT", `${notes}/${mr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { description: change.body } : {}) }));
     },
@@ -991,6 +1294,15 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       if (labels.length === 0) return;
       await api.call("PUT", `${notes}/${mr}`, { add_labels: labels.join(",") });
     },
+    async labels(mr) {
+      const m = await api.call("GET", `${notes}/${mr}`);
+      return isObject(m) && Array.isArray(m.labels) ? m.labels.filter((l): l is string => typeof l === "string") : [];
+    },
+    async pullRequestState(mr) {
+      const m = await api.call("GET", `${notes}/${mr}`);
+      if (!isObject(m)) return "open";
+      return m.state === "merged" ? "merged" : m.state === "closed" ? "closed" : "open";
+    },
     async mergePullRequest(mr, m) {
       const method = m.method ?? "merge";
       if (method === "rebase") throw new Error("GitLab has no one-call rebase merge; use method merge or squash");

package/src/pr-loop-bundle.test.ts

@@ -41,7 +41,7 @@ describe("the pull-request loop bundle", () => {
       "packages/core/src/pr-forge.ts",
       "packages/core/src/pr-loop.ts",
     ]);
-    // About 65 KB today, after the pull request authors (#4000).
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(72 * 1024);
+    // About 89 KB today, after the hooks line (#4288), the blocked set (#4291), the scheduled-run reads (#4289) and the requires checks (#4301).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(96 * 1024);
   });
 });

package/src/pr-loop.test.ts

@@ -366,3 +366,61 @@ describe("a gate per wave on merge (#4003)", () => {
     expect(prStatusDescription({ ...waiting, waves: [wave1], refusal: "earlier-wave" })).toBe("refused: an earlier wave has not applied");
   });
 });
+
+describe("stage hooks in the report and the note (#4288)", () => {
+  const hooked: PrReport = {
+    ...planReport,
+    status: "plan-failed",
+    message: "The before-plan hook lint exited 1, so nothing was planned or applied.",
+    hooks: [
+      { moment: "before-observe", name: "init", target: "a", exit: 0, outcome: "passed" },
+      { moment: "before-plan", name: "lint", exit: 1, outcome: "failed" },
+    ],
+  };
+
+  test("a report with hooks validates", () => {
+    expectValid(hooked);
+  });
+
+  test("the note counts the hooks that passed and names the one that failed", () => {
+    const note = renderPrNote(hooked);
+    expect(note).toContain("A hook failed, so nothing can apply.");
+    expect(note).toContain("Hooks: 1 passed; `lint` before-plan failed (exit 1).");
+  });
+});
+
+describe("the policy in the report and the note (#4294)", () => {
+  const policy = {
+    result: "denied" as const,
+    engine: "opa" as const,
+    base: "b".repeat(40),
+    denials: [{ rule: "main.deny_public", message: "bucket logs is public" }],
+    rules: ["main.deny_public"],
+    holds: [{ rule: "main.hold_iam", message: "an IAM role changes" }],
+    warnings: ["three deletes"],
+    overrideCommand: 'chant approve policy-override pr-7 --rule main.deny_public --reason "<why>"',
+  };
+  const denied: PrReport = { ...planReport, policy };
+
+  test("a report with a policy, and an apply the policy refused, validate", () => {
+    expectValid(denied);
+    expectValid({ ...denied, stage: "apply", status: "refused", refusal: "policy-denied", message: "The policy denied this plan." });
+    expectValid({ ...denied, policy: { ...policy, result: "error", denials: [], rules: undefined, holds: [], error: "opa did not run" }, stage: "apply", status: "refused", refusal: "policy-error" });
+  });
+
+  test("the note names the denial, the hold and the override command", () => {
+    const note = renderPrNote(denied);
+    expect(note).toContain("Policy (opa, read at `bbbbbbbbbbbb`) denied this plan:");
+    expect(note).toContain("- `main.deny_public`: bucket logs is public");
+    expect(note).toContain("holds this plan for a person's approval of its digest:");
+    expect(note).toContain(policy.overrideCommand);
+    expect(note).toContain("Policy warnings: three deletes");
+  });
+
+  test("a denied plan fails its status until an override counts; the apply's refusal says why", () => {
+    expect(prStatusState(denied)).toBe("failure");
+    expect(prStatusState({ ...denied, policy: { ...policy, override: { by: "github:carol", at: "2026-10-22T12:00:00Z", reason: "docs site", digest: "sha256:1" } } })).toBe("success");
+    expect(prStatusState({ ...denied, policy: { ...policy, result: "held", denials: [] } })).toBe("success");
+    expect(prStatusDescription({ ...denied, stage: "apply", status: "refused", refusal: "policy-denied" })).toBe("refused: the policy denied the plan (main.deny_public)");
+  });
+});