@intentius/chant 0.124.46 → 0.124.49

package/src/op/op-waves.ts

@@ -17,8 +17,16 @@
  * (`shares` > 1) is a deciding job that plans every run and decides the gate,
  * plus `shares` jobs that each apply a slice of the runs and refuse a run
  * whose plan moved since the decision. Each wave's jobs need the previous
- * wave's last jobs, so a wave that waits (exit 3) or fails stops every later
- * wave.
+ * wave's last jobs, so a wave that waits (exit 3) stops every later wave.
+ *
+ * ## A failed run blocks its dependents (#4322)
+ *
+ * A run's `dependsOn` names the runs it needs applied first. Each job writes
+ * an outcome file ({@link OpWaveJob.outcome}, `../wave-blocked.ts`) and the
+ * next wave's jobs read every earlier one, so a run that failed blocks only
+ * the runs that depend on it, in its own wave and later ones, and the rest
+ * apply. The generated pipelines run a wave's jobs after a failure in the
+ * wave before; a job exits 1 only for its own failed or blocked runs.
  *
  * ## The gate
  *
@@ -51,6 +59,13 @@
  * in `.chant/trust.json` at base), one of them not the author with
  * `notAuthor`. See `./gate-quorum.ts`.
  *
+ * Two more settings feed those rules, read at base with them (#4333):
+ * `approvals.reviewLedger` names the op whose ledger holds the reviews a
+ * product records itself under `pr-review` (terragucci's `tf-apply`), and
+ * `approvals.involved` names the accounts an agent acts as and, with
+ * `exclude`, leaves an approval by anyone involved in the change out of
+ * every rule.
+ *
  * ## Wave-level commands and hooks (#3762)
  *
  * A product whose tool plans a whole wave in one call (Terragrunt's `run
@@ -81,6 +96,7 @@ 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";
+import { waveOutcomeFileName } from "../wave-blocked";
 
 /**
  * The variables a wave job reads its notify secrets from, for the lexicons
@@ -217,6 +233,15 @@ export interface OpWaveRun {
   target: string;
   /** The Op to run. Default: the spec's `op`. */
   op?: string;
+  /**
+   * The runs this one needs applied first (#4322), by target: a run of an
+   * earlier wave (the latest earlier wave that has the target), or one listed
+   * before it in its own wave. A run that failed, or was blocked, blocks this
+   * one, which then is neither planned nor applied; a run with no failed
+   * dependency applies whatever else failed. Within its own wave only when
+   * one job applies the wave (no `shares`, no `jobs`).
+   */
+  dependsOn?: string[];
 }
 
 /**
@@ -505,6 +530,48 @@ export interface OpWavesApprovals {
    * author from that pull request. See `./gate-quorum.ts`.
    */
   quorum?: GateQuorumRule[];
+  /**
+   * The op whose ledger (`_gates/<op>.jsonl` on `chant/lifecycle`) holds the
+   * reviews a product records itself (#4333): lines with `via: "pr-review"`,
+   * the reviewed `head` and the approving `reviewers` by forge login, as
+   * terragucci writes them under `tf-apply`. Each reviewer counts toward
+   * `quorum` as one approver of the line's digest, and under `pr-review` is
+   * proven, as a review chant reads from the forge is. Read at the base
+   * commit, so a change cannot name a ledger its own wave is judged by.
+   */
+  reviewLedger?: string;
+  /** Who else was involved in a change, for `quorum` (#4333). Read at the base commit. */
+  involved?: OpWavesInvolved;
+}
+
+/**
+ * Who was involved in a change besides its pull request's author (#4333):
+ * each login a `Requested-by:` trailer names on the commits after base, and
+ * the accounts listed here. `notAuthor` is met only by a proven approver
+ * none of them is.
+ */
+export interface OpWavesInvolved {
+  /** The accounts an agent acts as, as principals (`github:tg-bot`) or logins: a change's author can post a review as the agent with its token. */
+  agents?: string[];
+  /** An approval by anyone involved counts toward no rule, not only toward `notAuthor`. Default false. */
+  exclude?: boolean;
+}
+
+/** An op name a ledger file is named by (`_gates/<op>.jsonl`). */
+export const OP_LEDGER_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/** Everything wrong with `approvals.involved` (#4333), one line each. */
+export function opWavesInvolvedProblems(value: unknown): string[] {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return ["`approvals.involved` must be { \"agents\"?: [...], \"exclude\"?: true | false }"];
+  const problems: string[] = [];
+  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+    if (key === "agents") {
+      if (!Array.isArray(v) || v.length === 0 || v.some((a) => typeof a !== "string" || a.trim() === "")) problems.push("`approvals.involved.agents` must be a non-empty list of principals or logins");
+    } else if (key === "exclude") {
+      if (typeof v !== "boolean") problems.push("`approvals.involved.exclude` must be true or false");
+    } else problems.push(`\`approvals.involved.${key}\` is not a setting; use agents or exclude`);
+  }
+  return problems;
 }
 
 /** The scheduled resume job of an Op waves pipeline (#3683). */
@@ -549,6 +616,23 @@ export interface OpWaveJob {
   command: string[];
   /** On a share job: the decision record to download. On a deciding job: the one to upload. */
   record?: string;
+  /**
+   * The outcome file the job writes (#4322), which the forge keeps whatever
+   * the job's exit code: each of its runs' outcome, as `../wave-blocked.ts`
+   * writes them. A job with `needs` reads the earlier ones from
+   * {@link opWaveOutcomeDir} first.
+   */
+  outcome: string;
+}
+
+/** Where a wave job writes its outcome file and finds the earlier ones (#4322), at any depth. */
+export function opWaveOutcomeDir(spec: Pick<OpWavesSpec, "name">): string {
+  return `.chant/op-waves/${spec.name}/outcomes`;
+}
+
+/** The outcome file of wave `wave`'s job, or of one group or share of it (#4322). */
+export function opWaveOutcomePath(spec: Pick<OpWavesSpec, "name">, wave: number, part: { group?: string; share?: number } = {}): string {
+  return `${opWaveOutcomeDir(spec)}/${waveOutcomeFileName(wave, part)}`;
 }
 
 const NAME = /^[a-z0-9][a-z0-9_-]*$/;
@@ -592,7 +676,7 @@ 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, "quorum"?: [...] }.`);
+    if (a === null || typeof a !== "object" || Array.isArray(a)) throw new Error(`${where}: \`approvals\` must be { "spend"?: true | false, "quorum"?: [...], "reviewLedger"?: "<op>", "involved"?: {...} }.`);
     for (const [key, value] of Object.entries(a as Record<string, unknown>)) {
       if (key === "quorum") {
         // #4290: approval rules, read at base like the policy.
@@ -601,7 +685,17 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
         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 (key === "reviewLedger") {
+        // #4333: the op a product records its reviews under, read at base.
+        if (typeof value !== "string" || !OP_LEDGER_NAME.test(value)) throw new Error(`${where}: approvals.reviewLedger must name an op, such as "tf-apply": letters, digits, dot, dash and underscore.`);
+        continue;
+      }
+      if (key === "involved") {
+        const problems = opWavesInvolvedProblems(value);
+        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, approvals.quorum, approvals.reviewLedger and approvals.involved.`);
       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))) {
@@ -698,6 +792,41 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       if (problem) throw new Error(`${where}: ${problem}.`);
     }
   }
+  assertOpWaveDependsOn(where, spec);
+}
+
+/**
+ * Refuse a `dependsOn` (#4322) that names no run this one could follow: each
+ * entry is a target of an earlier wave, or of a run listed before it in its
+ * own wave when one job applies that wave. A discovering wave's runs are not
+ * in the spec, so after one any target is taken.
+ */
+function assertOpWaveDependsOn(where: string, spec: OpWavesSpec): void {
+  const earlier = new Set<string>();
+  let discovered = false;
+  for (const wave of spec.waves) {
+    const own = new Set<string>();
+    for (const run of wave.runs ?? []) {
+      const deps = run.dependsOn as unknown;
+      if (deps !== undefined) {
+        const at = `wave "${wave.name}" run "${run.target}"`;
+        if (!Array.isArray(deps) || !deps.every((d) => typeof d === "string" && d !== "")) throw new Error(`${where}: ${at} dependsOn must be a list of targets.`);
+        for (const dep of deps as string[]) {
+          if (dep === run.target && !earlier.has(dep)) throw new Error(`${where}: ${at} depends on itself.`);
+          if (own.has(dep)) {
+            if ((wave.shares ?? 1) > 1 || wave.jobs !== undefined) {
+              throw new Error(`${where}: ${at} depends on "${dep}" in its own wave, which ${wave.jobs ? "job groups" : "shares"} apply in separate jobs; move one of them to another wave.`);
+            }
+            continue;
+          }
+          if (!earlier.has(dep) && !discovered) throw new Error(`${where}: ${at} depends on "${dep}", which is no run of an earlier wave or listed before it in its own.`);
+        }
+      }
+      own.add(run.target);
+    }
+    for (const t of own) earlier.add(t);
+    if (wave.discover) discovered = true;
+  }
 }
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -888,18 +1017,18 @@ 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.
+ * moments too. `after-gate` (#4323) runs in `pr-apply` once the pull
+ * request's gate has decided.
  */
-export const PR_LOOP_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-observe", "before-plan", "after-plan", "before-apply", "after-apply"];
+export const PR_LOOP_HOOK_MOMENTS: readonly OpWaveHookMoment[] = ["before-observe", "before-plan", "after-plan", "after-gate", "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.
+ * {@link assertOpWaveHooks} refuses, plus `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.`);
 }
 
@@ -941,13 +1070,13 @@ export function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[] {
     const prefix = `wave-${k}-${wave.name}`;
     const shares = wave.shares ?? 1;
     if (shares === 1 && wave.jobs === undefined) {
-      jobs.push({ jobName: prefix, wave: k, waveName: wave.name, kind: "wave", needs: previous, command });
+      jobs.push({ jobName: prefix, wave: k, waveName: wave.name, kind: "wave", needs: previous, command, outcome: opWaveOutcomePath(spec, k) });
       previous = [prefix];
       return;
     }
     const record = opWaveRecordPath(spec, k);
     const decide = `${prefix}-decide`;
-    jobs.push({ jobName: decide, wave: k, waveName: wave.name, kind: "decide", needs: previous, command: [...command, "--decide"], record });
+    jobs.push({ jobName: decide, wave: k, waveName: wave.name, kind: "decide", needs: previous, command: [...command, "--decide"], record, outcome: opWaveOutcomePath(spec, k) });
     const shareJobs: string[] = [];
     if (wave.jobs !== undefined) {
       // #3914: a job per group, or per share of a group, each applying its runs under the deciding job's decision.
@@ -957,13 +1086,13 @@ export function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[] {
         if (groupShares === 1) {
           const jobName = `${prefix}-${group.name}`;
           shareJobs.push(jobName);
-          jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, needs: [decide], command: groupCommand, record });
+          jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, needs: [decide], command: groupCommand, record, outcome: opWaveOutcomePath(spec, k, { group: group.name }) });
           continue;
         }
         for (let share = 1; share <= groupShares; share++) {
           const jobName = `${prefix}-${group.name}-share-${share}`;
           shareJobs.push(jobName);
-          jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, share, needs: [decide], command: [...groupCommand, "--share", String(share)], record });
+          jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, share, needs: [decide], command: [...groupCommand, "--share", String(share)], record, outcome: opWaveOutcomePath(spec, k, { group: group.name, share }) });
         }
       }
       previous = shareJobs;
@@ -972,7 +1101,7 @@ export function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[] {
     for (let share = 1; share <= shares; share++) {
       const jobName = `${prefix}-share-${share}`;
       shareJobs.push(jobName);
-      jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", share, needs: [decide], command: [...command, "--share", String(share)], record });
+      jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", share, needs: [decide], command: [...command, "--share", String(share)], record, outcome: opWaveOutcomePath(spec, k, { share }) });
     }
     previous = shareJobs;
   });

package/src/op/runtime.ts

@@ -175,6 +175,14 @@ export interface OpRunRecord {
    * run id. Absent outside CI and on a record written before 0.124.28.
    */
   runOrigin?: RunOrigin;
+  /**
+   * The workspace run that started this one (#2554, #2524 D17): `chant
+   * workspace run`'s id, and the workspace gate it ran under when it named
+   * one. The workspace run's own record, under `_members/_workspace/` on
+   * `chant/lifecycle`, names this run in turn. Absent on a run nothing in a
+   * workspace started, and on a record written before 0.124.47.
+   */
+  workspaceRun?: { id: string; gate?: string };
   /**
    * The run's statement (#4044): a DSSE envelope over an in-toto statement
    * (`https://intentius.io/chant/op-run/v1`) a runner key signed at the end

package/src/op/schedule-overdue.ts

@@ -159,3 +159,36 @@ export async function checkOverdueOps(input: {
   }
   return out;
 }
+
+/**
+ * The overdue check over the Ops declared at `cwd` (#4289), as the plan note
+ * reports it: the Ops `discoverOps` finds there, and the repository root
+ * `cwd` is in. `pr-post` runs it in its own checkout, the target branch's
+ * commit, and `chant ci run plan` in a checkout of `--base` (#4328), so the
+ * Ops are never read from the change's code. Without a forge that can say
+ * when a job ran, nothing is checked. A failure is a line in `log` and no
+ * verdict, and the plan goes on.
+ */
+export async function overdueOpsAt(input: { forge: PrForge | undefined; cwd: string; member?: string; now?: Date; log: (line: string) => void }): Promise<OverdueOp[]> {
+  const { forge } = input;
+  if (!forge?.scheduledRuns) return [];
+  try {
+    const { discoverOps } = await import("./discover");
+    const discovered = await discoverOps({ cwd: input.cwd });
+    const watches = scheduledWatches([...discovered.ops.values()].map((d) => d.config));
+    if (watches.length === 0) return [];
+    const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: input.cwd, encoding: "utf-8" });
+    if (top.status !== 0) return [];
+    return await checkOverdueOps({
+      watches,
+      forge,
+      repoRoot: top.stdout.trim(),
+      ...(input.member ? { member: input.member } : {}),
+      now: input.now ?? new Date(),
+      log: input.log,
+    });
+  } catch (err) {
+    input.log(`could not check the scheduled Ops, so none is reported overdue: ${err instanceof Error ? err.message : String(err)}`);
+    return [];
+  }
+}

package/src/op/stage-hooks.ts

@@ -290,6 +290,11 @@ export interface RunStageHooksOptions {
   runsFile: string;
   /** `CHANT_HOLD`, relative to `cwd`. */
   holdFile: string;
+  /**
+   * Give the hooks that held on another gate in {@link StageHooksRun.otherGates}
+   * and leave them out of `holds` (#4323), for a caller that settles them.
+   */
+  keepOtherGates?: boolean;
   /** Added to every hook's environment. */
   env?: Record<string, string>;
   cwd?: string;
@@ -304,6 +309,8 @@ export interface StageHooksRun {
   failed?: string;
   /** The `onFailure: approve` hooks that failed. A hold on another gate counts as one here. */
   holds: string[];
+  /** The hook calls that held on another gate, with `keepOtherGates` (#4323); absent otherwise. */
+  otherGates?: OtherGateHold[];
 }
 
 /** {@link RunStageHooksOptions} for {@link runStageHooksAsync} (#4334). */
@@ -318,7 +325,8 @@ function stagePlace(options: Omit<RunStageHooksOptions, "exec">): Omit<HookPlace
 }
 
 /** A stage run's result: a hold on another gate counts as a plain hold. */
-function stageRun(out: HookListOutcome, name: string): StageHooksRun {
+function stageRun(out: HookListOutcome, name: string, keep = false): StageHooksRun {
+  if (keep) return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: out.holds, otherGates: out.otherGates };
   return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: [...out.holds, ...out.otherGates.map((g) => `${g.label} (on ${g.request.op ?? name} / ${g.request.gate})`)] };
 }
 
@@ -326,12 +334,12 @@ function stageRun(out: HookListOutcome, name: string): StageHooksRun {
  * Run one moment's hooks outside an Op waves job (#4288): the pull-request
  * jobs, or a product's own stage, with the same `targets`, `perRun`,
  * `onFailure` and argv filling a wave job uses. A hook that holds on another
- * gate (`CHANT_HOLD`) is counted as a plain hold; settling that gate is the
- * caller's.
+ * gate (`CHANT_HOLD`) is counted as a plain hold, unless `keepOtherGates` is
+ * set (#4323): then it comes back in `otherGates` for the caller to settle.
  */
 export function runStageHooks(moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, options: RunStageHooksOptions): StageHooksRun {
   const place = { ...stagePlace(options), exec: options.exec ?? spawnExec };
-  return stageRun(runHookList(place, moment, hooks, options.runs, options.runsFile, options.env), options.name);
+  return stageRun(runHookList(place, moment, hooks, options.runs, options.runsFile, options.env), options.name, options.keepOtherGates);
 }
 
 /**
@@ -342,5 +350,5 @@ export function runStageHooks(moment: OpWaveHookMoment, hooks: readonly OpWaveHo
  */
 export async function runStageHooksAsync(moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, options: RunStageHooksAsyncOptions): Promise<StageHooksRun> {
   const place = { ...stagePlace(options), exec: options.exec ?? spawnExecAsync };
-  return stageRun(await runHookListAsync(place, moment, hooks, options.runs, options.runsFile, options.env), options.name);
+  return stageRun(await runHookListAsync(place, moment, hooks, options.runs, options.runsFile, options.env), options.name, options.keepOtherGates);
 }

package/src/op/workspace-run-env.ts

@@ -0,0 +1,29 @@
+/**
+ * How a member's `chant run` learns that `chant workspace run` started it
+ * (#2554, #2524 D17). The workspace run sets these in the environment of the
+ * member's chant; the member's run record cites the workspace run, and a
+ * member gate may then ask the named workspace gate to stand in for it.
+ *
+ * Kept apart from the workspace code so the executor reads two environment
+ * variables and nothing more when no workspace run started it.
+ */
+
+/** The workspace run's id. */
+export const WORKSPACE_RUN_ENV = "CHANT_WORKSPACE_RUN";
+/** The workspace gate the run was started under, when one was named. */
+export const WORKSPACE_GATE_ENV = "CHANT_WORKSPACE_GATE";
+
+/** What a run started by a workspace run knows about it. */
+export interface WorkspaceRunCitation {
+  id: string;
+  /** The workspace gate the run was started under (`chant workspace run --gate`), when one was named. */
+  gate?: string;
+}
+
+/** The workspace run this process runs under, or undefined. */
+export function resolveWorkspaceRun(env: NodeJS.ProcessEnv = process.env): WorkspaceRunCitation | undefined {
+  const id = env[WORKSPACE_RUN_ENV]?.trim();
+  if (!id) return undefined;
+  const gate = env[WORKSPACE_GATE_ENV]?.trim();
+  return { id, ...(gate ? { gate } : {}) };
+}

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 50 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293), the four requires checks of an apply before merge (#4301) the approver filter (#4337) and the approved fields (#4287).
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(52 * 1024);
+    // About 52 KB today, after the pull request authors (#4000), pullRequestOpen for target locks (#4293), the four requires checks of an apply before merge (#4301) the approver filter (#4337) the approved fields (#4287) and the plan job's GitLab note (#4328).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(56 * 1024);
   });
 });

package/src/pr-forge.test.ts

@@ -321,6 +321,53 @@ describe("gitlab", () => {
     expect(await forge.pullRequestOpen!(5)).toBe(true);
     expect(await forge.pullRequestOpen!(6)).toBe(false);
   });
+
+  test("the plan job of each open merge request's newest pipeline at its head, in this project (#4328)", async () => {
+    const OLD = "b".repeat(40);
+    const { fetch, calls } = fakeFetch({
+      "GET /api/v4/projects/42/merge_requests": [
+        { iid: 9, sha: SHA, project_id: 42 },
+        { iid: 5, sha: SHA, project_id: 42 },
+        { iid: 6, sha: OLD, project_id: 42 },
+      ],
+      // Newest at the head first is 301; 300 is an older pipeline of the same head; 299 is of an older head.
+      "GET /api/v4/projects/42/merge_requests/5/pipelines": [
+        { id: 299, sha: OLD, project_id: 42 },
+        { id: 301, sha: SHA, project_id: 42 },
+        { id: 300, sha: SHA, project_id: 42 },
+      ],
+      "GET /api/v4/projects/42/pipelines/301/jobs": [
+        { id: 11, name: "plan", status: "success", web_url: "https://gitlab.example.com/acme/estate/-/jobs/11" },
+        { id: 12, name: "network-plan", status: "running" },
+      ],
+      // A fork's merge request whose pipeline ran in the fork: its jobs are not this project's.
+      "GET /api/v4/projects/42/merge_requests/6/pipelines": [{ id: 400, sha: OLD, project_id: 77 }],
+      // A merge request with no pipeline yet.
+      "GET /api/v4/projects/42/merge_requests/9/pipelines": [],
+    });
+    const forge = gitlabForge({ ...opts, fetch });
+    expect(await forge.mergeRequestJobs!("main", "plan")).toEqual([{ pr: 5, head: SHA, id: 11, status: "success", url: "https://gitlab.example.com/acme/estate/-/jobs/11" }]);
+    expect(new URL(calls[0]!.url).searchParams.get("target_branch")).toBe("main");
+    expect(new URL(calls[0]!.url).searchParams.get("state")).toBe("opened");
+    expect(calls.some((c) => c.url.includes("/pipelines/400/"))).toBe(false);
+  });
+
+  test("one file of a job's artifacts, undefined when the job kept none there, and the newest status's link (#4328)", async () => {
+    const { fetch, calls } = fakeFetch({
+      "GET /api/v4/projects/42/jobs/11/artifacts/infra/network/.chant/pr/pr-plan.json": { stage: "plan" },
+      [`GET /api/v4/projects/42/repository/commits/${SHA}/statuses`]: [
+        { id: 1, name: "chant/plan", target_url: "https://gitlab.example.com/-/jobs/10" },
+        { id: 3, name: "chant/plan", target_url: "https://gitlab.example.com/-/jobs/11" },
+        { id: 4, name: "chant/plan/network", target_url: "https://gitlab.example.com/-/jobs/12" },
+      ],
+    });
+    const forge = gitlabForge({ ...opts, fetch });
+    expect(JSON.parse((await forge.jobArtifact!(11, "infra/network/.chant/pr/pr-plan.json"))!)).toEqual({ stage: "plan" });
+    expect(await forge.jobArtifact!(12, ".chant/pr/pr-plan.json")).toBeUndefined();
+    expect(calls[0]!.headers["PRIVATE-TOKEN"]).toBe("glpat");
+    expect(await forge.statusUrl!(SHA, "chant/plan")).toBe("https://gitlab.example.com/-/jobs/11");
+    expect(await forge.statusUrl!(SHA, "chant/plan/other")).toBeUndefined();
+  });
 });
 
 describe("naming reviewers", () => {

package/src/pr-forge.ts

@@ -223,6 +223,20 @@ export interface PullRequest {
 }
 
 /** An open pull request as `chant ci serve` polls it (#4095). */
+/** A merge request's job in its newest pipeline at its head (#4328), as {@link PrForge.mergeRequestJobs} finds it. */
+export interface MergeRequestJob {
+  /** The merge request's iid. */
+  pr: number;
+  /** The merge request's head commit, as GitLab says it. */
+  head: string;
+  /** The job's id, which {@link PrForge.jobArtifact} reads its artifacts by. */
+  id: number;
+  /** GitLab's word for the job: `success`, `failed` and `canceled` are settled, any other is not. */
+  status: string;
+  /** The job's page. */
+  url?: string;
+}
+
 export interface OpenPullRequest {
   number: number;
   /** Its head branch. */
@@ -440,6 +454,17 @@ export interface PrForge {
    * Pending while one still runs or none has reported.
    */
   prChecksPassed?(pr: number, head: string, ignore?: readonly string[]): Promise<PrRequireResult>;
+  /**
+   * GitLab (#4328): each open merge request into `branch` whose newest
+   * pipeline at its head commit, in this project, ran a job named `job`,
+   * with that job. A merge request whose pipeline runs in a fork's project
+   * is left out, since its jobs and artifacts are the fork's. Oldest first.
+   */
+  mergeRequestJobs?(branch: string, job: string): Promise<MergeRequestJob[]>;
+  /** GitLab (#4328): the text of the file at `path` in job `id`'s artifacts, or undefined when it has none there. */
+  jobArtifact?(id: number, path: string): Promise<string | undefined>;
+  /** GitLab (#4328): the target URL of the newest commit status named `context` on `sha`, or undefined when there is none or it has no URL. */
+  statusUrl?(sha: string, context: string): Promise<string | undefined>;
 }
 
 /**
@@ -596,6 +621,8 @@ export function forgePrincipalOf(kind: ForgeKind, host: string, login: string):
 
 interface Transport {
   call(method: string, path: string, body?: unknown): Promise<unknown>;
+  /** A GET whose body is returned as text, not parsed; undefined on a 404. */
+  text(path: string): Promise<string | undefined>;
   /** Every page of a list, `pageParams(page)` appended to `path`. */
   list(path: string, pageParams: (page: number) => string, pageSize: number): Promise<unknown[]>;
 }
@@ -615,6 +642,14 @@ function transport(base: string, headers: Record<string, string>, fetchImpl: For
   };
   return {
     call,
+    async text(path) {
+      const url = `${root}${path}`;
+      const res = await fetchImpl(url, { method: "GET", headers });
+      const body = await res.text();
+      if (res.status === 404) return undefined;
+      if (!res.ok) throw new ForgeApiError("GET", url, res.status, body);
+      return body;
+    },
     async list(path, pageParams, pageSize) {
       const out: unknown[] = [];
       for (let page = 1; page <= 50; page++) {
@@ -1414,6 +1449,39 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
       const last = newestTime(pipelines.map((p) => (isObject(p) ? str(p.created_at) : undefined)));
       return { ...(last ? { last } : {}), ...(ours.length === 0 ? { noSchedule: true } : {}) };
     },
+    async mergeRequestJobs(branch, job) {
+      const out: MergeRequestJob[] = [];
+      const open = await api.list(`${notes}?state=opened&target_branch=${encodeURIComponent(branch)}`, pageParams, 100);
+      for (const m of open) {
+        if (!isObject(m)) continue;
+        const iid = num(m.iid);
+        const head = str(m.sha);
+        const own = num(m.project_id);
+        if (iid === undefined || !head) continue;
+        // Newest first; only this project's pipelines at the head count.
+        const pipelines = (await api.list(`${notes}/${iid}/pipelines`, pageParams, 100))
+          .filter((p): p is Record<string, unknown> => isObject(p) && p.sha === head && (own === undefined || num(p.project_id) === undefined || num(p.project_id) === own))
+          .sort((a, b) => (num(b.id) ?? 0) - (num(a.id) ?? 0));
+        const newest = pipelines[0];
+        const pid = newest ? num(newest.id) : undefined;
+        if (pid === undefined) continue;
+        const jobs = await api.list(`${project}/pipelines/${pid}/jobs`, pageParams, 100);
+        const found = jobs.filter((j): j is Record<string, unknown> => isObject(j) && j.name === job).sort((a, b) => (num(b.id) ?? 0) - (num(a.id) ?? 0))[0];
+        const id = found ? num(found.id) : undefined;
+        if (!found || id === undefined) continue;
+        const url = str(found.web_url);
+        out.push({ pr: iid, head, id, status: str(found.status) ?? "unknown", ...(url ? { url } : {}) });
+      }
+      return out.sort((a, b) => a.pr - b.pr);
+    },
+    async jobArtifact(id, path) {
+      return api.text(`${project}/jobs/${id}/artifacts/${path.split("/").map(encodeURIComponent).join("/")}`);
+    },
+    async statusUrl(sha, context) {
+      const statuses = await api.list(`${project}/repository/commits/${sha}/statuses?all=true&name=${encodeURIComponent(context)}`, pageParams, 100);
+      const newest = statuses.filter((st): st is Record<string, unknown> => isObject(st) && st.name === context).sort((a, b) => (num(b.id) ?? 0) - (num(a.id) ?? 0))[0];
+      return newest ? (str(newest.target_url) ?? undefined) : undefined;
+    },
     async editPullRequest(mr, change) {
       return mergeRequest(await api.call("PUT", `${notes}/${mr}`, { ...(change.title !== undefined ? { title: change.title } : {}), ...(change.body !== undefined ? { description: change.body } : {}) }));
     },

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

@@ -40,8 +40,9 @@ describe("the pull-request loop bundle", () => {
       "packages/core/src/plan-summary.ts",
       "packages/core/src/pr-forge.ts",
       "packages/core/src/pr-loop.ts",
+      "packages/core/src/pr-migrations.ts",
     ]);
-    // 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);
+    // About 89 KB today, after the hooks line (#4288), the blocked set (#4291), the scheduled-run reads (#4289) the requires checks (#4301) and the migration notes (#4407), about 97 KB.
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(100 * 1024);
   });
 });

package/src/pr-loop.test.ts

@@ -424,3 +424,55 @@ describe("the policy in the report and the note (#4294)", () => {
     expect(prStatusDescription({ ...denied, stage: "apply", status: "refused", refusal: "policy-denied" })).toBe("refused: the policy denied the plan (main.deny_public)");
   });
 });
+
+describe("new migration files in the plan note (#4407)", () => {
+  const migrations: NonNullable<PrReport["migrations"]> = [
+    {
+      member: "ledger",
+      reader: "goose-dir",
+      file: "db/00002_index.sql",
+      version: "00002",
+      name: "index",
+      type: "versioned",
+      dialect: "postgres",
+      statements: [
+        {
+          index: 1,
+          sql: "CREATE INDEX orders_status_idx ON orders (status)",
+          outcome: "classified",
+          changes: [{ rule: "SQLPG241", class: "concurrently", label: "needs CONCURRENTLY", title: "Create an index without CONCURRENTLY", lock: "SHARE" }],
+        },
+        {
+          index: 2,
+          sql: "ALTER TABLE orders ALTER COLUMN a TYPE bigint",
+          outcome: "undecided",
+          changes: [],
+          candidates: [
+            { rule: "SQLPG206", class: "metadata", label: "metadata only", title: "t" },
+            { rule: "SQLPG207", class: "rewrite", label: "ACCESS EXCLUSIVE rewrite or scan", title: "t" },
+          ],
+          note: "x",
+        },
+      ],
+    },
+  ];
+  const withMigrations: PrReport = { ...planReport, migrations };
+
+  test("the report validates and the note lists each statement with its class, rule and lock", () => {
+    expectValid(withMigrations);
+    const note = renderPrNote(withMigrations);
+    expect(note).toContain("New migration files (1), classified offline. Nothing is applied and no server is contacted.");
+    expect(note).toContain("`db/00002_index.sql` (member `ledger`, postgres)");
+    expect(note).toContain("- 1. `CREATE INDEX orders_status_idx ON orders (status)`: needs CONCURRENTLY (SQLPG241, SHARE)");
+    expect(note).toContain("undecided between SQLPG206 metadata only and SQLPG207 ACCESS EXCLUSIVE rewrite or scan");
+  });
+
+  test("a report with none renders as before", () => {
+    expect(renderPrNote(planReport)).not.toContain("migration");
+  });
+
+  test("a note line cannot be broken out of by a file's text", () => {
+    const note = renderPrNote({ ...withMigrations, migrations: [{ ...migrations[0]!, statements: [], error: "bad\n\n# heading `x`" }] });
+    expect(note).toContain("- not read: bad # heading `x`");
+  });
+});