@intentius/chant 0.124.40 → 0.124.42

package/src/components/pr-hooks.ts

@@ -0,0 +1,157 @@
+/**
+ * Stage hooks on the pull-request path (#4288): `ci.hooks` in the workspace
+ * declaration, run by `chant components pr-plan`, `pr-record` and
+ * `pr-apply` with the runner an Op waves job uses (`runStageHooks`).
+ *
+ * The hooks are read from the declaration at the base the job measures the
+ * change from, never from the change itself, so a pull request cannot add,
+ * edit or remove a hook its own jobs run. The top level's hooks run first,
+ * then those of the member the job runs in. When the base has no workspace
+ * declaration no hook runs. When the declaration at base cannot be read and
+ * the working tree's names hooks, the job refuses to run rather than guess.
+ *
+ * The runs a hook sees are the components the change selects, in apply
+ * order: `{target}` and `CHANT_TARGET` name one, and `targets` match their
+ * names. After the plan, a `perRun` hook's `{plan}` is a JSON file with that
+ * component's members and the plans its steps hand the apply.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import type { OpWaveHook, OpWaveHookMoment, OpWaveHooks } from "../op/op-waves";
+import { PR_LOOP_HOOK_MOMENTS } from "../op/op-waves";
+import { runStageHooks, type OpWaveExec, type OpWaveHookRun, type StageHooksRun } from "../op/op-waves-run";
+import { readDeclaration, WorkspaceReadError, type Declaration } from "../workspace/declaration";
+import { memberAtCwd } from "../workspace/security";
+import { locateWorkspace } from "../workspace/which-chant";
+import type { PrHookOutcome, PrMember } from "../pr-loop";
+
+/** The hooks a pull-request job runs, by moment, and where they were read. */
+export interface PrLoopHooks {
+  hooks: Partial<Record<OpWaveHookMoment, OpWaveHook[]>>;
+  /** The commit they were read at. */
+  base: string;
+  /** A line for the log when none run because the base has no declaration, or could not be read. */
+  note?: string;
+}
+
+/** The hooks of one `ci.hooks` block at `moment`. */
+function at(hooks: OpWaveHooks | null | undefined, moment: OpWaveHookMoment): OpWaveHook[] {
+  const [side, stage] = moment.split("-") as ["before" | "after", string];
+  return ((hooks?.[side] as Record<string, OpWaveHook[] | undefined> | undefined)?.[stage]) ?? [];
+}
+
+/** The hooks `declaration` gives a job run in `cwd`: the top level's, then the member's. */
+export function prLoopHooksOf(declaration: Pick<Declaration, "ci" | "members">, member: string | null): Partial<Record<OpWaveHookMoment, OpWaveHook[]>> {
+  const own = member === null ? null : (declaration.members.find((m) => m.name === member)?.ciHooks ?? null);
+  const out: Partial<Record<OpWaveHookMoment, OpWaveHook[]>> = {};
+  for (const moment of PR_LOOP_HOOK_MOMENTS) {
+    const list = [...at(declaration.ci?.hooks, moment), ...at(own, moment)];
+    if (list.length > 0) out[moment] = list;
+  }
+  return out;
+}
+
+/** Whether the working tree's declaration names any `ci.hooks`. */
+function checkoutNamesHooks(cwd: string): boolean {
+  try {
+    const located = locateWorkspace(cwd);
+    const d = readDeclaration(located.tree);
+    return Object.keys(prLoopHooksOf(d, memberAtCwd({ declaration: d, rootOnDisk: located.rootOnDisk }, cwd))).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The hooks a pull-request job in `cwd` runs, read from the workspace
+ * declaration at `base`. Throws when the declaration at base cannot be read
+ * and the working tree's names hooks.
+ */
+export function prLoopHooksAt(cwd: string, base: string): PrLoopHooks {
+  let declaration: Declaration;
+  let rootOnDisk: string;
+  try {
+    const located = locateWorkspace(cwd, base);
+    declaration = readDeclaration(located.tree);
+    rootOnDisk = located.rootOnDisk;
+  } catch (err) {
+    const missing = err instanceof WorkspaceReadError && (err.code === "declaration-missing" || err.code === "not-a-git-repository");
+    const why = err instanceof Error ? err.message : String(err);
+    if (checkoutNamesHooks(cwd)) {
+      if (missing) return { hooks: {}, base, note: `ci.hooks: the base ${base.slice(0, 12)} has no workspace declaration, so the hooks this change declares do not run until it merges` };
+      throw new Error(`ci.hooks are read from the workspace declaration at ${base.slice(0, 12)}, and it could not be read (${why}), so no hook can be trusted to run`);
+    }
+    return missing ? { hooks: {}, base } : { hooks: {}, base, note: `ci.hooks: the declaration at ${base.slice(0, 12)} could not be read (${why}); this checkout names no hooks, so none run` };
+  }
+  return { hooks: prLoopHooksOf(declaration, memberAtCwd({ declaration, rootOnDisk }, cwd)), base };
+}
+
+/** Where a pull-request job's hooks run, and what they are told. */
+export interface PrHookPlace {
+  /** The gate's op, `pr-<n>`: `{op}` and `CHANT_OP_WAVES`. */
+  op: string;
+  /** The environment: `{wave}`, `CHANT_WAVE` and `CHANT_ENV`. */
+  env: string;
+  stage: "plan" | "apply" | "record";
+  /** The report directory, relative to `cwd`; the runs and plan files go under `<dir>/hooks`. */
+  dir: string;
+  cwd: string;
+  exec?: OpWaveExec;
+  log?: (line: string) => void;
+}
+
+/** What one moment's hooks came to on the pull-request path. */
+export interface PrHooksRun {
+  outcomes: PrHookOutcome[];
+  failed?: string;
+  holds: string[];
+}
+
+/**
+ * Run the hooks of `moment` for `components` (#4288). `plans`, after the
+ * plan, gives each component's members and step plans, written where a
+ * `perRun` hook's `{plan}` points.
+ */
+export function runPrHooks(
+  read: PrLoopHooks,
+  moment: OpWaveHookMoment,
+  place: PrHookPlace,
+  components: readonly string[],
+  planned?: { members: readonly PrMember[]; plans: Record<string, Record<string, unknown>> },
+): PrHooksRun {
+  const hooks = read.hooks[moment];
+  if (!hooks || hooks.length === 0) return { outcomes: [], holds: [] };
+  // Relative to cwd, as an Op waves job's paths are, whether --output was given relative or absolute.
+  const dir = relative(place.cwd, resolve(place.cwd, place.dir, "hooks")) || ".";
+  mkdirSync(join(place.cwd, dir, "plans"), { recursive: true });
+  const runs: OpWaveHookRun[] = components.map((component) => {
+    if (!planned) return { target: component, op: place.op };
+    const plan = join(dir, "plans", `${component.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+    const body = { component, members: planned.members.filter((m) => m.component === component), plans: planned.plans[component] ?? {} };
+    writeFileSync(join(place.cwd, plan), JSON.stringify(body, null, 2) + "\n");
+    return { target: component, op: place.op, plan };
+  });
+  const runsFile = join(dir, "runs.json");
+  writeFileSync(join(place.cwd, runsFile), JSON.stringify({ version: 1, op: place.op, env: place.env, stage: place.stage, base: read.base, hook: moment, runs }, null, 2) + "\n");
+  const ran: StageHooksRun = runStageHooks(moment, hooks, {
+    name: place.op,
+    op: place.op,
+    wave: place.env,
+    runs,
+    runsFile,
+    holdFile: join(dir, "hold.json"),
+    env: { CHANT_ENV: place.env, CHANT_PR_STAGE: place.stage, CHANT_HOOKS_BASE: read.base },
+    cwd: place.cwd,
+    ...(place.exec ? { exec: place.exec } : {}),
+    ...(place.log ? { log: place.log } : {}),
+  });
+  const outcomes = ran.outcomes.map((o): PrHookOutcome => ({
+    moment: o.moment,
+    name: o.name,
+    ...(o.target ? { target: o.target } : {}),
+    exit: o.exit,
+    outcome: o.outcome === "failed" ? "failed" : o.outcome === "held" ? "held" : "passed",
+  }));
+  return { outcomes, ...(ran.failed ? { failed: ran.failed } : {}), holds: ran.holds };
+}

package/src/components/pr-pipeline.ts

@@ -8,8 +8,11 @@
  * values they read from the forge live here so the three cannot disagree.
  *
  * - The plan job runs `chant components pr-plan` against the pull request's
- *   target commit. It posts the note and the `chant/plan` status and writes
- *   nothing to `chant/lifecycle`, since it runs the pull request's code.
+ *   target commit. It writes nothing to `chant/lifecycle` and holds no forge
+ *   token, since it runs the pull request's code (#4295): it writes the note
+ *   and the status into its report with `--no-status`, and the `plan-note`
+ *   job after it posts them with `chant components pr-post`
+ *   ({@link prLoopPostJob}, ../ci-handover.ts).
  * - The record job (#4168 step 1, the default) runs `chant components
  *   pr-record` against the commit the push replaced. It plans the same
  *   members on the merged commit, stores the change set and writes the merge
@@ -81,10 +84,12 @@
 import type { ForgeKind } from "../pr-forge";
 import { PR_APPLY_GATE } from "../pr-loop";
 import { CI_IMAGE, GITHUB_JOB_TOKEN } from "../ci-jobs";
+import { withoutForgeTokens } from "../ci-handover";
 import { EMPTY_TREE_SHA } from "./changed-files";
 import { layerWaves } from "../gated-waves";
 import type { DriverComponent } from "./driver";
 import type { GatedWavePipelineOptions } from "./gated-wave-pipeline";
+import type { PipelineCloudIdentity } from "../ci-identity";
 
 /** The variable `chant ci run` reads its runner key from (`RUNNER_KEY_ENV` in ../workspace/ci-green.ts). */
 const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
@@ -143,6 +148,16 @@ export interface PrLoopPipelineOptions {
    * false, so a merge deploys nothing. `waveGate` needs it.
    */
   applyOnMerge?: boolean;
+  /**
+   * Apply an open pull request before it merges (#4301, ws-106): the apply
+   * job runs `pr-apply --before-merge` at the pull request's head, started
+   * by a `/chant apply` comment on GitHub and Forgejo, or on GitLab by a
+   * pipeline of the target branch with `CHANT_APPLY_PR` set. A merge still
+   * records. `pr-apply` refuses unless the declaration at base sets
+   * `ci.workflow: "apply-before-merge"`. It takes neither `applyOnMerge`,
+   * `waveGate` nor `build`.
+   */
+  applyBeforeMerge?: boolean;
   /**
    * Stream each job's run events (#4007): `--events-json` on both commands,
    * and `CHANT_RUN_EVENTS_DIR` set to {@link PR_LOOP_EVENTS_DIR}. Default false.
@@ -175,11 +190,27 @@ export interface PrLoopPipelineOptions {
    * wave. Set from `--wave-gate` beside `--pr-loop` ({@link prLoopWithWaves}).
    */
   waveGate?: string;
+  /**
+   * The plan and apply cloud identities (#4296), from `ci.identity.cloud`
+   * resolved for the pipeline's environment and member
+   * (`resolveCloudIdentity` in ../ci-identity.ts). The plan job trades its
+   * OIDC token for the plan identity before the checkout, the record job
+   * for the plan identity, and the apply jobs for the apply identity.
+   * Absent: no job requests an OIDC token.
+   */
+  identity?: PipelineCloudIdentity;
   /**
    * Which GitHub-shaped forge the workflow is for. Set by the forgejo
    * generator, which reuses the github one; a caller never needs to.
    */
   forge?: "github" | "forgejo";
+  /**
+   * An environment per open pull request (#4298, `ci.prEnvironment`): an
+   * `env-up` job on each opened, updated or reopened pull request, an
+   * `env-down` job when it closes, and an `env-sweep` job on a schedule
+   * ({@link prEnvJobs}). Set from `--pr-env` beside `--pr-loop`. Default false.
+   */
+  prEnvironment?: boolean;
 }
 
 /** One job's command and the forge values it reads, as environment variables for its step. */
@@ -238,6 +269,10 @@ export function prLoopBuildLines(env: string, options: PrLoopPipelineOptions = {
  */
 export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelineOptions = {}, member?: string): PrLoopJob[] {
   const gate = options.gate ?? PR_APPLY_GATE;
+  const early = options.applyBeforeMerge === true;
+  if (early && options.applyOnMerge) throw new Error("--apply-before-merge applies an open pull request and a merge records, so it takes no --apply-on-merge; pass one of them");
+  if (early && options.waveGate) throw new Error("--apply-before-merge applies the pull request's plan in one job, so it takes no --wave-gate");
+  if (early && (options.build || options.buildCommand)) throw new Error("--apply-before-merge runs no build before its requires checks, so it takes no --pr-build or --pr-build-command yet");
   const common = [
     "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
     ...(member ? ["--member", member] : []),
@@ -254,7 +289,8 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   // #4156: the flags `chant ci run` rebuilds `command` from. It finds the member from the directory it runs in.
   const ciRun = (job: PrLoopJob["jobName"]): string[] => [
     "chant", "ci", "run", job, "--in-place", ...(job === "plan" ? ["--no-push"] : []),
-    ...(job === "apply" ? [] : ["--base", '"$BASE_SHA"']), ...(job === "plan" ? ["--pr", '"$PR_NUMBER"'] : []),
+    ...(job === "apply" && !early ? [] : ["--base", '"$BASE_SHA"']), ...(job === "plan" || (job === "apply" && early) ? ["--pr", '"$PR_NUMBER"'] : []),
+    ...(job === "apply" && early ? ["--apply-before-merge"] : []),
     "--env", env, "--gate", gate, "--forge", forge,
     ...(job !== "record" && options.waveGate ? ["--wave-gate", options.waveGate] : []),
     ...(job !== "plan" && options.branch ? ["--branch", JSON.stringify(options.branch)] : []),
@@ -264,35 +300,54 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
     ...(options.reportUrl ? ["--report-url", JSON.stringify(options.reportUrl)] : []),
   ];
   const runEnv = (env: Record<string, string>): Record<string, string> => (github ? { ...env, [RUNNER_KEY_ENV]: `\${{ secrets.${RUNNER_KEY_ENV} }}` } : env);
+  // #4295: the plan runs the pull request's code, so it gets no forge token. It writes the note and the
+  // status into its report (--no-status), and the plan-note job posts them (prLoopPostJob).
   const planEnv = github
-    ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...jobEnv }
-    : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", ...jobEnv };
+    ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...withoutForgeTokens(jobEnv) }
+    : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", ...withoutForgeTokens(jobEnv) };
   const greenBranch = github ? JSON.stringify(options.branch ?? "main") : options.branch ? JSON.stringify(options.branch) : "$CI_DEFAULT_BRANCH";
   const applyEnv = github ? { BASE_SHA: "${{ github.event.before }}", ...jobEnv } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA", ...jobEnv };
+  // #4301: the apply before merge runs in a job of the target branch, whose commit is the base, at the pull request's head.
+  const earlyEnv = github
+    ? { BASE_SHA: "${{ github.sha }}", PR_NUMBER: "${{ github.event.issue.number }}", ...jobEnv }
+    : { BASE_SHA: "$CI_COMMIT_SHA", PR_NUMBER: `$${GITLAB_APPLY_PR_VAR}`, ...jobEnv };
+  const greenApply: PrLoopJob = {
+    // #4168 step 9: the apply applies the newest green commit, measured from the one applied before it.
+    jobName: "apply",
+    command: [
+      "chant", "components", "pr-apply", "--green", ...common,
+      ...(options.requireReview === true ? ["--require-review"] : []),
+      ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
+      "--resume", PR_APPLY_RECORD,
+    ].join(" "),
+    env: jobEnv,
+    checkout: [greenCheckout(greenBranch)],
+    greenBranch,
+    ...build,
+    run: { command: ciRun("apply").join(" "), env: runEnv(jobEnv) },
+  };
+  const earlyApply: PrLoopJob = {
+    // #4301: the requires checks run inside pr-apply, before any of the head's code loads.
+    jobName: "apply",
+    command: [
+      "chant", "components", "pr-apply", "--before-merge", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common,
+      ...(options.requireReview === true ? ["--require-review"] : []),
+      "--resume", PR_APPLY_RECORD,
+    ].join(" "),
+    env: earlyEnv,
+    checkout: [pullRequestCheckout(forge)],
+    run: { command: ciRun("apply").join(" "), env: runEnv(earlyEnv) },
+  };
   return [
     {
       jobName: "plan",
       // With `waveGate` the plan's note says the later waves may stop at their own gates (#4003).
-      command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common, ...(options.waveGate ? ["--wave-gate", options.waveGate] : [])].join(" "),
+      command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common, ...(options.waveGate ? ["--wave-gate", options.waveGate] : []), "--no-status"].join(" "),
       env: planEnv,
       ...build,
       run: { command: ciRun("plan").join(" "), env: runEnv(planEnv) },
     },
-    {
-      // #4168 step 9: the apply applies the newest green commit, measured from the one applied before it.
-      jobName: "apply",
-      command: [
-        "chant", "components", "pr-apply", "--green", ...common,
-        ...(options.requireReview === true ? ["--require-review"] : []),
-        ...(options.waveGate ? ["--wave-gate", options.waveGate] : []),
-        "--resume", PR_APPLY_RECORD,
-      ].join(" "),
-      env: jobEnv,
-      checkout: [greenCheckout(greenBranch)],
-      greenBranch,
-      ...build,
-      run: { command: ciRun("apply").join(" "), env: runEnv(jobEnv) },
-    },
+    early ? earlyApply : greenApply,
     {
       jobName: "record",
       command: ["chant", "components", "pr-record", "--base", '"$BASE_SHA"', ...common].join(" "),
@@ -304,6 +359,35 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   ];
 }
 
+/** The name of the job that posts the plan's note and status (#4295). */
+export const PR_PLAN_NOTE_JOB = "plan-note";
+
+/**
+ * The plan-note job's command and the values it reads (#4295). It runs in a
+ * fresh job after the plan, at the target branch's commit, and posts the
+ * note and the `chant/plan` status from the report the plan job handed on,
+ * with the forge token the plan job never held. `HEAD_SHA` is the commit
+ * the plan job checked out, `PR_NUMBER` the pull request, and on GitHub and
+ * Forgejo `PLAN_RESULT` the plan job's result, which fails the status when
+ * the plan job failed. `BASE_SHA` is the commit the note job checks out on
+ * GitLab, whose runner checks out the pipeline's own commit.
+ */
+export function prLoopPostJob(forge: ForgeKind, env: string, member?: string): { command: string; env: Record<string, string> } {
+  const github = forge !== "gitlab";
+  const command = [
+    "chant", "components", "pr-post", "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"',
+    "--env", env, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
+    ...(member ? ["--member", member] : []),
+    ...(github ? ["--result", '"$PLAN_RESULT"'] : []),
+  ].join(" ");
+  return {
+    command,
+    env: github
+      ? { PR_NUMBER: "${{ github.event.pull_request.number }}", HEAD_SHA: "${{ github.sha }}", PLAN_RESULT: "${{ needs.plan.result }}", GITHUB_TOKEN: GITHUB_JOB_TOKEN }
+      : { PR_NUMBER: "$CI_MERGE_REQUEST_IID", HEAD_SHA: "$CI_COMMIT_SHA", BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA" },
+  };
+}
+
 /**
  * What starts the apply under apply on merge (#4168 step 9): on GitHub the
  * tick's workflow finishing (`workflow_run`, since tags its token pushes start
@@ -408,6 +492,22 @@ function pushBaseFallback(target: string, commit: string, diffBase?: string): st
   );
 }
 
+/** The GitLab variable a person sets on a pipeline of the target branch to apply a merge request before it merges (#4301). */
+export const GITLAB_APPLY_PR_VAR = "CHANT_APPLY_PR";
+
+/** The comment that starts the apply before merge on GitHub and Forgejo (#4301). */
+export const APPLY_COMMENT = "/chant apply";
+
+/**
+ * The line that checks out pull request `$PR_NUMBER`'s head (#4301) in a job
+ * of the target branch: the forge's `refs/pull/<n>/head`, or GitLab's
+ * `refs/merge-requests/<n>/head`. A number that is not one fails the job.
+ */
+export function pullRequestCheckout(forge: ForgeKind): string {
+  const ref = forge === "gitlab" ? 'refs/merge-requests/$PR_NUMBER/head' : 'refs/pull/$PR_NUMBER/head';
+  return `echo "$PR_NUMBER" | grep -Eq '^[0-9]+$' && git fetch --quiet origin "+${ref}:refs/remotes/origin/chant-apply/$PR_NUMBER" && git checkout --quiet --detach "refs/remotes/origin/chant-apply/$PR_NUMBER"`;
+}
+
 /**
  * The line that checks out the newest green commit of `branch` (#4168 step
  * 9), after fetching the branch and its tags, for the apply job. `chant ci
@@ -450,3 +550,76 @@ export function gitlabBaseFallback(branch?: string): string {
 export function githubBaseFallback(branch?: string): string {
   return pushBaseFallback(JSON.stringify(branch ?? "main"), "$GITHUB_SHA");
 }
+
+/** Where the pull request environment jobs (#4298) write their reports, kept as a CI artifact. */
+export const PR_ENV_REPORT_DIR = ".chant/pr-env";
+
+/** The cron the generated `env-sweep` job runs on (#4298): hourly, at a minute off the hour. */
+export const PR_ENV_SWEEP_CRON = "17 * * * *";
+
+/** One job of a pull request's environment (#4298): its command and the forge values it reads. */
+export interface PrEnvJob {
+  jobName: "env-up" | "env-post" | "env-down" | "env-sweep";
+  /** The command line. `env-up` reads `$BASE_SHA` and `$PR_NUMBER`, `env-down` `$PR_NUMBER`. */
+  command: string;
+  /** Values the command reads, as the forge spells them. `CHANT_ENV` is the pull request's environment. */
+  env: Record<string, string>;
+  /** With `build`: the build and lint lines, run before the command. */
+  build?: string[];
+}
+
+/** The name of the job that keeps an environment's record and posts its note (#4298, #4295). */
+export const PR_ENV_POST_JOB = "env-post";
+
+/**
+ * The jobs of a pull request's environment (#4298), when `prEnvironment` is
+ * on, in this order:
+ *
+ * - `env-up` runs `chant components pr-env up --no-push`. It runs the
+ *   change's code, so it gets no forge token (#4295): it passes no
+ *   `--forge`, and it hands its report and its record on.
+ * - `env-post` runs `pr-env post` in a fresh job at the target branch's
+ *   commit, with the token: it keeps the record on chant/lifecycle and posts
+ *   the note and the `chant/pr-env` status. On GitHub and Forgejo it reads
+ *   the up job's result as `UP_RESULT`.
+ * - `env-down` runs `pr-env down --reason closed`, and `env-sweep` runs
+ *   `pr-env sweep`. Neither builds the change's code: a teardown reads the
+ *   markers off the live resources.
+ *
+ * Each writes its report under {@link PR_ENV_REPORT_DIR}.
+ */
+export function prEnvJobs(forge: ForgeKind, options: PrLoopPipelineOptions = {}, member?: string): PrEnvJob[] {
+  const github = forge !== "gitlab";
+  const out = ["--output", PR_ENV_REPORT_DIR, ...(member ? ["--member", member] : [])];
+  const common = ["--forge", forge, ...out];
+  const token: Record<string, string> = github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {};
+  const prNumber = github ? "${{ github.event.pull_request.number }}" : "$CI_MERGE_REQUEST_IID";
+  const prEnv = { CHANT_ENV: `pr-${prNumber}` };
+  const buildLines = prLoopBuildLines('"$CHANT_ENV"', options);
+  return [
+    {
+      jobName: "env-up",
+      // #4295: no --forge and no token; the record stays in the report directory for env-post.
+      command: ["chant", "components", "pr-env", "up", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...out, "--no-push"].join(" "),
+      env: { BASE_SHA: github ? "${{ github.event.pull_request.base.sha }}" : "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: prNumber, ...prEnv },
+      ...(buildLines.length > 0 ? { build: buildLines } : {}),
+    },
+    {
+      jobName: PR_ENV_POST_JOB,
+      command: ["chant", "components", "pr-env", "post", "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"', ...common, ...(github ? ["--result", '"$UP_RESULT"'] : [])].join(" "),
+      env: github
+        ? { PR_NUMBER: prNumber, HEAD_SHA: "${{ github.sha }}", UP_RESULT: "${{ needs.env-up.result }}", ...token }
+        : { PR_NUMBER: prNumber, HEAD_SHA: "$CI_COMMIT_SHA", BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA" },
+    },
+    {
+      jobName: "env-down",
+      command: ["chant", "components", "pr-env", "down", "--pr", '"$PR_NUMBER"', "--reason", "closed", ...common].join(" "),
+      env: { PR_NUMBER: prNumber, ...prEnv, ...token },
+    },
+    {
+      jobName: "env-sweep",
+      command: ["chant", "components", "pr-env", "sweep", ...common].join(" "),
+      env: { ...token },
+    },
+  ];
+}

package/src/components/pr-policy.test.ts

@@ -0,0 +1,145 @@
+/**
+ * `ci.policy` on the pull-request path (#4294): the settings and the policy
+ * read at base, the engine run over the change set, and a denial decided
+ * against the override ledger. The engine is a fake that prints opa's
+ * result shape; nothing reaches a network.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { parseDeclaration, WorkspaceReadError } from "../workspace/declaration";
+import { composeChangeSet } from "../change-set";
+import { memoryGateLedgerPort } from "../op/gate";
+import { overrideDigest } from "../override-gate";
+import type { GatePolicyExec } from "../gate-policy";
+import { decidePrPolicyOverride, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrPolicyInput } from "./pr-policy";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+const tmp = (): string => {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), "pr-policy-")));
+  scratch.push(d);
+  return d;
+};
+const git = (cwd: string, ...args: string[]): string => execFileSync("git", args, { cwd, encoding: "utf-8" }).trim();
+
+const declaration = (policy: unknown) => ({
+  name: "acme",
+  schema: 1,
+  members: [{ name: "infra", dir: "infra", kind: "other", because: "test" }],
+  ...(policy ? { ci: { policy } } : {}),
+});
+
+/** A repo whose base declares `ci.policy` with an opa policy and one overrider. */
+function repoWithPolicy(): { repo: string; base: string } {
+  const repo = tmp();
+  git(repo, "init", "-q", "-b", "main");
+  git(repo, "config", "user.email", "t@example.com");
+  git(repo, "config", "user.name", "t");
+  mkdirSync(join(repo, "infra"));
+  mkdirSync(join(repo, "policy"));
+  mkdirSync(join(repo, ".chant"));
+  writeFileSync(join(repo, "chant.workspace.json"), JSON.stringify(declaration({ engine: "opa", path: "policy" })));
+  writeFileSync(join(repo, "policy", "main.rego"), "package main\n# base\n");
+  writeFileSync(join(repo, ".chant", "overriders"), "github:carol\n");
+  git(repo, "add", ".");
+  git(repo, "commit", "-q", "-m", "base");
+  return { repo, base: git(repo, "rev-parse", "HEAD") };
+}
+
+const doc = composeChangeSet([]);
+const input = (base: string): PrPolicyInput => ({ version: 1, stage: "apply", op: "pr-7", gate: "pr-apply", env: "prod", pr: 7, base, head: "h".repeat(40), changeSet: doc });
+const opaOut = (value: unknown): string => JSON.stringify({ result: [{ expressions: [{ value }] }] });
+
+describe("ci.policy in the declaration (#4294)", () => {
+  test("parses at the top level, and refuses an unattended outcome", () => {
+    const read = (policy: unknown) => parseDeclaration(JSON.stringify(declaration(policy)), "chant.workspace.json", "0.124.41");
+    expect(read({ engine: "opa", path: "rules" }).ci?.policy).toEqual({ engine: "opa", path: "rules" });
+    expect(() => read({ outcomes: ["allow_unattended"] })).toThrow(WorkspaceReadError);
+    expect(() => read({ engine: "rego" })).toThrow(/conftest or opa/);
+  });
+});
+
+describe("prLoopPolicyAt and runPrPolicy (#4294)", () => {
+  test("the settings and the policy come from the base: the change's edits to either do not run", () => {
+    const { repo, base } = repoWithPolicy();
+    writeFileSync(join(repo, "chant.workspace.json"), JSON.stringify(declaration({ engine: "opa", path: "policy", command: ["true", "{input}"] })));
+    writeFileSync(join(repo, "policy", "main.rego"), "package main\n# the change loosens it\n");
+    const read = prLoopPolicyAt(join(repo, "infra"), base);
+    expect(read.settings).toEqual({ engine: "opa", path: "policy" });
+    let seen = "";
+    let fed: unknown;
+    const exec: GatePolicyExec = (argv) => {
+      seen = readFileSync(join(argv[argv.indexOf("--data") + 1]!, "main.rego"), "utf-8");
+      fed = JSON.parse(readFileSync(argv[argv.indexOf("--input") + 1]!, "utf-8"));
+      return { status: 0, stdout: opaOut({ deny: ["public bucket"] }), stderr: "" };
+    };
+    const verdict = runPrPolicy(read, input(base), exec)!;
+    expect(seen).toBe("package main\n# base\n");
+    expect(fed).toMatchObject({ op: "pr-7", stage: "apply", changeSet: { digest: doc.digest } });
+    expect(prPolicyReport(verdict, base)).toEqual({ result: "denied", engine: "opa", base, denials: [{ rule: "main.deny", message: "public bucket" }], rules: ["main.deny"], holds: [], warnings: [] });
+  });
+
+  test("no policy at base runs none, and says so when the change declares one", () => {
+    const repo = tmp();
+    git(repo, "init", "-q", "-b", "main");
+    git(repo, "config", "user.email", "t@example.com");
+    git(repo, "config", "user.name", "t");
+    writeFileSync(join(repo, "README"), "x");
+    git(repo, "add", ".");
+    git(repo, "commit", "-q", "-m", "base");
+    const base = git(repo, "rev-parse", "HEAD");
+    expect(prLoopPolicyAt(repo, base)).toEqual({ base });
+    writeFileSync(join(repo, "chant.workspace.json"), JSON.stringify(declaration({ engine: "opa" })));
+    const read = prLoopPolicyAt(repo, base);
+    expect(read.settings).toBeUndefined();
+    expect(read.note).toMatch(/runs once it merges/);
+    expect(runPrPolicy(read, input(base))).toBeUndefined();
+  });
+
+  test("a policy directory the base lacks is an error, which stops the apply", () => {
+    const { repo, base } = repoWithPolicy();
+    const read = { ...prLoopPolicyAt(repo, base), settings: { engine: "opa" as const, path: "missing" } };
+    expect(runPrPolicy(read, input(base), () => ({ status: 0, stdout: opaOut({}), stderr: "" }))).toMatchObject({ result: "error", error: "the policy directory missing does not exist at base" });
+  });
+});
+
+describe("a denial and its override (#4294)", () => {
+  test("no override records the denial once; a listed overrider's override counts; spent, it counts no more", async () => {
+    const { repo, base } = repoWithPolicy();
+    const port = memoryGateLedgerPort();
+    const ask = (record: boolean) =>
+      decidePrPolicyOverride({ port, subject: "pr-7", digest: doc.digest, rules: ["main.deny"], base, cwd: repo, sealed: false, record, now: "2026-10-22T10:00:00Z" });
+
+    const plan = await ask(false);
+    expect(plan).toMatchObject({ status: "none", recorded: false, overriders: ["github:carol"], command: 'chant approve policy-override pr-7 --rule main.deny --reason "<why>"' });
+    expect(port.appended).toHaveLength(0);
+
+    expect(await ask(true)).toMatchObject({ status: "none", recorded: true });
+    expect(port.appended[0]).toMatchObject({ op: "policy-override", gate: "pr-7", plan: doc.digest, rules: ["main.deny"] });
+    // The denial stands, so a second refusal records no other.
+    expect(await ask(true)).toMatchObject({ status: "none", recorded: false });
+
+    const od = overrideDigest("pr-7", doc.digest, ["main.deny"]);
+    await port.appendResolution!({ op: "policy-override", gate: "pr-7", resolvedBy: "github:dave", timestamp: "2026-10-22T11:00:00Z", planDigest: od, note: "not listed" });
+    expect(await ask(true)).toMatchObject({ status: "none", refusals: [expect.stringContaining("github:dave is not listed")] });
+
+    await port.appendResolution!({ op: "policy-override", gate: "pr-7", resolvedBy: "github:carol", timestamp: "2026-10-22T12:00:00Z", planDigest: od, note: "the bucket is the public docs site" });
+    const counted = await ask(true);
+    expect(counted).toEqual({ status: "overridden", override: { by: "github:carol", at: "2026-10-22T12:00:00Z", reason: "the bucket is the public docs site", digest: od } });
+
+    if (counted.status !== "overridden") throw new Error("expected an override");
+    await spendPrPolicyOverride(port, "pr-7", counted.override, { now: "2026-10-22T12:30:00Z", commit: "c".repeat(40) });
+    expect(port.applied).toEqual([expect.objectContaining({ op: "policy-override", gate: "pr-7", planDigest: od, approvedBy: "github:carol", commit: "c".repeat(40) })]);
+    expect(await ask(true)).toMatchObject({ status: "none", refusals: expect.arrayContaining([expect.stringContaining("is spent")]) });
+  });
+
+  test("an applied record that does not reach the remote throws, so nothing applies", async () => {
+    const port = { ...memoryGateLedgerPort(), appendApplied: async () => ({ pushed: false, pushWarning: 'the push of chant/lifecycle to "origin" failed' }) };
+    await expect(spendPrPolicyOverride(port, "pr-7", { by: "github:carol", at: "2026-10-22T12:00:00Z", reason: "ok", digest: "sha256:1" })).rejects.toThrow(/did not reach the remote/);
+  });
+});