@intentius/chant-lexicon-github 0.124.54 → 0.124.56

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;AAUlC,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,CAuM1D;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,16 @@
  * 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";
+import { assertScheduledOpCloud, scheduledOpUpdateJobName, withoutTokenRequestLine } from "@intentius/chant/scheduled-op-cloud";
+import { TRADE_SPEC_ENV, tradeLine } from "@intentius/chant/ci-identity";
+import { CHANT_EXIT } from "@intentius/chant/exit-codes";
 // 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 +259,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 +307,50 @@ 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) {
+        // #4631: the job's cloud identities and the update on drift, checked before anything renders.
+        assertScheduledOpCloud(spec);
+        // #4616: the comment agent is a workflow of its own, on pull request comments; the spec's trigger is not read.
+        if (spec.agent?.on === "comment") {
+            const settings = resolveAgentSpec(spec.name, spec.agent, words.product);
+            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,7 +363,14 @@ 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 cloud = spec.cloud;
+        const update = spec.update;
         const setup = spec.setup ?? [];
         assertSetupSteps(spec.name, setup);
         if (spec.environment)
@@ -334,11 +383,17 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
         const invocation = gated
             ? [...runParts, ...GATED_EXIT_FLAG, "--json"].join(" ")
             : runParts.join(" ");
-        const steps = [checkoutStep(), ...setup.map(setupStepDoc), ...runSteps(beforeScript)];
-        steps.push(gated
+        const later = [...setup.map(setupStepDoc), ...runSteps(beforeScript)];
+        later.push(gated
             ? gatedRunStep(RUN_STEP_ID, spec.name, invocation, stepEnv)
-            : { run: invocation, env: stepEnv });
-        steps.push(...runSteps(extraScript));
+            : driftAgent
+                ? driftRunStep(invocation, stepEnv, forge)
+                : update
+                    ? driftFlagStep(invocation, stepEnv)
+                    : { run: invocation, env: stepEnv });
+        later.push(...runSteps(extraScript));
+        // #4631: the trade before the checkout, and every step after it without the token request variables.
+        const steps = cloud ? [tradeStep(cloud), checkoutStep(), ...later.map(withoutTokenRequest)] : [checkoutStep(), ...later];
         const review = split
             ? reviewJobs({
                 name: spec.name,
@@ -352,6 +407,7 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
                 ...(options.member ? { member: options.member } : {}),
             })
             : undefined;
+        const workflowPermissions = mergePermissions(spec.name, permissionsFor(findingMode, trigger), spec.permissions ?? {}, trigger);
         const doc = {
             name: spec.name,
             on: onTrigger(trigger),
@@ -359,10 +415,10 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
             // One run at a time per Op — a slow audit must not overlap its own next
             // scheduled trigger. A push Op's `build` (#4169) widens the group.
             concurrency: concurrency(opConcurrencyGroup(jobName, trigger)),
-            permissions: mergePermissions(spec.name, permissionsFor(findingMode, trigger), spec.permissions ?? {}, trigger),
+            permissions: workflowPermissions,
             jobsDoc: {
                 [jobName]: {
-                    "runs-on": 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,
@@ -374,6 +430,8 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
                     // behind the same reviewer would hold the message back until
                     // somebody had already acted.
                     ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
+                    // #4631: the trade needs id-token: write, on this job alone; the finding-mode's scopes stay as they are.
+                    ...(cloud ? { permissions: { ...workflowPermissions, "id-token": "write" } } : {}),
                     ...(gated
                         ? {
                             outputs: Object.fromEntries(["gated", "op", "gate", "approve"].map((name) => [
@@ -381,16 +439,47 @@ export function buildGithubOpPipelineDocs(ops, options = {}) {
                                 `\${{ steps.${RUN_STEP_ID}.outputs.${name} }}`,
                             ])),
                         }
-                        : {}),
+                        : driftAgent
+                            ? { outputs: driftRunOutputs(forge) }
+                            : update
+                                ? { outputs: { drift: `\${{ steps.${DRIFT_FLAG_STEP_ID}.outputs.drift }}` } }
+                                : {}),
                     steps,
                 },
+                ...(update
+                    ? {
+                        [scheduledOpUpdateJobName(jobName)]: updateJob(jobName, update, {
+                            image,
+                            ...(spec.runner !== undefined ? { runner: spec.runner } : {}),
+                            setup: setup.map(setupStepDoc),
+                            beforeScript,
+                        }),
+                    }
+                    : {}),
             },
-            ...(gated ? { gatedNoticeDoc: { [`${jobName}-gate-notice`]: gateNoticeJob(jobName, image) } } : {}),
+            ...(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 +534,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
@@ -461,3 +550,42 @@ export function generateGithubOpPipeline(ops, options = {}) {
         jobs,
     };
 }
+/** The id of the run step that says whether an update's drift check found drift (#4631). */
+const DRIFT_FLAG_STEP_ID = "drift-check";
+/** The Op's run step when an update follows it (#4631): `drift=true` as an output on chant's drift code, and the run's own exit code. */
+function driftFlagStep(invocation, env) {
+    return {
+        id: DRIFT_FLAG_STEP_ID,
+        env,
+        run: ["set +e", invocation, "code=$?", `if [ "$code" -eq ${CHANT_EXIT.drift} ]; then echo "drift=true" >>"$GITHUB_OUTPUT"; fi`, 'exit "$code"'].join("\n"),
+    };
+}
+/** The trade step (#4631), as an op wave job's (#4332): the job's OIDC token for `cloud`, written to GITHUB_ENV. */
+function tradeStep(cloud) {
+    return { name: "Trade the job's OIDC token for its cloud identities", env: { [TRADE_SPEC_ENV]: JSON.stringify(cloud) }, run: tradeLine("$GITHUB_ENV", "github-env") };
+}
+/** A run step after the trade, with the token request variables unset first. A `uses:` step is left as it is. */
+function withoutTokenRequest(step) {
+    return typeof step.run === "string" ? { ...step, run: withoutTokenRequestLine(step.run) } : step;
+}
+/**
+ * The update job (#4631): after the Op's job, only when its run found
+ * drift; its own trade for `update.cloud` before its checkout, then the
+ * update's command. Its permissions are `contents: read`, `id-token: write`
+ * with a cloud, and the update's own scopes, which may raise `contents` to
+ * `write` so the update records on `chant/lifecycle` (2026-10-28 ruling).
+ * The Op's own job keeps its scopes.
+ */
+function updateJob(after, update, i) {
+    const later = [...i.setup, ...runSteps(i.beforeScript), { name: "Update what drifted", run: update.command }];
+    return {
+        needs: after,
+        if: `always() && needs.${after}.outputs.drift == 'true'`,
+        "runs-on": githubRunsOn(i.runner),
+        container: i.image,
+        permissions: { contents: "read", ...(update.cloud ? { "id-token": "write" } : {}), ...(update.permissions ?? {}) },
+        ...nonEmpty("env", update.variables),
+        ...(update.environment ? { environment: environmentDoc(update.environment) } : {}),
+        steps: update.cloud ? [tradeStep(update.cloud), checkoutStep(), ...later.map(withoutTokenRequest)] : [checkoutStep(), ...later],
+    };
+}

package/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
@@ -31,6 +34,8 @@
  * `pull-requests: read`, so a wave can read the merged pull request's
  * reviews, and a second workflow, `<name>-plans.yml`, runs `chant run wave
  * --record-plans` on each pull request to record the digests its head plans.
+ * A `pull-request` wave (#4630) gets the plans workflow too, for the approval
+ * status before merge; it asks for no `pull-requests: read` on the waves.
  *
  * With `notify` on the spec (#3761), the workflow maps each variable it names
  * from the repository secret of the same name, so a wave job can post to
@@ -49,6 +54,25 @@
  * 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).
+ *
+ * Every wave, deciding and share job starts with the apply-job guard
+ * (#4624, `@intentius/chant/ci-job-guard`), before the trade and the
+ * checkout: it stops the job unless `GITHUB_REF` is one of the spec's
+ * branches, the job runs in its forge environment (read from an OIDC
+ * token's claims, so only in a job that may request one), and, for a
+ * runner whose labels include `self-hosted`, on a self-hosted runner. The
+ * forgejo generator passes `forge: "forgejo"`, which checks the ref and
+ * runner only.
  */
 import { type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
@@ -60,7 +84,9 @@ export declare function opWaveRecordArtifact(spec: Pick<OpWavesSpec, "name">, wa
 /** The artifact a job keeps its outcome file in (#4322). */
 export declare function opWaveOutcomeArtifact(spec: Pick<OpWavesSpec, "name">, jobName: string): string;
 /** The workflow document, before emission, and the jobs it holds. */
-export declare function buildGithubOpWavesDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): {
+export declare function buildGithubOpWavesDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions, dialect?: {
+    forge?: "github" | "forgejo";
+}): {
     doc: GithubOpPipelineDoc;
     jobs: OpWavesPipelineResult["jobs"];
     resumeDoc?: GithubOpPipelineDoc;