@intentius/chant-lexicon-github 0.124.54 → 0.124.55

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

@@ -0,0 +1,147 @@
+/**
+ * The agent jobs (#4616): `ScheduledOpSpec.agent` and `runner`. The model's
+ * job holds a read token and the model's key; only the push job writes.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import { FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+import { generateGithubOpPipeline } from "./generate-op-pipeline";
+
+interface Step {
+  id?: string;
+  name?: string;
+  run?: string;
+  env?: Record<string, string>;
+}
+interface Job {
+  needs?: string;
+  if?: string;
+  "runs-on"?: unknown;
+  "timeout-minutes"?: number;
+  permissions?: Record<string, string>;
+  env?: Record<string, string>;
+  outputs?: Record<string, string>;
+  steps: Step[];
+}
+interface Doc {
+  on: Record<string, unknown>;
+  permissions?: Record<string, string>;
+  jobs: Record<string, Job>;
+}
+
+const gen = (spec: ScheduledOpSpec) => {
+  const out = generateGithubOpPipeline([spec]);
+  return { doc: parseYAML(out.files[0]!.yaml) as unknown as Doc, name: out.files[0]!.name, jobs: out.jobs };
+};
+
+const COMMENT: ScheduledOpSpec = { name: "chant-agent", agent: { on: "comment", comment: "/chant agent", maxRuns: 3, timeout: 20 } };
+
+describe("the comment agent", () => {
+  const { doc, name } = gen(COMMENT);
+  const agent = doc.jobs["chant-agent"]!;
+  const push = doc.jobs["chant-agent-push"]!;
+
+  test("is a workflow of its own on pull request comments from a writer", () => {
+    expect(name).toBe("chant-agent.yml");
+    expect(doc.on).toEqual({ issue_comment: { types: ["created"] } });
+    expect(agent.if).toContain("startsWith(github.event.comment.body, '/chant agent ')");
+    expect(agent.if).toContain("author_association");
+  });
+
+  test("the agent job reads, stops at its timeout, and runs the model with its key and no forge token", () => {
+    expect(agent.permissions).toEqual({ contents: "read", "pull-requests": "read" });
+    expect(agent["timeout-minutes"]).toBe(35);
+    expect(agent.env).toMatchObject({ CHANT_AGENT_NAME: "chant-agent", CHANT_AGENT_ON: "comment", CHANT_AGENT_MAX_RUNS: "3", CHANT_AGENT_TIMEOUT: "20" });
+    const run = agent.steps.at(-1)!;
+    expect(run.id).toBe("chant-agent");
+    expect(run.env).toEqual({ ANTHROPIC_API_KEY: "${{ secrets.ANTHROPIC_API_KEY }}" });
+    expect(run.run).toContain("chant agent run --forge github");
+    expect(run.run).toContain("trap chant_handover EXIT");
+    expect(Object.keys(run.env ?? {}).filter((n) => (FORGE_TOKEN_VARS as readonly string[]).includes(n))).toEqual([]);
+    expect(agent.steps[0]!.run).toContain("refs/pull/$PR_NUMBER/head:refs/chant/agent-head");
+    expect(agent.steps.some((s) => s.run?.includes("chant agent prepare"))).toBe(true);
+  });
+
+  test("the push job holds the write token, takes the change as data and lands it", () => {
+    expect(push.needs).toBe("chant-agent");
+    expect(push.permissions).toEqual({ contents: "write", "pull-requests": "write", issues: "write" });
+    const land = push.steps.at(-1)!;
+    expect(land.run).toContain("chant agent land --forge github");
+    expect(land.env?.CHANT_AGENT_TOKEN).toBe("${{ github.token }}");
+    expect(push.steps.some((s) => s.run?.includes("needs.chant-agent.outputs.report_0"))).toBe(true);
+  });
+
+  test("a push token secret replaces the job token, and the runner names where both jobs run", () => {
+    const { doc: d } = gen({ ...COMMENT, runner: ["self-hosted", "agents"], agent: { ...COMMENT.agent!, tokenEnv: "AGENT_PUSH_TOKEN" } });
+    expect(d.jobs["chant-agent"]!["runs-on"]).toEqual(["self-hosted", "agents"]);
+    expect(d.jobs["chant-agent-push"]!["runs-on"]).toEqual(["self-hosted", "agents"]);
+    expect(d.jobs["chant-agent-push"]!.steps.at(-1)!.env?.CHANT_AGENT_TOKEN).toBe("${{ secrets.AGENT_PUSH_TOKEN || github.token }}");
+  });
+
+  test("refuses settings no job could run", () => {
+    expect(() => gen({ name: "a", agent: { on: "comment" } })).toThrow(/comment/);
+  });
+});
+
+describe("the drift agent", () => {
+  const DRIFT: ScheduledOpSpec = { name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue", agent: { on: "drift", maxRuns: 1 } };
+  const { doc } = gen(DRIFT);
+  const op = doc.jobs["drift-app"]!;
+  const agent = doc.jobs["drift-app-agent"]!;
+  const push = doc.jobs["drift-app-agent-push"]!;
+
+  test("the Op's job keeps its output and says when it found drift", () => {
+    const run = op.steps.find((s) => s.id === "chant-run")!;
+    expect(run.run).toContain('if [ "$code" -eq 2 ]; then echo "drift=true"');
+    expect(run.run).toContain("tee .chant/agent/drift.txt");
+    expect(op.outputs?.drift).toBe("${{ steps.chant-run.outputs.drift }}");
+  });
+
+  test("the agent job follows it on drift and takes its output", () => {
+    expect(agent.needs).toBe("drift-app");
+    expect(agent.if).toBe("always() && needs.drift-app.outputs.drift == 'true'");
+    expect(agent.steps.some((s) => s.run?.includes("needs.drift-app.outputs.report_0"))).toBe(true);
+    expect(agent.env?.CHANT_AGENT_BRANCH).toBe("chant/agent/drift-app");
+  });
+
+  test("the push job opens or updates the agent's pull request", () => {
+    expect(push.needs).toBe("drift-app-agent");
+    expect(push.steps.at(-1)!.name).toBe("Open or update the agent's pull request");
+  });
+
+  test("refuses a drift agent on a push trigger", () => {
+    expect(() => gen({ ...DRIFT, trigger: { kind: "push" } })).toThrow(/drift agent/);
+  });
+});
+
+describe("the runner field", () => {
+  test("names the Op job's runner, a group included", () => {
+    const { doc } = gen({ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, runner: { group: "infra", labels: ["linux"] } });
+    expect(doc.jobs["drift-app"]!["runs-on"]).toEqual({ group: "infra", labels: ["linux"] });
+    expect(gen({ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" } }).doc.jobs["drift-app"]!["runs-on"]).toBe("ubuntu-latest");
+  });
+});
+
+// #4619: a member's drift Op runs in the member's directory and hands its output on; the agent job takes it at the root.
+describe("the drift agent of a workspace member", () => {
+  const out = generateGithubOpPipeline([{ name: "drift-app", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue", agent: { on: "drift", maxCostUsd: 2.5 } }], { member: { name: "app", dir: "stacks/app" } });
+  const doc = parseYAML(out.files[0]!.yaml) as unknown as Doc & { jobs: Record<string, Job & { defaults?: { run?: { "working-directory"?: string } } }> };
+  const op = doc.jobs["drift-app"]!;
+  const agent = doc.jobs["drift-app-agent"]!;
+
+  test("the drift check runs in the member's directory and hands on the member's own output", () => {
+    expect(op.defaults?.run?.["working-directory"]).toBe("stacks/app");
+    expect(op.steps.find((s) => s.id === "chant-run")!.run).toContain("tee .chant/agent/drift.txt");
+  });
+
+  test("the agent job runs at the root and takes that output into its agent directory", () => {
+    expect(agent.defaults).toBeUndefined();
+    const take = agent.steps.find((s) => s.name === "Take the drift from the drift check")!;
+    expect(take.run).toContain("needs.drift-app.outputs.report_0");
+    expect(take.run).toContain(" .chant/agent <<");
+    expect(agent.steps.some((s) => s.run?.includes("chant agent prepare --forge github --output .chant/agent"))).toBe(true);
+    expect(agent.env?.CHANT_AGENT_MAX_COST_USD).toBe("2.5");
+  });
+});

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

@@ -87,7 +87,8 @@ async function fakeForge(routes: Record<string, (body?: Record<string, unknown>)
 }
 
 async function runNotice(env: Record<string, string>): Promise<string> {
-  const { stdout } = await run(process.execPath, ["--import", "tsx", "notice.mjs"], {
+  // chant here is the source tree, with no dist/: the development condition picks src/*.ts over the import condition's dist/*.js (#4591).
+  const { stdout } = await run(process.execPath, ["--conditions=development", "--import", "tsx", "notice.mjs"], {
     cwd: jobDir(),
     env: {
       PATH: process.env.PATH ?? "",

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

@@ -79,7 +79,7 @@ import {
   environmentDoc,
   fillCommand,
   GITHUB_JOB_TOKEN,
-  GITHUB_RUNNER,
+  githubRunsOn,
   mergePermissions,
   nonEmpty,
   permissionsFor,
@@ -97,6 +97,9 @@ import type {
 } from "@intentius/chant/lexicon";
 import { checkoutStep, concurrency, emitWorkflowYAML, jobTokenEnv, onTrigger, opConcurrencyGroup, runSteps } from "./ci-jobs";
 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";
 
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 
@@ -162,6 +165,13 @@ export interface GithubOpPipelineDoc {
    * dialect transforms this job on its own terms.
    */
   reviewNoteDoc?: Record<string, unknown>;
+  /**
+   * The agent jobs (#4616), when the spec sets `agent`: the agent job and
+   * the push job. Kept out of {@link jobsDoc} so a member's
+   * `working-directory` default stays on the Op's own job: these check out
+   * at the repository root.
+   */
+  agentDoc?: Record<string, unknown>;
 }
 
 /** One generated file: a suggested name plus its pipeline document, pre-emission. */
@@ -361,12 +371,12 @@ function gateNoticeScript(version: string): string {
  * no branch and merges nothing. The Forgejo dialect drops them, as it drops
  * every scope but `id-token`.
  */
-function gateNoticeJob(applyJobName: string, image: string): Record<string, unknown> {
+function gateNoticeJob(applyJobName: string, image: string, runner?: ScheduledOpSpec["runner"]): Record<string, unknown> {
   const output = (name: string) => "${{ needs." + applyJobName + ".outputs." + name + ' }}';
   return {
     needs: applyJobName,
     if: `needs.${applyJobName}.outputs.gated == 'true'`,
-    "runs-on": GITHUB_RUNNER,
+    "runs-on": githubRunsOn(runner),
     container: image,
     permissions: { contents: "read", issues: "write", "pull-requests": "write" },
     steps: [
@@ -415,6 +425,7 @@ function assertTriggerSupportsMode(name: string, mode: OpFindingMode, trigger: O
 export function buildGithubOpPipelineDocs(
   ops: ScheduledOpSpec[],
   options: GenerateGithubOpOptions = {},
+  forge: "github" | "forgejo" = "github",
 ): { files: GithubOpPipelineFile[]; jobs: OpPipelineJob[] } {
   const image = options.image ?? CI_IMAGE;
   const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
@@ -424,7 +435,41 @@ export function buildGithubOpPipelineDocs(
   const files: GithubOpPipelineFile[] = [];
   const jobs: OpPipelineJob[] = [];
 
+  const words = activeProductWords();
   for (const spec of ops) {
+    // #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);
+      const jobName = ciJobName(spec.name);
+      const setup = spec.setup ?? [];
+      assertSetupSteps(spec.name, setup);
+      jobs.push({ jobName, op: spec.name, trigger: { kind: "pull_request" }, findingMode: "report" });
+      const { agent, push } = githubAgentJobs({
+        forge,
+        jobName,
+        image,
+        settings,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        setup: setup.map(setupStepDoc),
+        beforeScript,
+        ...(spec.agent.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+      });
+      files.push({
+        name: `${spec.name}.yml`,
+        doc: {
+          name: spec.name,
+          on: { issue_comment: { types: ["created"] } },
+          ...nonEmpty("env", options.variables),
+          // One agent run at a time, so two asks never count the limit at once.
+          concurrency: concurrency(jobName),
+          permissions: { contents: "read" },
+          jobsDoc: {},
+          agentDoc: { [jobName]: agent, [agentPushJobName(jobName)]: push },
+        },
+      });
+      continue;
+    }
     const findingMode = spec.findingMode ?? "report";
     const trigger = resolveOpTrigger(spec);
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
@@ -438,6 +483,11 @@ export function buildGithubOpPipelineDocs(
     // A split review (#4326) runs the change's code beside a model: no step of that job holds a forge token.
     const split = spec.reviewAgent === true;
     if (split) assertReviewSplit(spec.name, trigger, findingMode, spec.permissions);
+    // #4616: a drift agent follows the Op's job, which hands its output on and says whether it found drift.
+    const driftAgent = spec.agent?.on === "drift" ? resolveAgentSpec(spec.name, spec.agent, words.product) : undefined;
+    if (driftAgent && (split || trigger.kind === "push")) {
+      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 setup = spec.setup ?? [];
@@ -457,7 +507,9 @@ export function buildGithubOpPipelineDocs(
     steps.push(
       gated
         ? gatedRunStep(RUN_STEP_ID, spec.name, invocation, stepEnv)
-        : { run: invocation, env: stepEnv },
+        : driftAgent
+          ? driftRunStep(invocation, stepEnv, forge)
+          : { run: invocation, env: stepEnv },
     );
     steps.push(...runSteps(extraScript));
 
@@ -490,7 +542,7 @@ export function buildGithubOpPipelineDocs(
       ),
       jobsDoc: {
         [jobName]: {
-          "runs-on": GITHUB_RUNNER,
+          "runs-on": githubRunsOn(spec.runner),
           container: image,
           // Per-Op credentials (#2290): job-level `env:`, one level more
           // specific than `options.variables`'s workflow-level `env:` above,
@@ -511,16 +563,35 @@ export function buildGithubOpPipelineDocs(
                   ]),
                 ),
               }
-            : {}),
+            : driftAgent
+              ? { outputs: driftRunOutputs(forge) }
+              : {}),
           steps,
         },
       },
-      ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image) } } : {}),
+      ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image, spec.runner) } } : {}),
     };
+    if (driftAgent) {
+      const name = agentJobName(jobName, "drift");
+      const { agent, push } = githubAgentJobs({
+        forge,
+        jobName: name,
+        image,
+        settings: driftAgent,
+        ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+        setup: setup.map(setupStepDoc),
+        beforeScript,
+        ...(spec.agent?.tokenEnv ? { tokenEnv: spec.agent.tokenEnv } : {}),
+        ...(words.bin ? { bin: words.bin } : {}),
+        after: jobName,
+      });
+      doc.agentDoc = { [name]: agent, [agentPushJobName(name)]: push };
+    }
     // A split review (#4326): the Op's job is the review job, and the note job rides beside it.
     if (review) {
-      doc.jobsDoc = { [jobName]: { ...review.review, ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) } };
-      doc.reviewNoteDoc = { [reviewNoteJobName(jobName)]: review.note };
+      const runsOn = spec.runner !== undefined ? { "runs-on": githubRunsOn(spec.runner) } : {};
+      doc.jobsDoc = { [jobName]: { ...review.review, ...runsOn, ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}) } };
+      doc.reviewNoteDoc = { [reviewNoteJobName(jobName)]: { ...review.note, ...runsOn } };
     }
 
     files.push({ name: `${spec.name}.yml`, doc });
@@ -580,8 +651,8 @@ export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
   // The gated-apply notice job rides in `jobs:` beside the Op's own job; it
   // is carried separately on the doc so a dialect transforms it on its own.
   // A dialect's `header` note (#2257) is absent on github.
-  const { gatedNoticeDoc, reviewNoteDoc, ...workflow } = doc;
-  return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}), ...(reviewNoteDoc ?? {}) } });
+  const { gatedNoticeDoc, reviewNoteDoc, agentDoc, ...workflow } = doc;
+  return emitWorkflowYAML({ ...workflow, jobsDoc: { ...doc.jobsDoc, ...(gatedNoticeDoc ?? {}), ...(reviewNoteDoc ?? {}), ...(agentDoc ?? {}) } });
 }
 
 /**

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

@@ -0,0 +1,64 @@
+/**
+ * An Op waves spec's `control` (#4617): after the last wave, one job adds up
+ * the wave jobs' outcomes and tells the control repo how the waves ended.
+ * 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 { generateGithubOpWavesPipeline } 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" }, { target: "b" }], shares: 2 },
+  ],
+  control: { repo: "github.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 (#4617)", () => {
+  test("needs the last wave's share jobs and runs after a failure, unless the run was cancelled", () => {
+    const yaml = generateGithubOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toMatch(/control-dispatch:\n\s+runs-on: ubuntu-latest\n\s+needs:\n\s+- wave-2-rest-share-1\n\s+- wave-2-rest-share-2\n\s+if: '!cancelled\(\)'/);
+  });
+
+  test("downloads every outcome file and adds them up through the product's bin", () => {
+    const yaml = generateGithubOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml).toContain("name: Download the waves' outcomes");
+    expect(yaml).toContain("path: .chant/op-waves/stacks/outcomes");
+    expect(yaml).toContain('outcome="$(npx --no-install plywood run wave --spec waves.json --waves-outcome)" || exit 1');
+    expect(yaml).toContain('echo "CHANT_CONTROL_OUTCOME=$outcome" >> "$GITHUB_ENV"');
+  });
+
+  test("the dispatch step alone holds the token, maps it from the product's secret and pipes it to curl", () => {
+    const yaml = generateGithubOpWavesPipeline(spec, options).files[0]!.yaml;
+    expect(yaml.match(/secrets\.PLYWOOD_CONTROL_TOKEN/g)).toHaveLength(1);
+    expect(yaml).toContain("CHANT_CONTROL_TOKEN: '${{ secrets.PLYWOOD_CONTROL_TOKEN }}'");
+    expect(yaml).toContain("CHANT_CONTROL_SHA: '${{ github.sha }}'");
+    expect(yaml).toContain("-H @-");
+    expect(yaml).toContain('"event_type":"plywood-applied"');
+    expect(yaml).toContain(`"outcome":"'"$outcome"'"`);
+  });
+
+  test("markSent asks for statuses: write and hands the job token over", () => {
+    const yaml = generateGithubOpWavesPipeline({ ...spec, control: { ...spec.control!, markSent: "plywood post status control success" } }, options).files[0]!.yaml;
+    expect(yaml).toMatch(/control-dispatch:[\s\S]*permissions:\n\s+contents: write\n\s+statuses: write/);
+    expect(yaml).toContain("plywood post status control success");
+    expect(yaml).toContain("GITHUB_TOKEN: '${{ github.token }}'");
+  });
+
+  test("no control, no job", () => {
+    const { control: _drop, ...plain } = spec;
+    expect(generateGithubOpWavesPipeline(plain, options).files[0]!.yaml).not.toContain("control-dispatch");
+  });
+
+  test("a control without a member is refused, since a spec has no repository name to default it to", () => {
+    const { member: _m, ...noMember } = spec.control!;
+    expect(() => generateGithubOpWavesPipeline({ ...spec, control: noMember as never }, options)).toThrow(/control\.member/);
+  });
+});

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

@@ -121,4 +121,21 @@ describe("a runner per wave and job groups per wave (#3914)", () => {
     expect(files.map((f) => f.name)).toEqual(["migrations.yml", "migrations-resume.yml", "migrations-plans.yml"]);
     for (const f of files) expect(f.yaml).not.toContain("ubuntu-latest");
   });
+
+  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 } = generateGithubOpWavesPipeline(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("run: 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 } = generateGithubOpWavesPipeline(spec, { specFile: "waves.json" });
+    expect(jobs.every((j) => j.command[0] === "chant")).toBe(true);
+  });
 });

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

@@ -22,6 +22,9 @@
  * downloads it. The forgejo generator reuses {@link buildGithubOpWavesDoc}
  * and applies its dialect.
  *
+ * `options.bin` (#4607) is a product's command in place of `chant` in every
+ * job line: the wave jobs, the resume job and the plans job.
+ *
  * With `resume` on the spec (#3683), a second workflow, `<name>-resume.yml`,
  * runs `chant run resume --op <name>` on that schedule: it re-runs the failed
  * jobs of a run whose waiting wave has been approved since, with the job's
@@ -49,9 +52,31 @@
  * checkout. Every later run step starts with an unset of the variables a
  * token is requested with, so the code the job runs holds no OIDC token
  * and cannot request one for another group's identity.
+ *
+ * With `control` on the spec (#4617), a `control-dispatch` job needs the
+ * last wave's jobs and runs after them unless the run was cancelled, so it
+ * runs after a failure too. It downloads every job's outcome file, adds
+ * them up with `chant run wave --waves-outcome` (through the product's
+ * bin) into `CHANT_CONTROL_OUTCOME`, and sends the control repo one
+ * dispatch carrying that outcome and the pushed commit. Only the dispatch
+ * step holds the control token: the `tokenSecret` secret, mapped into
+ * `CHANT_CONTROL_TOKEN` and handed to curl on its stdin
+ * (`controlDispatchScript`, #4568).
  */
 
-import { notifyVariables, opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import {
+  notifyVariables,
+  opWaveGroupOf,
+  opWaveJobs,
+  opWaveOutcomeDir,
+  opWavesControlTarget,
+  opWavesLastJobs,
+  opWavesOutcomeCommand,
+  opWavesRecordPlansCommand,
+  opWavesResumeCommand,
+  type OpWavesSpec,
+} from "@intentius/chant/op/op-waves";
+import { CONTROL_OUTCOME_VAR, controlDispatchJob } from "@intentius/chant/control/dispatch";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
 import {
   assertEnvironment,
@@ -89,7 +114,7 @@ export function buildGithubOpWavesDoc(
   spec: OpWavesSpec,
   options: OpWavesPipelineOptions,
 ): { doc: GithubOpPipelineDoc; jobs: OpWavesPipelineResult["jobs"]; resumeDoc?: GithubOpPipelineDoc; plansDoc?: GithubOpPipelineDoc } {
-  const jobs = opWaveJobs(spec, options.specFile);
+  const jobs = opWaveJobs(spec, options.specFile, { bin: options.bin });
   const image = options.image ?? OP_WAVES_IMAGE;
   const byReview = spec.waves.some((w) => w.approval === "pr-review");
   for (const wave of spec.waves) {
@@ -143,6 +168,12 @@ export function buildGithubOpWavesDoc(
     };
   }
 
+  // #4617: once the last wave ran, one job tells the control repo how the waves ended.
+  if (spec.control) {
+    const [name, job] = controlJob(spec, options, jobs, image, permissions);
+    jobsDoc[name] = job;
+  }
+
   // #3761: the notify variables come from the secrets of the same name.
   const env = { ...githubSecretEnv(notifyVariables(spec.notify)), ...(options.variables ?? {}) };
   const doc: GithubOpPipelineDoc = {
@@ -161,12 +192,58 @@ export function buildGithubOpWavesDoc(
   };
 }
 
+/**
+ * The control dispatch job (#4617): after the last wave, whatever it did,
+ * the waves' outcome read from every job's outcome file, then one dispatch
+ * carrying it. The pushed commit is the one every wave ran at.
+ */
+function controlJob(
+  spec: OpWavesSpec,
+  options: OpWavesPipelineOptions,
+  jobs: OpWavesPipelineResult["jobs"],
+  image: string,
+  permissions: Record<string, unknown>,
+): [string, Record<string, unknown>] {
+  const control = spec.control!;
+  const dispatch = controlDispatchJob("github", opWavesControlTarget(control), "${{ github.sha }}", {
+    ...(options.words ? { words: options.words } : {}),
+    ...(control.sentCheck ? { sentCheck: control.sentCheck } : {}),
+    ...(control.markSent ? { markSent: control.markSent } : {}),
+    outcome: true,
+  });
+  const marks = control.sentCheck !== undefined || control.markSent !== undefined;
+  const steps: Array<Record<string, unknown>> = [
+    checkoutStep(true),
+    { name: "Download the waves' outcomes", uses: DOWNLOAD_ARTIFACT, with: { path: opWaveOutcomeDir(spec) } },
+    ...(spec.waves[0]?.setup ?? []).map(setupStepDoc),
+    ...runSteps(options.beforeScript ?? []),
+    {
+      name: "Add up the waves' outcomes",
+      run: `outcome="$(${opWavesOutcomeCommand(options.specFile, options.bin).join(" ")})" || exit 1\necho "${CONTROL_OUTCOME_VAR}=$outcome" >> "$GITHUB_ENV"`,
+    },
+    { name: `Tell the control repo ${control.repo} how ${control.member}'s waves ended`, env: { ...dispatch.env, ...(marks ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {}) }, run: dispatch.script },
+  ];
+  return [
+    dispatch.name,
+    {
+      "runs-on": githubRunsOn(spec.runner),
+      needs: opWavesLastJobs(jobs),
+      // The waves ran, whatever they did: a failed run is an outcome the control repo is told about.
+      if: "!cancelled()",
+      container: image,
+      // markSent sets a commit status; the rest reads the repository and the run's artifacts.
+      permissions: marks ? { ...permissions, statuses: "write" } : permissions,
+      steps,
+    },
+  ];
+}
+
 /** The scheduled resume workflow (#3683). */
 function buildResumeDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): GithubOpPipelineDoc {
   const steps: Array<Record<string, unknown>> = [checkoutStep(), ...runSteps(options.beforeScript ?? [])];
   steps.push({
     name: `Resume the waves of ${spec.name} whose approval arrived`,
-    run: opWavesResumeCommand(spec).join(" "),
+    run: opWavesResumeCommand(spec, options.bin).join(" "),
     env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN },
   });
   return {
@@ -182,7 +259,7 @@ 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 {
   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: ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ") });
+  steps.push({ name: "Plan every wave at the head and record its digests", run: opWavesRecordPlansCommand(options.specFile, options.bin).join(" ") });
   return {
     name: `${spec.name}-plans`,
     on: { pull_request: { branches: pushBranches(spec.branches) } },