@intentius/chant 0.124.39 → 0.124.41

package/src/op/schedule-overdue.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Scheduled watch and reconcile Ops that stopped running (#4289): the UTC
+ * cron count, the verdict, the forge clients' `scheduledRuns`, the check the
+ * plan job runs, and the warning line in the plan note.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { cronFiresUtc } from "./cron";
+import { checkOverdueOps, opPipelineFile, overdueVerdict, scheduledWatches } from "./schedule-overdue";
+import { forgejoForge, githubForge, gitlabForge, type ForgeFetch, type PrForge } from "../pr-forge";
+import { renderPrNote, type PrReport } from "../pr-loop";
+import type { OpConfig } from "./types";
+
+function fakeFetch(route: (method: string, url: URL) => unknown): ForgeFetch {
+  return async (url, init) => {
+    const found = route(init.method, new URL(url));
+    if (found === undefined) return { ok: false, status: 404, text: async () => '{"message":"Not Found"}' };
+    if (typeof found === "number") return { ok: false, status: found, text: async () => "" };
+    return { ok: true, status: 200, text: async () => JSON.stringify(found) };
+  };
+}
+
+describe("cronFiresUtc", () => {
+  test("counts fires in UTC, after the start and up to the end", () => {
+    const fires = cronFiresUtc("0 6 * * *", new Date("2026-10-01T06:00:00Z"), new Date("2026-10-04T05:59:00Z"), 5);
+    expect(fires.map((d) => d.toISOString())).toEqual(["2026-10-02T06:00:00.000Z", "2026-10-03T06:00:00.000Z"]);
+  });
+
+  test("stops at max, reads weekday names as numbers and 7 as Sunday", () => {
+    expect(cronFiresUtc("*/15 * * * *", new Date("2026-10-01T00:00:00Z"), new Date("2026-10-02T00:00:00Z"), 2)).toHaveLength(2);
+    const sundays = cronFiresUtc("0 0 * * 7", new Date("2026-10-01T00:00:00Z"), new Date("2026-10-31T00:00:00Z"), 10);
+    expect(sundays.every((d) => d.getUTCDay() === 0)).toBe(true);
+    expect(sundays).toHaveLength(4);
+  });
+
+  test("an expression that is not 5 or 6 fields fires never", () => {
+    expect(cronFiresUtc("0 6 *", new Date("2026-01-01T00:00:00Z"), new Date("2026-12-31T00:00:00Z"), 2)).toEqual([]);
+  });
+});
+
+describe("scheduledWatches", () => {
+  const op = (name: string, labels?: Record<string, string>, cron?: string): OpConfig =>
+    ({ name, overview: "", phases: [], ...(labels ? { labels } : {}), ...(cron ? { schedule: { cron } } : {}) }) as OpConfig;
+
+  test("keeps scheduled Ops labelled Watch or Reconcile, sorted", () => {
+    const got = scheduledWatches([
+      op("z-watch", { Watch: "true" }, "0 * * * *"),
+      op("a-reconcile", { Reconcile: "true" }, "0 6 * * *"),
+      op("unscheduled", { Watch: "true" }),
+      op("deploy", undefined, "0 6 * * *"),
+    ]);
+    expect(got).toEqual([
+      { op: "a-reconcile", cron: "0 6 * * *" },
+      { op: "z-watch", cron: "0 * * * *" },
+    ]);
+  });
+});
+
+describe("overdueVerdict", () => {
+  const watch = { op: "drift", cron: "0 6 * * *" };
+  const now = new Date("2026-10-22T12:00:00Z");
+
+  test("one missed fire is on time; two is overdue", () => {
+    expect(overdueVerdict(watch, "github", { last: "2026-10-21T06:01:00Z" }, undefined, now)).toBeUndefined();
+    const late = overdueVerdict(watch, "github", { last: "2026-10-20T06:01:00Z" }, undefined, now);
+    expect(late?.since).toBe("2026-10-20T06:01:00Z");
+    expect(late?.message).toContain("Op `drift` is overdue");
+    expect(late?.message).toContain("its last run was on 2026-10-20");
+  });
+
+  test("a job that never ran counts from its pipeline file's commit", () => {
+    const v = overdueVerdict(watch, "forgejo", {}, "2026-10-01T00:00:00Z", now);
+    expect(v?.neverRan).toBe(true);
+    expect(v?.message).toContain("no run is on record since its pipeline was added on 2026-10-01");
+  });
+
+  test("nothing to count from is no verdict", () => {
+    expect(overdueVerdict(watch, "github", {}, undefined, now)).toBeUndefined();
+  });
+
+  test("names a disabled workflow and a missing GitLab schedule", () => {
+    expect(overdueVerdict(watch, "github", { last: "2026-09-01T00:00:00Z", disabled: "disabled_inactivity" }, undefined, now)?.message).toContain("disabled_inactivity");
+    expect(overdueVerdict(watch, "gitlab", { noSchedule: true }, "2026-09-01T00:00:00Z", now)?.message).toContain("No active pipeline schedule sets CHANT_SCHEDULED_OP to drift");
+  });
+});
+
+describe("scheduledRuns", () => {
+  test("github: the newest schedule or dispatch run, and a disabled workflow", async () => {
+    const fetch = fakeFetch((_m, u) => {
+      if (u.pathname === "/repos/acme/infra/actions/workflows/drift.yml") return { state: "disabled_inactivity" };
+      if (u.pathname === "/repos/acme/infra/actions/workflows/drift.yml/runs") {
+        return { workflow_runs: [{ created_at: u.searchParams.get("event") === "schedule" ? "2026-08-01T06:00:00Z" : "2026-08-03T10:00:00Z" }] };
+      }
+      return undefined;
+    });
+    const forge = githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t", fetch });
+    expect(await forge.scheduledRuns!({ op: "drift", workflow: "drift.yml" })).toEqual({ last: "2026-08-03T10:00:00Z", disabled: "disabled_inactivity" });
+  });
+
+  test("forgejo: only this workflow's schedule and dispatch runs", async () => {
+    const fetch = fakeFetch((_m, u) =>
+      u.pathname === "/api/v1/repos/acme/infra/actions/runs"
+        ? {
+            workflow_runs: [
+              { event: "schedule", workflow_id: "other.yml", created: "2026-10-20T00:00:00Z" },
+              { event: "push", workflow_id: "drift.yml", created: "2026-10-19T00:00:00Z" },
+              { event: "schedule", workflow_id: "drift.yml", created: "2026-10-10T00:00:00Z" },
+            ],
+          }
+        : undefined,
+    );
+    const forge = forgejoForge({ apiBase: "https://code.example/api/v1", repo: "acme/infra", host: "code.example", token: "t", fetch });
+    expect(await forge.scheduledRuns!({ op: "drift", workflow: "drift.yml" })).toEqual({ last: "2026-10-10T00:00:00Z" });
+  });
+
+  test("gitlab: the schedules that select the Op, and none", async () => {
+    const fetch = fakeFetch((_m, u) => {
+      const p = u.pathname.replace("/api/v4/projects/42", "");
+      if (p === "/pipeline_schedules") return [{ id: 1 }, { id: 2 }];
+      if (p === "/pipeline_schedules/1") return { id: 1, variables: [{ key: "CHANT_SCHEDULED_OP", value: "drift" }], last_pipeline: { id: 900 } };
+      if (p === "/pipeline_schedules/2") return { id: 2, variables: [{ key: "CHANT_SCHEDULED_OP", value: "other" }], last_pipeline: { id: 901 } };
+      if (p === "/pipelines/900") return { id: 900, created_at: "2026-10-01T06:00:00Z" };
+      return undefined;
+    });
+    const forge = gitlabForge({ apiBase: "https://gitlab.com/api/v4", project: "42", token: "t", fetch });
+    expect(await forge.scheduledRuns!({ op: "drift", workflow: "ops.gitlab-ci.yml" })).toEqual({ last: "2026-10-01T06:00:00Z" });
+    expect(await forge.scheduledRuns!({ op: "nobody", workflow: "ops.gitlab-ci.yml" })).toEqual({ noSchedule: true });
+  });
+});
+
+describe("checkOverdueOps", () => {
+  let dir: string | undefined;
+  afterEach(() => {
+    if (dir) rmSync(dir, { recursive: true, force: true });
+    dir = undefined;
+  });
+
+  function repo(files: Record<string, string>, date: string): string {
+    dir = mkdtempSync(join(tmpdir(), "chant-overdue-"));
+    const git = (...args: string[]) =>
+      execFileSync("git", ["-C", dir!, ...args], { env: { ...process.env, GIT_COMMITTER_DATE: date, GIT_AUTHOR_DATE: date }, stdio: "pipe" });
+    git("init", "-q");
+    for (const [path, body] of Object.entries(files)) {
+      mkdirSync(join(dir, path, ".."), { recursive: true });
+      writeFileSync(join(dir, path), body);
+    }
+    git("add", ".");
+    git("-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "add");
+    return dir;
+  }
+
+  const forgeWith = (kind: PrForge["kind"], scheduledRuns: PrForge["scheduledRuns"]): PrForge => ({ kind, host: "example", scheduledRuns }) as PrForge;
+
+  test("warns for an Op whose job never ran since its workflow was added, and skips one with no pipeline file", async () => {
+    const root = repo({ ".github/workflows/drift.yml": "on: schedule" }, "2026-10-01T00:00:00Z");
+    const asked: string[] = [];
+    const lines: string[] = [];
+    const found = await checkOverdueOps({
+      watches: [
+        { op: "drift", cron: "0 6 * * *" },
+        { op: "operator-only", cron: "0 6 * * *" },
+      ],
+      forge: forgeWith("github", async (q) => {
+        asked.push(q.workflow);
+        return {};
+      }),
+      repoRoot: root,
+      now: new Date("2026-10-22T00:00:00Z"),
+      log: (l) => lines.push(l),
+    });
+    expect(asked).toEqual(["drift.yml"]);
+    expect(found.map((o) => [o.op, o.neverRan, o.since.slice(0, 10)])).toEqual([["drift", true, "2026-10-01"]]);
+    expect(lines).toHaveLength(1);
+  });
+
+  test("a forge that will not answer is a log line and no verdict", async () => {
+    const root = repo({ ".github/workflows/web-drift.yml": "on: schedule" }, "2026-10-01T00:00:00Z");
+    const lines: string[] = [];
+    const found = await checkOverdueOps({
+      watches: [{ op: "drift", cron: "0 6 * * *" }],
+      forge: forgeWith("github", async () => {
+        throw new Error("GET answered 403");
+      }),
+      repoRoot: root,
+      member: "web",
+      now: new Date("2026-10-22T00:00:00Z"),
+      log: (l) => lines.push(l),
+    });
+    expect(found).toEqual([]);
+    expect(lines[0]).toContain("did not say when Op drift last ran");
+  });
+
+  test("gitlab: the root file whose rules select the Op", () => {
+    const root = repo({ "ops.gitlab-ci.yml": 'rules:\n  - if: $CI_PIPELINE_SOURCE == "schedule" && $CHANT_SCHEDULED_OP == "drift"\n' }, "2026-10-01T00:00:00Z");
+    expect(opPipelineFile(root, "gitlab", "drift")).toBe("ops.gitlab-ci.yml");
+    expect(opPipelineFile(root, "gitlab", "other")).toBeUndefined();
+  });
+});
+
+describe("the plan note", () => {
+  test("prints each overdue Op as a warning", () => {
+    const report = {
+      stage: "plan",
+      env: "prod",
+      base: "b".repeat(40),
+      head: "a".repeat(40),
+      status: "nothing",
+      digest: "",
+      members: [],
+      selection: { changed: [], dependents: [], unclaimed: [], indeterminate: [], waves: [] },
+      changeSet: { members: [], entries: [], summary: { byMember: {} } },
+      approval: { status: "pending" },
+      overdue: [{ op: "drift", cron: "0 6 * * *", since: "2026-10-01T00:00:00Z", message: "Op `drift` is overdue: test." }],
+    } as unknown as PrReport;
+    expect(renderPrNote(report)).toContain("Warning: Op `drift` is overdue: test.");
+  });
+});

package/src/op/schedule-overdue.ts

@@ -0,0 +1,161 @@
+/**
+ * Scheduled watch and reconcile Ops that stopped running (#4289).
+ *
+ * A schedule can stop with no error anywhere. GitHub turns a scheduled
+ * workflow off after 60 days with no activity in the repository and drops
+ * scheduled runs under load. A GitLab schedule exists only once someone
+ * creates it. A watch Op cannot report its own absence, so the pull-request
+ * plan job does. For each discovered Op with a `schedule` and the `Watch` or
+ * `Reconcile` label, whose generated pipeline file is in the checkout, it
+ * asks the forge when the Op's job last ran. When the cron has fired at
+ * least twice since then, or since the pipeline file was added for a job
+ * that never ran, the job log and the plan note say the Op is overdue.
+ *
+ * One late or dropped run is not enough: two fires are. A forge that will
+ * not answer is a line in the log and no verdict.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { OpConfig } from "./types";
+import { cronFiresUtc } from "./cron";
+import type { ForgeKind, PrForge, ScheduledRuns } from "../pr-forge";
+
+/** One scheduled watch or reconcile Op the plan job checks. */
+export interface ScheduledWatch {
+  op: string;
+  cron: string;
+}
+
+/** An Op the plan note warns about. */
+export interface OverdueOp {
+  op: string;
+  cron: string;
+  /** The time the count starts from: the job's last run, or the pipeline file's first commit (ISO 8601). */
+  since: string;
+  /** True when no run is on record and `since` is the pipeline file's first commit. */
+  neverRan?: boolean;
+  /** The line for the job log and the plan note. */
+  message: string;
+}
+
+/**
+ * The discovered Ops that are scheduled watch or reconcile Ops: a
+ * `schedule`, and the `Watch` label `WatchOp` sets (./composites/watch-op.ts)
+ * or the `Reconcile` label `ReconcileOp` sets (./composites/reconcile-op.ts).
+ * Sorted by name.
+ */
+export function scheduledWatches(ops: Iterable<OpConfig>): ScheduledWatch[] {
+  const out: ScheduledWatch[] = [];
+  for (const op of ops) {
+    if (!op.schedule?.cron) continue;
+    if (op.labels?.Watch !== "true" && op.labels?.Reconcile !== "true") continue;
+    out.push({ op: op.name, cron: op.schedule.cron });
+  }
+  return out.sort((a, b) => a.op.localeCompare(b.op));
+}
+
+/**
+ * The file `chant run --generate <forge>` writes for an Op, relative to the
+ * repository root: `<dir>/<op>.yml` on GitHub and Forgejo, `<member>-<op>.yml`
+ * in a workspace member. GitLab puts every Op in one file, so the root's
+ * `*.gitlab-ci.yml` files are read for the one whose rules select the Op.
+ * Undefined when the checkout has no such file, so an Op that some other
+ * scheduler runs is never checked.
+ */
+export function opPipelineFile(repoRoot: string, forge: ForgeKind, op: string, member?: string): string | undefined {
+  const base = member ? `${member}-${op}` : op;
+  if (forge === "github" || forge === "forgejo") {
+    const path = `.${forge}/workflows/${base}.yml`;
+    return existsSync(join(repoRoot, path)) ? path : undefined;
+  }
+  // The gitlab lexicon's cron rule: `$CHANT_SCHEDULED_OP == "<op>"`.
+  const selector = `$CHANT_SCHEDULED_OP == "${op}"`;
+  let names: string[];
+  try {
+    names = readdirSync(repoRoot).filter((n) => n.endsWith(".gitlab-ci.yml")).sort();
+  } catch {
+    return undefined;
+  }
+  return names.find((n) => {
+    try {
+      return readFileSync(join(repoRoot, n), "utf8").includes(selector);
+    } catch {
+      return false;
+    }
+  });
+}
+
+/** When `path` was first committed (ISO 8601), if the checkout's history has it. */
+export function fileAdded(repoRoot: string, path: string): string | undefined {
+  const r = spawnSync("git", ["-C", repoRoot, "log", "--format=%cI", "--diff-filter=A", "--", path], { encoding: "utf-8" });
+  if (r.status !== 0) return undefined;
+  return r.stdout.trim().split("\n").filter(Boolean).pop();
+}
+
+const HINT: Record<ForgeKind, string> = {
+  github: "GitHub turns a scheduled workflow off after 60 days with no activity in the repository. Turn the workflow on again under Actions, or run it by hand",
+  gitlab: "A GitLab project runs a scheduled Op only from a pipeline schedule. Check its schedule under CI/CD > Schedules",
+  forgejo: "Check that Actions is on for the repository and a runner is up, or run the workflow by hand",
+};
+
+/**
+ * Whether one Op is overdue: its cron has fired at least twice since its
+ * last run, or since `added` when no run is on record. Undefined when it is
+ * on time, or when nothing says when it should have run.
+ */
+export function overdueVerdict(watch: ScheduledWatch, forge: ForgeKind, runs: ScheduledRuns, added: string | undefined, now: Date): OverdueOp | undefined {
+  const since = runs.last ?? added;
+  if (!since) return undefined;
+  if (cronFiresUtc(watch.cron, new Date(since), now, 2).length < 2) return undefined;
+  const day = since.slice(0, 10);
+  const what = runs.last ? `its last run was on ${day}` : `no run is on record since its pipeline was added on ${day}`;
+  const why = runs.disabled
+    ? `GitHub has turned the workflow off (${runs.disabled}). Turn it on again under Actions`
+    : forge === "gitlab" && runs.noSchedule
+      ? `No active pipeline schedule sets CHANT_SCHEDULED_OP to ${watch.op}. Add one with the cron \`${watch.cron}\` under CI/CD > Schedules`
+      : HINT[forge];
+  return {
+    op: watch.op,
+    cron: watch.cron,
+    since,
+    ...(runs.last ? {} : { neverRan: true }),
+    message: `Op \`${watch.op}\` is overdue: its schedule \`${watch.cron}\` has fired at least twice and ${what}. ${why}.`,
+  };
+}
+
+/**
+ * The plan job's check over every scheduled watch or reconcile Op that has a
+ * generated pipeline file. Each Op the forge will not answer for is a line
+ * in `log` and no verdict. A forge client with no `scheduledRuns` checks
+ * nothing.
+ */
+export async function checkOverdueOps(input: {
+  watches: readonly ScheduledWatch[];
+  forge: PrForge;
+  repoRoot: string;
+  member?: string;
+  now: Date;
+  log: (line: string) => void;
+}): Promise<OverdueOp[]> {
+  const { forge } = input;
+  if (!forge.scheduledRuns) return [];
+  const out: OverdueOp[] = [];
+  for (const watch of input.watches) {
+    const file = opPipelineFile(input.repoRoot, forge.kind, watch.op, input.member);
+    if (!file) continue;
+    let runs: ScheduledRuns;
+    try {
+      runs = await forge.scheduledRuns({ op: watch.op, workflow: file.split("/").pop()! });
+    } catch (err) {
+      input.log(`schedule check: ${forge.kind} did not say when Op ${watch.op} last ran, so it is not checked: ${(err instanceof Error ? err.message : String(err)).split("\n")[0]}`);
+      continue;
+    }
+    const found = overdueVerdict(watch, forge.kind, runs, runs.last ? undefined : fileAdded(input.repoRoot, file), input.now);
+    if (found) {
+      input.log(found.message);
+      out.push(found);
+    }
+  }
+  return out;
+}

package/src/override-gate-bundle.test.ts

@@ -34,10 +34,10 @@ describe("the override-gate bundle", () => {
       "packages/core/src/effect-receipt.ts",
       "packages/core/src/intrinsic.ts",
       "packages/core/src/lifecycle/gate-ledger-select.ts",
+      "packages/core/src/lifecycle/gate-seal.ts",
       "packages/core/src/lifecycle/plan-digest.ts",
       "packages/core/src/op/gate-name.ts",
       "packages/core/src/override-gate.ts",
-      "packages/core/src/workspace/trust/gate-seal.ts",
       "packages/core/src/workspace/trust/trust-files.ts",
     ]);
     // About 16 KB today.

package/src/override-gate.ts

@@ -38,14 +38,14 @@ import { spawnSync } from "node:child_process";
 import { OVERRIDE_GATE_OP } from "./op/gate-name";
 import { latestPendingGate } from "./lifecycle/gate-ledger-select";
 import { samePlanDigest } from "./lifecycle/plan-digest";
-import { gateSealRefusal, type GateSigners } from "./workspace/trust/gate-seal";
+import { gateSealRefusal, type GateSigners } from "./lifecycle/gate-seal";
 import { DEFAULT_SIGNERS_PATH } from "./workspace/trust/trust-files";
 import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
 import type { GateApprovalSource } from "./op/op-waves";
 import type { GateAuditApply } from "./lifecycle/gate-audit";
 
 export type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
-export type { GateSigners } from "./workspace/trust/gate-seal";
+export type { GateSigners } from "./lifecycle/gate-seal";
 
 /** The op every override and denial is recorded under. `./lifecycle/gate-audit.ts` reads this op as overrides by default. */
 export const OVERRIDE_OP = OVERRIDE_GATE_OP;

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

@@ -34,7 +34,7 @@ describe("the pr-forge bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual(["packages/core/src/pr-forge.ts"]);
-    // About 33 KB today, after the pull request authors (#4000).
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(36 * 1024);
+    // About 37 KB today, after the pull request authors (#4000) and pullRequestOpen for target locks (#4293).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(40 * 1024);
   });
 });

package/src/pr-forge.test.ts

@@ -127,6 +127,17 @@ describe("github", () => {
     expect(await githubForge({ ...opts, fetch }).pullRequestFor(SHA)).toBe(9);
   });
 
+  test("a pull request is open while its state is open and it has not merged; an unknown one is not (#4293)", async () => {
+    const { fetch } = fakeFetch({
+      "GET /repos/acme/infra/pulls/1": { number: 1, state: "open", merged: false },
+      "GET /repos/acme/infra/pulls/2": { number: 2, state: "closed", merged: true },
+    });
+    const forge = githubForge({ ...opts, fetch });
+    expect(await forge.pullRequestOpen!(1)).toBe(true);
+    expect(await forge.pullRequestOpen!(2)).toBe(false);
+    expect(await forge.pullRequestOpen!(3)).toBe(false);
+  });
+
   test("resolves to the note's web URL", async () => {
     const { fetch } = fakeFetch({
       "GET /repos/acme/infra/issues/12/comments": [],
@@ -237,6 +248,11 @@ describe("forgejo", () => {
     expect(await forgejoForge({ ...opts, fetch: none.fetch }).pullRequestFor(SHA)).toBeNull();
   });
 
+  test("reads whether a pull request is open from the same pulls endpoint (#4293)", async () => {
+    const { fetch } = fakeFetch({ "GET /api/v1/repos/acme/infra/pulls/4": { number: 4, state: "open", merged: false } });
+    expect(await forgejoForge({ ...opts, fetch }).pullRequestOpen!(4)).toBe(true);
+  });
+
   test("names reviewers on its host", () => {
     expect(forgejoForge({ ...opts, fetch: fakeFetch({}).fetch }).principalOf("Ana")).toBe("forgejo@codeberg.org:ana");
   });
@@ -295,6 +311,16 @@ describe("gitlab", () => {
     expect(await forge.pullRequestFor(SHA)).toBe(5);
     expect(forge.principalOf("ana")).toBe("gitlab@gitlab.example.com:ana");
   });
+
+  test("a merge request is open while its state is opened (#4293)", async () => {
+    const { fetch } = fakeFetch({
+      "GET /api/v4/projects/42/merge_requests/5": { iid: 5, state: "opened" },
+      "GET /api/v4/projects/42/merge_requests/6": { iid: 6, state: "merged" },
+    });
+    const forge = gitlabForge({ ...opts, fetch });
+    expect(await forge.pullRequestOpen!(5)).toBe(true);
+    expect(await forge.pullRequestOpen!(6)).toBe(false);
+  });
 });
 
 describe("naming reviewers", () => {
@@ -891,6 +917,13 @@ describe("pull requests over REST (#3798)", () => {
     expect(l.calls.map((c) => c.body)).toEqual([{ description: "d" }, { add_labels: "minor,breaking" }]);
   });
 
+  test("labels reads the names a pull request carries on each forge (#4292)", async () => {
+    const f = fakeFetch({ "GET /api/v1/repos/acme/infra/issues/10/labels": [{ name: "plan:prod" }, { name: "bug" }, { id: 3 }] });
+    expect(await forgejoForge({ ...fjOpts, fetch: f.fetch }).labels!(10)).toEqual(["plan:prod", "bug"]);
+    const l = fakeFetch({ "GET /api/v4/projects/group%2Finfra/merge_requests/7": { iid: 7, labels: ["plan:prod", 4] } });
+    expect(await gitlabForge({ ...gl, fetch: l.fetch }).labels!(7)).toEqual(["plan:prod"]);
+  });
+
   test("Forgejo's 404 on the pull list of a just-pushed empty repository is no pull request (#3845)", async () => {
     const empty = fakeFetch({ "GET /api/v1/repos/acme/infra": { default_branch: "main" } });
     expect(await forgejoForge({ ...fjOpts, fetch: empty.fetch }).findPullRequest("chant/x")).toBeUndefined();

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,38 @@ 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>;
+}
+
+/** 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. */
@@ -691,6 +734,15 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       }
       return [...logins].sort();
     },
+    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;
+      }
+    },
     async pullRequestFor(sha) {
       if (kind === "forgejo") {
         try {
@@ -777,6 +829,27 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       const commit = isObject(b) && isObject(b.commit) ? b.commit : undefined;
       return commit ? str(commit.sha) ?? str(commit.id) : undefined;
     },
+    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 } : {}) };
+      }
+      // 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 +857,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;
@@ -962,6 +1045,15 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       }
       return [...logins].sort();
     },
+    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;
+      }
+    },
     async pullRequestFor(sha) {
       const mrs = await api.call("GET", `${project}/repository/commits/${sha}/merge_requests`);
       if (!Array.isArray(mrs)) return null;
@@ -984,6 +1076,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 +1096,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");