@intentius/chant 0.124.40 → 0.124.42

package/src/op/op-waves.ts

@@ -43,6 +43,14 @@
  * `chant/lifecycle`, as terragucci's wave gate does, and that approval is
  * spent: the same digest needs a new approval to apply again.
  *
+ * ## Approval rules (#4290)
+ *
+ * With `approvals: { quorum: [...] }` (read at base), a wave takes each rule
+ * whose `targets` glob matches one of its runs' targets and waits until each
+ * is met: `count` distinct people, from `roles` when it names them (granted
+ * in `.chant/trust.json` at base), one of them not the author with
+ * `notAuthor`. See `./gate-quorum.ts`.
+ *
  * ## Wave-level commands and hooks (#3762)
  *
  * A product whose tool plans a whole wave in one call (Terragrunt's `run
@@ -69,6 +77,7 @@
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import type { CiRunner } from "../ci-jobs";
 import { gatePointProblems, type GatePoint } from "./gate-point";
+import { quorumProblems, type GateQuorumRule } from "./gate-quorum";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
 import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout";
 
@@ -156,20 +165,30 @@ export interface OpWaveHook {
   onFailure?: OpWaveHookFailure;
   /** Run once per run of the wave, rather than once for the wave. */
   perRun?: boolean;
+  /**
+   * The runs the hook is for (#4288): targets, or patterns where `*` matches
+   * within one `/` segment and `**` across segments, as a job group's `runs`.
+   * A `perRun` hook runs for the matching runs only. A hook that runs once
+   * for the wave runs when any run matches, or when no run is known yet (a
+   * `discover` wave before its plan). Absent: every run.
+   */
+  targets?: string[];
 }
 
 /** The stages a hook runs around. */
-export type OpWaveHookStage = "plan" | "apply" | "gate";
+export type OpWaveHookStage = "observe" | "plan" | "apply" | "gate";
 
 /** When a hook runs. */
-export type OpWaveHookMoment = "before-plan" | "after-plan" | "after-gate" | "before-apply" | "after-apply";
+export type OpWaveHookMoment = "before-observe" | "before-plan" | "after-plan" | "after-gate" | "before-apply" | "after-apply";
 
 /**
- * Every moment, in the order a wave reaches them. `after-gate` (#3821) runs
+ * Every moment, in the order a wave reaches them. `before-observe` (#4288)
+ * runs before anything reads live state: ahead of `before-plan` in every job
+ * that plans, the deciding job's and each share's. `after-gate` (#3821) runs
  * once the gate decided, whatever it decided: approved, let through,
  * waiting, or refused by a policy denial.
  */
-export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
+export const OP_WAVE_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-observe", "before-plan", "after-plan", "after-gate", "before-apply", "after-apply"];
 
 /**
  * Who runs the `before.apply` and `after.apply` hooks (#3804). `chant`: the
@@ -183,7 +202,8 @@ export const OP_WAVE_APPLY_HOOKS_RUNNERS: readonly OpWaveApplyHooksRunner[] = ["
 
 /** Stage hooks (#3762), read from the spec at the base commit like the gate policy. */
 export interface OpWaveHooks {
-  before?: { plan?: OpWaveHook[]; apply?: OpWaveHook[] };
+  /** `before.observe` (#4288) runs before anything reads live state, ahead of `before.plan`. */
+  before?: { observe?: OpWaveHook[]; plan?: OpWaveHook[]; apply?: OpWaveHook[] };
   /** `after.gate` (#3821) runs once the gate decided, whatever it decided, with the decision in its environment. */
   after?: { plan?: OpWaveHook[]; gate?: OpWaveHook[]; apply?: OpWaveHook[] };
   /** Who runs the apply-stage hooks (#3804). Default `{ runBy: "chant" }`. A wave's own setting wins over the spec's. */
@@ -456,6 +476,18 @@ export interface OpWavesApprovals {
    * approval of a digest passes that digest as often as it is planned.
    */
   spend?: boolean;
+  /**
+   * Approval rules (#4290): a wave takes each rule whose `targets` glob
+   * matches one of its runs' targets (a rule with no `targets` covers every
+   * wave), and applies once each is met by distinct human approvers of its
+   * set digest. Read at the base commit, with the roles from
+   * `.chant/trust.json` there, so a change cannot loosen the rules its own
+   * wave is judged by. A role, or `notAuthor`, counts only a proven
+   * approver: a seal that verifies against the signers at base, or under
+   * `pr-review` the merged pull request's review. `notAuthor` reads the
+   * author from that pull request. See `./gate-quorum.ts`.
+   */
+  quorum?: GateQuorumRule[];
 }
 
 /** The scheduled resume job of an Op waves pipeline (#3683). */
@@ -543,11 +575,21 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
   }
   if (spec.approvals !== undefined) {
     const a = spec.approvals as unknown;
-    if (a === null || typeof a !== "object" || Array.isArray(a)) throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false }.`);
+    if (a === null || typeof a !== "object" || Array.isArray(a)) throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false, "quorum"?: [...] }.`);
     for (const [key, value] of Object.entries(a as Record<string, unknown>)) {
-      if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the one there is approvals.spend.`);
+      if (key === "quorum") {
+        // #4290: approval rules, read at base like the policy.
+        if (!Array.isArray(value)) throw new Error(`${where}: approvals.quorum must be a list of rules, each { "targets"?, "count", "roles"?, "notAuthor"? }.`);
+        const problems = quorumProblems(value, "approvals.quorum", { notAuthor: true });
+        if (problems.length > 0) throw new Error(`${where}: ${problems.join("; ")}.`);
+        continue;
+      }
+      if (key !== "spend") throw new Error(`${where}: approvals.${key} is not a setting; the ones there are approvals.spend and approvals.quorum.`);
       if (typeof value !== "boolean") throw new Error(`${where}: approvals.spend must be true or false.`);
     }
+    if ((a as OpWavesApprovals).quorum?.length && (spec.point !== undefined || spec.waves.some((w) => w.point !== undefined))) {
+      throw new Error(`${where}: approvals.quorum and a decision point are both set; a gate that asks a point takes its deciders and quorum from the point, so drop one of them.`);
+    }
   }
   if (spec.gateName !== undefined) {
     if (typeof spec.gateName !== "string" || !spec.gateName.includes("{k}") || /\s/.test(spec.gateName)) {
@@ -720,6 +762,15 @@ export function opWaveRunMatches(pattern: string, target: string): boolean {
   return new RegExp(`^${re}$`).test(target);
 }
 
+/**
+ * The runs of `runs` hook `hook` is for (#4288): those its `targets` match,
+ * or every run when it names none.
+ */
+export function opWaveHookRuns<T extends { target: string }>(hook: Pick<OpWaveHook, "targets">, runs: readonly T[]): T[] {
+  if (!hook.targets) return [...runs];
+  return runs.filter((run) => hook.targets!.some((pattern) => opWaveRunMatches(pattern, run.target)));
+}
+
 /** The runs of `runs` that job group `group` holds (#3914). */
 export function opWaveGroupRuns<T extends { target: string }>(group: Pick<OpWaveJobGroup, "runs">, runs: readonly T[]): T[] {
   return runs.filter((run) => group.runs.some((pattern) => opWaveRunMatches(pattern, run.target)));
@@ -748,7 +799,7 @@ function assertArgv(where: string, field: string, argv: unknown): void {
 export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined): void {
   if (hooks === undefined) return;
   if (hooks === null || typeof hooks !== "object" || Array.isArray(hooks)) {
-    throw new Error(`${where}: \`hooks\` must be { "before"?: { "plan"?, "apply"? }, "after"?: { "plan"?, "apply"? } }.`);
+    throw new Error(`${where}: \`hooks\` must be { "before"?: { "observe"?, "plan"?, "apply"? }, "after"?: { "plan"?, "gate"?, "apply"? } }.`);
   }
   for (const [side, stages] of Object.entries(hooks as Record<string, unknown>)) {
     if (side === "apply") {
@@ -766,7 +817,8 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
     for (const [stage, list] of Object.entries(stages as Record<string, unknown>)) {
       const at = `hooks.${side}.${stage}`;
       if (stage === "gate" && side === "before") throw new Error(`${where}: ${at} is not a moment; a hook runs after the gate (hooks.after.gate), or before the plan or the apply.`);
-      if (stage !== "plan" && stage !== "apply" && stage !== "gate") throw new Error(`${where}: ${at} is not a stage; a hook runs before or after plan or apply, or after the gate.`);
+      if (stage === "observe" && side === "after") throw new Error(`${where}: ${at} is not a moment; a hook runs before the observe (hooks.before.observe), or after the plan, which reads what the observe saw.`);
+      if (stage !== "observe" && stage !== "plan" && stage !== "apply" && stage !== "gate") throw new Error(`${where}: ${at} is not a stage; a hook runs before the observe, before or after plan or apply, or after the gate.`);
       if (!Array.isArray(list)) throw new Error(`${where}: ${at} must be a list of hooks.`);
       list.forEach((hook: OpWaveHook, i: number) => {
         const which = `${at}[${i}]${hook && typeof hook === "object" && typeof hook.name === "string" ? ` (${hook.name})` : ""}`;
@@ -782,10 +834,13 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
           throw new Error(`${where}: ${which} has onFailure "approve", but the gate has already decided when it runs. Use "fail", or hold the wave from an after.plan hook.`);
         }
         if (hook.perRun !== undefined && typeof hook.perRun !== "boolean") throw new Error(`${where}: ${which}.perRun must be true or false.`);
+        if (hook.targets !== undefined && (!Array.isArray(hook.targets) || hook.targets.length === 0 || !hook.targets.every((t) => typeof t === "string" && t !== ""))) {
+          throw new Error(`${where}: ${which}.targets must be a non-empty list of targets or patterns, such as ["prod/*"].`);
+        }
         if (!hook.perRun) {
           const named = hook.command.find((part) => part.includes("{target}") || part.includes("{plan}"));
           if (named) throw new Error(`${where}: ${which} runs once for the wave, so it has no {target} or {plan} ("${named}"). Set "perRun": true, or read the runs from {runs}.`);
-        } else if (side === "before" && stage === "plan" && hook.command.some((part) => part.includes("{plan}"))) {
+        } else if (side === "before" && (stage === "plan" || stage === "observe") && hook.command.some((part) => part.includes("{plan}"))) {
           throw new Error(`${where}: ${which} runs before the plan, so it has no {plan} yet.`);
         }
       });
@@ -793,6 +848,24 @@ export function assertOpWaveHooks(where: string, hooks: OpWaveHooks | undefined)
   }
 }
 
+/**
+ * The moments a pull-request job runs hooks at (#4288): `pr-plan` and
+ * `pr-record` run the observe and plan moments, and `pr-apply` the apply
+ * moments too. The pull request's gate has no `after-gate` moment.
+ */
+export const PR_LOOP_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-observe", "before-plan", "after-plan", "before-apply", "after-apply"];
+
+/**
+ * Refuse `ci.hooks` a pull-request job could not run (#4288): what
+ * {@link assertOpWaveHooks} refuses, plus `after.gate` and `apply.runBy`,
+ * since chant itself runs a pull request's apply.
+ */
+export function assertPrLoopHooks(where: string, hooks: OpWaveHooks | undefined): void {
+  assertOpWaveHooks(where, hooks);
+  if (hooks?.after?.gate !== undefined) throw new Error(`${where}: hooks.after.gate runs in an Op waves job only; a pull-request job runs hooks before the observe, before and after the plan, and before and after the apply.`);
+  if (hooks?.apply !== undefined) throw new Error(`${where}: hooks.apply.runBy is for an Op waves spec; chant runs a pull request's apply, so it runs the apply-stage hooks itself.`);
+}
+
 /** The hooks of each moment for wave `name`: the spec's, then the wave's own. */
 export function opWaveHooksAt(spec: Pick<OpWavesSpec, "hooks" | "waves">, name: string): Record<OpWaveHookMoment, OpWaveHook[]> {
   const wave = spec.waves.find((w) => w.name === name);

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;
+}