@intentius/chant-lexicon-github 0.124.40 → 0.124.41

package/src/components/__fixtures__/pr-loop-waves.github.golden.yml

@@ -24,20 +24,74 @@ jobs:
     container: node:22
     permissions:
       contents: read
-      pull-requests: write
-      statuses: write
+    outputs:
+      report_0: '${{ steps.plan.outputs.report_0 }}'
     steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Check out the change
+        env:
+          CHANT_CHECKOUT_TOKEN: '${{ github.token }}'
+        run: |
+          set -eu
+          git config --global --add safe.directory "$PWD" 2>/dev/null || true
+          [ -d .git ] || git init -q .
+          git remote get-url origin >/dev/null 2>&1 || git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"
+          if [ -n "${CHANT_CHECKOUT_TOKEN:-}" ]; then
+            chant_auth="$(printf 'x-access-token:%s' "$CHANT_CHECKOUT_TOKEN" | base64 | tr -d '\n')"
+            export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraheader GIT_CONFIG_VALUE_0="AUTHORIZATION: basic $chant_auth"
+            unset chant_auth
+          fi
+          ref="$GITHUB_REF"
+          want="$GITHUB_SHA"
+          case "$ref" in
+            refs/heads/*) target="refs/remotes/origin/${ref#refs/heads/}" ;;
+            refs/tags/*) target="$ref" ;;
+            refs/*) target="refs/remotes/${ref#refs/}" ;;
+            *) target="refs/remotes/origin/chant-head" ;;
+          esac
+          if git rev-parse -q --verify HEAD >/dev/null; then git clean -ffdxq; fi
+          git -c protocol.version=2 fetch -q --prune --no-recurse-submodules origin '+refs/heads/*:refs/remotes/origin/*' '+refs/tags/*:refs/tags/*' "+$want:$target"
+          git -c protocol.version=2 fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true
+          case "$ref" in
+            refs/heads/*) git checkout -q --force -B "${ref#refs/heads/}" "$target" ;;
+            *) git checkout -q --force --detach "$target" ;;
+          esac
+      - run: |
+          if [ -z "${CHANT_NO_FORGE_TOKEN:-}" ] && [ "${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "${0##*/}" = sh ] || [ "${0##*/}" = bash ] || [ "${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v sh >/dev/null 2>&1; then exec env -u CHANT_FORGE_TOKEN -u CHANT_GITHUB_TOKEN -u CHANT_FORGEJO_TOKEN -u CHANT_GITLAB_TOKEN -u CHANT_CHECKOUT_TOKEN -u GITHUB_TOKEN -u GH_TOKEN -u FORGEJO_TOKEN -u GITEA_TOKEN -u GITLAB_TOKEN -u CI_JOB_TOKEN -u ACTIONS_RUNTIME_TOKEN CHANT_NO_FORGE_TOKEN=1 sh -e "$0"; fi; unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
+          command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
       - name: Plan the members this pull request reaches
+        id: plan
         env:
           BASE_SHA: '${{ github.event.pull_request.base.sha }}'
           PR_NUMBER: '${{ github.event.pull_request.number }}'
-          GITHUB_TOKEN: '${{ github.token }}'
           CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
-        run: chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github --wave-gate release
+        run: |
+          if [ -z "${CHANT_NO_FORGE_TOKEN:-}" ] && [ "${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "${0##*/}" = sh ] || [ "${0##*/}" = bash ] || [ "${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v sh >/dev/null 2>&1; then exec env -u CHANT_FORGE_TOKEN -u CHANT_GITHUB_TOKEN -u CHANT_FORGEJO_TOKEN -u CHANT_GITLAB_TOKEN -u CHANT_CHECKOUT_TOKEN -u GITHUB_TOKEN -u GH_TOKEN -u FORGEJO_TOKEN -u GITEA_TOKEN -u GITLAB_TOKEN -u CI_JOB_TOKEN -u ACTIONS_RUNTIME_TOKEN CHANT_NO_FORGE_TOKEN=1 sh -e "$0"; fi; unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
+          chant_report="$PWD/.chant/pr"
+          chant_handover() { node -e 'const fs=require("fs"),p=require("path"),z=require("zlib");const [dir,out]=process.argv.slice(1);const CHUNK=450000,PARTS=1,NOTE=["pr-plan.json","pr-note.md"];const all={};const walk=(d,r)=>{let n=[];try{n=fs.readdirSync(d).sort()}catch{return}for(const x of n){const f=p.join(d,x),k=r?r+"/"+x:x;let s;try{s=fs.lstatSync(f)}catch{continue}if(s.isDirectory())walk(f,k);else if(s.isFile())all[k]=fs.readFileSync(f).toString("base64")}};walk(dir,"");const pack=(o)=>z.gzipSync(JSON.stringify(o)).toString("base64");let b=pack(all);if(b.length>CHUNK*PARTS){b=pack(Object.fromEntries(Object.entries(all).filter(([k])=>NOTE.includes(k))));if(b.length>CHUNK*PARTS){b=pack({});console.error("chant: the plan report is too large to hand to the note job, even cut to the report and the note; it hands on none of it")}else console.error("chant: the plan report is too large to hand to the note job whole; it hands on pr-plan.json and pr-note.md")}let o="";for(let i=0;i*CHUNK<b.length;i++)o+="report_"+i+"="+b.slice(i*CHUNK,(i+1)*CHUNK)+"\n";fs.appendFileSync(out,o);' "$chant_report" "${GITHUB_OUTPUT:-/dev/null}" || echo "chant: the plan report could not be handed to the note job" >&2; }
+          trap chant_handover EXIT
+          chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github --wave-gate release
+  plan-note:
+    needs:
+      - plan
+    if: always() && github.event_name == 'pull_request' && (needs.plan.result == 'success' || needs.plan.result == 'failure')
+    runs-on: ubuntu-latest
+    container: node:22
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: write
+      statuses: write
+    steps:
+      - name: Check out the target branch's commit
+        uses: actions/checkout@v7
+        with:
+          ref: '${{ github.event.pull_request.base.sha }}'
+      - name: Take the plan report from the plan job
+        run: |
+          set -u
+          node -e 'const fs=require("fs"),p=require("path"),z=require("zlib");const dir=process.argv[1];let b="";for(const l of fs.readFileSync(0,"utf8").split("\n")){if(!l.trim())continue;let s="";try{s=JSON.parse(l)}catch{}if(typeof s==="string")b+=s}if(!b){console.log("chant: the plan job handed on no report");process.exit(0)}let files;try{files=JSON.parse(z.gunzipSync(Buffer.from(b,"base64"),{maxOutputLength:268435456}).toString("utf8"))}catch(e){console.log("chant: the report the plan job handed on does not read: "+e.message);process.exit(0)}if(!files||typeof files!=="object"||Array.isArray(files)){console.log("chant: the report the plan job handed on is not a set of files");process.exit(0)}let n=0;for(const [k,v] of Object.entries(files)){const parts=k.split("/");if(typeof v!=="string"||k.length>1024||parts.some((x)=>!x||x==="."||x===".."||/[\\\x00-\x1f]/.test(x))){console.log("chant: left out "+JSON.stringify(k));continue}try{const f=p.join(dir,...parts);fs.mkdirSync(p.dirname(f),{recursive:true});fs.writeFileSync(f,Buffer.from(v,"base64"));n++}catch(e){console.log("chant: could not write "+JSON.stringify(k)+": "+e.message)}}console.log("chant: took "+n+" report files from the plan job")' .chant/pr <<'END_OF_REPORT'
+          ${{ toJSON(needs.plan.outputs.report_0) }}
+          END_OF_REPORT
       - name: Keep the plan report
         if: always()
         uses: actions/upload-artifact@v4
@@ -46,6 +100,14 @@ jobs:
           path: .chant/pr
           if-no-files-found: ignore
           include-hidden-files: true
+      - name: Post the plan note and chant/plan
+        if: always()
+        env:
+          PR_NUMBER: '${{ github.event.pull_request.number }}'
+          HEAD_SHA: '${{ github.sha }}'
+          PLAN_RESULT: '${{ needs.plan.result }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+        run: chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge github --result "$PLAN_RESULT"
   record:
     if: github.event_name == 'push'
     runs-on: ubuntu-latest
@@ -126,7 +188,7 @@ jobs:
           if-no-files-found: ignore
           include-hidden-files: true
   apply-wave-2:
-    if: github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'
+    if: '!cancelled() && needs.apply-wave-1.result != ''skipped'' && (github.event_name == ''workflow_run'' || github.event_name == ''workflow_dispatch'')'
     runs-on: ubuntu-latest
     needs:
       - apply-wave-1
@@ -176,7 +238,7 @@ jobs:
           if-no-files-found: ignore
           include-hidden-files: true
   apply-wave-3:
-    if: github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'
+    if: '!cancelled() && needs.apply-wave-2.result != ''skipped'' && (github.event_name == ''workflow_run'' || github.event_name == ''workflow_dispatch'')'
     runs-on: ubuntu-latest
     needs:
       - apply-wave-2

package/src/components/__fixtures__/pr-loop.github.golden.yml

@@ -24,20 +24,74 @@ jobs:
     container: node:22
     permissions:
       contents: read
-      pull-requests: write
-      statuses: write
+    outputs:
+      report_0: '${{ steps.plan.outputs.report_0 }}'
     steps:
-      - uses: actions/checkout@v7
-        with:
-          fetch-depth: 0
-      - run: command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
+      - name: Check out the change
+        env:
+          CHANT_CHECKOUT_TOKEN: '${{ github.token }}'
+        run: |
+          set -eu
+          git config --global --add safe.directory "$PWD" 2>/dev/null || true
+          [ -d .git ] || git init -q .
+          git remote get-url origin >/dev/null 2>&1 || git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY"
+          if [ -n "${CHANT_CHECKOUT_TOKEN:-}" ]; then
+            chant_auth="$(printf 'x-access-token:%s' "$CHANT_CHECKOUT_TOKEN" | base64 | tr -d '\n')"
+            export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraheader GIT_CONFIG_VALUE_0="AUTHORIZATION: basic $chant_auth"
+            unset chant_auth
+          fi
+          ref="$GITHUB_REF"
+          want="$GITHUB_SHA"
+          case "$ref" in
+            refs/heads/*) target="refs/remotes/origin/${ref#refs/heads/}" ;;
+            refs/tags/*) target="$ref" ;;
+            refs/*) target="refs/remotes/${ref#refs/}" ;;
+            *) target="refs/remotes/origin/chant-head" ;;
+          esac
+          if git rev-parse -q --verify HEAD >/dev/null; then git clean -ffdxq; fi
+          git -c protocol.version=2 fetch -q --prune --no-recurse-submodules origin '+refs/heads/*:refs/remotes/origin/*' '+refs/tags/*:refs/tags/*' "+$want:$target"
+          git -c protocol.version=2 fetch -q --no-tags origin '+refs/heads/chant/lifecycle:refs/heads/chant/lifecycle' 2>/dev/null || true
+          case "$ref" in
+            refs/heads/*) git checkout -q --force -B "${ref#refs/heads/}" "$target" ;;
+            *) git checkout -q --force --detach "$target" ;;
+          esac
+      - run: |
+          if [ -z "${CHANT_NO_FORGE_TOKEN:-}" ] && [ "${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "${0##*/}" = sh ] || [ "${0##*/}" = bash ] || [ "${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v sh >/dev/null 2>&1; then exec env -u CHANT_FORGE_TOKEN -u CHANT_GITHUB_TOKEN -u CHANT_FORGEJO_TOKEN -u CHANT_GITLAB_TOKEN -u CHANT_CHECKOUT_TOKEN -u GITHUB_TOKEN -u GH_TOKEN -u FORGEJO_TOKEN -u GITEA_TOKEN -u GITLAB_TOKEN -u CI_JOB_TOKEN -u ACTIONS_RUNTIME_TOKEN CHANT_NO_FORGE_TOKEN=1 sh -e "$0"; fi; unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
+          command -v tofu >/dev/null 2>&1 || (curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh && sh /tmp/install-opentofu.sh --install-method standalone)
       - name: Plan the members this pull request reaches
+        id: plan
         env:
           BASE_SHA: '${{ github.event.pull_request.base.sha }}'
           PR_NUMBER: '${{ github.event.pull_request.number }}'
-          GITHUB_TOKEN: '${{ github.token }}'
           CHANT_RUNNER_KEY: '${{ secrets.CHANT_RUNNER_KEY }}'
-        run: chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github
+        run: |
+          if [ -z "${CHANT_NO_FORGE_TOKEN:-}" ] && [ "${0#*/}" != "$0" ] && [ -f "$0" ] && ! { [ "${0##*/}" = sh ] || [ "${0##*/}" = bash ] || [ "${0##*/}" = dash ]; } && command -v env >/dev/null 2>&1 && command -v sh >/dev/null 2>&1; then exec env -u CHANT_FORGE_TOKEN -u CHANT_GITHUB_TOKEN -u CHANT_FORGEJO_TOKEN -u CHANT_GITLAB_TOKEN -u CHANT_CHECKOUT_TOKEN -u GITHUB_TOKEN -u GH_TOKEN -u FORGEJO_TOKEN -u GITEA_TOKEN -u GITLAB_TOKEN -u CI_JOB_TOKEN -u ACTIONS_RUNTIME_TOKEN CHANT_NO_FORGE_TOKEN=1 sh -e "$0"; fi; unset CHANT_FORGE_TOKEN CHANT_GITHUB_TOKEN CHANT_FORGEJO_TOKEN CHANT_GITLAB_TOKEN CHANT_CHECKOUT_TOKEN GITHUB_TOKEN GH_TOKEN FORGEJO_TOKEN GITEA_TOKEN GITLAB_TOKEN CI_JOB_TOKEN ACTIONS_RUNTIME_TOKEN
+          chant_report="$PWD/.chant/pr"
+          chant_handover() { node -e 'const fs=require("fs"),p=require("path"),z=require("zlib");const [dir,out]=process.argv.slice(1);const CHUNK=450000,PARTS=1,NOTE=["pr-plan.json","pr-note.md"];const all={};const walk=(d,r)=>{let n=[];try{n=fs.readdirSync(d).sort()}catch{return}for(const x of n){const f=p.join(d,x),k=r?r+"/"+x:x;let s;try{s=fs.lstatSync(f)}catch{continue}if(s.isDirectory())walk(f,k);else if(s.isFile())all[k]=fs.readFileSync(f).toString("base64")}};walk(dir,"");const pack=(o)=>z.gzipSync(JSON.stringify(o)).toString("base64");let b=pack(all);if(b.length>CHUNK*PARTS){b=pack(Object.fromEntries(Object.entries(all).filter(([k])=>NOTE.includes(k))));if(b.length>CHUNK*PARTS){b=pack({});console.error("chant: the plan report is too large to hand to the note job, even cut to the report and the note; it hands on none of it")}else console.error("chant: the plan report is too large to hand to the note job whole; it hands on pr-plan.json and pr-note.md")}let o="";for(let i=0;i*CHUNK<b.length;i++)o+="report_"+i+"="+b.slice(i*CHUNK,(i+1)*CHUNK)+"\n";fs.appendFileSync(out,o);' "$chant_report" "${GITHUB_OUTPUT:-/dev/null}" || echo "chant: the plan report could not be handed to the note job" >&2; }
+          trap chant_handover EXIT
+          chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge github
+  plan-note:
+    needs:
+      - plan
+    if: always() && github.event_name == 'pull_request' && (needs.plan.result == 'success' || needs.plan.result == 'failure')
+    runs-on: ubuntu-latest
+    container: node:22
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: write
+      statuses: write
+    steps:
+      - name: Check out the target branch's commit
+        uses: actions/checkout@v7
+        with:
+          ref: '${{ github.event.pull_request.base.sha }}'
+      - name: Take the plan report from the plan job
+        run: |
+          set -u
+          node -e 'const fs=require("fs"),p=require("path"),z=require("zlib");const dir=process.argv[1];let b="";for(const l of fs.readFileSync(0,"utf8").split("\n")){if(!l.trim())continue;let s="";try{s=JSON.parse(l)}catch{}if(typeof s==="string")b+=s}if(!b){console.log("chant: the plan job handed on no report");process.exit(0)}let files;try{files=JSON.parse(z.gunzipSync(Buffer.from(b,"base64"),{maxOutputLength:268435456}).toString("utf8"))}catch(e){console.log("chant: the report the plan job handed on does not read: "+e.message);process.exit(0)}if(!files||typeof files!=="object"||Array.isArray(files)){console.log("chant: the report the plan job handed on is not a set of files");process.exit(0)}let n=0;for(const [k,v] of Object.entries(files)){const parts=k.split("/");if(typeof v!=="string"||k.length>1024||parts.some((x)=>!x||x==="."||x===".."||/[\\\x00-\x1f]/.test(x))){console.log("chant: left out "+JSON.stringify(k));continue}try{const f=p.join(dir,...parts);fs.mkdirSync(p.dirname(f),{recursive:true});fs.writeFileSync(f,Buffer.from(v,"base64"));n++}catch(e){console.log("chant: could not write "+JSON.stringify(k)+": "+e.message)}}console.log("chant: took "+n+" report files from the plan job")' .chant/pr <<'END_OF_REPORT'
+          ${{ toJSON(needs.plan.outputs.report_0) }}
+          END_OF_REPORT
       - name: Keep the plan report
         if: always()
         uses: actions/upload-artifact@v4
@@ -46,6 +100,14 @@ jobs:
           path: .chant/pr
           if-no-files-found: ignore
           include-hidden-files: true
+      - name: Post the plan note and chant/plan
+        if: always()
+        env:
+          PR_NUMBER: '${{ github.event.pull_request.number }}'
+          HEAD_SHA: '${{ github.sha }}'
+          PLAN_RESULT: '${{ needs.plan.result }}'
+          GITHUB_TOKEN: '${{ github.token }}'
+        run: chant components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge github --result "$PLAN_RESULT"
   record:
     if: github.event_name == 'push'
     runs-on: ubuntu-latest

package/src/components/ci-jobs.ts

@@ -46,6 +46,19 @@ export function keepRecordStep(name: string, artifact: string, path: string): Re
   };
 }
 
+/**
+ * The `if:` of a wave job after the first (#4291): it runs when the wave
+ * before it failed, so a failed member blocks only the members that depend
+ * on it, and the next wave's job blocks those and runs the rest. It does not
+ * run when the run was cancelled, or when the job before it was skipped
+ * (its own condition was false). `condition` is the job's own condition,
+ * which still has to hold.
+ */
+export function afterEarlierWave(previous: string, condition?: string): string {
+  const runs = `!cancelled() && needs.${previous}.result != 'skipped'`;
+  return condition ? `${runs} && (${condition})` : runs;
+}
+
 /** A `concurrency:` mapping: one run at a time per group. */
 export function concurrency(group: string, cancelInProgress = false): Record<string, unknown> {
   return { group, "cancel-in-progress": cancelInProgress };

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

@@ -434,6 +434,9 @@ describe("generateGithubPipeline: gated waves (#3049)", () => {
     const parsed = parseYAML(result.yaml) as { jobs: Record<string, { needs?: string[]; steps: Array<Record<string, unknown>> }> };
     expect(Object.keys(parsed.jobs)).toEqual(["wave-1", "wave-2", "wave-3"]);
     expect(parsed.jobs["wave-2"].needs).toEqual(["wave-1"]);
+    // #4291: wave 2 runs after wave 1 failed, so a failure blocks only its dependents.
+    expect((parsed.jobs["wave-2"] as Record<string, unknown>).if).toBe("!cancelled() && needs.wave-1.result != 'skipped'");
+    expect((parsed.jobs["wave-1"] as Record<string, unknown>).if).toBeUndefined();
 
     const steps = parsed.jobs["wave-2"].steps;
     expect(steps[0].with).toEqual({ "fetch-depth": 0 });

package/src/components/generate-pipeline.ts

@@ -59,7 +59,9 @@
 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_RUNNER } from "@intentius/chant/ci-jobs";
+import { CI_IMAGE, ciJobName, dirnameOf, fillCommand, GITHUB_JOB_TOKEN, GITHUB_RUNNER } 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 {
   GREEN_TAG_PATTERN,
   GREEN_TICK_WORKFLOW,
@@ -70,9 +72,15 @@ import {
   prApplyRecordKey,
   prApplyWaveJobName,
   prLoopJobs,
+  prLoopPostJob,
   prLoopSetup,
+  PR_PLAN_NOTE_JOB,
   prLoopWaveJobs,
   prLoopWithWaves,
+  prEnvJobs,
+  PR_ENV_REPORT_DIR,
+  PR_ENV_SWEEP_CRON,
+  PR_ENV_POST_JOB,
 } from "@intentius/chant/components/pr-pipeline";
 import { memberRepoPath } from "@intentius/chant/lexicon";
 import type {
@@ -81,7 +89,8 @@ import type {
   ComponentPipelineResult as GenerateGithubResult,
   PipelineMember,
 } from "@intentius/chant/lexicon";
-import { checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs";
+import { afterEarlierWave, checkoutStep, concurrency, downloadArtifactStep, emitWorkflowYAML, keepRecordStep, runSteps, UPLOAD_ARTIFACT } from "./ci-jobs";
+import { actionRef } from "../action-pins";
 
 export type { GeneratedJob, GenerateGithubOptions, GenerateGithubResult };
 
@@ -122,6 +131,9 @@ export interface GithubPipelineDoc {
   jobs: GeneratedJob[];
 }
 
+/** The plan job's last step, whose outputs carry its report to the plan-note job (#4295). */
+const PLAN_STEP_ID = "plan";
+
 /** 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";
 const WAVE_STEP_ID = "apply";
@@ -158,6 +170,8 @@ function gatedWaveGithubDoc(
     steps.push(...runSteps(prLoopSetup(image)), ...runSteps(beforeScript), { run: job.command.join(" ") }, ...runSteps(extraScript));
     steps.push(keepRecordStep(`Upload the record for wave ${job.wave}`, waveRecordArtifact(job.wave), GATED_WAVE_RECORD));
     jobsDoc[job.jobName] = {
+      // #4291: a wave runs after one that failed, and blocks only what depends on the failure.
+      ...(job.needs.length > 0 ? { if: afterEarlierWave(job.needs[0]!) } : {}),
       "runs-on": GITHUB_RUNNER,
       ...(job.needs.length > 0 ? { needs: job.needs } : {}),
       container: image,
@@ -203,6 +217,26 @@ function gatedWaveGithubDoc(
  * for the pushed commit, so wave k reads what wave k-1 left, and a re-run of
  * a wave that stopped at its gate reads what it left itself. Each keeps its
  * report as `chant-pr-apply-wave-<k>`.
+ *
+ * The plan job holds no forge token while the pull request's code runs
+ * (#4295, `@intentius/chant/ci-handover`). It checks the change out with a
+ * script that gives the job's token to its fetches alone, starts every later
+ * step again without the token variables, and ends with the plan step, which
+ * hands its report on as the job's outputs. The `plan-note` job then checks
+ * out the target branch's commit, takes the report back, keeps it as the
+ * `chant-pr-plan` artifact, and posts the note and `chant/plan` with
+ * `chant components pr-post`. Only the note job may write to the pull
+ * request and its statuses.
+ *
+ * With `identity` (#4296, `@intentius/chant/ci-identity`) the plan, record
+ * and apply jobs get `id-token: write`, and each starts with a step that
+ * trades the job's OIDC token for its cloud identity before anything is
+ * checked out: the plan and record jobs for the plan identity, the apply
+ * jobs for the apply identity. The trade leaves the credentials in
+ * `GITHUB_ENV`. Every later step of the plan job starts without the
+ * variables a token is requested with, so the pull request's code holds no
+ * OIDC token and cannot request one, and the plan job names no apply
+ * identity.
  */
 function prLoopGithubDoc(
   components: DriverComponent[],
@@ -235,8 +269,18 @@ function prLoopGithubDoc(
     uses: "actions/cache/save@v4",
     with: { path: recordPath, key: recordKey(wave) },
   });
+  // #4296: the step that trades the job's OIDC token for its cloud identity, before the checkout.
+  const identity = loop.identity;
+  const tradeStep = (spec: CloudTradeSpec, which: "plan" | "apply"): Record<string, unknown> => ({
+    name: `Trade the job's OIDC token for the ${which} identity`,
+    ...(rooted ? {} : { "working-directory": "." }),
+    env: { [TRADE_SPEC_ENV]: JSON.stringify(spec) },
+    run: tradeLine("$GITHUB_ENV", "github-env"),
+  });
+  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}`;
   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(beforeScript),
@@ -267,12 +311,13 @@ function prLoopGithubDoc(
   const onGreen = forgejo ? "startsWith(github.ref, 'refs/tags/ci/green/')" : "github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch'";
   const onPush = loop.applyOnMerge && forgejo ? "github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')" : "github.event_name == 'push'";
   const applyJob = (job: typeof plan, needs: string[], name: string) => ({
-    if: job.jobName === "record" ? onPush : onGreen,
+    // #4291: a wave after the first runs after one that failed, and blocks only what depends on the failure.
+    if: job.jobName === "record" ? onPush : needs.length > 0 && job.wave ? afterEarlierWave(needs[0]!, onGreen) : onGreen,
     "runs-on": GITHUB_RUNNER,
     ...(needs.length > 0 ? { needs } : {}),
     container: image,
     concurrency: concurrency(prApplyGroup(env, member?.name)),
-    permissions: { contents: "write", "pull-requests": "write", statuses: "write" },
+    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),
   });
@@ -287,31 +332,84 @@ function prLoopGithubDoc(
       ? [["apply", applyJob(apply, [], "Apply the newest green commit under the merged changes' approvals")]]
       : [];
   const applyJobs: Array<[string, Record<string, unknown>]> = [recordJob, ...greenJobs];
+  // #4295: the plan job runs the pull request's code and holds no forge token while it does.
+  const forgeName = loop.forge ?? "github";
+  // #4296: once the plan job has traded its OIDC token, its later steps start without the variables a token is requested with.
+  const drop = dropForgeTokens("sh", identity ? OIDC_REQUEST_VARS : []);
+  const headStep = (line: string, name?: string): Record<string, unknown> => ({ ...(name ? { name } : {}), run: `${drop}\n${line}` });
+  const planSteps: Array<Record<string, unknown>> = [
+    // #4296: the trade runs first, before the change is checked out, with the plan identity alone.
+    ...(identity ? [tradeStep(identity.plan, "plan")] : []),
+    // A script, not actions/checkout, whose post step runs at the job's end with the token as its input.
+    {
+      name: "Check out the change",
+      ...(rooted ? {} : { "working-directory": "." }),
+      env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
+      run: checkoutScript(true, true),
+    },
+    ...[...prLoopSetup(image), ...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.
+    {
+      name: "Plan the members this pull request reaches",
+      id: PLAN_STEP_ID,
+      env: plan.run.env,
+      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);
+  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: actionRef("actions/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 },
+  ];
+  // #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;
   const jobsDoc: Record<string, unknown> = {
     plan: {
-      if: "github.event_name == 'pull_request'",
+      if: prEnv ? "github.event_name == 'pull_request' && github.event.action != 'closed'" : "github.event_name == 'pull_request'",
       "runs-on": GITHUB_RUNNER,
       container: image,
-      permissions: { contents: "read", "pull-requests": "write", statuses: "write" },
-      steps: steps(plan, "Plan the members this pull request reaches"),
+      permissions: withIdToken({ contents: "read" }),
+      outputs: handoverOutputs(PLAN_STEP_ID, forgeName),
+      steps: planSteps,
+    },
+    [PR_PLAN_NOTE_JOB]: {
+      needs: ["plan"],
+      if: "always() && github.event_name == 'pull_request' && (needs.plan.result == 'success' || needs.plan.result == 'failure')",
+      "runs-on": GITHUB_RUNNER,
+      container: image,
+      // #4289: `actions: read` lets pr-post ask when each scheduled watch or reconcile Op last ran.
+      permissions: { actions: "read", contents: "read", "pull-requests": "write", statuses: "write" },
+      steps: noteSteps,
     },
     ...Object.fromEntries(applyJobs),
+    ...(prEnv ? prEnv.jobs : {}),
   };
   const applyNames = applyJobs.map(([name]) => name);
+  const on: Record<string, unknown> = !loop.applyOnMerge
+    ? { pull_request: { branches: [branch] }, push: { branches: [branch] } }
+    : forgejo
+      ? { pull_request: { branches: [branch] }, push: { branches: [branch], tags: [GREEN_TAG_PATTERN] } }
+      : { pull_request: { branches: [branch] }, push: { branches: [branch] }, workflow_run: { workflows: [GREEN_TICK_WORKFLOW], types: ["completed"] }, workflow_dispatch: {} };
+  if (prEnv) {
+    on.pull_request = { branches: [branch], types: ["opened", "synchronize", "reopened", "closed"] };
+    on.schedule = [{ cron: PR_ENV_SWEEP_CRON }];
+  }
   return {
     name: member ? `chant-pr.${member.name}.${env}` : `chant-pr-${env}`,
     environment: env,
-    on: !loop.applyOnMerge
-      ? { pull_request: { branches: [branch] }, push: { branches: [branch] } }
-      : forgejo
-        ? { pull_request: { branches: [branch] }, push: { branches: [branch], tags: [GREEN_TAG_PATTERN] } }
-        : { pull_request: { branches: [branch] }, push: { branches: [branch] }, workflow_run: { workflows: [GREEN_TICK_WORKFLOW], types: ["completed"] }, workflow_dispatch: {} },
+    on,
     ...(rooted ? {} : { defaults: { run: { "working-directory": member!.dir } } }),
     env: { ...options.variables, CHANT_ENV: env },
     jobsDoc,
-    stages: ["plan", ...applyNames],
+    stages: ["plan", PR_PLAN_NOTE_JOB, ...applyNames, ...(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"] },
       ...applyNames.map((name, i) => ({
         jobName: name,
         component: name === "record" ? "merge record" : loop.waveGate ? `green apply, wave ${i}` : "green apply",
@@ -319,10 +417,120 @@ 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]] : [],
       })),
+      ...(prEnv ? prEnv.listed : []),
+    ],
+  };
+}
+
+/**
+ * The jobs of a pull request's environment (#4298). `env-up` runs on an
+ * opened, updated or reopened pull request and runs the change's code, so it
+ * follows the plan job's handover (#4295): a checkout script that alone sees
+ * the job's token, every later step started without the token variables,
+ * and the `pr-env up` step last, handing its report and record on as the
+ * job's outputs. `env-post` checks out the target branch's commit, takes
+ * them back, keeps the record on chant/lifecycle and posts the note.
+ * `env-down` runs when the pull request closes and `env-sweep` on the
+ * schedule, both from the base branch's code: a teardown reads the markers
+ * off the live resources and builds nothing of the change. `env-up` and
+ * `env-down` run one at a time per pull request, and a close waits for an
+ * apply still running rather than cancelling it.
+ */
+function prEnvGithubJobs(
+  forge: "github" | "forgejo",
+  image: string,
+  beforeScript: string[],
+  extraScript: string[],
+  loop: NonNullable<GenerateGithubOptions["prLoop"]>,
+  member: GenerateGithubOptions["member"],
+): { jobs: Record<string, unknown>; listed: GeneratedJob[] } {
+  const [up, post, down, sweep] = prEnvJobs(forge, loop, member?.name);
+  const rooted = !member || member.dir === "." || member.dir === "";
+  const reportPath = member ? memberRepoPath(member, PR_ENV_REPORT_DIR) : PR_ENV_REPORT_DIR;
+  const prNumber = "${{ github.event.pull_request.number }}";
+  const group = `chant-pr-env-${member ? `${member.name}-` : ""}${prNumber}`;
+  const writes = { contents: "write", "pull-requests": "write", statuses: "write" };
+  const keep = (name: string) => ({ name: `Keep the ${name} report`, if: "always()", uses: UPLOAD_ARTIFACT, with: { name: `chant-pr-${name}`, path: reportPath, "if-no-files-found": "ignore", "include-hidden-files": true } });
+  const opened = "github.event_name == 'pull_request' && github.event.action != 'closed'";
+
+  // #4295: env-up runs the change's code and holds no forge token while it does.
+  const drop = dropForgeTokens("sh");
+  const headStep = (line: string, name?: string, env?: Record<string, string>): Record<string, unknown> => ({ ...(name ? { name } : {}), ...(env ? { env } : {}), run: `${drop}\n${line}` });
+  const upJob = {
+    if: opened,
+    "runs-on": GITHUB_RUNNER,
+    container: image,
+    concurrency: concurrency(group),
+    permissions: { contents: "read" },
+    outputs: handoverOutputs(PR_ENV_UP_STEP_ID, forge),
+    steps: [
+      {
+        name: "Check out the change",
+        ...(rooted ? {} : { "working-directory": "." }),
+        env: { [CHECKOUT_TOKEN_ENV]: GITHUB_JOB_TOKEN },
+        run: checkoutScript(true, true),
+      },
+      ...[...prLoopSetup(image), ...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.
+      {
+        name: "Apply this pull request's environment once its plan is approved",
+        id: PR_ENV_UP_STEP_ID,
+        env: up.env,
+        run: [drop, ...handoverTrap(PR_ENV_REPORT_DIR, forge), up.command, ...extraScript].join("\n"),
+      },
+    ],
+  };
+  const postJob = {
+    needs: ["env-up"],
+    if: `always() && ${opened} && (needs.env-up.result == 'success' || needs.env-up.result == 'failure')`,
+    "runs-on": GITHUB_RUNNER,
+    container: image,
+    concurrency: concurrency(`chant-pr-env-post-${member ? `${member.name}-` : ""}${prNumber}`),
+    permissions: writes,
+    steps: [
+      // 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: actionRef("actions/checkout"), with: { ref: "${{ github.event.pull_request.base.sha }}", "fetch-depth": 0 } },
+      ...runSteps(beforeScript),
+      { name: "Take the environment's report from the env-up job", run: takeOverScript("env-up", PR_ENV_REPORT_DIR, forge) },
+      keep("env-up"),
+      { name: "Keep the environment's record and post its note", if: "always()", env: post.env, run: post.command },
+    ],
+  };
+  const baseJob = (j: typeof up, condition: string, ref: string, name: string, groupName: string) => ({
+    if: condition,
+    "runs-on": GITHUB_RUNNER,
+    container: image,
+    concurrency: concurrency(groupName),
+    permissions: writes,
+    steps: [
+      { uses: actionRef("actions/checkout"), with: { "fetch-depth": 0, ...(ref ? { ref } : {}) } },
+      ...runSteps(prLoopSetup(image)),
+      ...runSteps(beforeScript),
+      { name, env: j.env, run: j.command },
+      ...runSteps(extraScript),
+      keep(j.jobName),
+    ],
+  });
+  return {
+    jobs: {
+      "env-up": upJob,
+      [PR_ENV_POST_JOB]: postJob,
+      "env-down": baseJob(down, "github.event_name == 'pull_request' && github.event.action == 'closed'", "${{ github.event.pull_request.base.ref }}", "Tear down what this pull request's environment owns", group),
+      "env-sweep": baseJob(sweep, "github.event_name == 'schedule'", "", "Tear down the environments whose TTL passed or whose pull request closed", `chant-pr-env-sweep${member ? `-${member.name}` : ""}`),
+    },
+    listed: [
+      { jobName: "env-up", component: "pull request environment", stage: "env-up", needs: [] },
+      { jobName: PR_ENV_POST_JOB, component: "pull request environment note", stage: PR_ENV_POST_JOB, needs: ["env-up"] },
+      { jobName: "env-down", component: "pull request environment teardown", stage: "env-down", needs: [] },
+      { jobName: "env-sweep", component: "pull request environment sweep", stage: "env-sweep", needs: [] },
     ],
   };
 }
 
+/** The id of the `pr-env up` step, whose outputs carry the report (#4295). */
+const PR_ENV_UP_STEP_ID = "env-up";
+
 /** The file a producer dumps its resolved outputs to, and a dependent seeds from — one per component, matching gitlab's naming so both generators produce interchangeable artifacts. */
 function outputsFile(name: string): string {
   return `${name}.outputs.json`;