@intentius/chant 0.124.46 → 0.124.49

package/src/components/pr-hooks.test.ts

@@ -8,6 +8,7 @@ import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSy
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { parseDeclaration, WorkspaceReadError } from "../workspace/declaration";
+import { PR_LOOP_HOOK_MOMENTS } from "../op/op-waves";
 import { prLoopHooksAt, prLoopHooksOf, runPrHooks } from "./pr-hooks";
 import type { OpWaveExec } from "../op/op-waves-run";
 
@@ -30,6 +31,12 @@ const declaration = (hooks: unknown, memberHooks?: unknown) => ({
 });
 
 describe("ci.hooks in the declaration (#4288)", () => {
+  test("accepts after.gate, and runs it after the plan-side moments (#4323)", () => {
+    const d = parseDeclaration(JSON.stringify(declaration({ after: { gate: [{ name: "report", command: ["report"] }] } }, { after: { gate: [{ name: "member-report", command: ["mr"] }] } })), "chant.workspace.json", "0.124.41");
+    expect(prLoopHooksOf(d, "infra")["after-gate"]!.map((h) => h.name)).toEqual(["report", "member-report"]);
+    expect(PR_LOOP_HOOK_MOMENTS).toContain("after-gate");
+  });
+
   test("parses at the top level and on a member; the member's run after the top level's", () => {
     const d = parseDeclaration(
       JSON.stringify(declaration({ before: { observe: [{ name: "init", command: ["init"] }] } }, { before: { observe: [{ name: "member-init", command: ["mi"], targets: ["db*"] }] } })),
@@ -43,7 +50,7 @@ describe("ci.hooks in the declaration (#4288)", () => {
 
   test("refuses hooks a pull-request job cannot run", () => {
     const read = (hooks: unknown) => () => parseDeclaration(JSON.stringify(declaration(hooks)), "chant.workspace.json", "0.124.41");
-    expect(read({ after: { gate: [{ command: ["x"] }] } })).toThrow(WorkspaceReadError);
+    expect(read({ before: { plan: [{ command: ["x"], onFailure: "bogus" }] } })).toThrow(WorkspaceReadError);
     expect(read({ before: { plan: [{ command: [] }] } })).toThrow(/must be a command as argv/);
     expect(read({ apply: { runBy: "apply" } })).toThrow(/runBy is for an Op waves spec/);
   });
@@ -84,7 +91,7 @@ describe("prLoopHooksAt (#4288)", () => {
 });
 
 describe("runPrHooks (#4288)", () => {
-  test("runs a moment for the selected components, writes the runs and plan files, and reports a failure", () => {
+  test("runs a moment for the selected components, writes the runs and plan files, and reports a failure", async () => {
     const cwd = tmp();
     const calls: Array<{ argv: string; env?: Record<string, string> }> = [];
     const exec: OpWaveExec = (argv, _dir, env) => {
@@ -95,7 +102,7 @@ describe("runPrHooks (#4288)", () => {
       base: "b".repeat(40),
       hooks: { "after-plan": [{ name: "check", command: ["check", "{target}", "{plan}"], perRun: true, targets: ["api", "web"] }] },
     };
-    const ran = runPrHooks(read, "after-plan", { op: "pr-7", env: "prod", stage: "plan", dir: ".chant/pr", cwd, exec, log: () => {} }, ["api", "db", "web"], {
+    const ran = await runPrHooks(read, "after-plan", { op: "pr-7", env: "prod", stage: "plan", dir: ".chant/pr", cwd, exec, log: () => {} }, ["api", "db", "web"], {
       members: [{ member: "api", component: "api", planDigest: "sha256:1", status: "planned", counts: { create: 1, update: 0, replace: 0, delete: 0 } }],
       plans: { api: { api: { file: "plan.bin" } } },
     });
@@ -110,9 +117,70 @@ describe("runPrHooks (#4288)", () => {
     expect(ran.failed).toBe("after-plan hook check (web) exited 1");
   });
 
-  test("a moment with no hooks runs nothing and writes nothing", () => {
+  test("a moment with no hooks runs nothing and writes nothing", async () => {
     const cwd = tmp();
-    const ran = runPrHooks({ base: "b", hooks: {} }, "before-apply", { op: "pr-7", env: "prod", stage: "apply", dir: ".chant/pr", cwd, log: () => {} }, ["api"]);
+    const ran = await runPrHooks({ base: "b", hooks: {} }, "before-apply", { op: "pr-7", env: "prod", stage: "apply", dir: ".chant/pr", cwd, log: () => {} }, ["api"]);
     expect(ran).toEqual({ outcomes: [], holds: [] });
   });
+
+  const holdBody = { gate: "db-migrate", digest: "sha256:m1", op: "other-op" };
+  /** An exec for a hook that holds on db-migrate until CHANT_HOLD_APPROVED is set. */
+  const holdingExec = (cwd: string, calls: Array<Record<string, string> | undefined>): OpWaveExec => (argv, _dir, env) => {
+    calls.push(env);
+    if (env?.CHANT_HOLD_APPROVED) return 0;
+    writeFileSync(join(cwd, env!.CHANT_HOLD!), JSON.stringify(holdBody));
+    return argv[0] === "hold" ? 1 : 0;
+  };
+  const gateHooks = { "after-gate": [{ name: "migrate", command: ["hold"], onFailure: "approve" as const }] };
+  const place = (cwd: string, exec: OpWaveExec) => ({ op: "pr-7", env: "prod", stage: "apply" as const, dir: ".chant/pr", cwd, exec, log: () => {} });
+
+  test("an after-gate hook gets the gate's decision in its environment (#4323)", async () => {
+    const cwd = tmp();
+    const calls: Array<Record<string, string> | undefined> = [];
+    const exec: OpWaveExec = (_argv, _dir, env) => (calls.push(env), 0);
+    const read = { base: "b", hooks: { "after-gate": [{ name: "report", command: ["report"] }] } };
+    const decision = { CHANT_GATE_STATUS: "approved", CHANT_GATE_OP: "pr-7", CHANT_GATE: "pr-apply", CHANT_GATE_DIGEST: "sha256:p" };
+    const ran = await runPrHooks(read, "after-gate", place(cwd, exec), ["api"], undefined, { env: decision });
+    expect(calls[0]).toMatchObject({ CHANT_HOOK: "after-gate", ...decision });
+    expect(ran.outcomes).toEqual([{ moment: "after-gate", name: "report", exit: 0, outcome: "passed" }]);
+  });
+
+  test("a hold on another gate clears once that gate is approved: the hook runs again with CHANT_HOLD_APPROVED (#4323)", async () => {
+    const cwd = tmp();
+    const calls: Array<Record<string, string> | undefined> = [];
+    let approved = false;
+    const asked: string[] = [];
+    const settle = async (hold: { request: { gate: string; digest: string; op?: string } }) => {
+      asked.push(`${hold.request.op} / ${hold.request.gate} @ ${hold.request.digest}`);
+      return approved ? { status: "approved" as const, approvedBy: "alice", approvedAt: "2026-10-23T00:00:00Z" } : { status: "waiting" as const };
+    };
+    const read = { base: "b", hooks: gateHooks };
+    const first = await runPrHooks(read, "after-gate", place(cwd, holdingExec(cwd, calls)), ["api"], undefined, { settle });
+    expect(first.failed).toMatch(/^after-gate hook migrate waits on other-op \/ db-migrate, which nobody approved at sha256:m1\. Approve: /);
+    expect(first.holds).toEqual([]);
+
+    approved = true;
+    calls.length = 0;
+    const second = await runPrHooks(read, "after-gate", place(cwd, holdingExec(cwd, calls)), ["api"], undefined, { settle });
+    expect(second.failed).toBeUndefined();
+    expect(second.holds).toEqual([]);
+    expect(asked).toEqual(["other-op / db-migrate @ sha256:m1", "other-op / db-migrate @ sha256:m1"]);
+    expect(JSON.parse(calls[1]!.CHANT_HOLD_APPROVED!)).toEqual({ op: "other-op", gate: "db-migrate", digest: "sha256:m1", approvedBy: "alice", approvedAt: "2026-10-23T00:00:00Z" });
+    expect(second.outcomes.map((o) => o.outcome)).toEqual(["held", "passed"]);
+  });
+
+  test("a re-run that holds on a gate already approved fails the stage (#4323)", async () => {
+    const cwd = tmp();
+    const exec: OpWaveExec = (_argv, _dir, env) => (writeFileSync(join(cwd, env!.CHANT_HOLD!), JSON.stringify(holdBody)), 1);
+    const settle = async () => ({ status: "approved" as const, approvedBy: "alice", approvedAt: "t" });
+    const ran = await runPrHooks({ base: "b", hooks: gateHooks }, "after-gate", place(cwd, exec), ["api"], undefined, { settle });
+    expect(ran.failed).toMatch(/holds again on other-op \/ db-migrate at sha256:m1, which is already approved/);
+  });
+
+  test("without a settler a hold on another gate stays a plain hold", async () => {
+    const cwd = tmp();
+    const ran = await runPrHooks({ base: "b", hooks: gateHooks }, "after-gate", place(cwd, holdingExec(cwd, [])), ["api"]);
+    expect(ran.holds).toEqual(["after-gate hook migrate (on other-op / db-migrate)"]);
+    expect(ran.failed).toBeUndefined();
+  });
 });

package/src/components/pr-hooks.ts

@@ -16,11 +16,13 @@
  * component's members and the plans its steps hand the apply.
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import type { OpWaveHook, OpWaveHookMoment, OpWaveHooks } from "../op/op-waves";
 import { PR_LOOP_HOOK_MOMENTS } from "../op/op-waves";
-import { runStageHooks, type OpWaveExec, type OpWaveHookRun, type StageHooksRun } from "../op/op-waves-run";
+import { OP_WAVE_MAX_CHAINED_HOLDS, runStageHooks, type OpWaveExec, type OpWaveHookRun, type StageHooksRun } from "../op/op-waves-run";
+import { readHoldRequest, spawnExec, type OpWaveHookOutcome, type OtherGateHold } from "../op/stage-hooks";
+import { approveCommand } from "../op/gate";
 import { readDeclaration, WorkspaceReadError, type Declaration } from "../workspace/declaration";
 import { memberAtCwd } from "../workspace/security";
 import { locateWorkspace } from "../workspace/which-chant";
@@ -101,6 +103,20 @@ export interface PrHookPlace {
   log?: (line: string) => void;
 }
 
+/** How a gate a hook holds the job on stands (#4323). */
+export interface PrHoldSettled {
+  status: "approved" | "waiting";
+  approvedBy?: string;
+  approvedAt?: string;
+}
+
+/**
+ * Settle a hold on another gate (#4323): an approval of `hold.request.gate`
+ * at `hold.request.digest`, else a pending fact for it. The pull-request
+ * jobs give this the ledger they decide their own gate by.
+ */
+export type PrHoldSettler = (hold: OtherGateHold) => Promise<PrHoldSettled>;
+
 /** What one moment's hooks came to on the pull-request path. */
 export interface PrHooksRun {
   outcomes: PrHookOutcome[];
@@ -108,18 +124,27 @@ export interface PrHooksRun {
   holds: string[];
 }
 
+/** The run's options: the gate's decision for `after-gate`, and who settles a hold on another gate. */
+export interface PrHooksRunOptions {
+  /** Added to every hook's environment: `after-gate` carries `CHANT_GATE_STATUS`, `CHANT_GATE_OP`, `CHANT_GATE` and `CHANT_GATE_DIGEST`. */
+  env?: Record<string, string>;
+  /** Without it a hold on another gate is a plain hold. */
+  settle?: PrHoldSettler;
+}
+
 /**
  * Run the hooks of `moment` for `components` (#4288). `plans`, after the
  * plan, gives each component's members and step plans, written where a
  * `perRun` hook's `{plan}` points.
  */
-export function runPrHooks(
+export async function runPrHooks(
   read: PrLoopHooks,
   moment: OpWaveHookMoment,
   place: PrHookPlace,
   components: readonly string[],
   planned?: { members: readonly PrMember[]; plans: Record<string, Record<string, unknown>> },
-): PrHooksRun {
+  options: PrHooksRunOptions = {},
+): Promise<PrHooksRun> {
   const hooks = read.hooks[moment];
   if (!hooks || hooks.length === 0) return { outcomes: [], holds: [] };
   // Relative to cwd, as an Op waves job's paths are, whether --output was given relative or absolute.
@@ -141,11 +166,18 @@ export function runPrHooks(
     runs,
     runsFile,
     holdFile: join(dir, "hold.json"),
-    env: { CHANT_ENV: place.env, CHANT_PR_STAGE: place.stage, CHANT_HOOKS_BASE: read.base },
+    env: { CHANT_ENV: place.env, CHANT_PR_STAGE: place.stage, CHANT_HOOKS_BASE: read.base, ...options.env },
+    keepOtherGates: options.settle !== undefined,
     cwd: place.cwd,
     ...(place.exec ? { exec: place.exec } : {}),
     ...(place.log ? { log: place.log } : {}),
   });
+  const log = place.log ?? ((line: string) => console.error(line));
+  const settled = ran.failed || !options.settle ? undefined : await settleHolds(ran.otherGates ?? [], options.settle, place, log);
+  if (settled) {
+    ran.outcomes.push(...settled.outcomes);
+    if (settled.failed) ran.failed = settled.failed;
+  }
   const outcomes = ran.outcomes.map((o): PrHookOutcome => ({
     moment: o.moment,
     name: o.name,
@@ -155,3 +187,61 @@ export function runPrHooks(
   }));
   return { outcomes, ...(ran.failed ? { failed: ran.failed } : {}), holds: ran.holds };
 }
+
+/**
+ * Settle each hook call that held the job on another gate (#4323), as an Op
+ * waves job does (`runHooks` in op-waves-run.ts): once the gate is approved
+ * the hook runs again with `CHANT_HOLD_APPROVED` (and `CHANT_HOLDS_APPROVED`,
+ * the gates approved so far), and it may hold on a further gate, settled in
+ * turn, up to {@link OP_WAVE_MAX_CHAINED_HOLDS}. A gate nobody approved fails
+ * the stage, with the command that approves it.
+ */
+async function settleHolds(holds: readonly OtherGateHold[], settle: PrHoldSettler, place: PrHookPlace, log: (line: string) => void): Promise<{ outcomes: OpWaveHookOutcome[]; failed?: string }> {
+  const outcomes: OpWaveHookOutcome[] = [];
+  const exec = place.exec ?? spawnExec;
+  for (const first of holds) {
+    let hold = first;
+    const approved: Array<{ op: string; gate: string; digest: string; approvedBy: string; approvedAt: string }> = [];
+    for (;;) {
+      const op = hold.request.op ?? place.op;
+      const held = await settle(hold);
+      if (held.status === "waiting") {
+        return { outcomes, failed: `${hold.label} waits on ${op} / ${hold.request.gate}, which nobody approved at ${hold.request.digest}. Approve: ${approveCommand(op, hold.request.gate, undefined, hold.request.digest)}` };
+      }
+      const now = { op, gate: hold.request.gate, digest: hold.request.digest, approvedBy: held.approvedBy ?? "", approvedAt: held.approvedAt ?? "" };
+      approved.push(now);
+      const holdFile = join(place.cwd, hold.env.CHANT_HOLD!);
+      rmSync(holdFile, { force: true });
+      let code: number;
+      try {
+        code = exec(hold.argv, place.cwd, { ...hold.env, CHANT_HOLD_APPROVED: JSON.stringify(now), CHANT_HOLDS_APPROVED: JSON.stringify(approved) });
+      } catch (err) {
+        log(`${hold.label} did not run: ${err instanceof Error ? err.message : String(err)}`);
+        code = 127;
+      }
+      const target = hold.target ? { target: hold.target } : {};
+      if (code === 0) {
+        outcomes.push({ moment: hold.moment, name: hold.name, ...target, exit: code, outcome: "passed" });
+        log(`${hold.label}: ${now.approvedBy} approved ${op} / ${now.gate} at ${now.digest}, and the hook ran again and passed`);
+        break;
+      }
+      const next = readHoldRequest(holdFile, log, hold.label);
+      const nextOp = next ? (next.op ?? place.op) : "";
+      const problem = !next
+        ? `${hold.label} exited ${code} after ${now.approvedBy} approved ${now.gate}`
+        : approved.some((a) => a.op === nextOp && a.gate === next.gate && a.digest === next.digest)
+          ? `${hold.label} exited ${code} after ${now.approvedBy} approved ${now.gate}, and holds again on ${nextOp} / ${next.gate} at ${next.digest}, which is already approved`
+          : approved.length >= OP_WAVE_MAX_CHAINED_HOLDS
+            ? `${hold.label} held the job on ${approved.length} gates in turn and asks for one more; a hook call holds on at most ${OP_WAVE_MAX_CHAINED_HOLDS}`
+            : undefined;
+      if (problem) {
+        outcomes.push({ moment: hold.moment, name: hold.name, ...target, exit: code, outcome: "failed" });
+        log(problem);
+        return { outcomes, failed: problem };
+      }
+      outcomes.push({ moment: hold.moment, name: hold.name, ...target, exit: code, outcome: "held" });
+      hold = { ...hold, request: next! };
+    }
+  }
+  return { outcomes };
+}

package/src/components/pr-pipeline.ts

@@ -73,6 +73,10 @@
  * forge's run as its `runOrigin`. `ci run` runs `command` in the job's own
  * checkout with the job's environment, less the key. The plan passes
  * `--no-push`, so it still writes nothing to the remote `chant/lifecycle`.
+ * The plan job gets no `CHANT_RUNNER_KEY` (#4328): it runs the pull request's
+ * code, and a key in the job's environment is one that code could read and
+ * sign with, whatever `ci run` leaves out of its steps. Its record is
+ * unsigned.
  *
  * In a workspace member (#3465) both commands run in the member's directory
  * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
@@ -211,6 +215,14 @@ export interface PrLoopPipelineOptions {
    * ({@link prEnvJobs}). Set from `--pr-env` beside `--pr-loop`. Default false.
    */
   prEnvironment?: boolean;
+  /**
+   * `ci.locks: plan` (#4293, #4327): a `lock` job after the plan that runs
+   * `chant lock --from-report`, and an `unlock` job when the pull request
+   * closes that runs `chant unlock`. Both check out the target branch's
+   * commit, so neither runs the change's code. Set from the declaration at
+   * base; GitHub and Forgejo only. Absent: neither job.
+   */
+  locks?: "plan";
   /**
    * The cloud identity a pull request environment's jobs take (#4330), from
    * `ci.identity.cloud` (`resolvePrEnvCloudIdentity` in ../ci-identity.ts):
@@ -222,6 +234,18 @@ export interface PrLoopPipelineOptions {
   prEnvIdentity?: CloudTradeSpec;
 }
 
+/** The lock job's step names and commands (#4327), shared by the GitHub-shaped generators. */
+export const PR_LOCK_JOB = "lock";
+export const PR_UNLOCK_JOB = "unlock";
+
+/** `chant lock --from-report` for the plan's report in {@link PR_LOOP_REPORT_DIR}; reads `PR_NUMBER` and `HEAD_SHA`. */
+export function prLockCommand(forge: ForgeKind): string {
+  return ["chant", "lock", "--from-report", `${PR_LOOP_REPORT_DIR}/pr-plan.json`, "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"', "--stage", "plan", "--forge", forge].join(" ");
+}
+
+/** `chant unlock` for the pull request that closed; reads `PR_NUMBER`. */
+export const PR_UNLOCK_COMMAND = 'chant unlock --pr "$PR_NUMBER"';
+
 /** One job's command and the forge values it reads, as environment variables for its step. */
 export interface PrLoopJob {
   /** `plan`, `apply` or `record` (#4168). */
@@ -258,8 +282,10 @@ export interface PrLoopJob {
    * <job> --in-place` with the same environment, gate, forge, events and
    * report URL, which runs `command` and records the run. `env` is the
    * job's `env` and, on GitHub and Forgejo, `CHANT_RUNNER_KEY` from the
-   * repository secret of that name. GitLab hands its CI/CD variables to a
-   * job itself.
+   * repository secret of that name, except for the plan, which runs the
+   * pull request's code (#4328). GitLab hands its CI/CD variables to a job
+   * itself, so there the key is a protected variable, which a merge request
+   * pipeline never gets.
    */
   run: { command: string; env: Record<string, string> };
 }
@@ -354,7 +380,8 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
       command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common, ...(options.waveGate ? ["--wave-gate", options.waveGate] : []), "--no-status"].join(" "),
       env: planEnv,
       ...build,
-      run: { command: ciRun("plan").join(" "), env: runEnv(planEnv) },
+      // #4328: no runner key either. The step drops it, but the job's environment is the pull request's code's too.
+      run: { command: ciRun("plan").join(" "), env: planEnv },
     },
     early ? earlyApply : greenApply,
     {
@@ -372,31 +399,52 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
 export const PR_PLAN_NOTE_JOB = "plan-note";
 
 /**
- * The plan-note job's command and the values it reads (#4295). It runs in a
- * fresh job after the plan, at the target branch's commit, and posts the
- * note and the `chant/plan` status from the report the plan job handed on,
- * with the forge token the plan job never held. `HEAD_SHA` is the commit
- * the plan job checked out, `PR_NUMBER` the pull request, and on GitHub and
- * Forgejo `PLAN_RESULT` the plan job's result, which fails the status when
- * the plan job failed. `BASE_SHA` is the commit the note job checks out on
- * GitLab, whose runner checks out the pipeline's own commit.
+ * The plan-note job's command and the values it reads (#4295). On GitHub
+ * and Forgejo it runs in a fresh job after the plan, at the target branch's
+ * commit, and posts the note and the `chant/plan` status from the report
+ * the plan job handed on, with the forge token the plan job never held.
+ * `HEAD_SHA` is the commit the plan job checked out, `PR_NUMBER` the pull
+ * request, and `PLAN_RESULT` the plan job's result, which fails the status
+ * when the plan job failed.
+ *
+ * On GitLab (#4328) it runs `pr-post --open` in a pipeline of the target
+ * branch, which GitLab builds from that branch's files and gives the
+ * protected `CHANT_FORGE_TOKEN`. A merge request pipeline is built from the
+ * merge request's files, so no job in it holds the token. `pr-post --open`
+ * asks GitLab for each open merge request's plan job and reads its report
+ * from the job's artifacts.
  */
 export function prLoopPostJob(forge: ForgeKind, env: string, member?: string): { command: string; env: Record<string, string> } {
-  const github = forge !== "gitlab";
+  if (forge === "gitlab") {
+    return {
+      command: ["chant", "components", "pr-post", "--open", "--env", env, "--output", PR_LOOP_REPORT_DIR, "--forge", forge, ...(member ? ["--member", member] : [])].join(" "),
+      env: {},
+    };
+  }
   const command = [
     "chant", "components", "pr-post", "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"',
     "--env", env, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
     ...(member ? ["--member", member] : []),
-    ...(github ? ["--result", '"$PLAN_RESULT"'] : []),
+    "--result", '"$PLAN_RESULT"',
   ].join(" ");
   return {
     command,
-    env: github
-      ? { PR_NUMBER: "${{ github.event.pull_request.number }}", HEAD_SHA: "${{ github.sha }}", PLAN_RESULT: "${{ needs.plan.result }}", GITHUB_TOKEN: GITHUB_JOB_TOKEN }
-      : { PR_NUMBER: "$CI_MERGE_REQUEST_IID", HEAD_SHA: "$CI_COMMIT_SHA", BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA" },
+    env: { PR_NUMBER: "${{ github.event.pull_request.number }}", HEAD_SHA: "${{ github.sha }}", PLAN_RESULT: "${{ needs.plan.result }}", GITHUB_TOKEN: GITHUB_JOB_TOKEN },
   };
 }
 
+/** The plan job's name in a GitLab merge request pipeline (#3465, #4328): `plan`, or `<member>-plan` in a workspace member's included file. */
+export function gitlabPlanJobName(member?: string): string {
+  return member ? `${member}-plan` : "plan";
+}
+
+/**
+ * The GitLab variable a pipeline schedule (or a person starting a pipeline
+ * of the target branch) sets to `1` to post the open merge requests' plan
+ * notes (#4328).
+ */
+export const GITLAB_PLAN_NOTES_VAR = "CHANT_PLAN_NOTES";
+
 /**
  * What starts the apply under apply on merge (#4168 step 9): on GitHub the
  * tick's workflow finishing (`workflow_run`, since tags its token pushes start

package/src/components/pr-policy.test.ts

@@ -14,7 +14,9 @@ import { composeChangeSet } from "../change-set";
 import { memoryGateLedgerPort } from "../op/gate";
 import { overrideDigest } from "../override-gate";
 import type { GatePolicyExec } from "../gate-policy";
-import { decidePrPolicyOverride, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrPolicyInput } from "./pr-policy";
+import type { FoundComment, MarkerMatch, PrForge } from "../pr-forge";
+import { reviewMarker, reviewNoteBody } from "../op/activities/review-agent";
+import { decidePrPolicyOverride, policyReviewOf, prLoopPolicyAt, prPolicyReport, REVIEW_NOTE_AUTHORS, runPrPolicy, spendPrPolicyOverride, type PrPolicyInput } from "./pr-policy";
 
 const scratch: string[] = [];
 afterAll(() => {
@@ -143,3 +145,64 @@ describe("a denial and its override (#4294)", () => {
     await expect(spendPrPolicyOverride(port, "pr-7", { by: "github:carol", at: "2026-10-22T12:00:00Z", reason: "ok", digest: "sha256:1" })).rejects.toThrow(/did not reach the remote/);
   });
 });
+
+describe("input.review: a policy reads the review's risk (#4326)", () => {
+  const HEAD = "a".repeat(40);
+  const noteBody = (risk: "low" | "high", head = HEAD) =>
+    `${reviewMarker("pr-review")}\n\n${reviewNoteBody({ review: `Replaces the bucket.\n\nrisk: ${risk}\n`, exitCode: 0, digest: "sha256:0123456789ab", instructions: "base", head })}`;
+
+  /** A forge whose comments are `notes`; findComment applies the marker and author rules the real clients do. */
+  function forgeWith(notes: Array<{ body: string; author: string }>): PrForge {
+    return {
+      async findComment(_pr: number, marker: string, opts: MarkerMatch = {}): Promise<FoundComment | undefined> {
+        const want = typeof opts.author === "string" ? [opts.author] : (opts.author ?? []);
+        const hit = notes.find((n) => n.body.startsWith(marker) && (!opts.author || want.map((w) => w.toLowerCase()).includes(n.author.toLowerCase())));
+        return hit ? { id: 1, body: hit.body } : undefined;
+      },
+    } as unknown as PrForge;
+  }
+
+  test("a note the run's token wrote gives the risk and the head it read", async () => {
+    const forge = forgeWith([{ body: noteBody("high"), author: "github-actions[bot]" }]);
+    expect(await policyReviewOf(forge, 7)).toEqual({ found: true, risk: "high", head: HEAD });
+  });
+
+  test("a note a person wrote, even with the marker and a low risk, is not the review", async () => {
+    const forge = forgeWith([{ body: noteBody("low"), author: "mallory" }]);
+    expect(await policyReviewOf(forge, 7)).toMatchObject({ found: false, risk: "unknown", head: null });
+    expect(REVIEW_NOTE_AUTHORS).not.toContain("mallory");
+  });
+
+  test("no pull request, no forge and a forge that fails all read as no review, with the reason", async () => {
+    expect(await policyReviewOf(forgeWith([]), 7)).toMatchObject({ found: false, reason: expect.stringContaining("no review note") });
+    expect(await policyReviewOf(undefined, 7)).toMatchObject({ found: false });
+    expect(await policyReviewOf(forgeWith([]), null)).toMatchObject({ found: false });
+    const broken = { findComment: async () => { throw new Error("503"); } } as unknown as PrForge;
+    expect(await policyReviewOf(broken, 7)).toMatchObject({ found: false, reason: expect.stringContaining("503") });
+  });
+
+  test("a note whose command failed names the risk unknown", async () => {
+    const failed = `${reviewMarker("pr-review")}\n\n${reviewNoteBody({ review: "risk: low", exitCode: 2, digest: "sha256:01", instructions: "base", head: HEAD })}`;
+    expect(await policyReviewOf(forgeWith([{ body: failed, author: "gitea-actions" }]), 7)).toEqual({ found: true, risk: "unknown", head: HEAD });
+  });
+
+  // A stand-in for `deny[msg] { input.review.risk == "high" }`: it reads the input file the engine was handed, as opa does.
+  const denyHighRisk: GatePolicyExec = (argv) => {
+    const fed = JSON.parse(readFileSync(argv[argv.indexOf("--input") + 1]!, "utf-8")) as PrPolicyInput;
+    const deny = fed.review?.risk === "high" ? ["the review rated this plan high risk"] : [];
+    return { status: 0, stdout: opaOut({ deny }), stderr: "" };
+  };
+
+  test("a policy that denies on high risk denies a plan the review rated high, and passes one rated low", async () => {
+    const { repo, base } = repoWithPolicy();
+    const read = prLoopPolicyAt(join(repo, "infra"), base);
+    const high = await policyReviewOf(forgeWith([{ body: noteBody("high"), author: "github-actions[bot]" }]), 7);
+    const low = await policyReviewOf(forgeWith([{ body: noteBody("low"), author: "github-actions[bot]" }]), 7);
+    const denied = runPrPolicy(read, { ...input(base), review: high }, denyHighRisk)!;
+    expect(denied.result).toBe("denied");
+    expect(denied.denials).toEqual([{ rule: "main.deny", message: "the review rated this plan high risk" }]);
+    expect(runPrPolicy(read, { ...input(base), review: low }, denyHighRisk)!.result).toBe("passed");
+    // A plan nobody reviewed is not high risk; a policy that wants a review denies on `found` itself.
+    expect(runPrPolicy(read, { ...input(base), review: await policyReviewOf(forgeWith([]), 7) }, denyHighRisk)!.result).toBe("passed");
+  });
+});

package/src/components/pr-policy.ts

@@ -20,6 +20,9 @@
  *   no longer applies under the approvals of the merges it carries.
  * - error: the policy did not run or gave no readable answer. pr-apply
  *   applies nothing.
+ *
+ * A policy also reads `input.review` (#4326): the risk the pull request's
+ * review note names, when the review agent posted one ({@link policyReviewOf}).
  */
 
 import { readDeclaration, WorkspaceReadError } from "../workspace/declaration";
@@ -36,6 +39,8 @@ import {
 import type { ChangeSetDocument } from "../change-set";
 import type { GateLedgerPort } from "../op/gate";
 import type { PrPolicyReport } from "../pr-loop";
+import type { PrForge } from "../pr-forge";
+import { parseReviewResult, REVIEW_MARKER_PREFIX, type ReviewRisk } from "../op/activities/review-agent";
 
 /** `ci.policy` as read at base. */
 export interface PrLoopPolicy {
@@ -92,6 +97,54 @@ export interface PrPolicyInput {
   head: string;
   /** The change-set document the gate binds. Its `entries` are every change the plan proposes. */
   changeSet: ChangeSetDocument;
+  /** What the pull request's review note says (#4326). Absent only when the caller did not look. */
+  review?: PolicyReview;
+}
+
+/**
+ * The review agent's finding as a policy reads it, `input.review`. The risk is
+ * the model's, so a policy treats it as one signal beside the change set, never
+ * as a verdict. `head` is the commit the review read; a policy that cares
+ * whether the review is current compares it with `input.head`.
+ */
+export interface PolicyReview {
+  /** Whether a review note written by the run's own token was found on the pull request. */
+  found: boolean;
+  /** The risk the review named, or `unknown` when none was found, the command failed or the review gave none. */
+  risk: ReviewRisk | "unknown";
+  /** The commit the review read, or null when none was found. */
+  head: string | null;
+  /** Why nothing was found, for the log. Absent when a review was. */
+  reason?: string;
+}
+
+/**
+ * The users the run's own token acts as on GitHub and Forgejo. Only a note one
+ * of them wrote counts as the review: a pull request's author can post a
+ * comment that starts with the marker, and cannot post as these.
+ */
+export const REVIEW_NOTE_AUTHORS: readonly string[] = ["github-actions[bot]", "gitea-actions", "forgejo-actions"];
+
+/**
+ * The review of pull request `pr`, read from the sticky note the review job
+ * posted (`postReviewNote`, ../op/activities/review-agent.ts). A forge that
+ * cannot be read, a pull request that is not known and a note nobody trusted
+ * all give `found: false`, which a policy sees as `risk: "unknown"`.
+ */
+export async function policyReviewOf(forge: PrForge | undefined, pr: number | null): Promise<PolicyReview> {
+  const none = (reason: string): PolicyReview => ({ found: false, risk: "unknown", head: null, reason });
+  if (!forge) return none("no forge client, so no pull request note was read");
+  if (pr === null) return none("no pull request to read a review from");
+  let note;
+  try {
+    note = await forge.findComment(pr, REVIEW_MARKER_PREFIX, { author: REVIEW_NOTE_AUTHORS });
+  } catch (err) {
+    return none(`could not read the notes of #${pr}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!note) return none(`#${pr} has no review note written by the run's token`);
+  const result = parseReviewResult(note.body);
+  if (!result) return none(`the review note on #${pr} names no head and risk`);
+  return { found: true, risk: result.risk, head: result.head };
 }
 
 /** Run the policy over `input`. Undefined when the base sets no policy. */

package/src/components/pr-run.ts

@@ -99,6 +99,7 @@ import type { CapabilityRegistry, PlannedOutputs } from "./capability";
 import type { RunProgressEvent } from "./run-progress";
 import type { RunEventSink } from "../run-event-stream";
 import { capabilitySteps, planWaveComponent, readDeployedOutputs } from "./wave-plan";
+import type { PrMigrationFile } from "../pr-migrations";
 
 export interface PrPlanSetOptions {
   /** Every component in the project, not the selection: a planned member's dependency outside it is read too (#4104). */
@@ -773,6 +774,8 @@ export interface PrReportInput {
   waves?: PrWave[];
   /** The rounds the apply planned after an upstream applied (#3999). */
   rounds?: PrRound[];
+  /** Plan stage (#4407): the new migration files, classified. */
+  migrations?: PrMigrationFile[];
 }
 
 /** The report a stage writes. */
@@ -797,6 +800,7 @@ export function prReport(input: PrReportInput): PrReport {
     ...(input.set.deployedOutputs ? { deployedOutputs: input.set.deployedOutputs } : {}),
     ...(input.set.plannedOutputs ? { plannedOutputs: input.set.plannedOutputs } : {}),
     ...(input.rounds && input.rounds.length > 0 ? { rounds: input.rounds } : {}),
+    ...(input.migrations && input.migrations.length > 0 ? { migrations: input.migrations } : {}),
     approval: input.approval,
     ...(input.waveGate ? { waveGate: input.waveGate } : {}),
     ...(input.waveGate && input.waves?.length ? { waves: [...input.waves].sort((a, b) => a.wave - b.wave) } : {}),

package/src/components/registry.test.ts

@@ -99,7 +99,7 @@ describe("createCapabilityRegistry", () => {
   // for them to live in instead.
   test("family table lists exactly the agnostic starter families plus the Cloudflare apply leaves (#1293)", () => {
     expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
-      ["build", "cloudflare", "escapeHatch", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
+      ["build", "cloudflare", "escapeHatch", "publish", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
     );
   });
 

package/src/components/starter-plugin.ts

@@ -32,6 +32,8 @@ import {
   zipPackageCapability,
   jvmBuildCapability,
   generateSbomCapability,
+  publishImageCapability,
+  publishArtifactCapability,
   signCapability,
   attestProvenanceCapability,
   verifyCapability,
@@ -62,6 +64,8 @@ export const STARTER_VERB_FAMILIES = {
   // moved to the aws lexicon (#684) alongside the other AWS leaves; core's sbom
   // family keeps only the agnostic, artifact-type-keyed `generate-sbom`.
   sbom: ["generate-sbom"],
+  // `publish-image` is one agnostic verb (#3142, #3143); each cloud lexicon contributes its registry login as a backend (`CapabilityPlugin.registryBackends`).
+  publish: ["publish-image", "publish-artifact"],
   supplyChainSecurity: ["sign", "attest-provenance", "verify"],
   supplyChainPolicy: ["scan-vulnerabilities", "vuln-gate"],
   // Only the *agnostic* wait/verify verbs are in the starter set; the
@@ -93,6 +97,8 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
     zipPackageCapability,
     jvmBuildCapability,
     generateSbomCapability,
+    publishImageCapability,
+    publishArtifactCapability,
     signCapability,
     attestProvenanceCapability,
     verifyCapability,

package/src/components/verbs/index.ts

@@ -39,6 +39,8 @@
 
 export * from "./build-archive";
 export * from "./build";
+export * from "./publish-image";
+export * from "./publish-artifact";
 export * from "./bom-writer";
 export * from "./sbom-generator";
 export * from "./sbom";