@intentius/chant-lexicon-gitlab 0.124.54 → 0.124.56

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

@@ -103,6 +103,15 @@
  * internal and always wins at the job over a same-named spec entry, so a
  * caller cannot point the gate block somewhere the `artifacts:` declaration
  * beside it does not also point.
+ *
+ * `reviewAgent` (#4544) splits the review in two, as on GitHub and Forgejo,
+ * with GitLab's own shape (`./review-jobs.ts`). The review job runs in the
+ * merge request pipeline, unsets every forge token variable and keeps the
+ * review as its artifact. Its note job runs in a pipeline of the default
+ * branch that a schedule starts with `CHANT_REVIEW_NOTES` set to `1`, checks
+ * nothing out and posts each open merge request's review with the protected
+ * `CHANT_FORGE_TOKEN`. The header says to create that schedule and protect
+ * the token.
  */
 
 import {
@@ -114,6 +123,8 @@ import {
   gitlabIdTokens,
   gitlabRules,
   gitlabSetupScript,
+  gitlabTags,
+  assertRunnerLabels,
   nonEmpty,
   pushBranches,
 } from "@intentius/chant/ci-jobs";
@@ -129,6 +140,12 @@ import type {
 } from "@intentius/chant/lexicon";
 
 import { emitGitlabFile } from "./ci-jobs";
+import { assertReviewSplit, GITLAB_REVIEW_NOTES_VAR, gitlabReviewJobs, REVIEW_DIR, reviewNoteJobName } from "./review-jobs";
+import { AGENT_DIR, resolveAgentSpec } from "@intentius/chant/ci-agent";
+import { activeProductWords } from "@intentius/chant/ci-product-words";
+import { gitlabAgentHeader, gitlabAgentJobs, gitlabAgentPushJobName, gitlabDriftArtifacts, gitlabDriftRunLines } from "./agent-jobs";
+import { assertScheduledOpCloud, scheduledOpUpdateJobName } from "@intentius/chant/scheduled-op-cloud";
+import { gitlabTradeIdTokens, gitlabTradeLines, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
 
 export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
 
@@ -202,24 +219,6 @@ function assertTriggerSupportsMode(name: string, mode: OpFindingMode, trigger: O
   );
 }
 
-/**
- * Refuse `reviewAgent` (#4326). The split posts the review from a second job
- * that holds the forge write token, and a GitLab merge request pipeline hands
- * every job the project's unprotected CI/CD variables, the review job's
- * included. A token protected enough to stay out of it is not available to a
- * job of that pipeline either, so the post has to start from a pipeline of
- * the default branch, which this generator does not build. The refusal names
- * the Op and the way out rather than emitting a review job that holds the token.
- */
-function assertNoReviewSplit(spec: ScheduledOpSpec): void {
-  if (!spec.reviewAgent) return;
-  throw new Error(
-    `Scheduled Op "${spec.name}" sets reviewAgent, which keeps the model's job free of the forge write token and posts the note from a second job. ` +
-      `A GitLab merge request pipeline hands every job the project's unprotected variables, so the gitlab generator does not build that split. ` +
-      `Drop reviewAgent and run the review with findingMode "comment" (the model command still runs with a cleared environment), or generate this Op for GitHub or Forgejo.`,
-  );
-}
-
 /**
  * The follow-up line an Op with an `environment` adds under its own header
  * line (#2257). The `environment:` key on the job binds it to the
@@ -303,20 +302,70 @@ export function generateGitlabOpPipeline(
 
   const opLines: string[] = [];
   let anyCron = false;
+  let anyReview = false;
+  // The note job of each split review (#4544), emitted after the Op jobs.
+  const noteJobs: string[] = [];
+  const words = activeProductWords();
 
   for (const spec of ops) {
     const subject = `Scheduled Op "${spec.name}"`;
+    // #4631: the job's cloud identities and the update on drift, checked before anything renders.
+    assertScheduledOpCloud(spec);
+    if (spec.update?.permissions && Object.keys(spec.update.permissions).length > 0) {
+      throw new Error(`${subject}: update.permissions has no GitLab form; a GitLab job's token scopes are the project's (contents: write included: whether a job token may push is a project setting), and its cloud identity is update.cloud.`);
+    }
+    // #4616: GitLab picks a runner by tags.
+    assertRunnerLabels(subject, "runner", spec.runner, "GitLab");
+    const tags = gitlabTags(spec.runner);
     const setupScript = gitlabSetupScript(subject, spec.setup);
-    const idTokens = gitlabIdTokens(spec.name, spec.permissions);
+    // #4616: the comment agent is its own pair of jobs, in a pipeline of the default branch; the spec's trigger is not read.
+    if (spec.agent?.on === "comment") {
+      const settings = resolveAgentSpec(spec.name, spec.agent, words.product);
+      const jobName = jobPrefix + ciJobName(spec.name);
+      jobs.push({ jobName, op: spec.name, trigger: { kind: "pull_request" }, findingMode: "report" });
+      opLines.push(...gitlabAgentHeader(jobName, settings, spec.agent.tokenEnv));
+      const { agent, push } = gitlabAgentJobs({
+        jobName,
+        stage,
+        image,
+        settings,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        script: [...setupScript, ...beforeScript],
+        ...(spec.agent.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+      });
+      doc[jobName] = agent;
+      const pushName = gitlabAgentPushJobName(jobName);
+      doc[pushName] = push;
+      noteJobs.push(pushName);
+      continue;
+    }
+    const declaredIdTokens = gitlabIdTokens(spec.name, spec.permissions);
+    // #4631: a cloud trade takes an id token per cloud, beside the ones the spec declares.
+    const idTokens = spec.cloud ? { ...(declaredIdTokens ?? {}), ...gitlabTradeIdTokens(spec.cloud) } : declaredIdTokens;
+    const update = spec.update;
     const findingMode = spec.findingMode ?? "report";
     const trigger = resolveOpTrigger(spec);
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
-    assertNoReviewSplit(spec);
+    // A split review (#4544): the merge request pipeline runs the model with no forge token, and a pipeline of the default branch posts.
+    const split = spec.reviewAgent === true;
+    if (split) assertReviewSplit(spec.name, trigger, findingMode, spec.permissions);
     if (trigger.kind === "cron") anyCron = true;
+    const driftAgent = spec.agent?.on === "drift" ? resolveAgentSpec(spec.name, spec.agent, words.product) : undefined;
+    if (driftAgent && (split || trigger.kind === "push")) {
+      throw new Error(`${subject} sets a drift agent, which follows a drift check's run; give it a cron or pull_request trigger and no reviewAgent.`);
+    }
 
     const jobName = jobPrefix + ciJobName(spec.name);
     jobs.push({ jobName, op: spec.name, trigger, findingMode });
     opLines.push(headerLineFor(spec, trigger, jobName, findingMode));
+    if (split) {
+      anyReview = true;
+      opLines.push(
+        `#     reviewAgent: the review job holds no forge token and keeps its review as an artifact; ${reviewNoteJobName(jobName)} posts it` +
+          ` from a pipeline of the default branch started with ${GITLAB_REVIEW_NOTES_VAR}="1"`,
+      );
+    }
     if (spec.environment) {
       assertGitlabEnvironment(spec.name, spec.environment);
       opLines.push(environmentLine(spec.environment));
@@ -337,28 +386,102 @@ export function generateGitlabOpPipeline(
     // than a caller being able to repoint the gate block's own artifact path.
     const jobVariables: Record<string, string> = {
       ...(spec.variables ?? {}),
+      ...(spec.cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(spec.cloud) } : {}),
       ...(gated ? { [GATE_SUMMARY_VAR]: gateSummary } : {}),
     };
 
+    const rulesFor = changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules;
+    if (split) {
+      const { review, note } = gitlabReviewJobs({
+        name: spec.name,
+        jobName,
+        stage,
+        image,
+        rules: rulesFor,
+        script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
+        ...(spec.variables ? { variables: spec.variables } : {}),
+        ...(idTokens ? { idTokens } : {}),
+        artifactDir: member ? memberRepoPath(member, REVIEW_DIR) : REVIEW_DIR,
+        ...(trigger.kind === "pull_request" && trigger.branches?.length ? { branches: trigger.branches } : {}),
+      });
+      doc[jobName] = { ...review, ...(tags ? { tags } : {}), ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) };
+      const noteName = reviewNoteJobName(jobName);
+      doc[noteName] = { ...note, ...(tags ? { tags } : {}) };
+      noteJobs.push(noteName);
+      continue;
+    }
+
+    // #4631: an update follows a drift check the same way the drift agent does, on the dotenv the run leaves.
+    const flagsDrift = driftAgent !== undefined || update !== undefined;
+    const runLines = flagsDrift ? gitlabDriftRunLines(invocation.join(" ")) : [invocation.join(" ")];
+    const driftDir = member ? memberRepoPath(member, AGENT_DIR) : AGENT_DIR;
     doc[jobName] = {
       stage,
       image,
+      ...(tags ? { tags } : {}),
       // GitLab's stand-in for github's per-Op concurrency group: queue the
       // next run rather than cancel the current one.
       resource_group: jobName,
       ...(idTokens ? { id_tokens: idTokens } : {}),
       ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
       ...nonEmpty("variables", jobVariables),
-      rules: changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules,
-      script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
+      rules: rulesFor,
+      // #4631: the trade first, before any line of the checkout's code runs, and the token variables unset by it.
+      script: [...(spec.cloud ? gitlabTradeLines() : []), ...cdLine, ...setupScript, ...beforeScript, ...runLines, ...extraScript],
       // `when: always` because the run this publishes for is the green one: a
       // gated apply succeeds, and the block is the only thing that says a
       // human still has to act. A run that walked through its gate writes no
       // block, and GitLab reports the empty upload as a warning, not a failure.
       ...(gated
         ? { artifacts: { when: "always", paths: [member ? memberRepoPath(member, gateSummary) : gateSummary], expire_in: GATE_ARTIFACT_EXPIRY } }
-        : {}),
+        : flagsDrift
+          ? { artifacts: gitlabDriftArtifacts(driftDir) }
+          : {}),
     };
+    if (update) {
+      // #4631: the update's own job, which alone holds the update's identity, after a run that found drift.
+      const name = scheduledOpUpdateJobName(jobName);
+      opLines.push(`#     update: ${name} runs \`${update.command}\` when ${jobName} exits with chant's drift code${update.cloud ? ", holding its own cloud identity" : ""}`);
+      doc[name] = {
+        stage,
+        image,
+        ...(tags ? { tags } : {}),
+        needs: [{ job: jobName, artifacts: true }],
+        ...(update.cloud ? { id_tokens: gitlabTradeIdTokens(update.cloud) } : {}),
+        ...(update.environment ? { environment: environmentDoc(update.environment) } : {}),
+        ...nonEmpty("variables", { ...(update.variables ?? {}), ...(update.cloud ? { [TRADE_SPEC_ENV]: JSON.stringify(update.cloud) } : {}) }),
+        rules: rulesFor.map((r) => ({ ...(r as Record<string, unknown>), when: "always" })),
+        script: [
+          `if [ "\${CHANT_AGENT_DRIFT:-0}" != "1" ]; then echo "no drift, so the update does not run"; exit 0; fi`,
+          ...(update.cloud ? gitlabTradeLines() : []),
+          ...cdLine,
+          ...setupScript,
+          ...beforeScript,
+          update.command,
+        ],
+      };
+      noteJobs.push(name);
+    }
+    if (driftAgent) {
+      const name = `${jobName}-agent`;
+      opLines.push(...gitlabAgentHeader(name, driftAgent, spec.agent?.tokenEnv));
+      const { agent, push } = gitlabAgentJobs({
+        jobName: name,
+        stage,
+        image,
+        settings: driftAgent,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        script: [...setupScript, ...beforeScript],
+        ...(spec.agent?.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+        after: { job: jobName, rules: rulesFor },
+        // #4619: a member's drift Op left the drift under the member's directory.
+        ...(member ? { dir: memberRepoPath(member, AGENT_DIR) } : {}),
+      });
+      doc[name] = agent;
+      doc[gitlabAgentPushJobName(name)] = push;
+      noteJobs.push(name, gitlabAgentPushJobName(name));
+    }
   }
 
   const headerLines = [
@@ -375,10 +498,20 @@ export function generateGitlabOpPipeline(
       "# that job runs on that schedule.",
     );
   }
+  if (anyReview) {
+    headerLines.push(
+      "#",
+      "# A reviewAgent Op's note job posts from a pipeline of the default branch,",
+      `# never from the merge request's own. Create a Pipeline Schedule on the`,
+      `# default branch with ${GITLAB_REVIEW_NOTES_VAR}="1", and make CHANT_FORGE_TOKEN`,
+      "# (a token with the api scope) a protected, masked CI/CD variable so no",
+      "# merge request pipeline gets it.",
+    );
+  }
   headerLines.push("#", ...opLines);
 
   const yaml = emitGitlabFile(
-    [["stages", doc.stages], ...(doc.variables ? [["variables", doc.variables] as const] : []), ...jobs.map(({ jobName }) => [jobName, doc[jobName]] as const)],
+    [["stages", doc.stages], ...(doc.variables ? [["variables", doc.variables] as const] : []), ...jobs.map(({ jobName }) => [jobName, doc[jobName]] as const), ...noteJobs.map((name) => [name, doc[name]] as const)],
     headerLines,
   );
 

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

@@ -0,0 +1,28 @@
+/** #4630: GitLab approvals start no pipeline, so a schedule posts every open merge request's approval status. */
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGitlabOpWavesPipeline } 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 on GitLab (#4630)", () => {
+  test("runs in a schedule that sets CHANT_APPROVAL_STATUS, with --open", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json" }).files[0]!.yaml;
+    expect(yaml).toContain("plywood-up-approval-status:");
+    expect(yaml).toContain('$CI_PIPELINE_SOURCE == "schedule" && $CHANT_APPROVAL_STATUS == "1"');
+    expect(yaml).toContain("chant run wave --spec waves.json --approval-status --open --forge gitlab");
+  });
+
+  test("a pull-request wave records its plans and posts 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 yaml = generateGitlabOpWavesPipeline(pullRequest, { specFile: "waves.json" }).files[0]!.yaml;
+    expect(yaml).toContain("plywood-up-record-plans:");
+    expect(yaml).toContain("plywood-up-approval-status:");
+    expect(yaml).toContain("chant run wave --spec waves.json --approval-status --open --forge gitlab");
+  });
+});

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

@@ -0,0 +1,55 @@
+/**
+ * An Op waves spec's `control` on GitLab (#4617): a control stage after the
+ * waves, the outcome added up without the token, and every other job
+ * dropping the control repo's token variables. Written for the ci-products
+ * session; run at epic-ready.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { generateGitlabOpWavesPipeline } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "stacks",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  waves: [
+    { name: "canary", runs: [{ target: "dev" }], gate: "never" },
+    { name: "rest", runs: [{ target: "a" }] },
+  ],
+  resume: { schedule: "*/10 * * * *" },
+  control: { repo: "gitlab.com/acme/control", op: "deploy", member: "network", tokenSecret: "PLYWOOD_CONTROL_TOKEN" },
+};
+
+const options = { specFile: "waves.json", bin: "npx --no-install plywood", words: { product: "plywood" } };
+
+describe("the control dispatch after the last wave on GitLab (#4617)", () => {
+  test("a control stage after the waves, needing the last wave's job", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toMatch(/stages:\n\s+- wave-1-canary\n\s+- wave-2-rest\n\s+- control\n\s+- resume/);
+    expect(yaml).toMatch(/control-dispatch:\n\s+stage: control[\s\S]*needs:\n\s+- wave-2-rest\n/);
+  });
+
+  test("adds up the outcome in a subshell without the token, then sends it with the commit", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toContain("unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN\n      { :\n      } 1>&2\n      npx --no-install plywood run wave --spec waves.json --waves-outcome");
+    expect(yaml).toContain('export CHANT_CONTROL_OUTCOME="$outcome"');
+    expect(yaml).toContain('export CHANT_CONTROL_SHA="$CI_COMMIT_SHA"');
+    expect(yaml).toContain('CHANT_CONTROL_TOKEN="${PLYWOOD_CONTROL_TOKEN:-}"');
+    expect(yaml).toContain("--form 'token=<-'");
+    expect(yaml).toContain('--form "variables[CHANT_CONTROL_OUTCOME]=$outcome"');
+  });
+
+  test("every wave job and the resume job drop the control repo's token variables first", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toMatch(/wave-1-canary:[\s\S]*script:\n\s+- [^\n]*node -e[^\n]*\n\s+- unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN\n\s+- npx --no-install plywood run wave --spec waves.json --wave 1/);
+    expect(yaml).toMatch(/stacks-resume:[\s\S]*script:\n\s+- unset CHANT_CONTROL_TOKEN CHANT_CONTROL_READ_TOKEN PLYWOOD_CONTROL_TOKEN/);
+  });
+
+  test("no control, no stage, no unset", () => {
+    const { control: _drop, ...plain } = spec;
+    const yaml = generateGitlabOpWavesPipeline(plain, options).files[0]!.yaml;
+    expect(yaml).not.toContain("control-dispatch");
+    expect(yaml).not.toContain("unset CHANT_CONTROL_TOKEN");
+  });
+});

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

@@ -0,0 +1,63 @@
+/**
+ * The apply-job guard in GitLab op-wave jobs (#4624): the script's first
+ * line, before the trade, with the job's expectation in a variable: the
+ * environment, the branches and the runner's tags. Written for the
+ * ci-products post-merge pass.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { OpWavesSpec } from "@intentius/chant/op/op-waves";
+import { spawnSync } from "node:child_process";
+import { JOB_GUARD_ENV, JOB_GUARD_JS } from "@intentius/chant/ci-job-guard";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+import { generateGitlabOpWavesPipeline, OP_WAVE_ALLOWED_EXIT } from "./generate-op-waves-pipeline";
+
+const spec: OpWavesSpec = {
+  name: "deploy",
+  op: "pulumi-up",
+  plan: ["./bin/plan", "{target}", "{plan}"],
+  branches: ["main"],
+  runner: ["deploy"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "prod", runs: [{ target: "prod" }], environment: { name: "production" } },
+  ],
+};
+
+describe("the apply-job guard on GitLab (#4624)", () => {
+  test("the first script line of every wave job", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json", words: { product: "plywood" } }).files[0]!.yaml;
+    for (const job of ["wave-1-dev", "wave-2-prod"]) {
+      const body = yaml.slice(yaml.indexOf(`${job}:`));
+      const script = body.slice(body.indexOf("script:"));
+      expect(script.split("\n")[1]).toContain(JOB_GUARD_JS.slice(0, 40));
+    }
+  });
+
+  test("the variable names the environment, the branches, the tags and the product", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json", words: { product: "plywood" } }).files[0]!.yaml;
+    const prod = yaml.slice(yaml.indexOf("wave-2-prod:"));
+    expect(prod).toContain(JOB_GUARD_ENV);
+    for (const part of ['"forge":"gitlab"', '"forgeEnvironment":"production"', '"branches":["main"]', '"runnerTags":["deploy"]', '"product":"plywood"', '"job":"wave 2 (prod) of deploy"']) {
+      expect(prod).toContain(part);
+    }
+  });
+
+  test("a refused guard fails the job and stops the wave (#4624 ruling: fail hard)", () => {
+    const yaml = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json", words: { product: "plywood" } }).files[0]!.yaml;
+    const prod = yaml.slice(yaml.indexOf("wave-2-prod:"));
+    expect(prod).toContain(`exit_codes:\n      - ${OP_WAVE_ALLOWED_EXIT}`);
+    const guard = { forge: "gitlab", job: "wave 2 (prod) of deploy", forgeEnvironment: "production", branches: ["main"], runnerTags: ["deploy"] };
+    const r = spawnSync(process.execPath, ["-e", JOB_GUARD_JS], {
+      env: { PATH: process.env.PATH ?? "", [JOB_GUARD_ENV]: JSON.stringify(guard), CI_ENVIRONMENT_NAME: "dev", CI_COMMIT_REF_NAME: "main", CI_COMMIT_REF_PROTECTED: "true", CI_RUNNER_TAGS: "deploy" },
+      encoding: "utf-8",
+    });
+    expect(r.status).toBe(CHANT_EXIT.misplaced);
+    expect(r.status).not.toBe(OP_WAVE_ALLOWED_EXIT);
+  });
+
+  test("a guard with no spec to read fails the job too", () => {
+    const r = spawnSync(process.execPath, ["-e", JOB_GUARD_JS], { env: { PATH: process.env.PATH ?? "" }, encoding: "utf-8" });
+    expect(r.status).toBe(CHANT_EXIT.misplaced);
+  });
+});

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

@@ -97,7 +97,7 @@ describe("a runner per wave and job groups per wave (#3914)", () => {
     expect(yaml).toMatch(/wave-1-dev:\n\s+stage: wave-1-dev\n\s+image: node:22\n\s+tags:\n\s+- docker\n\s+- dev\n/);
     expect(yaml).toMatch(/wave-2-prod-decide:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- plan\n\s+resource_group: migrations-prod\n\s+id_tokens:\n\s+PLAN_TOKEN:\n\s+aud: plan.example\n/);
     expect(yaml).toMatch(
-      /wave-2-prod-us:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- us-apply\n\s+resource_group: migrations-prod\n\s+environment:\n\s+name: prod-us\n\s+id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: us.example\n\s+variables:\n\s+GIT_DEPTH: '0'\n\s+REGION: us\n[\s\S]*?needs:\n\s+- wave-2-prod-decide\n\s+script:\n\s+- echo us\n\s+- chant run wave --spec waves.json --wave 2 --group us\n/,
+      /wave-2-prod-us:\n\s+stage: wave-2-prod\n\s+image: node:22\n\s+tags:\n\s+- us-apply\n\s+resource_group: migrations-prod\n\s+environment:\n\s+name: prod-us\n\s+id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: us.example\n\s+variables:\n\s+GIT_DEPTH: '0'\n\s+REGION: us\n\s+CHANT_JOB_GUARD: [^\n]*\n[\s\S]*?needs:\n\s+- wave-2-prod-decide\n\s+script:\n\s+- [^\n]*node -e[^\n]*\n\s+- echo us\n\s+- chant run wave --spec waves.json --wave 2 --group us\n/,
     );
     expect(yaml).toMatch(/wave-2-prod-eu:[\s\S]*?id_tokens:\n\s+CLOUD_TOKEN:\n\s+aud: eu.example\n/);
     expect(yaml).not.toContain("_AUDIENCE");
@@ -122,11 +122,30 @@ describe("an Op wave's jobs by cloud identity (#4332)", () => {
     for (const [name, ids] of Object.entries(want)) {
       const job = doc[name]!;
       expect(job.id_tokens).toEqual({ OTHER_TOKEN: { aud: "other.example" }, CHANT_ID_TOKEN_AWS: { aud: "sts.amazonaws.com" } });
-      expect(job.script.slice(0, 3)).toEqual(gitlabTradeLines());
-      expect(job.script[3]).toBe("npm ci");
+      // #4624: the apply-job guard first, then the trade.
+      expect(job.script[0]).toMatch(/^\(cd \/ && node -e '/);
+      expect(job.script.slice(1, 4)).toEqual(gitlabTradeLines());
+      expect(job.script[4]).toBe("npm ci");
       expect(tradeIdentities(JSON.parse(job.variables[TRADE_SPEC_ENV]!))).toEqual(ids);
     }
     expect(JSON.stringify(doc["wave-1-prod-decide"])).not.toContain("apply\"");
     expect(JSON.stringify(doc["wave-1-prod-default"])).not.toContain("prod-apply");
   });
+
+  test("words.bin is the command in every job line: the waves, resume and the plans job (#4607)", () => {
+    const bin = "npx --no-install plywood";
+    const withBin = { ...spec, resume: { schedule: "*/10 * * * *" }, waves: spec.waves.map((w, i) => (i === spec.waves.length - 1 ? { ...w, approval: "pr-review" as const } : w)) };
+    const { files, jobs } = generateGitlabOpWavesPipeline(withBin, { specFile: "waves.json", bin });
+    expect(jobs.every((j) => j.command.slice(0, 3).join(" ") === bin)).toBe(true);
+    const yaml = files.map((f) => f.yaml).join("\n");
+    expect(yaml).toContain("- npx --no-install plywood run wave --spec waves.json --wave 1");
+    expect(yaml).toContain("npx --no-install plywood run resume --op migrations");
+    expect(yaml).toContain("npx --no-install plywood run wave --spec waves.json --record-plans");
+    expect(yaml).not.toMatch(/(^|\s)chant run (wave|resume)/m);
+  });
+
+  test("no bin keeps chant (#4607)", () => {
+    const { jobs } = generateGitlabOpWavesPipeline(spec, { specFile: "waves.json" });
+    expect(jobs.every((j) => j.command[0] === "chant")).toBe(true);
+  });
 });