@intentius/chant-lexicon-github 0.124.54 → 0.124.56

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
@@ -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,9 +54,42 @@
  * 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 { notifyVariables, opWaveGroupOf, opWaveJobs, opWaveOutcomeDir, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
+import {
+  notifyVariables,
+  opWaveGroupOf,
+  opWaveJobs,
+  opWaveOutcomeDir,
+  opWavesControlTarget,
+  opWavesLastJobs,
+  opWavesApprovalStatusCommand,
+  opWavesPostsApprovalStatus,
+  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,
@@ -68,6 +106,8 @@ import {
   setupStepDoc,
 } from "@intentius/chant/ci-jobs";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
+import { JOB_GUARD_ENV, jobGuardLine, jobGuardSpec, opWaveJobLabel } from "@intentius/chant/ci-job-guard";
+import { resolveProductWords } from "@intentius/chant/ci-product-words";
 import { checkoutStep, concurrency, DOWNLOAD_ARTIFACT, downloadArtifactStep, keepRecordStep, runSteps } from "./ci-jobs";
 import { emitOpPipelineYAML, type GithubOpPipelineDoc } from "./generate-op-pipeline";
 
@@ -88,10 +128,15 @@ export function opWaveOutcomeArtifact(spec: Pick<OpWavesSpec, "name">, jobName:
 export function buildGithubOpWavesDoc(
   spec: OpWavesSpec,
   options: OpWavesPipelineOptions,
+  dialect: { forge?: "github" | "forgejo" } = {},
 ): { doc: GithubOpPipelineDoc; jobs: OpWavesPipelineResult["jobs"]; resumeDoc?: GithubOpPipelineDoc; plansDoc?: GithubOpPipelineDoc } {
-  const jobs = opWaveJobs(spec, options.specFile);
+  const jobs = opWaveJobs(spec, options.specFile, { bin: options.bin });
+  const forge = dialect.forge ?? "github";
+  const product = resolveProductWords(options.words ?? {}).product;
   const image = options.image ?? OP_WAVES_IMAGE;
   const byReview = spec.waves.some((w) => w.approval === "pr-review");
+  // #4630: a pr-review or pull-request wave gets the plans workflow and its approval status.
+  const statusBeforeMerge = opWavesPostsApprovalStatus(spec);
   for (const wave of spec.waves) {
     assertSetupSteps(`${spec.name}/${wave.name}`, wave.setup ?? []);
     if (wave.environment) assertEnvironment(`${spec.name}/${wave.name}`, wave.environment);
@@ -109,7 +154,21 @@ export function buildGithubOpWavesDoc(
     const group = opWaveGroupOf(spec, job);
     // #4332: the job's cloud identities, traded before the checkout.
     const cloud = group?.cloud ?? wave.cloud;
-    const steps: Array<Record<string, unknown>> = [...(cloud ? [tradeStep(cloud)] : []), checkoutStep(true)];
+    const environment = group?.environment ?? wave.environment;
+    const idTokens = group?.idTokens ?? wave.idTokens;
+    const idToken = idTokens !== undefined || cloud !== undefined;
+    const runner = group?.runner ?? wave.runner ?? spec.runner;
+    // #4624: the guard first, before the trade and the checkout.
+    const guard = guardStep({
+      forge,
+      job: opWaveJobLabel(spec.name, job),
+      product,
+      ...(environment && forge === "github" ? { environment: environment.name } : {}),
+      branches: pushBranches(spec.branches),
+      ...(runner !== undefined ? { runner } : {}),
+      idToken,
+    });
+    const steps: Array<Record<string, unknown>> = [guard, ...(cloud ? [tradeStep(cloud)] : []), checkoutStep(true)];
     if (job.kind === "share") {
       steps.push(downloadArtifactStep(`Download wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), dirnameOf(job.record!)));
     }
@@ -126,11 +185,8 @@ export function buildGithubOpWavesDoc(
       steps.push(keepRecordStep(`Keep wave ${job.wave}'s decision`, opWaveRecordArtifact(spec, job.wave), job.record!));
     }
     steps.push(keepRecordStep(`Keep the job's outcome`, opWaveOutcomeArtifact(spec, job.jobName), job.outcome));
-    const environment = group?.environment ?? wave.environment;
-    const idTokens = group?.idTokens ?? wave.idTokens;
-    const idToken = idTokens !== undefined || cloud !== undefined;
     jobsDoc[job.jobName] = {
-      "runs-on": githubRunsOn(group?.runner ?? wave.runner ?? spec.runner),
+      "runs-on": githubRunsOn(runner),
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
       // #4322: a wave's jobs run after a failure in the wave before; a share job runs only on its deciding job's success.
       ...(job.needs.length > 0 && job.kind !== "share" ? { if: "!cancelled()" } : {}),
@@ -143,6 +199,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 = {
@@ -157,16 +219,62 @@ export function buildGithubOpWavesDoc(
     doc,
     jobs,
     ...(spec.resume ? { resumeDoc: buildResumeDoc(spec, options) } : {}),
-    ...(byReview ? { plansDoc: buildPlansDoc(spec, options) } : {}),
+    ...(statusBeforeMerge ? { plansDoc: buildPlansDoc(spec, options, forge) } : {}),
   };
 }
 
+/**
+ * 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 {
@@ -179,21 +287,55 @@ function buildResumeDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): Git
   };
 }
 
-/** The pull request workflow a `pr-review` wave needs (#3684): record the digests each head plans. */
-function buildPlansDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions): GithubOpPipelineDoc {
+/**
+ * The pull request workflow a `pr-review` wave needs (#3684): record the
+ * digests each head plans. The `approval-status` job after it (#4630) posts
+ * `<product>/approval` on the head, and runs alone on each review submitted
+ * or dismissed. It holds a read token that may write statuses and nothing
+ * else. A `pull-request` wave gets the same workflow: the record keeps its
+ * change set, and the status reads the pull request's own approval of it.
+ */
+function buildPlansDoc(spec: OpWavesSpec, options: OpWavesPipelineOptions, forge: "github" | "forgejo"): GithubOpPipelineDoc {
   const steps: Array<Record<string, unknown>> = [checkoutStep(true), ...(spec.waves[0]?.setup ?? []).map(setupStepDoc), ...runSteps(options.beforeScript ?? [])];
-  steps.push({ name: "Plan every wave at the head and record its digests", run: ["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(" ") });
+  const statusSteps: Array<Record<string, unknown>> = [checkoutStep(true), ...runSteps(options.beforeScript ?? [])];
+  statusSteps.push({
+    name: "Post the approval status on the head",
+    run: opWavesApprovalStatusCommand(options.specFile, forge, options.bin).join(" "),
+    env: {
+      GITHUB_TOKEN: GITHUB_JOB_TOKEN,
+      PR_NUMBER: "${{ github.event.pull_request.number }}",
+      HEAD_SHA: "${{ github.event.pull_request.head.sha }}",
+      BASE_SHA: "${{ github.event.pull_request.base.sha }}",
+    },
+  });
   return {
     name: `${spec.name}-plans`,
-    on: { pull_request: { branches: pushBranches(spec.branches) } },
+    on: { pull_request: { branches: pushBranches(spec.branches) }, pull_request_review: { types: ["submitted", "dismissed"] } },
     ...nonEmpty("env", options.variables),
-    concurrency: concurrency(spec.name + "-plans-${{ github.event.number }}", true),
+    concurrency: concurrency(spec.name + "-plans-${{ github.event_name }}-${{ github.event.pull_request.number }}", true),
     // contents: write pushes the record to chant/lifecycle.
     permissions: { contents: "write" },
-    jobsDoc: { "record-plans": { "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps } },
+    jobsDoc: {
+      "record-plans": { if: "github.event_name == 'pull_request'", "runs-on": githubRunsOn(spec.runner), container: options.image ?? OP_WAVES_IMAGE, steps },
+      "approval-status": {
+        needs: ["record-plans"],
+        // On a review the record-plans job is skipped, and the status reads the plans an earlier push recorded.
+        if: "${{ always() && (needs.record-plans.result == 'success' || needs.record-plans.result == 'skipped') }}",
+        "runs-on": githubRunsOn(spec.runner),
+        container: options.image ?? OP_WAVES_IMAGE,
+        permissions: { contents: "read", "pull-requests": "read", statuses: "write" },
+        steps: statusSteps,
+      },
+    },
   };
 }
 
+/** The apply-job guard step (#4624): the job's expectation in CHANT_JOB_GUARD, checked by `node -e` from `/`. */
+function guardStep(input: Parameters<typeof jobGuardSpec>[0]): Record<string, unknown> {
+  return { name: "Check the job runs where the spec set it to run", env: { [JOB_GUARD_ENV]: JSON.stringify(jobGuardSpec(input)) }, run: jobGuardLine() };
+}
+
 /** The step that trades the job's OIDC token for `cloud` (#4332), writing the credentials to GITHUB_ENV. */
 function tradeStep(cloud: CloudTradeSpec): Record<string, unknown> {
   return { name: "Trade the job's OIDC token for its cloud identities", env: { [TRADE_SPEC_ENV]: JSON.stringify(cloud) }, run: tradeLine("$GITHUB_ENV", "github-env") };

package/src/components/generate-pipeline.ts

@@ -59,11 +59,11 @@
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
 import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
 import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/gated-wave-pipeline";
-import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER } from "@intentius/chant/ci-jobs";
+import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER, githubRunsOn } from "@intentius/chant/ci-jobs";
 import { CHECKOUT_TOKEN_ENV, checkoutScript, dropForgeTokens, handoverOutputs, handoverTrap, takeOverScript } from "@intentius/chant/ci-handover";
 import { OIDC_REQUEST_VARS, TRADE_SPEC_ENV, tradeLine, type CloudTradeSpec } from "@intentius/chant/ci-identity";
 import {
-  APPLY_COMMENT,
+  prApplyComment,
   GREEN_TAG_PATTERN,
   GREEN_TICK_WORKFLOW,
   PR_APPLY_RECORD,
@@ -80,14 +80,25 @@ import {
   PR_UNLOCK_JOB,
   PR_UNLOCK_COMMAND,
   prLockCommand,
+  prCommentLockJobs,
+  prCommentPreviewJob,
+  PREVIEW_REF_ENV,
+  PREVIEW_HEAD_OUTPUT,
   prLoopWaveJobs,
   prLoopWithWaves,
   prEnvJobs,
+  prLoopJobStage,
+  prStaleJob,
+  PR_STALE_JOB,
+  prLoopRunner,
   PR_ENV_REPORT_DIR,
   PR_ENV_SWEEP_CRON,
   PR_ENV_POST_JOB,
 } from "@intentius/chant/components/pr-pipeline";
+import { forgejoRepoLockLines, REPO_APPLY_GROUP } from "@intentius/chant/components/repo-lock";
 import { memberRepoPath } from "@intentius/chant/lexicon";
+import { productStatusContext, resolveProductWords } from "@intentius/chant/ci-product-words";
+import { controlDispatchJob, controlNoteCheckout } from "@intentius/chant/control/dispatch";
 import type {
   ComponentPipelineJob as GeneratedJob,
   ComponentPipelineOptions as GenerateGithubOptions,
@@ -137,6 +148,8 @@ export interface GithubPipelineDoc {
 
 /** The plan job's last step, whose outputs carry its report to the plan-note job (#4295). */
 const PLAN_STEP_ID = "plan";
+/** The comment preview's checkout step (#4620), whose output names the head it checked out. */
+const PREVIEW_HEAD_STEP_ID = "head";
 
 /** The output a gated apply wave hands the green commit it applies through, and the step that sets it (#4221). */
 const WAVE_GREEN_OUTPUT = "green-sha";
@@ -292,10 +305,12 @@ function prLoopGithubDoc(
   });
   const withIdToken = (permissions: Record<string, string>): Record<string, string> => (identity ? { ...permissions, "id-token": "write" } : permissions);
   const reportName = (job: typeof plan) => `chant-pr-${job.wave ? prApplyWaveJobName(job.wave) : job.jobName}`;
+  // #4552: on the repo grain a Forgejo apply takes the lock tag in its own step, before the command, since the runner does not queue on a concurrency group.
+  const repoLock = (job: typeof plan): string[] => (loop.lockGrain === "repo" && loop.forge === "forgejo" && job.jobName !== "record" ? forgejoRepoLockLines() : []);
   const steps = (job: typeof plan, name: string): Array<Record<string, unknown>> => [
     ...(identity ? [tradeStep(job.jobName === "record" ? identity.plan : identity.apply, job.jobName === "record" ? "plan" : "apply")] : []),
     checkoutStep(true),
-    ...runSteps(prLoopSetup(image)),
+    ...runSteps(prLoopSetup(image, loop.engineSetup)),
     ...runSteps(beforeScript),
     ...(job.build ? [{ name: "Build the templates", run: job.build[0] }, { name: "Lint the project", run: job.build[1] }] : []),
     ...(job.jobName === "apply" ? [restoreRecord(job.wave)] : []),
@@ -307,9 +322,9 @@ function prLoopGithubDoc(
           name,
           id: WAVE_STEP_ID,
           env: { ...job.run.env, ...(job.wave > 1 ? { GREEN_SHA: `\${{ needs.${prApplyWaveJobName(job.wave - 1)}.outputs.${WAVE_GREEN_OUTPUT} }}` } : {}) },
-          run: [...(job.checkout ?? []), `echo "${WAVE_GREEN_OUTPUT}=$GREEN_SHA" >> "$GITHUB_OUTPUT"`, ...(job.setup ?? []), job.run.command].join("\n"),
+          run: [...(job.checkout ?? []), `echo "${WAVE_GREEN_OUTPUT}=$GREEN_SHA" >> "$GITHUB_OUTPUT"`, ...(job.setup ?? []), ...repoLock(job), job.run.command].join("\n"),
         }
-      : { name, env: job.run.env, run: [...(job.checkout ?? []), ...(job.setup ?? []), job.run.command].join("\n") },
+      : { name, env: job.run.env, run: [...(job.checkout ?? []), ...(job.setup ?? []), ...repoLock(job), job.run.command].join("\n") },
     ...runSteps(extraScript),
     ...(job.jobName === "apply" ? [saveRecord(job.wave)] : []),
     {
@@ -328,7 +343,7 @@ function prLoopGithubDoc(
     "github.event_name == 'issue_comment'",
     // Forgejo's payload says so with is_pull (terragucci comment-apply.ts:129 at e6cb431).
     forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
-    `startsWith(github.event.comment.body, '${APPLY_COMMENT}')`,
+    `startsWith(github.event.comment.body, '${prApplyComment(loop)}')`,
     ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
   ].join(" && ");
   const applyJob = (job: typeof plan, needs: string[], name: string) => ({
@@ -337,7 +352,8 @@ function prLoopGithubDoc(
     "runs-on": GITHUB_RUNNER,
     ...(needs.length > 0 ? { needs } : {}),
     container: image,
-    concurrency: concurrency(prApplyGroup(env, member?.name)),
+    // #4552: on the repo grain every apply of the repository shares one group.
+    concurrency: concurrency(loop.lockGrain === "repo" ? REPO_APPLY_GROUP : prApplyGroup(env, member?.name)),
     permissions: withIdToken({ contents: "write", "pull-requests": "write", statuses: "write" }),
     ...(job.wave ? { outputs: { [WAVE_GREEN_OUTPUT]: `\${{ steps.${WAVE_STEP_ID}.outputs.${WAVE_GREEN_OUTPUT} }}` } } : {}),
     steps: steps(job, name),
@@ -370,7 +386,7 @@ function prLoopGithubDoc(
       env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
       run: checkoutScript(true, true),
     },
-    ...[...prLoopSetup(image), ...beforeScript].map((line) => headStep(line)),
+    ...[...prLoopSetup(image, loop.engineSetup), ...beforeScript].map((line) => headStep(line)),
     ...(plan.build ? [headStep(plan.build[0]!, "Build the templates"), headStep(plan.build[1]!, "Lint the project")] : []),
     // The job's last step: a step after it would start beside whatever the change's code left running.
     {
@@ -380,14 +396,58 @@ function prLoopGithubDoc(
       run: [drop, ...handoverTrap(PR_LOOP_REPORT_DIR, forgeName), ...(plan.checkout ?? []), ...(plan.setup ?? []), plan.run.command, ...extraScript].join("\n"),
     },
   ];
-  const post = prLoopPostJob(forgeName, env, member?.name);
+  // #4568: once the last apply on merge succeeded, one job tells the control repo this member applied.
+  const lastGreen = loop.control && !loop.applyBeforeMerge && greenJobs.length > 0 ? greenJobs[greenJobs.length - 1]![0] : undefined;
+  const controlJobs: Array<[string, Record<string, unknown>]> = [];
+  if (loop.control && lastGreen) {
+    // A wave job hands on the commit it applied; a single apply job applies the green commit its trigger names.
+    const sha = loop.waveGate ? `\${{ needs.${lastGreen}.outputs.${WAVE_GREEN_OUTPUT} }}` : forgejo ? "${{ github.sha }}" : "${{ github.event.workflow_run.head_sha || github.sha }}";
+    const dispatch = controlDispatchJob(forgeName, loop.control.target, sha, {
+      ...(loop.words ? { words: loop.words } : {}),
+      ...(loop.control.sentCheck ? { sentCheck: loop.control.sentCheck } : {}),
+      ...(loop.control.markSent ? { markSent: loop.control.markSent } : {}),
+    });
+    controlJobs.push([
+      dispatch.name,
+      {
+        needs: [lastGreen],
+        if: `success() && (${onGreen})`,
+        "runs-on": GITHUB_RUNNER,
+        container: image,
+        permissions: loop.control.markSent ? { contents: "read", statuses: "write" } : { contents: "read" },
+        steps: [{ name: dispatch.stepName, ...(rooted ? {} : { "working-directory": "." }), env: { ...dispatch.env, ...(loop.control.sentCheck || loop.control.markSent ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {}) }, run: dispatch.script }],
+      },
+    ]);
+  }
+  const post = prLoopPostJob(forgeName, env, member?.name, loop.words ? resolveProductWords(loop.words) : undefined, { ...(loop.staleNotes ? { staleNotes: true } : {}), ...(loop.respond ? { respond: loop.respond } : {}), ...(loop.decide ? { decide: loop.decide } : {}) });
+  // #4628: on a push to the target branch, the open pull requests' notes posted against another commit are marked stale.
+  const stale = prStaleJob(forgeName, env, loop, member?.name);
+  const staleJobs: Record<string, unknown> = stale
+    ? {
+        [PR_STALE_JOB]: {
+          if: "github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')",
+          "runs-on": GITHUB_RUNNER,
+          container: image,
+          permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
+          steps: [
+            // The pushed commit: the target branch's, so none of a pull request's code is here.
+            { name: "Check out the target branch's commit", uses: CHECKOUT },
+            ...runSteps(beforeScript),
+            { name: "Mark the open pull requests' notes stale", ...(rooted ? {} : { "working-directory": "." }), env: stale.env, run: stale.command },
+          ],
+        },
+      }
+    : {};
+  // #4619: with a control repo named, the note job reads its chant/lifecycle, read-only, so pr-post marks the cross-stack edges.
+  const controlRead = loop.control ? controlNoteCheckout(forgeName, loop.control.target, loop.words ?? {}) : undefined;
   const noteSteps: Array<Record<string, unknown>> = [
     // The target branch's commit: the chant this job runs is the target branch's, and none of the change's code is here.
     { name: "Check out the target branch's commit", uses: CHECKOUT, with: { ref: "${{ github.event.pull_request.base.sha }}" } },
     ...runSteps(beforeScript),
     { name: "Take the plan report from the plan job", run: takeOverScript("plan", PR_LOOP_REPORT_DIR, forgeName) },
     { name: "Keep the plan report", if: "always()", uses: UPLOAD_ARTIFACT, with: { name: reportName(plan), path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } },
-    { name: "Post the plan note and chant/plan", if: "always()", env: post.env, run: post.command },
+    ...(controlRead ? [{ name: controlRead.stepName, if: "always()", env: controlRead.env, run: controlRead.script }] : []),
+    { name: `Post the plan note and ${productStatusContext(resolveProductWords(loop.words), "plan")}`, if: "always()", env: post.env, run: post.command },
   ];
   // #4298: with a pull request environment the pull_request trigger fires on close too, and the plan skips that event.
   const prEnv = loop.prEnvironment ? prEnvGithubJobs(loop.forge ?? "github", image, beforeScript, extraScript, loop, member) : undefined;
@@ -428,6 +488,82 @@ function prLoopGithubDoc(
         },
       }
     : {};
+  // #4588: `/<product> lock` and `/<product> unlock` comments, at the target branch's commit, so none of the change's code runs.
+  const commentLocks = prCommentLockJobs(forgeName, loop);
+  const commentLockJobs: Record<string, unknown> = Object.fromEntries(
+    commentLocks.map((job) => [
+      job.jobName,
+      {
+        if: [
+          "github.event_name == 'issue_comment'",
+          forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+          `startsWith(github.event.comment.body, '${job.comment}')`,
+          ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+        ].join(" && "),
+        "runs-on": GITHUB_RUNNER,
+        container: image,
+        permissions: { contents: "write", "pull-requests": "read", statuses: "write" },
+        steps: [
+          { name: "Check out the target branch's commit", uses: CHECKOUT, with: { "fetch-depth": 0 } },
+          ...runSteps(beforeScript),
+          { name: job.command === "lock" ? "Keep the locks the pull request's plan took" : "Release the pull request's locks", env: job.env, run: job.line },
+        ],
+      },
+    ]),
+  );
+  // #4620: `/<product> <plan word>` plans the pull request's head again with a read token; the job after it posts the note.
+  const preview = prCommentPreviewJob(forgeName, env, loop, member?.name);
+  const previewJobs: Record<string, unknown> = preview
+    ? {
+        [preview.jobName]: {
+          if: [
+            "github.event_name == 'issue_comment'",
+            forgejo ? "(github.event.issue.pull_request || github.event.is_pull)" : "github.event.issue.pull_request",
+            `startsWith(github.event.comment.body, '${preview.comment}')`,
+            ...(forgejo ? [] : ["contains(fromJSON('[\"OWNER\",\"MEMBER\",\"COLLABORATOR\"]'), github.event.comment.author_association)"]),
+          ].join(" && "),
+          "runs-on": GITHUB_RUNNER,
+          container: image,
+          permissions: withIdToken({ contents: "read" }),
+          outputs: { ...handoverOutputs(PLAN_STEP_ID, forgeName), [PREVIEW_HEAD_OUTPUT]: `\${{ steps.${PREVIEW_HEAD_STEP_ID}.outputs.${PREVIEW_HEAD_OUTPUT} }}` },
+          steps: [
+            ...(identity ? [tradeStep(identity.plan, "plan")] : []),
+            // The head is read here, before any of the change's code runs, so the post job names the commit this job planned.
+            {
+              name: "Check out the pull request's head",
+              id: PREVIEW_HEAD_STEP_ID,
+              ...(rooted ? {} : { "working-directory": "." }),
+              env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN, [PREVIEW_REF_ENV]: "ref" in preview.head ? preview.head.ref : "" },
+              run: [checkoutScript(true, true, { refEnv: PREVIEW_REF_ENV }), `echo "${PREVIEW_HEAD_OUTPUT}=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"`].join("\n"),
+            },
+            ...[...prLoopSetup(image, loop.engineSetup), ...beforeScript].map((line) => headStep(line)),
+            ...(preview.plan.build ? [headStep(preview.plan.build[0]!, "Build the templates"), headStep(preview.plan.build[1]!, "Lint the project")] : []),
+            {
+              name: "Preview the members this pull request reaches",
+              id: PLAN_STEP_ID,
+              env: preview.plan.run.env,
+              run: [drop, ...handoverTrap(PR_LOOP_REPORT_DIR, forgeName), preview.base, ...(preview.plan.setup ?? []), preview.plan.run.command, ...extraScript].join("\n"),
+            },
+          ],
+        },
+        [preview.noteJobName]: {
+          needs: [preview.jobName],
+          if: `always() && github.event_name == 'issue_comment' && (needs.${preview.jobName}.result == 'success' || needs.${preview.jobName}.result == 'failure')`,
+          "runs-on": GITHUB_RUNNER,
+          container: image,
+          permissions: { actions: "read", contents: "read", "pull-requests": "write", statuses: "write" },
+          steps: [
+            // The target branch's commit, which an issue_comment run checks out: none of the change's code is here.
+            { name: "Check out the target branch's commit", uses: CHECKOUT },
+            ...runSteps(beforeScript),
+            { name: "Take the preview report from the preview job", run: takeOverScript(preview.jobName, PR_LOOP_REPORT_DIR, forgeName) },
+            { name: "Keep the preview report", if: "always()", uses: UPLOAD_ARTIFACT, with: { name: `chant-pr-${preview.jobName}`, path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } },
+            ...(controlRead ? [{ name: controlRead.stepName, if: "always()", env: controlRead.env, run: controlRead.script }] : []),
+            { name: `Post the preview note and ${productStatusContext(resolveProductWords(loop.words), "plan")}`, if: "always()", env: preview.post.env, run: preview.post.command },
+          ],
+        },
+      }
+    : {};
   const jobsDoc: Record<string, unknown> = {
     plan: {
       if: closes ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
@@ -447,7 +583,11 @@ function prLoopGithubDoc(
       steps: noteSteps,
     },
     ...lockJobs,
+    ...commentLockJobs,
+    ...previewJobs,
+    ...staleJobs,
     ...Object.fromEntries(applyJobs),
+    ...Object.fromEntries(controlJobs),
     ...(prEnv ? prEnv.jobs : {}),
   };
   const applyNames = applyJobs.map(([name]) => name);
@@ -461,8 +601,14 @@ function prLoopGithubDoc(
     on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
     on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
   }
-  // #4301: a /chant apply comment starts the apply before merge.
-  if (loop.applyBeforeMerge) on.issue_comment = { types: ["created"] };
+  // #4301: a /chant apply comment starts the apply before merge. #4588: and a lock or unlock comment its job.
+  if (loop.applyBeforeMerge || commentLocks.length > 0 || preview) on.issue_comment = { types: ["created"] };
+  // #4625: each job on its stage's runner, the plan side's, the apply side's, or the default.
+  if (loop.runners) {
+    for (const [name, job] of Object.entries(jobsDoc) as Array<[string, Record<string, unknown>]>) {
+      job["runs-on"] = githubRunsOn(prLoopRunner(loop, prLoopJobStage(name)));
+    }
+  }
   return {
     name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
     environment: env,
@@ -470,16 +616,24 @@ function prLoopGithubDoc(
     ...(rooted ? {} : { defaults: { run: { "working-directory": member!.dir } } }),
     env: { ...options.variables, CHANT_ENV: env },
     jobsDoc,
-    stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...applyNames, ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
+    stages: ["plan", PR_PLAN_NOTE_JOB, ...(locks ? [PR_LOCK_JOB, PR_UNLOCK_JOB] : []), ...commentLocks.map((j) => j.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...(stale ? [PR_STALE_JOB] : []), ...applyNames, ...controlJobs.map(([name]) => name), ...(prEnv ? ["env-up", PR_ENV_POST_JOB, "env-down", "env-sweep"] : [])],
     jobs: [
       { jobName: "plan", component: "pull request plan", stage: "plan", needs: [] },
       { jobName: PR_PLAN_NOTE_JOB, component: "pull request plan note", stage: PR_PLAN_NOTE_JOB, needs: ["plan"] },
+      ...(stale ? [{ jobName: PR_STALE_JOB, component: "pull request stale notes", stage: PR_STALE_JOB, needs: [] }] : []),
       ...(locks
         ? [
             { jobName: PR_LOCK_JOB, component: "pull request lock", stage: PR_LOCK_JOB, needs: ["plan"] },
             { jobName: PR_UNLOCK_JOB, component: "pull request unlock", stage: PR_UNLOCK_JOB, needs: [] },
           ]
         : []),
+      ...commentLocks.map((j) => ({ jobName: j.jobName, component: `pull request ${j.command} comment`, stage: j.jobName, needs: [] })),
+      ...(preview
+        ? [
+            { jobName: preview.jobName, component: "pull request preview comment", stage: preview.jobName, needs: [] },
+            { jobName: preview.noteJobName, component: "pull request preview comment note", stage: preview.noteJobName, needs: [preview.jobName] },
+          ]
+        : []),
       ...applyNames.map((name, i) => ({
         jobName: name,
         component: name === "record" ? "merge record" : loop.applyBeforeMerge ? "apply before merge" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
@@ -487,6 +641,7 @@ function prLoopGithubDoc(
         // The record runs on a push and the apply on a green commit, so only the waves need each other.
         needs: i > 1 ? [applyNames[i - 1]] : [],
       })),
+      ...controlJobs.map(([name]) => ({ jobName: name, component: "control repo dispatch", stage: name, needs: [lastGreen!] })),
       ...(prEnv ? prEnv.listed : []),
     ],
   };
@@ -547,7 +702,7 @@ function prEnvGithubJobs(
         env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
         run: checkoutScript(true, true),
       },
-      ...[...prLoopSetup(image), ...beforeScript].map((line) => headStep(line)),
+      ...[...prLoopSetup(image, loop.engineSetup), ...beforeScript].map((line) => headStep(line)),
       ...(up.build ? [headStep(up.build[0]!, "Build the templates", { CHANT_ENV: up.env.CHANT_ENV! }), headStep(up.build[1]!, "Lint the project")] : []),
       // The job's last step: a step after it would start beside whatever the change's code left running.
       {
@@ -583,7 +738,7 @@ function prEnvGithubJobs(
     steps: [
       ...tradeStep,
       { uses: CHECKOUT, with: { "fetch-depth": 0, ...(ref ? { ref } : {}) } },
-      ...runSteps(prLoopSetup(image)),
+      ...runSteps(prLoopSetup(image, loop.engineSetup)),
       ...runSteps(beforeScript),
       { name, env: j.env, run: j.command },
       ...runSteps(extraScript),

package/src/components/generate-pr-pipeline.comment-locks.test.ts

@@ -0,0 +1,53 @@
+/**
+ * `/<product> lock` and `/<product> unlock` (#4588): under `ci.locks: plan`,
+ * when the words name the commands, a job answers each comment at the
+ * target branch's commit. The lock job keeps the locks the plan took; the
+ * unlock job releases them.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+const WORDS = { product: "plywood", commands: { lock: "lock" as const, unlock: "unlock" as const }, bin: "npx --no-install plywood" };
+
+interface Step { name?: string; uses?: string; run?: string; env?: Record<string, string>; with?: Record<string, unknown> }
+interface Job { if?: string; needs?: string[]; permissions: Record<string, string>; steps: Step[] }
+type Doc = { on: Record<string, unknown>; jobs: Record<string, Job> };
+
+const gen = (prLoop: Record<string, unknown>) => parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml) as Doc;
+
+describe("the GitHub workflow's lock and unlock comments", () => {
+  const doc = gen({ locks: "plan", words: WORDS });
+
+  test("a job per comment, started by issue_comment from a commenter who can write", () => {
+    expect(Object.keys(doc.jobs)).toEqual(expect.arrayContaining(["comment-lock", "comment-unlock"]));
+    expect(doc.on.issue_comment).toEqual({ types: ["created"] });
+    const lock = doc.jobs["comment-lock"]!;
+    expect(lock.if).toContain("github.event_name == 'issue_comment'");
+    expect(lock.if).toContain("startsWith(github.event.comment.body, '/plywood lock')");
+    expect(lock.if).toContain("github.event.comment.author_association");
+    expect(doc.jobs["comment-unlock"]!.if).toContain("startsWith(github.event.comment.body, '/plywood unlock')");
+  });
+
+  test("the lock keeps the plan's locks through the product's bin, the unlock releases them, at the target branch's commit", () => {
+    const lock = doc.jobs["comment-lock"]!;
+    expect(lock.steps[0]!.with).toEqual({ "fetch-depth": 0 });
+    expect(lock.steps.at(-1)!.run).toBe('npx --no-install plywood lock --keep --pr "$PR_NUMBER" --forge github');
+    expect(lock.steps.at(-1)!.env!.PR_NUMBER).toBe("${{ github.event.issue.number }}");
+    expect(doc.jobs["comment-unlock"]!.steps.at(-1)!.run).toBe('npx --no-install plywood unlock --pr "$PR_NUMBER"');
+    expect(lock.permissions).toEqual({ contents: "write", "pull-requests": "read", statuses: "write" });
+  });
+
+  test("neither job without ci.locks, nor without the words for the commands", () => {
+    expect(Object.keys(gen({ words: WORDS }).jobs)).not.toContain("comment-lock");
+    const chant = gen({ locks: "plan" });
+    expect(Object.keys(chant.jobs)).not.toContain("comment-lock");
+    expect(chant.on.issue_comment).toBeUndefined();
+  });
+});