@intentius/chant-lexicon-github 0.124.55 → 0.124.57

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

@@ -1,8 +1,8 @@
 /**
  * Op waves → GitHub Actions workflow (#3679).
  *
- * One workflow for the whole spec, on a push to its branches (and by hand),
- * one run at a time. Each job is one of core's `opWaveJobs`: a wave, or a wide
+ * One workflow for the whole spec, on a push to its branches (and by hand).
+ * Each job is one of core's `opWaveJobs`: a wave, or a wide
  * wave's deciding job and share jobs, chained by `needs:`. Re-running the
  * failed jobs after `chant approve` carries on from that wave.
  *
@@ -34,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
@@ -62,15 +64,27 @@
  * 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,
+  opWaveJobTimeout,
   opWaveOutcomeDir,
   opWavesControlTarget,
   opWavesLastJobs,
+  opWavesApprovalStatusCommand,
+  opWavesPostsApprovalStatus,
   opWavesOutcomeCommand,
   opWavesRecordPlansCommand,
   opWavesResumeCommand,
@@ -93,6 +107,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";
 
@@ -113,10 +129,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, { 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);
@@ -126,6 +147,8 @@ export function buildGithubOpWavesDoc(
     }
   }
   const permissions = { contents: "write", ...(byReview ? { "pull-requests": "read" } : {}) };
+  // The ruling for ci-products (2026-10-28): every wave job carries its timeout and the lock wait under it.
+  const timeout = opWaveJobTimeout(options.jobTimeoutMinutes);
 
   const jobsDoc: Record<string, unknown> = {};
   for (const job of jobs) {
@@ -134,7 +157,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!)));
     }
@@ -151,11 +188,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()" } : {}),
@@ -163,7 +197,8 @@ export function buildGithubOpWavesDoc(
       ...(environment ? { environment: environmentDoc(environment) } : {}),
       // #3914: a job's own permissions replace the workflow's, so they repeat them.
       ...(idToken ? { permissions: { ...permissions, "id-token": "write" } } : {}),
-      ...nonEmpty("env", group || idTokens ? { ...wave.variables, ...group?.variables, ...idTokenAudienceEnv(idTokens) } : wave.variables),
+      "timeout-minutes": timeout.minutes,
+      env: { ...timeout.env, ...(group || idTokens ? { ...wave.variables, ...group?.variables, ...idTokenAudienceEnv(idTokens) } : wave.variables) },
       steps,
     };
   }
@@ -180,7 +215,8 @@ export function buildGithubOpWavesDoc(
     name: spec.name,
     on: { push: { branches: pushBranches(spec.branches) }, workflow_dispatch: {} },
     ...nonEmpty("env", env),
-    concurrency: concurrency(spec.name),
+    // The ruling for ci-products (2026-10-28): no workflow-level concurrency group. Runs on the target and repo grains wait for
+    // their rows on chant's ledger, oldest commit first; plunge stacks on the resource grain lease their resource rows and run.
     permissions,
     jobsDoc,
   };
@@ -188,7 +224,7 @@ export function buildGithubOpWavesDoc(
     doc,
     jobs,
     ...(spec.resume ? { resumeDoc: buildResumeDoc(spec, options) } : {}),
-    ...(byReview ? { plansDoc: buildPlansDoc(spec, options) } : {}),
+    ...(statusBeforeMerge ? { plansDoc: buildPlansDoc(spec, options, forge) } : {}),
   };
 }
 
@@ -256,21 +292,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: 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,7 +59,7 @@
 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 {
@@ -78,7 +78,7 @@ import {
   PR_PLAN_NOTE_JOB,
   PR_LOCK_JOB,
   PR_UNLOCK_JOB,
-  PR_UNLOCK_COMMAND,
+  prUnlockCommand,
   prLockCommand,
   prCommentLockJobs,
   prCommentPreviewJob,
@@ -87,6 +87,10 @@ import {
   prLoopWaveJobs,
   prLoopWithWaves,
   prEnvJobs,
+  prLoopJobStage,
+  prStaleJob,
+  PR_STALE_JOB,
+  prLoopRunner,
   PR_ENV_REPORT_DIR,
   PR_ENV_SWEEP_CRON,
   PR_ENV_POST_JOB,
@@ -415,7 +419,25 @@ function prLoopGithubDoc(
       },
     ]);
   }
-  const post = prLoopPostJob(forgeName, env, member?.name, loop.words ? resolveProductWords(loop.words) : undefined);
+  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>> = [
@@ -431,6 +453,8 @@ function prLoopGithubDoc(
   const prEnv = loop.prEnvironment ? prEnvGithubJobs(loop.forge ?? "github", image, beforeScript, extraScript, loop, member) : undefined;
   // #4327: with ci.locks: plan the pull_request trigger fires on close too, for the unlock job, and the plan skips that event.
   const locks = loop.locks === "plan";
+  // plywood#22: the lock lines run through the product's bin, as its other job lines do.
+  const lockBin = resolveProductWords(loop.words).bin;
   const closes = Boolean(prEnv) || locks;
   const lockJobs: Record<string, unknown> = locks
     ? {
@@ -449,7 +473,7 @@ function prLoopGithubDoc(
             {
               name: "Lock the components the plan selected",
               env: { PR_NUMBER: "${{ github.event.pull_request.number }}", HEAD_SHA: "${{ github.event.pull_request.head.sha }}", GITHUB_TOKEN: GITHUB_JOB_TOKEN },
-              run: prLockCommand(forgeName),
+              run: prLockCommand(forgeName, lockBin),
             },
           ],
         },
@@ -461,7 +485,7 @@ function prLoopGithubDoc(
           steps: [
             { name: "Check out the target branch's commit", uses: CHECKOUT, with: { ref: "${{ github.event.pull_request.base.sha }}", "fetch-depth": 0 } },
             ...runSteps(beforeScript),
-            { name: "Release the pull request's locks", env: { PR_NUMBER: "${{ github.event.pull_request.number }}" }, run: PR_UNLOCK_COMMAND },
+            { name: "Release the pull request's locks", env: { PR_NUMBER: "${{ github.event.pull_request.number }}" }, run: prUnlockCommand(lockBin) },
           ],
         },
       }
@@ -563,6 +587,7 @@ function prLoopGithubDoc(
     ...lockJobs,
     ...commentLockJobs,
     ...previewJobs,
+    ...staleJobs,
     ...Object.fromEntries(applyJobs),
     ...Object.fromEntries(controlJobs),
     ...(prEnv ? prEnv.jobs : {}),
@@ -580,6 +605,12 @@ function prLoopGithubDoc(
   }
   // #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,
@@ -587,10 +618,11 @@ 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] : []), ...commentLocks.map((j) => j.jobName), ...(preview ? [preview.jobName, preview.noteJobName] : []), ...applyNames, ...controlJobs.map(([name]) => name), ...(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"] },

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

@@ -0,0 +1,24 @@
+/**
+ * The preview comment's --target on GitHub (#4626): the preview step runs
+ * `pr-plan --comment-targets` with the comment body in CHANT_PREVIEW_COMMENT,
+ * and the body never appears in the shell line. Written for the
+ * ci-products post-merge pass.
+ */
+import { 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", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const }, bin: "npx --no-install plywood" };
+
+test("the preview step reads the comment from a variable (#4626)", () => {
+  const doc = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { previewComment: true, words: WORDS } }).yaml) as { jobs: Record<string, { steps: Array<{ name?: string; run?: string; env?: Record<string, string> }> }> };
+  const step = doc.jobs["comment-preview"]!.steps.find((s) => s.name === "Preview the members this pull request reaches")!;
+  expect(step.run).toContain("npx --no-install plywood ci run plan");
+  expect(step.run).toContain("--comment-targets");
+  expect(step.env!.CHANT_PREVIEW_COMMENT).toBe("${{ github.event.comment.body }}");
+  expect(step.run).not.toContain("comment.body");
+  const plan = doc.jobs.plan!.steps.find((s) => s.name === "Plan the members this pull request reaches")!;
+  expect(plan.run).not.toContain("--comment-targets");
+});

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

@@ -56,6 +56,16 @@ describe("the GitHub workflow with ci.locks: plan", () => {
   });
 });
 
+describe("a product's words (plywood#22)", () => {
+  test("the lock and unlock lines run through the product's bin, so its job image needs no chant on PATH", () => {
+    const doc = gen({ locks: "plan", words: { product: "plywood", bin: "npx --no-install plywood" } });
+    const lock = doc.jobs.lock!.steps.find((s) => s.run?.includes(" lock --from-report"))!;
+    expect(lock.run).toBe('npx --no-install plywood lock --from-report .chant/pr/pr-plan.json --pr "$PR_NUMBER" --head "$HEAD_SHA" --stage plan --forge github');
+    const unlock = doc.jobs.unlock!.steps.find((s) => s.run?.includes(" unlock --pr"))!;
+    expect(unlock.run).toBe('npx --no-install plywood unlock --pr "$PR_NUMBER"');
+  });
+});
+
 describe("with a pull request environment too", () => {
   test("the pull_request types and the plan condition are the same as with the environment alone", () => {
     const both = gen({ locks: "plan", prEnvironment: true });

package/src/components/generate-pr-pipeline.respond.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The pull request loop's responses, description check and merge on GitHub
+ * (#4629, #4636), as `chant build --pr-loop --respond --decide-backend
+ * --decide-model --merge auto` sets them: the note job asks the decide
+ * service, and the apply job carries CHANT_RESPOND and the merge.
+ */
+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" }] }] }];
+
+type Step = { name?: string; run?: string; env?: Record<string, string> };
+type Doc = { jobs: Record<string, { steps: Step[] }> };
+const gen = (prLoop: Record<string, unknown>) => parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml) as Doc;
+
+describe("responses and the merge on GitHub (#4629, #4636)", () => {
+  const doc = gen({
+    applyBeforeMerge: true,
+    applyMerge: { tokenEnv: "CHANT_MERGE_TOKEN", method: "squash" },
+    respond: { "wave-refused": "off", description: "check" },
+    decide: { backend: "review", model: "m-1" },
+  });
+
+  test("the note job carries the responses and asks the decide service", () => {
+    const post = doc.jobs["plan-note"]!.steps.at(-1)!;
+    expect(post.run).toMatch(/--decide-backend "review" --decide-model "m-1"$/);
+    expect(post.env!.CHANT_RESPOND).toBe("wave-refused=off,description=check");
+  });
+
+  test("the apply job carries the responses and the merge", () => {
+    const steps = Object.values(doc.jobs).flatMap((j) => j.steps);
+    const apply = steps.find((s) => s.run?.includes("--apply-before-merge"))!;
+    expect(apply.run).toContain("--merge auto --merge-token-env CHANT_MERGE_TOKEN --merge-method squash");
+    expect(apply.env!.CHANT_RESPOND).toBe("wave-refused=off,description=check");
+    expect(apply.env!.CHANT_MERGE_TOKEN).toBe("${{ secrets.CHANT_MERGE_TOKEN }}");
+  });
+
+  test("without them, neither job changes", () => {
+    const plain = gen({ applyBeforeMerge: true });
+    const post = plain.jobs["plan-note"]!.steps.at(-1)!;
+    expect(post.run).not.toContain("--decide-backend");
+    expect(post.env!.CHANT_RESPOND).toBeUndefined();
+    expect(JSON.stringify(plain)).not.toContain("--merge auto");
+  });
+});

package/src/components/generate-pr-pipeline.runners.test.ts

@@ -0,0 +1,61 @@
+/**
+ * The pull request loop's runners, variables and passed secrets on GitHub
+ * (#4625): every job on its stage's runner, and the jobs that plan or apply
+ * with the variables and the secrets mapped from the repository's. Written
+ * for the ci-products post-merge pass.
+ */
+
+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", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const, lock: "lock" as const, unlock: "unlock" as const } };
+
+type Step = { name?: string; run?: string; env?: Record<string, string> };
+type Doc = { jobs: Record<string, { "runs-on": unknown; steps: Step[] }> };
+
+const doc = parseYAML(
+  generateGithubPipeline(ESTATE, {
+    env: "prod",
+    prLoop: {
+      words: WORDS,
+      previewComment: true,
+      locks: "plan",
+      applyOnMerge: true,
+      runners: { plan: ["self-hosted", "big"], apply: "deployer", default: "small" },
+      variables: { REGION: "eu-west-1" },
+      secrets: { DB_PASSWORD: "PROD_DB_PASSWORD" },
+      parallelism: 2,
+    },
+  }).yaml,
+) as Doc;
+
+describe("the GitHub pull request loop's runners and variables (#4625)", () => {
+  test("every job runs on its stage's runner", () => {
+    expect(doc.jobs.plan!["runs-on"]).toEqual(["self-hosted", "big"]);
+    expect(doc.jobs["comment-preview"]!["runs-on"]).toEqual(["self-hosted", "big"]);
+    expect(doc.jobs.apply!["runs-on"]).toBe("deployer");
+    expect(doc.jobs.record!["runs-on"]).toBe("deployer");
+    for (const name of ["plan-note", "comment-preview-note", "lock", "unlock", "comment-lock", "comment-unlock"]) expect(doc.jobs[name]!["runs-on"], name).toBe("small");
+  });
+
+  test("the plan step gets the variable and the secret, and still drops the forge tokens first", () => {
+    const step = doc.jobs.plan!.steps.find((s) => s.name === "Plan the members this pull request reaches")!;
+    expect(step.env).toMatchObject({ REGION: "eu-west-1", DB_PASSWORD: "${{ secrets.PROD_DB_PASSWORD }}" });
+    expect(step.env).not.toHaveProperty("GITHUB_TOKEN");
+    expect(step.run!.split("\n")[0]).toContain("unset");
+    expect(step.run).toContain("--parallelism 2");
+  });
+
+  test("the apply step gets them too", () => {
+    const step = doc.jobs.apply!.steps.find((s) => s.run?.includes("ci run apply"))!;
+    expect(step.env).toMatchObject({ REGION: "eu-west-1", DB_PASSWORD: "${{ secrets.PROD_DB_PASSWORD }}" });
+  });
+
+  test("without runners every job keeps the forge's default", () => {
+    const plain = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: {} }).yaml) as Doc;
+    expect(plain.jobs.plan!["runs-on"]).toBe("ubuntu-latest");
+  });
+});

package/src/components/generate-pr-pipeline.stale-notes.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Stale marking on GitHub (#4628): with staleNotes the note job passes the
+ * target branch's commit, and a stale-notes job on a push to the branch
+ * runs `pr-post --stale` at the pushed commit with a token that may edit the
+ * notes and set the statuses. Written for the ci-products post-merge pass.
+ */
+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", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const }, bin: "npx --no-install plywood" };
+
+type Step = { name?: string; run?: string; env?: Record<string, string>; uses?: string };
+type Doc = { jobs: Record<string, { if?: string; permissions?: Record<string, string>; steps: Step[] }> };
+const gen = (prLoop: Record<string, unknown>) => parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml) as Doc;
+
+describe("stale notes on GitHub (#4628)", () => {
+  const doc = gen({ words: WORDS, staleNotes: true, previewComment: true });
+
+  test("the note job passes the target branch's commit", () => {
+    const post = doc.jobs["plan-note"]!.steps.at(-1)!;
+    expect(post.run).toContain('--tip "$TIP_SHA"');
+    expect(post.env!.TIP_SHA).toBe("${{ github.event.pull_request.base.sha }}");
+  });
+
+  test("a stale-notes job on a push marks the open notes stale, naming the preview comment", () => {
+    const job = doc.jobs["stale-notes"]!;
+    expect(job.if).toBe("github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')");
+    expect(job.permissions).toEqual({ contents: "read", "pull-requests": "write", statuses: "write" });
+    const step = job.steps.at(-1)!;
+    expect(step.run).toBe('npx --no-install plywood components pr-post --stale --tip "$TIP_SHA" --env prod --forge github --preview-comment');
+    expect(step.env).toEqual({ TIP_SHA: "${{ github.sha }}", GITHUB_TOKEN: "${{ github.token }}" });
+  });
+
+  test("without staleNotes, no job and no tip", () => {
+    const plain = gen({ words: WORDS });
+    expect(plain.jobs["stale-notes"]).toBeUndefined();
+    expect(plain.jobs["plan-note"]!.steps.at(-1)!.run).not.toContain("--tip");
+  });
+});