@intentius/chant-lexicon-github 0.124.55 → 0.124.56

package/src/components/generate-op-pipeline.cloud.test.ts

@@ -0,0 +1,96 @@
+/**
+ * #4631: cloud identities on a scheduled Op's job, traded before the
+ * checkout, and an update on drift in a job of its own that alone holds
+ * the update's identity.
+ */
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { generateGithubOpPipeline } from "./generate-op-pipeline";
+
+interface Step { id?: string; name?: string; uses?: string; run?: string; env?: Record<string, string> }
+interface Job { needs?: string; if?: string; permissions?: Record<string, string>; outputs?: Record<string, string>; environment?: unknown; steps: Step[] }
+interface Doc { permissions?: Record<string, string>; jobs: Record<string, Job> }
+
+const PREVIEW = { aws: { role: "arn:aws:iam::1:role/preview", region: "us-east-1", audience: "sts.amazonaws.com" } };
+const UPDATE = { aws: { role: "arn:aws:iam::1:role/update", region: "us-east-1", audience: "sts.amazonaws.com" } };
+const DRIFT: ScheduledOpSpec = { name: "plywood-drift-dev", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue", cloud: PREVIEW };
+
+const gen = (spec: ScheduledOpSpec) => parseYAML(generateGithubOpPipeline([spec]).files[0]!.yaml) as unknown as Doc;
+
+describe("a scheduled Op's cloud identities (#4631)", () => {
+  test("the trade runs before the checkout, and every later run step drops the token request variables", () => {
+    const doc = gen(DRIFT);
+    const job = doc.jobs["plywood-drift-dev"]!;
+    expect(job.steps[0]!.name).toBe("Trade the job's OIDC token for its cloud identities");
+    expect(JSON.parse(job.steps[0]!.env!.CHANT_CLOUD_TRADE!)).toEqual(PREVIEW);
+    expect(job.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+    for (const step of job.steps.slice(2)) if (step.run) expect(step.run).toMatch(/^unset ACTIONS_ID_TOKEN_REQUEST_TOKEN ACTIONS_ID_TOKEN_REQUEST_URL/);
+  });
+
+  test("the finding-mode's permissions stay; the job alone adds id-token: write", () => {
+    const plain = gen({ ...DRIFT, cloud: undefined } as ScheduledOpSpec);
+    const doc = gen(DRIFT);
+    expect(doc.permissions).toEqual(plain.permissions);
+    expect(doc.jobs["plywood-drift-dev"]!.permissions).toEqual({ ...plain.permissions, "id-token": "write" });
+  });
+
+  test("a malformed cloud and a cloud on a review split are refused", () => {
+    expect(() => gen({ ...DRIFT, cloud: { aws: { region: "us-east-1" } } as never })).toThrow(/audience/);
+    expect(() => gen({ name: "review", trigger: { kind: "pull_request" }, reviewAgent: true, cloud: PREVIEW })).toThrow(/no cloud identity/);
+  });
+});
+
+describe("an update on drift (#4631)", () => {
+  const spec: ScheduledOpSpec = { ...DRIFT, update: { command: "npx --no-install plywood up", cloud: UPDATE, environment: { name: "production" } } };
+  const doc = gen(spec);
+  const check = doc.jobs["plywood-drift-dev"]!;
+  const update = doc.jobs["plywood-drift-dev-update"]!;
+
+  test("the check says when it found drift, and holds only its own identity", () => {
+    expect(check.outputs).toEqual({ drift: "${{ steps.drift-check.outputs.drift }}" });
+    const run = check.steps.find((s) => s.id === "drift-check")!;
+    expect(run.run).toContain('if [ "$code" -eq 2 ]; then echo "drift=true"');
+    expect(JSON.stringify(check)).not.toContain("role/update");
+  });
+
+  test("the update job runs after a drift, trades for its own identity first, and runs the command", () => {
+    expect(update.needs).toBe("plywood-drift-dev");
+    expect(update.if).toBe("always() && needs.plywood-drift-dev.outputs.drift == 'true'");
+    expect(update.permissions).toEqual({ contents: "read", "id-token": "write" });
+    expect(update.environment).toEqual({ name: "production" });
+    expect(JSON.parse(update.steps[0]!.env!.CHANT_CLOUD_TRADE!)).toEqual(UPDATE);
+    expect(update.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+    expect(update.steps.at(-1)!.run).toMatch(/^unset .*\nnpx --no-install plywood up\n?$/);
+  });
+
+  test("an update on a push trigger, or with no command, is refused", () => {
+    expect(() => gen({ name: "apply", trigger: { kind: "push" }, update: { command: "x" } })).toThrow(/cron or pull_request/);
+    expect(() => gen({ ...DRIFT, update: { command: " " } })).toThrow(/command/);
+  });
+});
+
+describe("contents: write on the update job (#4631, 2026-10-28 ruling)", () => {
+  const plain = gen(DRIFT);
+  const spec: ScheduledOpSpec = { ...DRIFT, update: { command: "npx --no-install plywood up", cloud: UPDATE, permissions: { contents: "write" } } };
+  const doc = gen(spec);
+
+  test("the update job may raise contents to write, so it records on chant/lifecycle", () => {
+    expect(doc.jobs["plywood-drift-dev-update"]!.permissions).toEqual({ contents: "write", "id-token": "write" });
+  });
+
+  test("the drift check's job and the workflow keep their scopes", () => {
+    expect(doc.permissions).toEqual(plain.permissions);
+    expect(doc.jobs["plywood-drift-dev"]!.permissions).toEqual(plain.jobs["plywood-drift-dev"]!.permissions);
+    expect(doc.jobs["plywood-drift-dev"]!.permissions!.contents).not.toBe("write");
+  });
+
+  test("the identity scoping stays: the check holds the preview identity, the update its own", () => {
+    expect(JSON.stringify(doc.jobs["plywood-drift-dev"])).not.toContain("role/update");
+    expect(JSON.parse(doc.jobs["plywood-drift-dev-update"]!.steps[0]!.env!.CHANT_CLOUD_TRADE!)).toEqual(UPDATE);
+  });
+
+  test("contents restated at read is still refused", () => {
+    expect(() => gen({ ...DRIFT, update: { command: "x", permissions: { contents: "read" } } })).toThrow(/contents may only be raised to write/);
+  });
+});

package/src/components/generate-op-pipeline.ts

@@ -100,6 +100,9 @@ import { assertReviewSplit, reviewJobs, reviewNoteJobName } from "./review-jobs"
 import { resolveAgentSpec } from "@intentius/chant/ci-agent";
 import { activeProductWords } from "@intentius/chant/ci-product-words";
 import { agentJobName, agentPushJobName, driftRunOutputs, driftRunStep, githubAgentJobs } from "./agent-jobs";
+import { assertScheduledOpCloud, scheduledOpUpdateJobName, withoutTokenRequestLine } from "@intentius/chant/scheduled-op-cloud";
+import { TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
 
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 
@@ -437,6 +440,8 @@ export function buildGithubOpPipelineDocs(
 
   const words = activeProductWords();
   for (const spec of ops) {
+    // #4631: the job's cloud identities and the update on drift, checked before anything renders.
+    assertScheduledOpCloud(spec);
     // #4616: the comment agent is a workflow of its own, on pull request comments; the spec's trigger is not read.
     if (spec.agent?.on === "comment") {
       const settings = resolveAgentSpec(spec.name, spec.agent, words.product);
@@ -489,6 +494,8 @@ export function buildGithubOpPipelineDocs(
       throw new Error(`Scheduled Op "${spec.name}" sets a drift agent, which follows a drift check's run; give it a cron or pull_request trigger and no reviewAgent.`);
     }
     const stepEnv = split ? {} : jobTokenEnv(findingMode !== "report");
+    const cloud = spec.cloud;
+    const update = spec.update;
 
     const setup = spec.setup ?? [];
     assertSetupSteps(spec.name, setup);
@@ -503,15 +510,19 @@ export function buildGithubOpPipelineDocs(
       ? [...runParts, ...GATED_EXIT_FLAG, "--json"].join(" ")
       : runParts.join(" ");
 
-    const steps: Array<Record<string, unknown>> = [checkoutStep(), ...setup.map(setupStepDoc), ...runSteps(beforeScript)];
-    steps.push(
+    const later: Array<Record<string, unknown>> = [...setup.map(setupStepDoc), ...runSteps(beforeScript)];
+    later.push(
       gated
         ? gatedRunStep(RUN_STEP_ID, spec.name, invocation, stepEnv)
         : driftAgent
           ? driftRunStep(invocation, stepEnv, forge)
-          : { run: invocation, env: stepEnv },
+          : update
+            ? driftFlagStep(invocation, stepEnv)
+            : { run: invocation, env: stepEnv },
     );
-    steps.push(...runSteps(extraScript));
+    later.push(...runSteps(extraScript));
+    // #4631: the trade before the checkout, and every step after it without the token request variables.
+    const steps: Array<Record<string, unknown>> = cloud ? [tradeStep(cloud), checkoutStep(), ...later.map(withoutTokenRequest)] : [checkoutStep(), ...later];
 
     const review = split
       ? reviewJobs({
@@ -527,6 +538,12 @@ export function buildGithubOpPipelineDocs(
         })
       : undefined;
 
+    const workflowPermissions = mergePermissions(
+      spec.name,
+      permissionsFor(findingMode, trigger),
+      spec.permissions ?? {},
+      trigger,
+    );
     const doc: GithubOpPipelineDoc = {
       name: spec.name,
       on: onTrigger(trigger),
@@ -534,12 +551,7 @@ export function buildGithubOpPipelineDocs(
       // One run at a time per Op — a slow audit must not overlap its own next
       // scheduled trigger. A push Op's `build` (#4169) widens the group.
       concurrency: concurrency(opConcurrencyGroup(jobName, trigger)),
-      permissions: mergePermissions(
-        spec.name,
-        permissionsFor(findingMode, trigger),
-        spec.permissions ?? {},
-        trigger,
-      ),
+      permissions: workflowPermissions,
       jobsDoc: {
         [jobName]: {
           "runs-on": githubRunsOn(spec.runner),
@@ -554,6 +566,8 @@ export function buildGithubOpPipelineDocs(
           // behind the same reviewer would hold the message back until
           // somebody had already acted.
           ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
+          // #4631: the trade needs id-token: write, on this job alone; the finding-mode's scopes stay as they are.
+          ...(cloud ? { permissions: { ...workflowPermissions, "id-token": "write" } } : {}),
           ...(gated
             ? {
                 outputs: Object.fromEntries(
@@ -565,9 +579,21 @@ export function buildGithubOpPipelineDocs(
               }
             : driftAgent
               ? { outputs: driftRunOutputs(forge) }
-              : {}),
+              : update
+                ? { outputs: { drift: `\${{ steps.${DRIFT_FLAG_STEP_ID}.outputs.drift }}` } }
+                : {}),
           steps,
         },
+        ...(update
+          ? {
+              [scheduledOpUpdateJobName(jobName)]: updateJob(jobName, update, {
+                image,
+                ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+                setup: setup.map(setupStepDoc),
+                beforeScript,
+              }),
+            }
+          : {}),
       },
       ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image, spec.runner) } } : {}),
     };
@@ -671,3 +697,51 @@ export function generateGithubOpPipeline(
     jobs,
   };
 }
+
+/** The id of the run step that says whether an update's drift check found drift (#4631). */
+const DRIFT_FLAG_STEP_ID = "drift-check";
+
+/** The Op's run step when an update follows it (#4631): `drift=true` as an output on chant's drift code, and the run's own exit code. */
+function driftFlagStep(invocation: string, env: Record<string, string>): Record<string, unknown> {
+  return {
+    id: DRIFT_FLAG_STEP_ID,
+    env,
+    run: ["set +e", invocation, "code=$?", `if [ "$code" -eq ${CHANT_EXIT.drift} ]; then echo "drift=true" >>"$GITHUB_OUTPUT"; fi`, 'exit "$code"'].join("\n"),
+  };
+}
+
+/** The trade step (#4631), as an op wave job's (#4332): the job's OIDC token for `cloud`, written to GITHUB_ENV. */
+function tradeStep(cloud: CloudTradeSpec): Record<string, unknown> {
+  return { name: "Trade the job's OIDC token for its cloud identities", env: { [TRADE_SPEC_ENV]: JSON.stringify(cloud) }, run: tradeLine("$GITHUB_ENV", "github-env") };
+}
+
+/** A run step after the trade, with the token request variables unset first. A `uses:` step is left as it is. */
+function withoutTokenRequest(step: Record<string, unknown>): Record<string, unknown> {
+  return typeof step.run === "string" ? { ...step, run: withoutTokenRequestLine(step.run) } : step;
+}
+
+/**
+ * The update job (#4631): after the Op's job, only when its run found
+ * drift; its own trade for `update.cloud` before its checkout, then the
+ * update's command. Its permissions are `contents: read`, `id-token: write`
+ * with a cloud, and the update's own scopes, which may raise `contents` to
+ * `write` so the update records on `chant/lifecycle` (2026-10-28 ruling).
+ * The Op's own job keeps its scopes.
+ */
+function updateJob(
+  after: string,
+  update: NonNullable<ScheduledOpSpec["update"]>,
+  i: { image: string; runner?: ScheduledOpSpec["runner"]; setup: Array<Record<string, unknown>>; beforeScript: readonly string[] },
+): Record<string, unknown> {
+  const later: Array<Record<string, unknown>> = [...i.setup, ...runSteps(i.beforeScript), { name: "Update what drifted", run: update.command }];
+  return {
+    needs: after,
+    if: `always() && needs.${after}.outputs.drift == 'true'`,
+    "runs-on": githubRunsOn(i.runner),
+    container: i.image,
+    permissions: { contents: "read", ...(update.cloud ? { "id-token": "write" } : {}), ...(update.permissions ?? {}) },
+    ...nonEmpty("env", update.variables),
+    ...(update.environment ? { environment: environmentDoc(update.environment) } : {}),
+    steps: update.cloud ? [tradeStep(update.cloud), checkoutStep(), ...later.map(withoutTokenRequest)] : [checkoutStep(), ...later],
+  };
+}

package/src/components/generate-op-waves-pipeline.approval.test.ts

@@ -0,0 +1,46 @@
+/**
+ * #4630: a pr-review wave's plans workflow posts `<product>/approval` on the
+ * head after the plans are recorded and on every review, with a token that
+ * reads and writes statuses only.
+ */
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGithubOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "plywood-up",
+  op: "plywood-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pr-review" }],
+};
+
+describe("the approval status job (#4630)", () => {
+  test("runs after record-plans on a push and alone on a review, with a read token", () => {
+    const { files } = generateGithubOpWavesPipeline(spec, { specFile: ".chant/op-waves/plywood-up.spec.json", bin: "npx --no-install plywood" });
+    const plans = files.find((f) => f.name === "plywood-up-plans.yml")!.yaml;
+    expect(plans).toContain("pull_request_review:");
+    expect(plans).toMatch(/types:\n\s+- submitted\n\s+- dismissed/);
+    expect(plans).toContain("github.event_name == 'pull_request'");
+    expect(plans).toMatch(/approval-status:\n(.*\n)*?\s+needs:\n\s+- record-plans/);
+    expect(plans).toMatch(/permissions:\n\s+contents: read\n\s+pull-requests: read\n\s+statuses: write/);
+    expect(plans).toContain('npx --no-install plywood run wave --spec .chant/op-waves/plywood-up.spec.json --approval-status --pr "$PR_NUMBER" --head "$HEAD_SHA" --base "$BASE_SHA" --forge github');
+    expect(plans).toContain("HEAD_SHA: '${{ github.event.pull_request.head.sha }}'");
+    expect(plans).toContain("BASE_SHA: '${{ github.event.pull_request.base.sha }}'");
+  });
+
+  test("a spec with no pr-review wave has no plans workflow", () => {
+    const { files } = generateGithubOpWavesPipeline({ ...spec, waves: [{ name: "prod", runs: [{ target: "app" }] }] }, { specFile: "waves.json" });
+    expect(files.map((f) => f.name)).toEqual(["plywood-up.yml"]);
+  });
+
+  test("a pull-request wave gets the plans workflow and the status too (2026-10-28 ruling)", () => {
+    const pullRequest: OpWavesSpec = { ...spec, waves: [{ name: "prod", runs: [{ target: "app" }], approval: "pull-request" }], approvals: { pullRequest: { gate: "up" } } };
+    const { files } = generateGithubOpWavesPipeline(pullRequest, { specFile: "waves.json", bin: "npx --no-install plywood" });
+    expect(files.map((f) => f.name)).toEqual(["plywood-up.yml", "plywood-up-plans.yml"]);
+    const plans = files.find((f) => f.name === "plywood-up-plans.yml")!.yaml;
+    expect(plans).toContain("npx --no-install plywood run wave --spec waves.json --record-plans");
+    expect(plans).toContain("--approval-status --pr \"$PR_NUMBER\"");
+    // The waves read no review, so they ask for no pull-requests scope.
+    expect(files[0]!.yaml).not.toContain("pull-requests: read");
+  });
+});

package/src/components/generate-op-waves-pipeline.guard.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The apply-job guard in GitHub op-wave jobs (#4624): the first step of
+ * every wave, deciding and share job, before the trade and the checkout,
+ * carrying the job's forge environment, branches and runner. Written for
+ * the ci-products post-merge pass.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { JOB_GUARD_ENV, jobGuardLine } from "@intentius/chant/ci-job-guard";
+import { buildGithubOpWavesDoc } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "deploy",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  branches: ["main", "release"],
+  runner: ["self-hosted", "linux"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "prod", runs: [{ target: "prod" }], environment: { name: "production" }, idTokens: { CLOUD_TOKEN: "sts.amazonaws.com" } },
+    { name: "wide", runs: [{ target: "a" }, { target: "b" }], shares: 2, environment: { name: "production" } },
+  ],
+};
+
+type Job = { steps: Array<{ name?: string; env?: Record<string, string>; run?: string; uses?: string }> };
+const jobsOf = (s: OpWavesSpec, words?: { product: string }) => buildGithubOpWavesDoc(s, { specFile: "waves.json", ...(words ? { words } : {}) }).doc.jobsDoc as Record<string, Job>;
+const guardOf = (job: Job) => JSON.parse(job.steps[0]!.env![JOB_GUARD_ENV]!) as Record<string, unknown>;
+
+describe("the apply-job guard on GitHub (#4624)", () => {
+  test("every wave job starts with it, before the checkout", () => {
+    const jobs = jobsOf(spec);
+    for (const [name, job] of Object.entries(jobs)) {
+      expect(job.steps[0]!.run, name).toBe(jobGuardLine());
+      expect(job.steps[1]!.uses, name).toMatch(/checkout/);
+    }
+  });
+
+  test("carries the branches, the runner and, where it can read it, the environment", () => {
+    const jobs = jobsOf(spec);
+    expect(guardOf(jobs["wave-1-dev"]!)).toEqual({ forge: "github", job: "wave 1 (dev) of deploy", branches: ["main", "release"], selfHosted: true });
+    // Its id tokens give the job id-token: write, so the guard reads the environment from a token.
+    expect(guardOf(jobs["wave-2-prod"]!)).toMatchObject({ forgeEnvironment: "production" });
+    // A job that may request no token cannot be checked for its environment on GitHub.
+    expect(guardOf(jobs["wave-3-wide-decide"]!)).not.toHaveProperty("forgeEnvironment");
+    expect(guardOf(jobs["wave-3-wide-share-2"]!)).toMatchObject({ job: "share 2 of wave 3 (wide) of deploy" });
+  });
+
+  test("names the product", () => {
+    expect(guardOf(jobsOf(spec, { product: "plywood" })["wave-1-dev"]!)).toMatchObject({ product: "plywood" });
+  });
+
+  test("the default branch when the spec names none", () => {
+    const { branches: _b, ...plain } = spec;
+    expect(guardOf(jobsOf(plain)["wave-1-dev"]!)).toMatchObject({ branches: ["main"] });
+  });
+});

package/src/components/generate-op-waves-pipeline.identity.test.ts

@@ -57,7 +57,7 @@ interface Job {
 }
 
 const jobsOf = (spec: OpWavesSpec): Record<string, Job> => (parseYAML(generateGithubOpWavesPipeline(spec, { specFile: ".chant/op-waves/tf-apply.spec.json", beforeScript: ["npm ci"] }).files[0]!.yaml) as { jobs: Record<string, Job> }).jobs;
-const tradeOf = (job: Job): unknown => JSON.parse(job.steps[0]!.env![TRADE_SPEC_ENV]!);
+const tradeOf = (job: Job): unknown => JSON.parse(job.steps[1]!.env![TRADE_SPEC_ENV]!);
 const UNSET = `unset ${OIDC_REQUEST_VARS.join(" ")}`;
 
 describe("an Op wave's jobs by cloud identity (#4332)", () => {
@@ -70,9 +70,9 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
 
   test("the deciding job trades for every plan identity, before the checkout, and names no apply identity", () => {
     const decide = jobs["wave-1-wave-1-decide"]!;
-    expect(decide.steps[0]!.name).toBe("Trade the job's OIDC token for its cloud identities");
-    expect(decide.steps[0]!.run).toMatch(/^\(cd \/ && node -e '/);
-    expect(decide.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+    expect(decide.steps[1]!.name).toBe("Trade the job's OIDC token for its cloud identities");
+    expect(decide.steps[1]!.run).toMatch(/^\(cd \/ && node -e '/);
+    expect(decide.steps[2]!.uses).toMatch(/^actions\/checkout@/);
     expect(tradeOf(decide)).toEqual(plan);
     expect(decide.permissions).toEqual({ contents: "write", "id-token": "write" });
     for (const id of [role("prod-apply"), role("staging-apply"), role("own-apply")]) expect(JSON.stringify(decide)).not.toContain(id);
@@ -83,14 +83,14 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
     for (const [name, id] of Object.entries(want)) {
       const job = jobs[name]!;
       expect(tradeIdentities(tradeOf(job) as never)).toEqual([id]);
-      expect(job.steps[1]!.uses).toMatch(/^actions\/checkout@/);
+      expect(job.steps[2]!.uses).toMatch(/^actions\/checkout@/);
       for (const other of Object.values(want).filter((o) => o !== id)) expect(JSON.stringify(job)).not.toContain(other);
     }
   });
 
   test("every run step after the trade starts by unsetting the token request variables", () => {
     for (const job of Object.values(jobs)) {
-      const runs = job.steps.slice(1).filter((s) => s.run !== undefined);
+      const runs = job.steps.slice(2).filter((s) => s.run !== undefined);
       expect(runs.length).toBeGreaterThan(0);
       for (const s of runs) expect(s.run!.split("\n")[0]).toBe(UNSET);
     }
@@ -124,8 +124,8 @@ describe("the deciding job, run step by step against the emulator (#4332)", () =
     const githubEnv = join(temp, "github-env");
     writeFileSync(githubEnv, "");
     const base = { PATH: process.env.PATH ?? "/usr/bin:/bin", HOME: process.env.HOME ?? "/tmp", RUNNER_TEMP: temp, ...emu.requestEnv };
-    const spec = emu.pointAt(JSON.parse(decide.steps[0]!.env![TRADE_SPEC_ENV]!));
-    await run("sh", ["-c", decide.steps[0]!.run!.replace("$GITHUB_ENV", githubEnv)], { env: { ...base, [TRADE_SPEC_ENV]: JSON.stringify(spec) } });
+    const spec = emu.pointAt(JSON.parse(decide.steps[1]!.env![TRADE_SPEC_ENV]!));
+    await run("sh", ["-c", decide.steps[1]!.run!.replace("$GITHUB_ENV", githubEnv)], { env: { ...base, [TRADE_SPEC_ENV]: JSON.stringify(spec) } });
     const traded = Object.fromEntries(readFileSync(githubEnv, "utf-8").split("\n").filter(Boolean).map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
     expect(traded.AWS_ACCESS_KEY_ID).toBe(emulatedCredentials(role("own-plan")).accessKeyId);
     const before = emu.log.minted.length;

package/src/components/generate-op-waves-pipeline.ts

@@ -34,6 +34,8 @@
  * `pull-requests: read`, so a wave can read the merged pull request's
  * reviews, and a second workflow, `<name>-plans.yml`, runs `chant run wave
  * --record-plans` on each pull request to record the digests its head plans.
+ * A `pull-request` wave (#4630) gets the plans workflow too, for the approval
+ * status before merge; it asks for no `pull-requests: read` on the waves.
  *
  * With `notify` on the spec (#3761), the workflow maps each variable it names
  * from the repository secret of the same name, so a wave job can post to
@@ -62,6 +64,15 @@
  * step holds the control token: the `tokenSecret` secret, mapped into
  * `CHANT_CONTROL_TOKEN` and handed to curl on its stdin
  * (`controlDispatchScript`, #4568).
+ *
+ * Every wave, deciding and share job starts with the apply-job guard
+ * (#4624, `@intentius/chant/ci-job-guard`), before the trade and the
+ * checkout: it stops the job unless `GITHUB_REF` is one of the spec's
+ * branches, the job runs in its forge environment (read from an OIDC
+ * token's claims, so only in a job that may request one), and, for a
+ * runner whose labels include `self-hosted`, on a self-hosted runner. The
+ * forgejo generator passes `forge: "forgejo"`, which checks the ref and
+ * runner only.
  */
 
 import {
@@ -71,6 +82,8 @@ import {
   opWaveOutcomeDir,
   opWavesControlTarget,
   opWavesLastJobs,
+  opWavesApprovalStatusCommand,
+  opWavesPostsApprovalStatus,
   opWavesOutcomeCommand,
   opWavesRecordPlansCommand,
   opWavesResumeCommand,
@@ -93,6 +106,8 @@ import {
   setupStepDoc,
 } from "@intentius/chant/ci-jobs";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
+import { JOB_GUARD_ENV, jobGuardLine, jobGuardSpec, opWaveJobLabel } from "@intentius/chant/ci-job-guard";
+import { resolveProductWords } from "@intentius/chant/ci-product-words";
 import { checkoutStep, concurrency, DOWNLOAD_ARTIFACT, downloadArtifactStep, keepRecordStep, runSteps } from "./ci-jobs";
 import { emitOpPipelineYAML, type GithubOpPipelineDoc } from "./generate-op-pipeline";
 
@@ -113,10 +128,15 @@ export function opWaveOutcomeArtifact(spec: Pick<OpWavesSpec, "name">, jobName:
 export function buildGithubOpWavesDoc(
   spec: OpWavesSpec,
   options: OpWavesPipelineOptions,
+  dialect: { forge?: "github" | "forgejo" } = {},
 ): { doc: GithubOpPipelineDoc; jobs: OpWavesPipelineResult["jobs"]; resumeDoc?: GithubOpPipelineDoc; plansDoc?: GithubOpPipelineDoc } {
   const jobs = opWaveJobs(spec, options.specFile, { bin: options.bin });
+  const forge = dialect.forge ?? "github";
+  const product = resolveProductWords(options.words ?? {}).product;
   const image = options.image ?? OP_WAVES_IMAGE;
   const byReview = spec.waves.some((w) => w.approval === "pr-review");
+  // #4630: a pr-review or pull-request wave gets the plans workflow and its approval status.
+  const statusBeforeMerge = opWavesPostsApprovalStatus(spec);
   for (const wave of spec.waves) {
     assertSetupSteps(`${spec.name}/${wave.name}`, wave.setup ?? []);
     if (wave.environment) assertEnvironment(`${spec.name}/${wave.name}`, wave.environment);
@@ -134,7 +154,21 @@ export function buildGithubOpWavesDoc(
     const group = opWaveGroupOf(spec, job);
     // #4332: the job's cloud identities, traded before the checkout.
     const cloud = group?.cloud ?? wave.cloud;
-    const steps: Array<Record<string, unknown>> = [...(cloud ? [tradeStep(cloud)] : []), checkoutStep(true)];
+    const environment = group?.environment ?? wave.environment;
+    const idTokens = group?.idTokens ?? wave.idTokens;
+    const idToken = idTokens !== undefined || cloud !== undefined;
+    const runner = group?.runner ?? wave.runner ?? spec.runner;
+    // #4624: the guard first, before the trade and the checkout.
+    const guard = guardStep({
+      forge,
+      job: opWaveJobLabel(spec.name, job),
+      product,
+      ...(environment && forge === "github" ? { environment: environment.name } : {}),
+      branches: pushBranches(spec.branches),
+      ...(runner !== undefined ? { runner } : {}),
+      idToken,
+    });
+    const steps: Array<Record<string, unknown>> = [guard, ...(cloud ? [tradeStep(cloud)] : []), checkoutStep(true)];
     if (job.kind === "share") {
       steps.push(downloadArtifactStep(`Download wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), dirnameOf(job.record!)));
     }
@@ -151,11 +185,8 @@ export function buildGithubOpWavesDoc(
       steps.push(keepRecordStep(`Keep wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), job.record!));
     }
     steps.push(keepRecordStep(`Keep the job's outcome`, opWaveOutcomeArtifact(spec, job.jobName), job.outcome));
-    const environment = group?.environment ?? wave.environment;
-    const idTokens = group?.idTokens ?? wave.idTokens;
-    const idToken = idTokens !== undefined || cloud !== undefined;
     jobsDoc[job.jobName] = {
-      "runs-on": githubRunsOn(group?.runner ?? wave.runner ?? spec.runner),
+      "runs-on": githubRunsOn(runner),
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
       // #4322: a wave's jobs run after a failure in the wave before; a share job runs only on its deciding job's success.
       ...(job.needs.length > 0 && job.kind !== "share" ? { if: "!cancelled()" } : {}),
@@ -188,7 +219,7 @@ export function buildGithubOpWavesDoc(
     doc,
     jobs,
     ...(spec.resume ? { resumeDoc: buildResumeDoc(spec, options) } : {}),
-    ...(byReview ? { plansDoc: buildPlansDoc(spec, options) } : {}),
+    ...(statusBeforeMerge ? { plansDoc: buildPlansDoc(spec, options, forge) } : {}),
   };
 }
 
@@ -256,21 +287,55 @@ function buildResumeDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): Git
   };
 }
 
-/** The pull request workflow a `pr-review` wave needs (#3684): record the digests each head plans. */
-function buildPlansDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): GithubOpPipelineDoc {
+/**
+ * The pull request workflow a `pr-review` wave needs (#3684): record the
+ * digests each head plans. The `approval-status` job after it (#4630) posts
+ * `<product>/approval` on the head, and runs alone on each review submitted
+ * or dismissed. It holds a read token that may write statuses and nothing
+ * else. A `pull-request` wave gets the same workflow: the record keeps its
+ * change set, and the status reads the pull request's own approval of it.
+ */
+function buildPlansDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions, forge: "github" | "forgejo"): GithubOpPipelineDoc {
   const steps: Array<Record<string, unknown>> = [checkoutStep(true), ...(spec.waves[0]?.setup ?? []).map(setupStepDoc), ...runSteps(options.beforeScript ?? [])];
   steps.push({ name: "Plan every wave at the head and record its digests", run: opWavesRecordPlansCommand(options.specFile, options.bin).join(" ") });
+  const statusSteps: Array<Record<string, unknown>> = [checkoutStep(true), ...runSteps(options.beforeScript ?? [])];
+  statusSteps.push({
+    name: "Post the approval status on the head",
+    run: opWavesApprovalStatusCommand(options.specFile, forge, options.bin).join(" "),
+    env: {
+      GITHUB_TOKEN: GITHUB_JOB_TOKEN,
+      PR_NUMBER: "${{ github.event.pull_request.number }}",
+      HEAD_SHA: "${{ github.event.pull_request.head.sha }}",
+      BASE_SHA: "${{ github.event.pull_request.base.sha }}",
+    },
+  });
   return {
     name: `${spec.name}-plans`,
-    on: { pull_request: { branches: pushBranches(spec.branches) } },
+    on: { pull_request: { branches: pushBranches(spec.branches) }, pull_request_review: { types: ["submitted", "dismissed"] } },
     ...nonEmpty("env", options.variables),
-    concurrency: concurrency(spec.name + "-plans-${{ github.event.number }}", true),
+    concurrency: concurrency(spec.name + "-plans-${{ github.event_name }}-${{ github.event.pull_request.number }}", true),
     // contents: write pushes the record to chant/lifecycle.
     permissions: { contents: "write" },
-    jobsDoc: { "record-plans": { "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps } },
+    jobsDoc: {
+      "record-plans": { if: "github.event_name == 'pull_request'", "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps },
+      "approval-status": {
+        needs: ["record-plans"],
+        // On a review the record-plans job is skipped, and the status reads the plans an earlier push recorded.
+        if: "${{ always() && (needs.record-plans.result == 'success' || needs.record-plans.result == 'skipped') }}",
+        "runs-on": githubRunsOn(spec.runner),
+        container: options.image ?? OP_WAVES_IMAGE,
+        permissions: { contents: "read", "pull-requests": "read", statuses: "write" },
+        steps: statusSteps,
+      },
+    },
   };
 }
 
+/** The apply-job guard step (#4624): the job's expectation in CHANT_JOB_GUARD, checked by `node -e` from `/`. */
+function guardStep(input: Parameters<typeof jobGuardSpec>[0]): Record<string, unknown> {
+  return { name: "Check the job runs where the spec set it to run", env: { [JOB_GUARD_ENV]: JSON.stringify(jobGuardSpec(input)) }, run: jobGuardLine() };
+}
+
 /** The step that trades the job's OIDC token for `cloud` (#4332), writing the credentials to GITHUB_ENV. */
 function tradeStep(cloud: CloudTradeSpec): Record<string, unknown> {
   return { name: "Trade the job's OIDC token for its cloud identities", env: { [TRADE_SPEC_ENV]: JSON.stringify(cloud) }, run: tradeLine("$GITHUB_ENV", "github-env") };