@intentius/chant-lexicon-github 0.124.54 → 0.124.55

package/dist/components/agent-jobs.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The agent jobs on GitHub and Forgejo (#4616): `ScheduledOpSpec.agent`.
+ * What each job does is @intentius/chant/ci-agent's; this file lays them
+ * out so the model never shares a job with a write token:
+ *
+ * - the agent job holds `contents: read` and `pull-requests: read`. Its
+ *   checkout script alone sees the job token, for the fetches (the target
+ *   branch's commit, chant/lifecycle for the run count, and for a comment
+ *   the pull request's head). `chant agent prepare` reads with the job
+ *   token; `chant agent run` is the last step and starts without any forge
+ *   token, with the model's key from its secret, and hands the agent
+ *   directory on as the job's outputs (`handoverTrap`).
+ * - the push job checks out the target branch's commit, takes the agent
+ *   directory back as data and runs `chant agent land` with the push token:
+ *   `tokenEnv`'s secret, else the job token. A push made with the job token
+ *   starts no workflow on GitHub, so the pull request is planned again only
+ *   with a token of a user or an app.
+ *
+ * Forgejo's runner ignores `permissions:` and has no author association, so
+ * there `chant agent prepare` asks the forge whether the commenter can write,
+ * and both jobs drop the token variables before any step that does not need
+ * them.
+ */
+import { type CiRunner } from "@intentius/chant/ci-jobs";
+import { type AgentSettings } from "@intentius/chant/ci-agent";
+/** The agent step's id, which the agent job's outputs come from. */
+export declare const AGENT_STEP_ID = "chant-agent";
+/** The drift Op's run step id, whose outputs carry the drift and the code. */
+export declare const AGENT_DRIFT_STEP_ID = "chant-run";
+/** The name of the push job beside the agent job. */
+export declare function agentPushJobName(jobName: string): string;
+/** The agent job's name for a drift Op's job. */
+export declare function agentJobName(jobName: string, on: AgentSettings["on"]): string;
+export interface GithubAgentJobsInput {
+    forge: "github" | "forgejo";
+    /** The agent job's name. */
+    jobName: string;
+    image: string;
+    settings: AgentSettings;
+    runner?: CiRunner;
+    /** Setup steps, as built by `setupStepDoc`. */
+    setup: Array<Record<string, unknown>>;
+    beforeScript: readonly string[];
+    /** The secret holding the push token; absent: the job token. */
+    tokenEnv?: string;
+    /** The command in place of `chant`: the product's bin. */
+    bin?: string;
+    /** For a drift agent: the Op's job, which handed the drift on. */
+    after?: string;
+}
+/** The comment condition of the agent job: a pull request comment that starts with the agent's line, from a writer on GitHub. */
+export declare function agentCommentIf(forge: "github" | "forgejo", comment: string): string;
+/**
+ * The drift Op's run step (#4616): the run with its output kept as the
+ * drift for the agent, `drift=true` among the step's outputs when it exits
+ * with chant's `drift` code, and the output handed on. The step still exits
+ * with the run's code.
+ */
+export declare function driftRunStep(invocation: string, env: Record<string, string>, forge: "github" | "forgejo"): Record<string, unknown>;
+/** The drift Op job's outputs: the handed-on drift and the drift flag. */
+export declare function driftRunOutputs(forge: "github" | "forgejo"): Record<string, string>;
+/** The agent job and the push job. */
+export declare function githubAgentJobs(i: GithubAgentJobsInput): {
+    agent: Record<string, unknown>;
+    push: Record<string, unknown>;
+};
+//# sourceMappingURL=agent-jobs.d.ts.map

package/dist/components/agent-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jobs.d.ts","sourceRoot":"","sources":["../../src/components/agent-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAwE,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAC/H,OAAO,EAUL,KAAK,aAAa,EACnB,MAAM,2BAA2B,CAAC;AAGnC,oEAAoE;AACpE,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAC3C,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAQ/C,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,MAAM,CAE7E;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC5B,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,CAAC;IACxB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,+CAA+C;IAC/C,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,iIAAiI;AACjI,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOnF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAclI;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEnF;AAED,sCAAsC;AACtC,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CA2D1H"}

package/dist/components/agent-jobs.js

@@ -0,0 +1,139 @@
+/**
+ * The agent jobs on GitHub and Forgejo (#4616): `ScheduledOpSpec.agent`.
+ * What each job does is @intentius/chant/ci-agent's; this file lays them
+ * out so the model never shares a job with a write token:
+ *
+ * - the agent job holds `contents: read` and `pull-requests: read`. Its
+ *   checkout script alone sees the job token, for the fetches (the target
+ *   branch's commit, chant/lifecycle for the run count, and for a comment
+ *   the pull request's head). `chant agent prepare` reads with the job
+ *   token; `chant agent run` is the last step and starts without any forge
+ *   token, with the model's key from its secret, and hands the agent
+ *   directory on as the job's outputs (`handoverTrap`).
+ * - the push job checks out the target branch's commit, takes the agent
+ *   directory back as data and runs `chant agent land` with the push token:
+ *   `tokenEnv`'s secret, else the job token. A push made with the job token
+ *   starts no workflow on GitHub, so the pull request is planned again only
+ *   with a token of a user or an app.
+ *
+ * Forgejo's runner ignores `permissions:` and has no author association, so
+ * there `chant agent prepare` asks the forge whether the commenter can write,
+ * and both jobs drop the token variables before any step that does not need
+ * them.
+ */
+import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
+import { githubRunsOn, GITHUB_JOB_TOKEN, githubSecret, githubSecretOrJobToken } from "@intentius/chant/ci-jobs";
+import { AGENT_DECISION_FILE, AGENT_DIR, AGENT_DRIFT_FILE, AGENT_PATCH_FILE, AGENT_RC_FILE, agentCommandLines, agentGitAuthLines, agentHeadFetchLine, agentSettingsEnv, } from "@intentius/chant/ci-agent";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
+/** The agent step's id, which the agent job's outputs come from. */
+export const AGENT_STEP_ID = "chant-agent";
+/** The drift Op's run step id, whose outputs carry the drift and the code. */
+export const AGENT_DRIFT_STEP_ID = "chant-run";
+/** The variable the push step holds its token in, for git's header and the forge client. */
+const PUSH_TOKEN_ENV = "CHANT_AGENT_TOKEN";
+/** The files the handover keeps when the agent directory is too large to hand on whole. */
+const HANDED = { label: "chant-agent", noteFiles: [AGENT_DECISION_FILE, AGENT_RC_FILE, AGENT_PATCH_FILE, "prompt.sha256"] };
+const DRIFT_HANDED = { label: "chant-agent", noteFiles: [AGENT_DRIFT_FILE] };
+/** The name of the push job beside the agent job. */
+export function agentPushJobName(jobName) {
+    return `${jobName}-push`;
+}
+/** The agent job's name for a drift Op's job. */
+export function agentJobName(jobName, on) {
+    return on === "drift" ? `${jobName}-agent` : jobName;
+}
+/** The comment condition of the agent job: a pull request comment that starts with the agent's line, from a writer on GitHub. */
+export function agentCommentIf(forge, comment) {
+    return [
+        "github.event_name == 'issue_comment'",
+        forge === "forgejo" ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+        `startsWith(github.event.comment.body, '${comment.replace(/'/g, "''")} ')`,
+        ...(forge === "forgejo" ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+    ].join(" && ");
+}
+/**
+ * The drift Op's run step (#4616): the run with its output kept as the
+ * drift for the agent, `drift=true` among the step's outputs when it exits
+ * with chant's `drift` code, and the output handed on. The step still exits
+ * with the run's code.
+ */
+export function driftRunStep(invocation, env, forge) {
+    return {
+        id: AGENT_DRIFT_STEP_ID,
+        env,
+        run: [
+            "set +e",
+            `mkdir -p ${AGENT_DIR}`,
+            ...handoverTrap(AGENT_DIR, forge, DRIFT_HANDED),
+            `{ ${invocation}; echo "$?" >"\${RUNNER_TEMP:-/tmp}/chant-run.code"; } 2>&1 | tee ${AGENT_DIR}/${AGENT_DRIFT_FILE}`,
+            'code=$(cat "${RUNNER_TEMP:-/tmp}/chant-run.code")',
+            `if [ "$code" -eq ${CHANT_EXIT.drift} ]; then echo "drift=true" >>"$GITHUB_OUTPUT"; fi`,
+            'exit "$code"',
+        ].join("\n"),
+    };
+}
+/** The drift Op job's outputs: the handed-on drift and the drift flag. */
+export function driftRunOutputs(forge) {
+    return { ...handoverOutputs(AGENT_DRIFT_STEP_ID, forge), drift: `\${{ steps.${AGENT_DRIFT_STEP_ID}.outputs.drift }}` };
+}
+/** The agent job and the push job. */
+export function githubAgentJobs(i) {
+    const s = i.settings;
+    const lines = agentCommandLines(i.forge, i.bin);
+    const drop = dropForgeTokens("sh");
+    const comment = s.on === "comment";
+    const settingsEnv = agentSettingsEnv(s);
+    const checkout = (head) => ({
+        name: head ? "Check out the target branch's commit and the pull request's head" : "Check out the commit the drift check ran on",
+        env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN, ...(head ? { PR_NUMBER: "${{ github.event.issue.number }}" } : {}) },
+        // The ledger branch too: prepare counts the agent's runs on it, and land appends to it.
+        run: [checkoutScript(true, true), ...(head ? [agentHeadFetchLine(i.forge, "PR_NUMBER")] : [])].join("\n"),
+    });
+    const before = i.beforeScript.map((line) => ({ run: `${drop}\n${line}` }));
+    const timeout = s.timeout + 15;
+    const agent = {
+        ...(comment ? { if: agentCommentIf(i.forge, s.comment) } : { needs: i.after, if: `always() && needs.${i.after}.outputs.drift == 'true'` }),
+        "runs-on": githubRunsOn(i.runner),
+        container: i.image,
+        "timeout-minutes": timeout,
+        permissions: { contents: "read", "pull-requests": "read" },
+        env: settingsEnv,
+        outputs: handoverOutputs(AGENT_STEP_ID, i.forge),
+        steps: [
+            checkout(comment),
+            ...(comment ? [] : [{ name: "Take the drift from the drift check", run: takeOverScript(i.after, AGENT_DIR, i.forge) }]),
+            ...i.setup,
+            ...before,
+            // Reads only: the comment, the commenter's access, the pull request's head and the ledger.
+            { name: "Decide whether the agent runs", env: { GITHUB_TOKEN: GITHUB_JOB_TOKEN }, run: lines.prepare },
+            // The job's last step: the model's key and no forge token, and the agent directory handed on however it ends.
+            {
+                id: AGENT_STEP_ID,
+                name: "Run the agent",
+                env: { [s.keyEnv]: githubSecret(s.keyEnv) },
+                run: [drop, ...handoverTrap(AGENT_DIR, i.forge, HANDED), lines.run].join("\n"),
+            },
+        ],
+    };
+    const token = i.tokenEnv ? githubSecretOrJobToken(i.tokenEnv) : GITHUB_JOB_TOKEN;
+    const push = {
+        needs: i.jobName,
+        if: `always() && needs.${i.jobName}.result == 'success'`,
+        "runs-on": githubRunsOn(i.runner),
+        container: i.image,
+        permissions: { contents: "write", "pull-requests": "write", issues: "write" },
+        env: settingsEnv,
+        steps: [
+            checkout(comment),
+            { name: "Take the change from the agent job", run: takeOverScript(i.jobName, AGENT_DIR, i.forge) },
+            ...i.setup,
+            ...before,
+            {
+                name: comment ? "Push the change to the pull request" : "Open or update the agent's pull request",
+                env: { [PUSH_TOKEN_ENV]: token, GITHUB_TOKEN: token, ...(i.forge === "forgejo" ? { CHANT_FORGEJO_TOKEN: token } : {}) },
+                run: [...agentGitAuthLines(PUSH_TOKEN_ENV, "x-access-token"), lines.land].join("\n"),
+            },
+        ],
+    };
+    return { agent, push };
+}

package/dist/components/control-pipeline.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The control repo's own workflow (#4568) on GitHub, and on Forgejo through
+ * its dialect: a member's dispatch starts it, and it runs the member's
+ * dependents with `chant workspace run --dependents-of`. The pieces are
+ * core's (`controlPipelineSpec` in `@intentius/chant/control/dispatch`);
+ * this file writes them as a workflow. The member's side, the
+ * `control-dispatch` job, comes from the pull request loop's `control`
+ * option (./generate-pipeline.ts).
+ */
+import type { CiProductWords, CiProductWordsInput } from "@intentius/chant/ci-product-words";
+import { type GithubWorkflowDoc } from "./ci-jobs.js";
+/** A control repo's pipeline file: where it goes, its text, and what a person still sets up. */
+export interface ControlPipelineFile {
+    path: string;
+    content: string;
+    notes: string[];
+}
+/** What {@link controlGithubDoc} and the generators take. */
+export interface ControlPipelineOptions {
+    words?: CiProductWordsInput | CiProductWords;
+    /** The image the job runs in. Default chant's CI image. */
+    image?: string;
+    /** The command the job runs chant with. Default `npx --no-install chant`. */
+    command?: string;
+}
+/** The control repo's workflow document for a GitHub-shaped forge, before emission. Forgejo transforms it first. */
+export declare function controlGithubDoc(forge: "github" | "forgejo", options?: ControlPipelineOptions): {
+    doc: GithubWorkflowDoc;
+    path: string;
+    notes: string[];
+};
+/** The control repo's workflow on GitHub: `.github/workflows/<product>-dependents.yml`. */
+export declare function generateControlPipeline(options?: ControlPipelineOptions): ControlPipelineFile;
+//# sourceMappingURL=control-pipeline.d.ts.map

package/dist/components/control-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/control-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EAA2C,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE5F,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAAC;IAC7C,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oHAAoH;AACpH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,OAAO,GAAE,sBAA2B,GAAG;IAAE,GAAG,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CA0B7J;AAED,2FAA2F;AAC3F,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,sBAA2B,GAAG,mBAAmB,CAGjG"}

package/dist/components/control-pipeline.js

@@ -0,0 +1,45 @@
+/**
+ * The control repo's own workflow (#4568) on GitHub, and on Forgejo through
+ * its dialect: a member's dispatch starts it, and it runs the member's
+ * dependents with `chant workspace run --dependents-of`. The pieces are
+ * core's (`controlPipelineSpec` in `@intentius/chant/control/dispatch`);
+ * this file writes them as a workflow. The member's side, the
+ * `control-dispatch` job, comes from the pull request loop's `control`
+ * option (./generate-pipeline.ts).
+ */
+import { CI_IMAGE, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
+import { controlPipelineSpec } from "@intentius/chant/control/dispatch";
+import { CHECKOUT, concurrency, emitWorkflowYAML } from "./ci-jobs.js";
+/** The control repo's workflow document for a GitHub-shaped forge, before emission. Forgejo transforms it first. */
+export function controlGithubDoc(forge, options = {}) {
+    const spec = controlPipelineSpec(forge, options.words ?? {}, options.command ? { command: options.command } : {});
+    const doc = {
+        header: spec.header,
+        name: spec.path.split("/").pop().replace(/\.yml$/, ""),
+        on: {
+            ...(forge === "github" ? { repository_dispatch: { types: [spec.event] } } : {}),
+            workflow_dispatch: { inputs: spec.inputs },
+        },
+        // #4617: contents: write pushes the record of each dispatch that carries an outcome to chant/lifecycle.
+        permissions: { contents: "write" },
+        // One run per member at a time, and none cancelled: a later apply of the same member waits for the one running.
+        concurrency: concurrency(spec.group),
+        jobsDoc: {
+            dependents: {
+                "runs-on": GITHUB_RUNNER,
+                container: options.image ?? CI_IMAGE,
+                steps: [
+                    // The full history, so the job reads and appends to chant/lifecycle (#4617).
+                    { uses: CHECKOUT, with: { "fetch-depth": 0 } },
+                    { name: "Run the dependents of the member that applied", shell: "bash", env: spec.env, run: spec.script },
+                ],
+            },
+        },
+    };
+    return { doc, path: spec.path, notes: spec.notes };
+}
+/** The control repo's workflow on GitHub: `.github/workflows/<product>-dependents.yml`. */
+export function generateControlPipeline(options = {}) {
+    const { doc, path, notes } = controlGithubDoc("github", options);
+    return { path, content: emitWorkflowYAML(doc), notes };
+}

package/dist/components/generate-op-pipeline.d.ts

@@ -131,6 +131,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. */
 export interface GithubOpPipelineFile {
@@ -150,7 +157,7 @@ export interface GithubOpPipelineFile {
  * assertSetupSteps}), or a `permissions` entry that is not additive ({@link
  * mergePermissions}).
  */
-export declare function buildGithubOpPipelineDocs(ops: ScheduledOpSpec[], options?: GenerateGithubOpOptions): {
+export declare function buildGithubOpPipelineDocs(ops: ScheduledOpSpec[], options?: GenerateGithubOpOptions, forge?: "github" | "forgejo"): {
     files: GithubOpPipelineFile[];
     jobs: OpPipelineJob[];
 };

package/dist/components/generate-op-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAGH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAOhB,gBAAgB,EAIjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAG1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAIhE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AAuOD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CAoH1D;AAwCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAMnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAGH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAOhB,gBAAgB,EAIjB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAG1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAOlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAIhE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AAEjE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AAuOD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,EACrC,KAAK,GAAE,QAAQ,GAAG,SAAoB,GACrC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CAgL1D;AAwCD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAMnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}

package/dist/components/generate-op-pipeline.js

@@ -70,10 +70,13 @@
  * that job either, same as `environment:` above does not).
  */
 import { readFileSync } from "node:fs";
-import { assertEnvironment, assertSetupSteps, CI_IMAGE, ciJobName, environmentDoc, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER, mergePermissions, nonEmpty, permissionsFor, setupStepDoc, } from "@intentius/chant/ci-jobs";
+import { assertEnvironment, assertSetupSteps, CI_IMAGE, ciJobName, environmentDoc, fillCommand, GITHUB_JOB_TOKEN, githubRunsOn, mergePermissions, nonEmpty, permissionsFor, setupStepDoc, } from "@intentius/chant/ci-jobs";
 import { memberPathFilter, resolveOpTrigger } from "@intentius/chant/lexicon";
 import { checkoutStep, concurrency, emitWorkflowYAML, jobTokenEnv, onTrigger, opConcurrencyGroup, runSteps } from "./ci-jobs.js";
 import { assertReviewSplit, reviewJobs, reviewNoteJobName } from "./review-jobs.js";
+import { resolveAgentSpec } from "@intentius/chant/ci-agent";
+import { activeProductWords } from "@intentius/chant/ci-product-words";
+import { agentJobName, agentPushJobName, driftRunOutputs, driftRunStep, githubAgentJobs } from "./agent-jobs.js";
 // The setup, environment and permission checks are shared with the Op waves
 // generator and the forgejo lexicon (#3765); they stay importable from here.
 export { assertEnvironment, assertSetupSteps, mergePermissions };
@@ -253,12 +256,12 @@ function gateNoticeScript(version) {
  * no branch and merges nothing. The Forgejo dialect drops them, as it drops
  * every scope but `id-token`.
  */
-function gateNoticeJob(applyJobName, image) {
+function gateNoticeJob(applyJobName, image, runner) {
     const output = (name) => "${{ 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: [
@@ -301,14 +304,48 @@ function assertTriggerSupportsMode(name, mode, trigger) {
  * assertSetupSteps}), or a `permissions` entry that is not additive ({@link
  * mergePermissions}).
  */
-export function buildGithubOpPipelineDocs(ops, options = {}) {
+export function buildGithubOpPipelineDocs(ops, options = {}, forge = "github") {
     const image = options.image ?? CI_IMAGE;
     const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
     const beforeScript = options.beforeScript ?? [];
     const extraScript = options.extraScript ?? [];
     const files = [];
     const jobs = [];
+    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);
@@ -321,6 +358,11 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
         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 ?? [];
         assertSetupSteps(spec.name, setup);
@@ -337,7 +379,9 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
         const steps = [checkoutStep(), ...setup.map(setupStepDoc), ...runSteps(beforeScript)];
         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));
         const review = split
             ? reviewJobs({
@@ -362,7 +406,7 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
             permissions: mergePermissions(spec.name, permissionsFor(findingMode, trigger), spec.permissions ?? {}, trigger),
             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,
@@ -381,16 +425,35 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
                                 `\${{ steps.${RUN_STEP_ID}.outputs.${name} }}`,
                             ])),
                         }
-                        : {}),
+                        : 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 });
     }
@@ -445,8 +508,8 @@ export function emitOpPipelineYAML(doc) {
     // 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 ?? {}) } });
 }
 /**
  * Synthesize one `.github/workflows/*.yml` per scheduled Op. Thin wrapper

package/dist/components/generate-op-waves-pipeline.d.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,6 +52,16 @@
  * 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 { type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";

package/dist/components/generate-op-waves-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAsF,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AACpJ,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAiB9F,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAW,CAAC;AAEvC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9F;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,GAC9B;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAuEpI;AAoDD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAMvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAUL,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAiB9F,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,yFAAyF;AACzF,eAAO,MAAM,cAAc,YAAW,CAAC;AAEvC,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9F;AAED,qEAAqE;AACrE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,GAC9B;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CA6EpI;AAkGD,4EAA4E;AAC5E,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAMvH"}

package/dist/components/generate-op-waves-pipeline.js

@@ -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,8 +52,19 @@
  * 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 } from "@intentius/chant/op/op-waves";
+import { notifyVariables, opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesControlTarget, opWavesLastJobs, opWavesOutcomeCommand, opWavesRecordPlansCommand, opWavesResumeCommand, } from "@intentius/chant/op/op-waves";
+import { CONTROL_OUTCOME_VAR, controlDispatchJob } from "@intentius/chant/control/dispatch";
 import { assertEnvironment, assertSetupSteps, CI_IMAGE, dirnameOf, environmentDoc, GITHUB_JOB_TOKEN, githubRunsOn, githubSecretEnv, idTokenAudienceEnv, nonEmpty, pushBranches, setupStepDoc, } from "@intentius/chant/ci-jobs";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine } from "@intentius/chant/ci-identity";
 import { checkoutStep, concurrency, DOWNLOAD_ARTIFACT, downloadArtifactStep, keepRecordStep, runSteps } from "./ci-jobs.js";
@@ -67,7 +81,7 @@ export function opWaveOutcomeArtifact(spec, jobName) {
 }
 /** The workflow document, before emission, and the jobs it holds. */
 export function buildGithubOpWavesDoc(spec, options) {
-    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) {
@@ -121,6 +135,11 @@ export function buildGithubOpWavesDoc(spec, options) {
             steps,
         };
     }
+    // #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 = {
@@ -138,12 +157,51 @@ export function buildGithubOpWavesDoc(spec, options) {
         ...(byReview ? { plansDoc: buildPlansDoc(spec, options) } : {}),
     };
 }
+/**
+ * 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, options, jobs, image, permissions) {
+    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 = [
+        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, options) {
     const steps = [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 {
@@ -158,7 +216,7 @@ function buildResumeDoc(spec, options) {
 /** The pull request workflow a `pr-review` wave needs (#3684): record the digests each head plans. */
 function buildPlansDoc(spec, options) {
     const steps = [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) } },