@intentius/chant 0.124.32 → 0.124.33

package/src/workspace/ci-serve-builds.test.ts

@@ -0,0 +1,86 @@
+/**
+ * #4169 — `ci serve --build-command` serves each `ci/build/<sha>` tag once,
+ * within `maxJobs`, and records how each build ended.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { buildRequestAnnotation, requestedBuild } from "./ci-builds";
+import { ciServeBuilds, ciServePass, formatCiServeEvent, newCiServeRuntime, type CiServeEvent, type CiServeOptions } from "./ci-serve";
+import type { CiGreen } from "./declaration";
+
+afterAll(cleanScratch);
+
+const GREEN = { branch: "main", phases: [], require: ["suites"] } as unknown as CiGreen;
+
+function clone(): { root: string; shas: string[] } {
+  const origin = scratchDir("chant-serve-builds-origin-");
+  git(origin, "init", "-q", "--bare");
+  const root = scratchDir("chant-serve-builds-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "remote", "add", "origin", origin);
+  const shas: string[] = [];
+  for (const n of ["a", "b"]) {
+    writeFiles(root, { [`${n}.txt`]: `${n}\n` });
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", n);
+    shas.push(git(root, "rev-parse", "HEAD"));
+    const r = requestedBuild(GREEN, shas.at(-1)!, ["suites"], new Date(`2026-10-20T1${shas.length}:00:00Z`));
+    git(root, "tag", "-a", "-m", buildRequestAnnotation(r), r.tag, r.commit);
+  }
+  git(root, "push", "-q", "origin", "main", "--tags");
+  // The serve's clone learns the tags from the forge.
+  for (const s of shas) git(root, "tag", "-d", `ci/build/${s}`);
+  return { root, shas };
+}
+
+const options = (root: string, built: string[], log: CiServeEvent[], extra: Partial<CiServeOptions> = {}): CiServeOptions => ({
+  cwd: root,
+  forge: "github",
+  repo: "acme/app",
+  env: "prod",
+  client: { openPullRequests: async () => [], branchHead: async () => undefined },
+  stateDir: join(root, ".serve"),
+  buildCommand: "true",
+  build: async ({ request }) => (built.push(request.commit), request.commit === built[0] ? 0 : 2),
+  log: (e) => log.push(e),
+  ...extra,
+});
+
+describe("ci serve --build-command (#4169)", () => {
+  test("serves each request once, oldest first, within maxJobs, and records how it ended", async () => {
+    const { root, shas } = clone();
+    const built: string[] = [];
+    const log: CiServeEvent[] = [];
+    const rt = newCiServeRuntime();
+    const first = ciServeBuilds(options(root, built, log), rt);
+    expect(first.events.map((e) => e.type === "build" && e.status)).toEqual(["started", "held"]);
+    await Promise.all(first.started);
+    const second = ciServeBuilds(options(root, built, log), rt);
+    await Promise.all(second.started);
+    expect(built).toEqual(shas);
+    const state = JSON.parse(readFileSync(join(root, ".serve", "chant-apply-prod.json"), "utf-8"));
+    expect(Object.fromEntries(Object.entries(state.builds).map(([k, v]) => [k, (v as { status: string }).status]))).toEqual({ [`build:${shas[0]}`]: "ok", [`build:${shas[1]}`]: "fail" });
+    // Served once: another pass starts nothing.
+    expect(ciServeBuilds(options(root, built, log), rt).started).toEqual([]);
+    expect(log.map((e) => formatCiServeEvent(e))).toContain(`the build of suites at ${shas[1].slice(0, 12)} failed with exit code 2`);
+  });
+
+  test("without --build-command a pass leaves the tags alone; the default build runs the command in a worktree of the commit", async () => {
+    const { root, shas } = clone();
+    const log: CiServeEvent[] = [];
+    await ciServePass({ ...options(root, [], log), buildCommand: undefined });
+    expect(log.filter((e) => e.type === "build")).toEqual([]);
+    const out = join(root, ".serve-out");
+    await ciServePass({ ...options(root, [], log), build: undefined, buildCommand: `git rev-parse HEAD >> ${out}; echo "$CHANT_BUILD_PHASES $CHANT_BUILD_REASON" >> ${out}`, maxJobs: 2 });
+    expect(existsSync(out)).toBe(true);
+    const lines = readFileSync(out, "utf-8").trim().split("\n");
+    expect(lines.filter((l) => /^[0-9a-f]{40}$/.test(l)).sort()).toEqual([...shas].sort());
+    expect(lines.filter((l) => l === "suites requested")).toHaveLength(2);
+  });
+});

package/src/workspace/ci-serve.test.ts

@@ -143,6 +143,8 @@ function serve(app: string, client: CiServeForge, extra: Partial<CiServeOptions>
       client,
       stateDir: state,
       holder: "serve-test",
+      // Most tests here cover the apply on merge, which #4168 made opt-in; the record tests pass false.
+      applyOnMerge: true,
       // A job image of its own, so no setup line downloads OpenTofu.
       job: { image: "chant-ci-serve-test:local", chant: fakeChant(), hostEnv: env, passEnv: Object.keys(hostEnv ?? {}) },
       log: (e) => events.push(e),
@@ -177,6 +179,63 @@ const isAncestor = (cwd: string, a: string, b: string): boolean => {
 const argsOf = (report: string, stage: string): string[] => readFileSync(join(report, `${stage}.args`), "utf-8").trimEnd().split("\n");
 const ofType = <T extends CiServeEvent["type"]>(events: CiServeEvent[], type: T) => events.filter((e): e is Extract<CiServeEvent, { type: T }> => e.type === type);
 
+describe("ci serve records each merge unless apply on merge is opted in (#4168)", () => {
+  test("a merge to the target branch gets the record job, measured from the head before it, and no resume record", async () => {
+    const { root, app, main } = workspace();
+    const forge = fakeForge(main);
+    const { opts, events, state } = serve(app, forge, { applyOnMerge: false });
+    await ciServePass(opts);
+    const merged = commit(root, "app/merged.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = merged;
+    forge.merges.set(merged, 21);
+
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "record", commit: merged, base: main, pr: 21, status: "ok" })]);
+    const argv = argsOf(pass.jobs[0]!.report!, "pr-record");
+    expect(argv.slice(0, 4)).toEqual(["components", "pr-record", "--base", main]);
+    expect(argv).not.toContain("--resume");
+    expect(ofType(events, "started")[0]).not.toHaveProperty("resume");
+    expect(existsSync(join(state, "resume"))).toBe(false);
+    const saved = readCiServeState(join(state, `${prApplyGroup("prod", "app")}.json`), { forge: "forgejo", repo: "demo/estate", env: "prod", branch: "main" });
+    expect(saved.target).toBe(merged);
+    expect(saved.jobs[ciServeKey({ job: "record", commit: merged })]).toMatchObject({ status: "ok" });
+    expect((await ciServePass(opts)).jobs).toEqual([]);
+  });
+
+  test("each settled job runs the tick, and a tick that fails is an error event, never a failed job", async () => {
+    const { root, app, main } = workspace();
+    const forge = fakeForge(main);
+    const ticks: string[] = [];
+    let fail = false;
+    const { opts, events } = serve(app, forge, {
+      applyOnMerge: false,
+      tick: async () => {
+        ticks.push("tick");
+        if (fail) throw new Error("forge said no");
+        return ["ci/green/abc"];
+      },
+    });
+    await ciServePass(opts);
+    expect(ticks).toEqual([]);
+    const merged = commit(root, "app/merged.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = merged;
+    await ciServePass(opts);
+    expect(ticks).toEqual(["tick"]);
+    expect(ofType(events, "tick")).toEqual([{ type: "tick", made: ["ci/green/abc"] }]);
+    expect(formatCiServeEvent({ type: "tick", made: ["ci/green/abc"] })).toBe("ci tick made ci/green/abc");
+
+    fail = true;
+    const next = commit(root, "app/next.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = next;
+    const pass = await ciServePass(opts);
+    expect(pass.jobs[0]).toMatchObject({ job: "record", status: "ok" });
+    expect(ofType(events, "error").map((e) => e.message)).toContain("ci tick after a job settled: forge said no");
+  });
+});
+
 describe("chant ci serve (#4095)", () => {
   test("one poll plans a new pull request head once, and skips forks and authors not given", async () => {
     const { root, app, main } = workspace();

package/src/workspace/ci-serve.ts

@@ -3,11 +3,15 @@
  * host. It polls the forge for the open pull requests into the target branch
  * and for the branch's head, and runs the pull-request jobs with
  * {@link ciRun} (./ci-run.ts): `plan` for each new pull request head, and
- * `apply` for each new commit on the target branch, measured from the head
- * the previous poll saw (the push's `before`).
+ * `record` for each new commit on the target branch (#4168), measured from
+ * the head the previous poll saw (the push's `before`). The record applies
+ * nothing; with `applyOnMerge` (`--apply-on-merge`) the commit gets `apply`
+ * in its place, as before #4168. After each job settles it runs `ci tick`
+ * from the runs the jobs recorded, when the declaration has `ci.green`.
+ * What the list below says of the apply holds for it under `applyOnMerge`.
  *
  * - Dedupe. A state file in the state directory keeps every job it started,
- *   keyed by job and commit (`plan:<pr>:<sha>`, `apply:<sha>`), with how it
+ *   keyed by job and commit (`plan:<pr>:<sha>`, `record:<sha>`, `apply:<sha>`), with how it
  *   ended, and the target head the last apply was measured to. A job already
  *   in it is not started again, unless it failed and `rerunFailed` asks for
  *   it: the forge's "re-run failed jobs".
@@ -37,6 +41,14 @@
  * - `[skip ci]` (#4122). A target head or pull request head whose commit
  *   message says `[skip ci]` or `[ci skip]` is recorded as seen and not run,
  *   as Actions does.
+ * - Build requests (#4169). With `buildCommand`, each `ci/build/<sha>`
+ *   tag the tick or `ci run --at` pushed is served once: the command runs
+ *   in a fresh detached worktree of the commit, with `CHANT_BUILD_COMMIT`,
+ *   `CHANT_BUILD_PHASES` (comma-separated) and `CHANT_BUILD_REASON` set,
+ *   and is expected to run the phases' Ops (`chant run <op>`), whose
+ *   records the tick reads. A build counts against `maxJobs`, and the state
+ *   file keeps it under `build:<sha>`. Without `buildCommand` the tags are
+ *   left alone.
  * - The forge's ledger (#4121). Before each job, when no other job of this
  *   serve runs, the clone's `chant/lifecycle` follows the forge's: it is
  *   deleted when the forge has none, and reset to the forge's when neither
@@ -54,9 +66,11 @@
  * turn a checked payload into the same triggers and schedule them.
  */
 
-import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { CI_BUILD_TAG_PREFIX, readBuildRequests, type BuildRequest } from "./ci-builds";
 import { prApplyGroup, prApplyRecordKey } from "../components/pr-pipeline";
 import { forgeFromEnv, type OpenPullRequest } from "../pr-forge";
 import type { CommandContext } from "../cli/registry";
@@ -65,7 +79,7 @@ import { acquireLease, currentHolderId, releaseLease, DEFAULT_LEASE_TTL_MS, type
 import { parseDuration } from "../op/duration";
 import { reportUrlOf } from "./ci-report-url";
 import { CI_JOB_OPS, ciJobPlace, ciLoopOptions, ciSecretsOf, ciRun, ciStatusFromEnv, CiRunError, type CiJobName, type CiRunRequest, type CiRunResult } from "./ci-run";
-import { RUNNER_KEY_ENV, signedRunsRequired } from "./ci-green";
+import { CiGreenError, ciTick, RUNNER_KEY_ENV, signedRunsRequired } from "./ci-green";
 import { gitTop } from "./tree";
 import { ciServeRunnerKey, formatRunnerKeySetup, setupRunnerKey } from "./ci-runner-key";
 
@@ -80,10 +94,14 @@ export interface CiServeForge {
   pullRequestFor?(sha: string): Promise<number | null>;
 }
 
-/** A job the forge's state calls for: the plan of a pull request's head, or the apply of a target-branch commit. */
+/**
+ * A job the forge's state calls for: the plan of a pull request's head, or
+ * for a target-branch commit its record (#4168) or, with `applyOnMerge`,
+ * its apply.
+ */
 export type CiServeTrigger =
   | { job: "plan"; commit: string; base: string; pr: number; rerun?: boolean }
-  | { job: "apply"; commit: string; base: string; rerun?: boolean };
+  | { job: "apply" | "record"; commit: string; base: string; rerun?: boolean };
 
 /** One job in the state file. */
 export interface CiServeJobState {
@@ -116,6 +134,8 @@ export interface CiServeState {
   jobs: Record<string, CiServeJobState>;
   /** Plans seen and not run, by state key, with why (#4122). */
   skipped?: Record<string, "skip-ci">;
+  /** The build requests served (#4169), by `build:<sha>`, with how each ended. */
+  builds?: Record<string, { tag: string; status: "running" | "ok" | "fail"; startedAt: string; settledAt?: string }>;
 }
 
 /** What a pass did, in order, for the log. */
@@ -128,6 +148,9 @@ export type CiServeEvent =
   | { type: "settled"; job: CiJobName; commit: string; pr?: number; status: "ok" | "fail"; failure?: string; report?: string }
   | { type: "not-run"; job: CiJobName; commit: string; pr?: number; reason: "not-fast-forward" | "skip-ci"; branch?: string; from?: string }
   | { type: "ledger"; action: "deleted" | "reset"; local: string; forge?: string }
+  | { type: "build"; commit: string; phases: string[]; status: "started" | "ok" | "fail" | "held"; exitCode?: number }
+  /** `ci tick` after the pass (#4168): the tags it made from the runs. */
+  | { type: "tick"; made: string[] }
   | { type: "error"; message: string };
 
 /** The `ciRun` request fields `ci serve` passes through to every job: the generator's options and the runner's. */
@@ -149,6 +172,18 @@ export interface CiServeOptions {
   authors?: readonly string[];
   /** Run again the failed apply at the target's head, and the failed plans of open heads. */
   rerunFailed?: boolean;
+  /**
+   * Apply each new target-branch commit (#4168), as `ci serve` did before
+   * #4168. Default false: each new commit gets the record job, which applies
+   * nothing.
+   */
+  applyOnMerge?: boolean;
+  /**
+   * Run after each pass that settled a job (#4168): `ci tick` from the runs
+   * the jobs recorded. Returns the tags it made, or undefined when the
+   * declaration has no `ci.green`. The command passes one; a test may not.
+   */
+  tick?: () => Promise<string[] | undefined>;
   /** Passed to each job. `job.hostEnv` gets `GITHUB_REPOSITORY` set to `repo`. */
   job?: CiServeJobOptions;
   /** This process's lease identity. Default `currentHolderId()`. */
@@ -158,18 +193,26 @@ export interface CiServeOptions {
   now?: () => Date;
   /** Runs a job. Default {@link ciRun}. */
   run?: (req: CiRunRequest) => Promise<CiRunResult>;
+  /**
+   * The shell line that builds a requested commit (#4169), run in a fresh
+   * worktree of it. Without it `ci/build/<sha>` tags are not served.
+   */
+  buildCommand?: string;
+  /** Runs a build. Default: `sh -c <buildCommand>` in a detached worktree of the commit. */
+  build?: (input: { top: string; request: BuildRequest; command: string }) => Promise<number>;
 }
 
 /** The jobs this process runs now, by state key, shared by every pass of one loop. */
 export interface CiServeRuntime {
-  inflight: Map<string, Promise<CiServeJobState>>;
+  /** Jobs and build requests (#4169) alike, by state key: they share `maxJobs`. */
+  inflight: Map<string, Promise<unknown>>;
 }
 
 export const newCiServeRuntime = (): CiServeRuntime => ({ inflight: new Map() });
 
 /** The state key of a job. */
 export function ciServeKey(t: { job: CiJobName; commit: string; pr?: number }): string {
-  return t.job === "plan" ? `plan:${t.pr}:${t.commit}` : `apply:${t.commit}`;
+  return t.job === "plan" ? `plan:${t.pr}:${t.commit}` : `${t.job}:${t.commit}`;
 }
 
 const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
@@ -324,6 +367,8 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
   const triggers: CiServeTrigger[] = [];
   const events: CiServeEvent[] = [];
   const [head, prs] = await Promise.all([opts.client.branchHead(place.branch), opts.client.openPullRequests(place.branch)]);
+  // #4168: a new target commit is recorded, and applied only with applyOnMerge.
+  const onMerge: "apply" | "record" = opts.applyOnMerge ? "apply" : "record";
 
   if (head === undefined) {
     events.push({ type: "no-branch", branch: place.branch });
@@ -336,7 +381,7 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
   } else if (head !== state.target) {
     const from = state.target;
     const move = targetMove(place.top, place.branch, from, head);
-    const entry = state.jobs[ciServeKey({ job: "apply", commit: head })];
+    const entry = state.jobs[ciServeKey({ job: onMerge, commit: head })];
     if (move === "unknown") {
       events.push({ type: "error", message: `${place.branch} is at ${head.slice(0, 12)} on the forge, and that commit could not be fetched; the next poll tries again` });
     } else if (move === "other" || (!entry && skipsCi(place.top, head))) {
@@ -344,13 +389,13 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
       update((s) => {
         s.target = head;
       });
-      events.push({ type: "not-run", job: "apply", commit: head, reason: move === "other" ? "not-fast-forward" : "skip-ci", ...(move === "other" ? { branch: place.branch, from } : {}) });
-    } else if (!entry) triggers.push({ job: "apply", commit: head, base: from });
-    else if (opts.rerunFailed && failedEntry(entry, ciServeKey(entry), rt)) triggers.push({ job: "apply", commit: head, base: entry.base, rerun: true });
+      events.push({ type: "not-run", job: onMerge, commit: head, reason: move === "other" ? "not-fast-forward" : "skip-ci", ...(move === "other" ? { branch: place.branch, from } : {}) });
+    } else if (!entry) triggers.push({ job: onMerge, commit: head, base: from });
+    else if (opts.rerunFailed && failedEntry(entry, ciServeKey(entry), rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true });
   } else {
-    const key = ciServeKey({ job: "apply", commit: head });
+    const key = ciServeKey({ job: onMerge, commit: head });
     const entry = state.jobs[key];
-    if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: "apply", commit: head, base: entry.base, rerun: true });
+    if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: onMerge, commit: head, base: entry.base, rerun: true });
   }
 
   const authors = opts.authors?.length ? new Set(opts.authors.map((a) => a.toLowerCase())) : undefined;
@@ -453,7 +498,7 @@ export async function ciServeSchedule(opts: CiServeOptions, triggers: readonly C
     const entry: CiServeJobState = { job: t.job, commit: t.commit, base: t.base, ...pr, status: "running", runId, attempts: attempt, startedAt: now().toISOString() };
     update((s) => {
       s.jobs[key] = entry;
-      if (t.job === "apply" && !t.rerun) s.target = t.commit;
+      if (t.job !== "plan" && !t.rerun) s.target = t.commit;
     });
     emit({ type: "started", job: t.job, commit: t.commit, ...pr, base: t.base, runId, attempt, ...(resume && existsSync(resume) ? { resume } : {}) });
 
@@ -468,7 +513,7 @@ export async function ciServeSchedule(opts: CiServeOptions, triggers: readonly C
         emit({ type: "error", message: `${key} settled, and the state file could not be written: ${message(err)}` });
       }
       emit({ type: "settled", job: t.job, commit: t.commit, ...pr, status: settled.status === "ok" ? "ok" : "fail", ...(settled.failure ? { failure: settled.failure } : {}), ...(settled.report ? { report: settled.report } : {}) });
-      return settled;
+      return serveTick(opts).then(() => settled);
     });
     rt.inflight.set(key, job);
     started.push(job);
@@ -496,7 +541,7 @@ async function runJob(
     tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", t.job === "plan" ? `refs/pull/${t.pr}/head` : place.branch]);
     const hostEnv = { ...(opts.job?.hostEnv ?? process.env), GITHUB_REPOSITORY: opts.repo };
     // An apply is for a merge: pass the pull request whose merge commit it is, so the commit status link and the run index use `<pr>/<commit>`. None found, or a forge that errs, is today's behaviour.
-    if (t.job === "apply" && opts.client.pullRequestFor) merged = (await opts.client.pullRequestFor(t.commit).catch(() => null)) ?? undefined;
+    if (t.job !== "plan" && opts.client.pullRequestFor) merged = (await opts.client.pullRequestFor(t.commit).catch(() => null)) ?? undefined;
     const run = opts.run ?? ciRun;
     const r = await run({
       ...opts.job,
@@ -522,13 +567,101 @@ async function runJob(
   }
 }
 
-/** One pass: observe, schedule, and with `wait` wait for the jobs it started. */
+/** One pass: observe, schedule, serve build requests, and with `wait` wait for the jobs it started. */
 export async function ciServePass(opts: CiServeOptions, rt: CiServeRuntime = newCiServeRuntime(), wait = true): Promise<{ events: CiServeEvent[]; jobs: CiServeJobState[] }> {
   const observed = await ciServeObserve(opts, rt);
   for (const e of observed.events) opts.log?.(e);
   const scheduled = await ciServeSchedule(opts, observed.triggers, rt);
+  const builds = opts.buildCommand ? ciServeBuilds(opts, rt) : { started: [], events: [] };
   const jobs = wait ? await Promise.all(scheduled.started) : [];
-  return { events: [...observed.events, ...scheduled.events], jobs };
+  if (wait) await Promise.all(builds.started);
+  return { events: [...observed.events, ...scheduled.events, ...builds.events], jobs };
+}
+
+/**
+ * Serve the build requests (#4169): fetch the `ci/build/*` tags, and start
+ * `buildCommand` for each one not in the state file yet, oldest first, while
+ * fewer than `maxJobs` jobs run. A build that fails is recorded and not run
+ * again; the tick decides what its phases say.
+ */
+export function ciServeBuilds(opts: CiServeOptions, rt: CiServeRuntime): { started: Promise<void>[]; events: CiServeEvent[] } {
+  const place = servePlace(opts);
+  const fresh = { forge: opts.forge, repo: opts.repo, env: opts.env, branch: place.branch, ...(place.member ? { member: place.member } : {}) };
+  const update = (fn: (s: CiServeState) => void): void => {
+    const st = readCiServeState(place.stateFile, fresh);
+    fn(st);
+    writeState(place.stateFile, st);
+  };
+  const events: CiServeEvent[] = [];
+  const started: Promise<void>[] = [];
+  tryGit(place.top, ["fetch", "--quiet", "--prune", "origin", `+refs/tags/${CI_BUILD_TAG_PREFIX}*:refs/tags/${CI_BUILD_TAG_PREFIX}*`]);
+  const served = readCiServeState(place.stateFile, fresh).builds ?? {};
+  const max = opts.maxJobs ?? 1;
+  const now = opts.now ?? (() => new Date());
+  const requests = [...readBuildRequests(place.top).values()].sort((a, b) => a.at.localeCompare(b.at));
+  for (const request of requests) {
+    const key = `build:${request.commit}`;
+    if (served[key]?.tag === request.tag || rt.inflight.has(key)) continue;
+    const log = (e: CiServeEvent) => {
+      events.push(e);
+      opts.log?.(e);
+    };
+    if (rt.inflight.size >= max) {
+      log({ type: "build", commit: request.commit, phases: request.phases, status: "held" });
+      continue;
+    }
+    update((st) => {
+      st.builds = { ...st.builds, [key]: { tag: request.tag, status: "running", startedAt: now().toISOString() } };
+    });
+    log({ type: "build", commit: request.commit, phases: request.phases, status: "started" });
+    const build = opts.build ?? runBuild;
+    const job = build({ top: place.top, request, command: opts.buildCommand! })
+      .catch(() => 1)
+      .then((code) => {
+        update((st) => {
+          st.builds = { ...st.builds, [key]: { tag: request.tag, status: code === 0 ? "ok" : "fail", startedAt: st.builds?.[key]?.startedAt ?? now().toISOString(), settledAt: now().toISOString() } };
+        });
+        opts.log?.({ type: "build", commit: request.commit, phases: request.phases, status: code === 0 ? "ok" : "fail", exitCode: code });
+      });
+    const tracked = job.finally(() => rt.inflight.delete(key));
+    rt.inflight.set(key, tracked);
+    started.push(tracked);
+  }
+  return { started, events };
+}
+
+/** `sh -c <command>` in a fresh detached worktree of the request's commit, removed after. Resolves to the exit code. */
+async function runBuild(input: { top: string; request: BuildRequest; command: string }): Promise<number> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-ci-build-"));
+  try {
+    execFileSync("git", ["worktree", "add", "--quiet", "--detach", dir, input.request.commit], { cwd: input.top, stdio: ["ignore", "pipe", "pipe"] });
+    return await new Promise<number>((done) => {
+      const child = spawn("sh", ["-c", input.command], {
+        cwd: dir,
+        stdio: ["ignore", "inherit", "inherit"],
+        env: { ...process.env, CHANT_BUILD_COMMIT: input.request.commit, CHANT_BUILD_PHASES: input.request.phases.join(","), CHANT_BUILD_REASON: input.request.reason },
+      });
+      child.on("error", () => done(127));
+      child.on("close", (code) => done(code ?? 1));
+    });
+  } finally {
+    tryGit(input.top, ["worktree", "remove", "--force", dir]);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** `ci tick` after a job settled (#4168), logged; a tick that fails is an error event and never fails the job. */
+async function serveTick(opts: CiServeOptions): Promise<CiServeEvent | undefined> {
+  if (!opts.tick) return undefined;
+  let event: CiServeEvent | undefined;
+  try {
+    const made = await opts.tick();
+    event = made === undefined ? undefined : { type: "tick", made };
+  } catch (err) {
+    event = { type: "error", message: `ci tick after a job settled: ${message(err)}` };
+  }
+  if (event) opts.log?.(event);
+  return event;
 }
 
 /**
@@ -579,6 +712,13 @@ export function formatCiServeEvent(e: CiServeEvent): string {
       return e.action === "deleted"
         ? `the forge has no ${LEDGER}, so this clone's, at ${e.local.slice(0, 12)}, was deleted`
         : `the forge's ${LEDGER} at ${e.forge!.slice(0, 12)} does not contain this clone's at ${e.local.slice(0, 12)}, so this clone's was reset to the forge's and not pushed`;
+    case "build": {
+      const what = `the build of ${e.phases.join(", ")} at ${e.commit.slice(0, 12)}`;
+      if (e.status === "held") return `${what} waits: --max-jobs jobs run`;
+      return e.status === "started" ? `${what} started` : e.status === "ok" ? `${what} passed` : `${what} failed${e.exitCode !== undefined ? ` with exit code ${e.exitCode}` : ""}`;
+    }
+    case "tick":
+      return e.made.length > 0 ? `ci tick made ${e.made.join(", ")}` : "ci tick: no tag due";
     case "error":
       return `error: ${e.message}`;
   }
@@ -615,7 +755,7 @@ export function runnerKeySetupCommand(ctx: CommandContext): number {
 const USAGE =
   "chant ci serve --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>] | " +
   "chant ci serve --forge forgejo|github --repo <owner/repo> --env <env> [--interval <s>] [--max-jobs <n>] [--state <dir>] " +
-  "[--author <login>]... [--once] [--rerun-failed] [--gate <name>] [--wave-gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--no-status] [--status-url <url template>] " +
+  "[--author <login>]... [--once] [--rerun-failed] [--build-command <line>] [--gate <name>] [--wave-gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--no-status] [--status-url <url template>] " +
   "[--image <image>] [--before-script <line>]... [--pr-build] [--pr-build-command <line>] [--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [--unsigned]";
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -638,6 +778,8 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
     if (!args.ciRepo) throw new CiRunError("--repo names the repository whose pull requests ci serve polls: --repo <owner/repo>");
     if (!args.env) throw new CiRunError("--env names the environment the pipeline is for: --env <env>");
     for (const name of args.passEnv ?? []) if (!ENV_NAME.test(name)) throw new CiRunError(`--pass-env takes a variable's name, not ${JSON.stringify(name)}`);
+    // #4168: a gate per wave gates the apply on merge, which a merge runs only when opted in.
+    if (args.waveGate && !args.applyOnMerge) throw new CiRunError("--wave-gate gates the apply on merge, so it needs --apply-on-merge (#4168); without it a merge gets the record job, which applies nothing");
     const intervalMs = ciServeInterval(args.interval);
     const cwd = process.cwd();
     const top = gitTop(cwd);
@@ -670,6 +812,8 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
     const { status, warning } = ciStatusFromEnv({ forge, hostEnv, noStatus: args.noStatus, statusUrl: args.statusUrl });
     if (warning) console.error(formatWarning({ message: warning }));
     if (!client.openPullRequests || !client.branchHead) throw new CiRunError(`the ${forge} client cannot list pull requests`);
+    // #4168: a host that applied each merge before the upgrade hears that it no longer does.
+    if (!args.applyOnMerge) console.error("ci serve: each new commit on the target branch gets the record job, which applies nothing (#4168); --apply-on-merge applies it");
     const opts: CiServeOptions = {
       cwd,
       forge,
@@ -680,6 +824,17 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
       ...(args.maxJobs ? { maxJobs: args.maxJobs } : {}),
       ...(args.ciAuthors?.length ? { authors: args.ciAuthors } : {}),
       ...(args.rerunFailed ? { rerunFailed: true } : {}),
+      ...(args.ciBuildCommand ? { buildCommand: args.ciBuildCommand } : {}),
+      ...(args.applyOnMerge ? { applyOnMerge: true } : {}),
+      // #4168: the tick from the runs the jobs recorded, signed with the runs' key. No ci.green, no tick.
+      tick: async () => {
+        try {
+          return (await ciTick({ cwd, source: "runs", ...(runnerKey !== undefined ? { runnerKey } : {}) })).made;
+        } catch (err) {
+          if (err instanceof CiGreenError && err.code === "ci-green-undeclared") return undefined;
+          throw err;
+        }
+      },
       job: {
         loop: ciLoopOptions(reportUrl ? { ...args, reportUrl } : args),
         ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),

package/src/workspace/declaration.schema.json

@@ -236,6 +236,14 @@
           "description": "A deploy counts as failed when, within this many days after it, the commit it deployed is revoked or the environment is rolled back from it. The default is 7."
         }
       }
+    },
+    "security": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "The security groups the workspace opts into (#4168), for every member; a member's own security adds to them. With none, a security feature the workspace has not turned on never refuses, warns or hides anything. verified-releases: release publish and promote --release take only a verified release. supply-chain: a publish without OIDC provenance warns, and a target with no SBOM source is refused. who-ran-it: ci tick needs a runner key. review-rules: pr-apply requires a forge review. isolated-runners: an apply job requires a runner-start statement. workspace check reports what a declared group lacks (WSP161 to WSP165). Added in schema 1 by chant 0.124.33, so a declaration that uses it sets minReader to 0.124.33 or newer.",
+      "items": {
+        "enum": ["verified-releases", "supply-chain", "who-ran-it", "review-rules", "isolated-runners"]
+      }
     }
   },
   "patternProperties": {
@@ -487,6 +495,14 @@
           "type": "boolean",
           "description": "Whether the member goes with an export (#2524 D10, #2552). chant workspace export writes only members that set travel to true into the export member, and refuses to name one that does not. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer."
         },
+        "security": {
+          "type": "array",
+          "uniqueItems": true,
+          "description": "The security groups this member opts into, added to the declaration's top-level security (#4168). A release, publish or pull-request job of this member runs under both lists. Added in schema 1 by chant 0.124.33, so a declaration that uses it sets minReader to 0.124.33 or newer.",
+          "items": {
+            "enum": ["verified-releases", "supply-chain", "who-ran-it", "review-rules", "isolated-runners"]
+          }
+        },
         "because": {
           "type": "string",
           "minLength": 1,
@@ -1562,6 +1578,13 @@
                 "fail"
               ],
               "description": "What a check run that finished as skipped counts as. fail (the default): it never passes. pass: it passes, for a job a path filter runs only on some commits."
+            },
+            "build": {
+              "enum": [
+                "every",
+                "newest"
+              ],
+              "description": "Added by #4169, read by chant 0.124.33 and newer. Which first-parent commits of the branch the phase runs on. every (the default): each one. newest: only the newest commit when a runner frees. Under either, a run that was cancelled leaves the commit unbuilt rather than red. Under newest, a commit a newer run superseded is unbuilt too, and a red commit starts a bisect over the unbuilt commits back to the last one the phase passed on. chant ci workflow writes the triggers and concurrency of the workflows holding a phase that sets build, and leaves them alone for a phase that does not."
             }
           },
           "patternProperties": {

package/src/workspace/declaration.test.ts

@@ -459,6 +459,23 @@ describe("ci.reportUrl (#4160)", () => {
   });
 });
 
+describe("security (#4168)", () => {
+  test("the groups are read in file order, empty when absent, and securityGroupsOf reads them", async () => {
+    const { securityGroupsOf } = await import("./security");
+    expect(parse(base([])).security).toEqual([]);
+    const decl = parse(base([], { security: ["supply-chain", "verified-releases"] }));
+    expect(decl.security).toEqual(["supply-chain", "verified-releases"]);
+    expect([...securityGroupsOf(decl)]).toEqual(["supply-chain", "verified-releases"]);
+    expect(securityGroupsOf(null).size).toBe(0);
+  });
+
+  test("an unknown group, a repeated group and a non-array are refused", () => {
+    for (const security of [["signed"], ["supply-chain", "supply-chain"], "supply-chain"]) {
+      expect(failure(base([], { security })).code).toBe("declaration-invalid");
+    }
+  });
+});
+
 describe("metrics (#4039)", () => {
   test("failureWindowDays is read as written, without x- keys, and the block is null when absent", () => {
     expect(parse(base([])).metrics).toBeNull();