@intentius/chant 0.124.31 → 0.124.32

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

@@ -15,7 +15,7 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { cleanScratch, declaration, git, repoFixture, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
 import { ciServeInterval, ciServeKey, ciServePass, formatCiServeEvent, readCiServeState, type CiServeEvent, type CiServeForge, type CiServeOptions } from "./ci-serve";
-import { ciRun } from "./ci-run";
+import { ciRun, type CiRunResult } from "./ci-run";
 import { acquireLease, releaseLease } from "../lifecycle/lease";
 import { prApplyGroup, prApplyRecordKey } from "../components/pr-pipeline";
 import { parseArgs } from "../cli/parse-args";
@@ -23,9 +23,9 @@ import { forgejoForge, githubForge, type ForgeFetch, type OpenPullRequest } from
 
 afterAll(cleanScratch);
 
-function commit(root: string, file: string): string {
+function commit(root: string, file: string, message = file): string {
   writeFiles(root, { [file]: `${file} ${Math.random()}\n` });
-  for (const args of [["add", "-A"], ["commit", "-q", "-m", file]]) {
+  for (const args of [["add", "-A"], ["commit", "-q", "-m", message]]) {
     execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], { cwd: root, stdio: "ignore" });
   }
   return git(root, "rev-parse", "HEAD");
@@ -53,11 +53,12 @@ const workspaceTemplate = repoFixture(() => {
 }, "chant-ci-serve-");
 
 /** A copy of the template, its origin pointed at the copy of the bare one. */
-function workspace(): { root: string; app: string; main: string } {
+function workspace(): { root: string; app: string; main: string; origin: string } {
   const top = workspaceTemplate();
   const root = join(top, "root");
-  git(root, "remote", "set-url", "origin", join(top, "origin"));
-  return { root, app: join(root, "app"), main: git(root, "rev-parse", "HEAD") };
+  const origin = join(top, "origin");
+  git(root, "remote", "set-url", "origin", origin);
+  return { root, app: join(root, "app"), main: git(root, "rev-parse", "HEAD"), origin };
 }
 
 /** A pull request's head commit, on a branch off main, pushed to the forge's refs/pull/<n>/head. */
@@ -150,6 +151,29 @@ function serve(app: string, client: CiServeForge, extra: Partial<CiServeOptions>
   };
 }
 
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+/** A commit on no branch, with `parent` when given, as a ledger commit stands in. */
+const ledgerCommit = (root: string, message: string, parent?: string): string => git(root, "commit-tree", EMPTY_TREE, ...(parent ? ["-p", parent] : []), "-m", message);
+
+/** Seed `chant/lifecycle` in the clone and on the forge, as an earlier apply left it. */
+function seedLedger(root: string): string {
+  const seed = ledgerCommit(root, "seed");
+  git(root, "update-ref", "refs/heads/chant/lifecycle", seed);
+  git(root, "push", "-q", "origin", "chant/lifecycle");
+  expect(git(root, "rev-parse", "refs/remotes/origin/chant/lifecycle")).toBe(seed);
+  return seed;
+}
+
+const isAncestor = (cwd: string, a: string, b: string): boolean => {
+  try {
+    git(cwd, "merge-base", "--is-ancestor", a, b);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
 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);
 
@@ -365,3 +389,123 @@ describe("chant ci serve (#4095)", () => {
     expect(() => ciServeInterval("0")).toThrow(/a second or more/);
   });
 });
+
+describe("ci serve follows the forge's chant/lifecycle (#4121)", () => {
+  /** A serve past its baseline pass, with one merge waiting to apply, and each run's result in `results`. */
+  async function mergeWaiting() {
+    const w = workspace();
+    const seed = seedLedger(w.root);
+    const forge = fakeForge(w.main);
+    const results: CiRunResult[] = [];
+    const { opts, events } = serve(w.app, forge, { run: async (req) => { const r = await ciRun(req); results.push(r); return r; } });
+    await ciServePass(opts);
+    const merged = commit(w.root, "app/merged.txt");
+    git(w.root, "push", "-q", "origin", "main");
+    forge.head = merged;
+    return { ...w, seed, opts, events, results };
+  }
+
+  test("a ledger the forge deleted is deleted here, and the next apply runs clean", async () => {
+    const { root, origin, seed, opts, events, results } = await mergeWaiting();
+    git(origin, "update-ref", "-d", "refs/heads/chant/lifecycle");
+
+    const pass = await ciServePass(opts);
+    expect(ofType(events, "ledger")).toEqual([{ type: "ledger", action: "deleted", local: seed }]);
+    expect(formatCiServeEvent(ofType(events, "ledger")[0]!)).toContain("was deleted");
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "apply", status: "ok" })]);
+    expect(results[0]).toMatchObject({ pushed: true });
+    const tip = git(origin, "rev-parse", "refs/heads/chant/lifecycle");
+    expect(git(root, "rev-parse", "chant/lifecycle")).toBe(tip);
+    expect(isAncestor(origin, seed, tip)).toBe(false);
+  });
+
+  test("a ledger the forge rewrote is reset to the forge's and not pushed back", async () => {
+    const { root, origin, seed, opts, events, results } = await mergeWaiting();
+    const rewritten = ledgerCommit(root, "rewritten");
+    git(root, "push", "-q", "origin", `${rewritten}:refs/scratch/rewritten`);
+    git(origin, "update-ref", "refs/heads/chant/lifecycle", rewritten);
+
+    const pass = await ciServePass(opts);
+    expect(ofType(events, "ledger")).toEqual([{ type: "ledger", action: "reset", local: seed, forge: rewritten }]);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "apply", status: "ok" })]);
+    expect(results[0]).toMatchObject({ pushed: true });
+    const tip = git(origin, "rev-parse", "refs/heads/chant/lifecycle");
+    expect(isAncestor(origin, rewritten, tip)).toBe(true);
+    expect(isAncestor(root, seed, tip)).toBe(false);
+  });
+
+  test("a ledger ahead of the forge's keeps its facts, and the apply pushes them", async () => {
+    const { root, origin, seed, opts, events, results } = await mergeWaiting();
+    const ahead = ledgerCommit(root, "unpushed fact", seed);
+    git(root, "update-ref", "refs/heads/chant/lifecycle", ahead);
+
+    const pass = await ciServePass(opts);
+    expect(ofType(events, "ledger")).toEqual([]);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "apply", status: "ok" })]);
+    expect(results[0]).toMatchObject({ pushed: true });
+    expect(isAncestor(origin, ahead, git(origin, "rev-parse", "refs/heads/chant/lifecycle"))).toBe(true);
+  });
+});
+
+describe("ci serve applies fast-forwards only, and honours [skip ci] (#4122)", () => {
+  test("a force push back to an older commit is recorded as seen and not applied, and the next fast-forward applies", async () => {
+    const { root, app, main } = workspace();
+    const later = commit(root, "app/later.txt");
+    git(root, "push", "-q", "origin", "main");
+    const forge = fakeForge(later);
+    const { opts, events, state } = serve(app, forge);
+    await ciServePass(opts);
+    expect(ofType(events, "baseline")).toEqual([{ type: "baseline", commit: later }]);
+
+    git(root, "reset", "-q", "--hard", main);
+    git(root, "push", "-q", "-f", "origin", "main");
+    forge.head = main;
+    const back = await ciServePass(opts);
+    expect(back.jobs).toEqual([]);
+    expect(ofType(events, "not-run")).toEqual([{ type: "not-run", job: "apply", commit: main, reason: "not-fast-forward", branch: "main", from: later }]);
+    expect(formatCiServeEvent(ofType(events, "not-run")[0]!)).toContain("not a fast-forward");
+    const file = join(state, `${prApplyGroup("prod", "app")}.json`);
+    expect(readCiServeState(file, { forge: "forgejo", repo: "demo/estate", env: "prod", branch: "main" }).target).toBe(main);
+
+    const next = commit(root, "app/next.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = next;
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "apply", commit: next, base: main, status: "ok" })]);
+  });
+
+  test("a target head whose message says [skip ci] is recorded as seen and not applied", async () => {
+    const { root, app, main } = workspace();
+    const forge = fakeForge(main);
+    const { opts, events, state } = serve(app, forge);
+    await ciServePass(opts);
+    const skip = commit(root, "app/tidy.txt", "tidy the app [skip ci]");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = skip;
+
+    expect((await ciServePass(opts)).jobs).toEqual([]);
+    expect(ofType(events, "not-run")).toEqual([{ type: "not-run", job: "apply", commit: skip, reason: "skip-ci" }]);
+    expect(formatCiServeEvent(ofType(events, "not-run")[0]!)).toContain("says [skip ci]");
+    const file = join(state, `${prApplyGroup("prod", "app")}.json`);
+    expect(readCiServeState(file, { forge: "forgejo", repo: "demo/estate", env: "prod", branch: "main" }).target).toBe(skip);
+  });
+
+  test("a pull request head whose message says [ci skip] is not planned", async () => {
+    const { root, app, main } = workspace();
+    git(root, "checkout", "-q", "-b", "pr-4");
+    const head = commit(root, "app/pr-4.txt", "draft [ci skip]");
+    git(root, "push", "-q", "origin", `${head}:refs/pull/4/head`);
+    git(root, "checkout", "-q", "main");
+    const forge = fakeForge(main);
+    forge.prs = [pr(4, head, main)];
+    const { opts, events, state } = serve(app, forge);
+
+    expect((await ciServePass(opts)).jobs).toEqual([]);
+    expect(ofType(events, "not-run")).toEqual([{ type: "not-run", job: "plan", commit: head, pr: 4, reason: "skip-ci" }]);
+    const file = join(state, `${prApplyGroup("prod", "app")}.json`);
+    expect(readCiServeState(file, { forge: "forgejo", repo: "demo/estate", env: "prod", branch: "main" }).skipped).toEqual({ [ciServeKey({ job: "plan", pr: 4, commit: head })]: "skip-ci" });
+    // Seen once: the next poll says nothing of it.
+    expect((await ciServePass(opts)).jobs).toEqual([]);
+    expect(ofType(events, "not-run")).toHaveLength(1);
+  });
+});

package/src/workspace/ci-serve.ts

@@ -23,8 +23,26 @@
  *   as its `--resume` record, so a re-run of a failed apply at the same
  *   commit finishes under the approval it has. This replaces the forge's CI
  *   cache.
+ * - A gate per wave (#4003). With `--wave-gate` the apply job runs
+ *   `pr-apply --wave-gate`, which applies the waves in order and stops at
+ *   the first whose moved plan waits on its own gate. The job fails, and the
+ *   resume record keeps the waves that applied; once the wave's plan is
+ *   approved, `rerunFailed` runs the apply again and it carries on from
+ *   that wave.
  * - Capacity. At most `maxJobs` jobs run at once. A job over the limit is not
  *   recorded, so a later poll starts it.
+ * - Fast-forwards only (#4122). An apply runs only when the target's new head
+ *   descends from the head seen before it. Any other move, such as a force
+ *   push back to an older commit, is recorded as seen and not applied.
+ * - `[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.
+ * - 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
+ *   contains the other. Each is a warning. A local branch ahead of the
+ *   forge's keeps its facts, and the job's push sends them. Nothing here
+ *   pushes the ledger.
  *
  * Host mode only: each job runs in a fresh worktree on this host as this
  * user, with the clean environment `ciRun` gives it. A pull request from a
@@ -36,7 +54,7 @@
  * turn a checked payload into the same triggers and schedule them.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { prApplyGroup, prApplyRecordKey } from "../components/pr-pipeline";
@@ -45,8 +63,9 @@ import type { CommandContext } from "../cli/registry";
 import { formatError, formatWarning } from "../cli/format";
 import { acquireLease, currentHolderId, releaseLease, DEFAULT_LEASE_TTL_MS, type LeaseRecord } from "../lifecycle/lease";
 import { parseDuration } from "../op/duration";
-import { CI_JOB_OPS, ciJobPlace, ciSecretsOf, ciRun, ciStatusFromEnv, CiRunError, type CiJobName, type CiRunRequest, type CiRunResult } from "./ci-run";
-import { RUNNER_KEY_ENV } from "./ci-green";
+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 { gitTop } from "./tree";
 import { ciServeRunnerKey, formatRunnerKeySetup, setupRunnerKey } from "./ci-runner-key";
 
@@ -92,9 +111,11 @@ export interface CiServeState {
   env: string;
   branch: string;
   member?: string;
-  /** The target branch's head the last apply was measured to, or the head the first poll found. */
+  /** The target branch's head the last apply was measured to, or the last head seen and not applied. */
   target?: string;
   jobs: Record<string, CiServeJobState>;
+  /** Plans seen and not run, by state key, with why (#4122). */
+  skipped?: Record<string, "skip-ci">;
 }
 
 /** What a pass did, in order, for the log. */
@@ -105,6 +126,8 @@ export type CiServeEvent =
   | { type: "held"; job: CiJobName; commit: string; pr?: number; reason: "capacity" | "lease"; heldBy?: string }
   | { type: "started"; job: CiJobName; commit: string; pr?: number; base: string; runId: string; attempt: number; resume?: string }
   | { 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: "error"; message: string };
 
 /** The `ciRun` request fields `ci serve` passes through to every job: the generator's options and the runner's. */
@@ -159,6 +182,78 @@ function tryGit(cwd: string, args: string[]): string | undefined {
   }
 }
 
+const LEDGER = "chant/lifecycle";
+/** Where the forge's ledger tip is fetched to, a ref only this module writes. */
+const FORGE_LEDGER = "refs/chant/ci-serve/forge-ledger";
+
+/** `git` with its exit status, for the calls whose answer is the status. */
+function gitStatus(cwd: string, args: string[]): { code: number; out: string } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, LC_ALL: "C" } });
+  return { code: r.status ?? -1, out: (r.stdout ?? "").trim() };
+}
+
+/**
+ * Make the clone's `chant/lifecycle` follow the forge's (#4121). The clone's
+ * branch outlives the forge's, so a ledger the forge deleted or rewrote would
+ * make the next pr-apply find the two diverged and stall.
+ *
+ * - The forge has none: the local branch and its remote-tracking ref go.
+ * - Neither contains the other: the local branch and its remote-tracking ref
+ *   are reset to the forge's tip.
+ * - The local branch is ahead of the forge's, or behind it, or the same: it
+ *   is left, and an apply's push sends what it holds that the forge lacks.
+ *
+ * Nothing is pushed, so a rewritten ledger never goes back to the forge. A
+ * forge that can't be reached leaves everything as it is; the job's own
+ * fetch says why.
+ */
+export function reconcileCiServeLedger(top: string): CiServeEvent | undefined {
+  const local = tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${LEDGER}^{commit}`]);
+  const listed = gitStatus(top, ["ls-remote", "--exit-code", "origin", `refs/heads/${LEDGER}`]);
+  if (listed.code === 2) {
+    // A remote-tracking ref left from a deleted branch would be the next push's lease, and refuse it.
+    tryGit(top, ["update-ref", "-d", `refs/remotes/origin/${LEDGER}`]);
+    if (!local) return undefined;
+    tryGit(top, ["update-ref", "-d", `refs/heads/${LEDGER}`, local]);
+    return { type: "ledger", action: "deleted", local };
+  }
+  if (listed.code !== 0 || !local) return undefined;
+  const forge = listed.out.split(/\s+/)[0];
+  if (!forge || forge === local) return undefined;
+  if (gitStatus(top, ["fetch", "--quiet", "--no-tags", "origin", `+refs/heads/${LEDGER}:${FORGE_LEDGER}`]).code !== 0) return undefined;
+  try {
+    const ahead = gitStatus(top, ["merge-base", "--is-ancestor", forge, local]).code === 0;
+    const behind = gitStatus(top, ["merge-base", "--is-ancestor", local, forge]).code === 0;
+    if (ahead || behind) return undefined;
+    tryGit(top, ["update-ref", `refs/heads/${LEDGER}`, forge, local]);
+    tryGit(top, ["update-ref", `refs/remotes/origin/${LEDGER}`, forge]);
+    return { type: "ledger", action: "reset", local, forge };
+  } finally {
+    tryGit(top, ["update-ref", "-d", FORGE_LEDGER]);
+  }
+}
+
+/** A commit message that asks for no CI run, as Actions and GitLab read it. */
+const SKIP_CI = /\[(?:skip ci|ci skip)\]/i;
+
+/** Whether `commit`'s message asks for no CI run. A commit this clone can't read is not skipped. */
+function skipsCi(top: string, commit: string): boolean {
+  const body = tryGit(top, ["log", "-1", "--format=%B", commit]);
+  return body !== undefined && SKIP_CI.test(body);
+}
+
+/**
+ * How the target branch moved from `from` to `head` (#4122): `fast-forward`
+ * when `head` descends from `from`, `other` when it does not, and `unknown`
+ * when `head` could not be fetched. Once `head` is here its history is too,
+ * so a `from` this clone lacks is not in that history.
+ */
+function targetMove(top: string, branch: string, from: string, head: string): "fast-forward" | "other" | "unknown" {
+  tryGit(top, ["fetch", "--quiet", "--no-tags", "origin", branch]);
+  if (gitStatus(top, ["cat-file", "-e", `${head}^{commit}`]).code !== 0) return "unknown";
+  return gitStatus(top, ["merge-base", "--is-ancestor", from, head]).code === 0 ? "fast-forward" : "other";
+}
+
 /** Where a serve keeps its state when `--state` names nowhere: beside the run events, in the repository's common git directory. */
 export function defaultCiServeStateDir(cwd: string): string {
   const common = tryGit(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
@@ -209,15 +304,23 @@ const failedEntry = (entry: CiServeJobState | undefined, key: string, rt: CiServ
 
 /**
  * One poll of the forge, as triggers: an apply when the target's head moved
- * since the last apply (none on the first poll, which only notes the head),
+ * since the last apply by a fast-forward (none on the first poll, which only
+ * notes the head, and none for a head whose message says `[skip ci]`),
  * then a plan for each open pull request head not yet planned, oldest pull
  * request first. A job already in the state file is left out unless it
- * failed and `rerunFailed` is set. The first poll's head is written to the
- * state file.
+ * failed and `rerunFailed` is set. The first poll's head, and a head seen
+ * and not applied, are written to the state file.
  */
 export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime = newCiServeRuntime()): Promise<{ triggers: CiServeTrigger[]; events: CiServeEvent[] }> {
   const place = servePlace(opts);
-  const state = readCiServeState(place.stateFile, { forge: opts.forge, repo: opts.repo, env: opts.env, branch: place.branch, ...(place.member ? { member: place.member } : {}) });
+  const fresh = { forge: opts.forge, repo: opts.repo, env: opts.env, branch: place.branch, ...(place.member ? { member: place.member } : {}) };
+  const state = readCiServeState(place.stateFile, fresh);
+  // Read again at the write: a job of this serve may have settled while the forge answered.
+  const update = (fn: (s: CiServeState) => void): void => {
+    const s = readCiServeState(place.stateFile, fresh);
+    fn(s);
+    writeState(place.stateFile, s);
+  };
   const triggers: CiServeTrigger[] = [];
   const events: CiServeEvent[] = [];
   const [head, prs] = await Promise.all([opts.client.branchHead(place.branch), opts.client.openPullRequests(place.branch)]);
@@ -226,12 +329,23 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
     events.push({ type: "no-branch", branch: place.branch });
   } else if (state.target === undefined) {
     // What the branch held before this runner watched it was applied by whatever ran then.
-    state.target = head;
-    writeState(place.stateFile, state);
+    update((s) => {
+      s.target = head;
+    });
     events.push({ type: "baseline", commit: head });
   } 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 })];
-    if (!entry) triggers.push({ job: "apply", commit: head, base: state.target });
+    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))) {
+      // #4122: a move that is not a fast-forward, or a head that asks for no run, is seen and not applied.
+      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 });
   } else {
     const key = ciServeKey({ job: "apply", commit: head });
@@ -252,8 +366,17 @@ export async function ciServeObserve(opts: CiServeOptions, rt: CiServeRuntime =
     const key = ciServeKey({ job: "plan", commit: pr.headSha, pr: pr.number });
     const entry = state.jobs[key];
     const base = pr.baseSha ?? head;
-    if (!base) continue;
-    if (!entry) triggers.push({ job: "plan", commit: pr.headSha, base, pr: pr.number });
+    if (!base || state.skipped?.[key]) continue;
+    if (!entry) {
+      // #4122: a head whose message asks for no run is seen and not planned.
+      if (gitStatus(place.top, ["cat-file", "-e", `${pr.headSha}^{commit}`]).code !== 0) tryGit(place.top, ["fetch", "--quiet", "--no-tags", "origin", `refs/pull/${pr.number}/head`]);
+      if (skipsCi(place.top, pr.headSha)) {
+        update((s) => {
+          s.skipped = { ...s.skipped, [key]: "skip-ci" };
+        });
+        events.push({ type: "not-run", job: "plan", commit: pr.headSha, pr: pr.number, reason: "skip-ci" });
+      } else triggers.push({ job: "plan", commit: pr.headSha, base, pr: pr.number });
+    }
     else if (opts.rerunFailed && failedEntry(entry, key, rt)) triggers.push({ job: "plan", commit: pr.headSha, base: entry.base, pr: pr.number, rerun: true });
   }
   return { triggers, events };
@@ -316,6 +439,12 @@ export async function ciServeSchedule(opts: CiServeOptions, triggers: readonly C
       lease = got.lease;
     }
 
+    // #4121: with no other job of this serve writing it, the clone's ledger follows the forge's.
+    if (rt.inflight.size === 0) {
+      const ledger = reconcileCiServeLedger(place.top);
+      if (ledger) emit(ledger);
+    }
+
     const previous = readCiServeState(place.stateFile, fresh).jobs[key];
     const attempt = (previous?.attempts ?? 0) + 1;
     const runId = `chant-serve-${now().getTime()}-${t.job}-${t.commit.slice(0, 8)}`;
@@ -442,6 +571,14 @@ export function formatCiServeEvent(e: CiServeEvent): string {
       return `${at(e.job, e.commit, e.pr)} started, run ${e.runId}, attempt ${e.attempt}${e.resume ? ", resuming" : ""}`;
     case "settled":
       return `${at(e.job, e.commit, e.pr)} ${e.status === "ok" ? "passed" : `failed${e.failure ? `: ${e.failure}` : ""}`}${e.report ? `; report ${e.report}` : ""}`;
+    case "not-run":
+      return e.reason === "skip-ci"
+        ? `${at(e.job, e.commit, e.pr)} is not run: its commit message says [skip ci]`
+        : `${e.branch ?? "the target branch"} moved from ${e.from?.slice(0, 12) ?? "a commit"} to ${e.commit.slice(0, 12)}, which is not a fast-forward, so ${e.commit.slice(0, 12)} is recorded as seen and not applied`;
+    case "ledger":
+      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 "error":
       return `error: ${e.message}`;
   }
@@ -478,7 +615,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>] [--branch <name>] [--events-json] [--report-url <url>] [--no-status] [--status-url <url template>] " +
+  "[--author <login>]... [--once] [--rerun-failed] [--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_]*$/;
@@ -508,12 +645,26 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
     const stateDir = args.statePath ? resolve(args.statePath) : defaultCiServeStateDir(cwd);
     const branch = args.branch ?? "main";
     // #4099: the host's key, checked against .chant/trust.json at the target's head before the first poll.
-    const keyed = ciServeRunnerKey({ top, stateDir, branch, ...(args.key !== undefined ? { keyFile: resolve(args.key) } : {}), envKey: process.env[RUNNER_KEY_ENV] || undefined, unsigned: args.unsigned });
+    // #4156: signing is opt-in. Without ci.green.signedSince no key is quiet, and an untrusted one warns once and serves unsigned.
+    const keyed = ciServeRunnerKey({
+      top,
+      stateDir,
+      branch,
+      ...(args.key !== undefined ? { keyFile: resolve(args.key) } : {}),
+      envKey: process.env[RUNNER_KEY_ENV] || undefined,
+      unsigned: args.unsigned,
+      required: signedRunsRequired(cwd),
+    });
     const fromFlag = keyed.fromFlag;
     const runnerKey = keyed.pem;
-    console.error(`ci serve: ${runnerKey === undefined ? "runs are not signed (--unsigned)" : `signing runs with the runner key from ${keyed.source}`}`);
+    if (keyed.warning) console.error(formatWarning({ message: keyed.warning }));
+    if (runnerKey !== undefined) console.error(`ci serve: signing runs with the runner key from ${keyed.source}`);
+    else if (keyed.note && args.verbose) console.error(`ci serve: ${keyed.note}`);
     // #4096: read once, so a loose or broken secrets file stops the serve before its first poll.
     const secrets = ciSecretsOf(args.ciSecrets);
+    // #4160: without --report-url, the declaration's ci.reportUrl.
+    const reportUrl = await reportUrlOf(args.reportUrl, cwd);
+    if (reportUrl && !args.reportUrl) console.error(`ci serve: reports and the run index go to ${reportUrl}, the declaration's ci.reportUrl`);
     const hostEnv = { ...process.env, GITHUB_REPOSITORY: args.ciRepo };
     const client = forgeFromEnv(forge, hostEnv);
     const { status, warning } = ciStatusFromEnv({ forge, hostEnv, noStatus: args.noStatus, statusUrl: args.statusUrl });
@@ -530,14 +681,7 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
       ...(args.ciAuthors?.length ? { authors: args.ciAuthors } : {}),
       ...(args.rerunFailed ? { rerunFailed: true } : {}),
       job: {
-        loop: {
-          ...(args.gate ? { gate: args.gate } : {}),
-          ...(args.branch ? { branch: args.branch } : {}),
-          ...(args.eventsJson ? { events: true } : {}),
-          ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
-          ...(args.prBuild ? { build: true } : {}),
-          ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
-        },
+        loop: ciLoopOptions(reportUrl ? { ...args, reportUrl } : args),
         ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),
         ...(args.image ? { image: args.image } : {}),
         ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
@@ -550,7 +694,7 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
         hostEnv,
         stepOutput: (line) => void process.stderr.write(`${line}\n`),
       },
-      log: (e) => console.error(e.type === "error" ? formatWarning({ message: formatCiServeEvent(e) }) : `ci serve: ${formatCiServeEvent(e)}`),
+      log: (e) => console.error(e.type === "error" || e.type === "ledger" ? formatWarning({ message: formatCiServeEvent(e) }) : `ci serve: ${formatCiServeEvent(e)}`),
     };
     if (args.once) {
       const pass = await ciServePass(opts);

package/src/workspace/declaration.schema.json

@@ -177,6 +177,11 @@
       "properties": {
         "green": {
           "$ref": "#/$defs/ciGreen"
+        },
+        "reportUrl": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the pull-request jobs copy their reports and events, and where chant ci run keeps the run index, <reportUrl>/runs/index.json (#4160): an s3://<bucket>/<prefix> or file://<directory> URL, as --report-url takes. chant build --pr-loop, chant ci run, chant ci serve and chant ci runs use it when --report-url is not given, and the flag wins. Readers find it in chant workspace ls --json as ci.reportUrl. Added in schema 1 by chant 0.124.32, so a declaration that uses it sets minReader to 0.124.32 or newer."
         }
       }
     },
@@ -581,7 +586,7 @@
     },
     "box": {
       "type": "object",
-      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its persistent sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Its services list what the box runs under its supervisor (#2880), which the fly lexicon observes, restarts and applies through sprite-env, and which chant workspace status --json prints. Its factory declares what the box builds, how a build is checked, which member declares the builder agents and where a finished build is published (#3146, ws-077), its listing what the box shows of itself (#3146), and its replicate where the box's work in progress is pushed so a lost box loses none of it (#3172, ws-085). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
+      "description": "The member is a box, or holds a box's declarations (#2726). A box holds no credential: each capability it needs outside itself is reached through a broker, a runtime such as a lobby or a door, which holds the credential and enforces the scope. chant workspace check fails when a file in the member's directory carries a literal secret (WSP121) and when a capability names no broker (WSP122). chant workspace status --json lists the capabilities, so a broker can read the scopes. Its host, slot, ports, state and cookies state the box's isolation (#2727): chant derives each value from the box's identity, its host, the member's name and its slot, and prints them in chant workspace status --json, so a runtime reads them instead of choosing its own. chant workspace check fails when two boxes on a host resolve to the same value (WSP123) and when a box hard-codes a machine path (WSP124). A member that builds the fountain lexicon's Box declares the callback token fountain gives its sandbox as the capability fountain-callback, brokered by fountain, with scope owner, or chant workspace check fails (WSP125, #2780). Its intent names the decision record that says what the box is for (#2850): chant workspace status --json reports the record's state and answer, and chant workspace check fails when no decision record has the id (WSP126) and warns when the record constrains no member or path of this workspace (WSP127, #2857). Its services list what the box runs under its supervisor (#2880), which the fly lexicon observes, restarts and applies through sprite-env, and which chant workspace status --json prints. Its factory declares what the box builds, how a build is checked, which member declares the builder agents and where a finished build is published (#3146, ws-077), its listing what the box shows of itself (#3146), and its replicate where the box's work in progress is pushed so a lost box loses none of it (#3172, ws-085). Added in schema 1 by chant 0.91.0, so a declaration that uses it sets minReader to 0.91.0 or newer.",
       "properties": {
         "intent": {
           "type": "string",
@@ -1518,7 +1523,7 @@
         "signedSince": {
           "type": "string",
           "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
-          "description": "Added by #4031, read by chant 0.124.28 and newer. The full sha of the first commit on branch whose ci/green and ci/revoked tags must carry a DSSE statement in their annotation, signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role. A tag on a strict first-parent ancestor of this commit counts unsigned, so existing tags keep working; a tag on any other commit, this one included, needs a statement. Position in history decides, never a date, which whoever makes a commit or a tag sets. A reader refuses a sha that names no commit in its clone with declaration-invalid. Absent, no tag needs a statement."
+          "description": "Added by #4031, read by chant 0.124.28 and newer. The full sha of the first commit on branch whose ci/green and ci/revoked tags must carry a DSSE statement in their annotation, signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role. A tag on a strict first-parent ancestor of this commit counts unsigned, so existing tags keep working; a tag on any other commit, this one included, needs a statement. Position in history decides, never a date, which whoever makes a commit or a tag sets. A reader refuses a sha that names no commit in its clone with declaration-invalid. Absent, no tag needs a statement. Since chant 0.124.32 (#4156) it covers Op run records the same way, when ci.green.source is runs: an unsigned run counts on a strict first-parent ancestor of this commit and needs a statement on any other, ci serve refuses to start without a runner key trusted at the target's head, and ci run and chant run warn about a run they leave unsigned. Absent, an unsigned run counts and nothing asks for a key."
         },
         "source": {
           "enum": [

package/src/workspace/declaration.test.ts

@@ -436,6 +436,29 @@ describe("retention (#4036)", () => {
   });
 });
 
+describe("ci.reportUrl (#4160)", () => {
+  test("an s3:// or file:// URL is read without its trailing slash, beside green or alone, and is null when absent", () => {
+    expect(parse(base([])).ci).toBeNull();
+    expect(parse(base([], { ci: {} })).ci).toEqual({ green: null, reportUrl: null });
+    expect(parse(base([], { ci: { reportUrl: "s3://acme-reports/prod/" } })).ci).toEqual({ green: null, reportUrl: "s3://acme-reports/prod" });
+    const green = { branch: "main", phases: { build: ["build"] }, require: ["build"] };
+    const d = parse(base([], { ci: { green, reportUrl: "file:///srv/chant-reports" } }));
+    expect(d.ci?.reportUrl).toBe("file:///srv/chant-reports");
+    expect(d.ci?.green?.branch).toBe("main");
+  });
+
+  test("a URL no job can upload to is declaration-invalid, at ci.reportUrl, with the reason --report-url gives", () => {
+    for (const reportUrl of ["https://reports.example/acme", "ftp://example/x", "reports/"]) {
+      const err = failure(base([], { ci: { reportUrl } }));
+      expect(err.code).toBe("declaration-invalid");
+      expect(err.message).toBe(`ci.reportUrl ${reportUrl}: takes an s3://<bucket>/<prefix> or file://<directory> URL`);
+      expect(err.location?.line).toBeGreaterThan(1);
+    }
+    expect(failure(base([], { ci: { reportUrl: "" } })).code).toBe("declaration-invalid");
+    expect(failure(base([], { ci: { reportUrl: 7 } })).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();

package/src/workspace/declaration.ts

@@ -17,6 +17,7 @@
  */
 
 import { RETENTION_KINDS, type RetentionOverride } from "../lifecycle/retention-policy";
+import { parseReportUrl } from "../pr-report-url";
 import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
@@ -232,6 +233,14 @@ export type CiSource = "checks" | "runs";
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
+  /**
+   * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
+   * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
+   * An `s3://` or `file://` URL, as `--report-url` takes, without a trailing
+   * slash. The commands that take `--report-url` default to it. Null when
+   * the declaration sets none.
+   */
+  reportUrl: string | null;
 }
 
 export interface MemberRole {
@@ -1087,8 +1096,15 @@ function retentionOf(raw: unknown): RetentionOverride | null {
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[]; signedSince?: string; source?: CiSource } };
-  if (block.green === undefined) return { green: null };
+  const block = raw as { reportUrl?: string; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[]; signedSince?: string; source?: CiSource } };
+  let reportUrl: string | null = null;
+  if (block.reportUrl !== undefined) {
+    // #4160: refused here as pr-plan and ci run refuse the flag, so a reader never gets a URL no job can write to.
+    const target = parseReportUrl(block.reportUrl, "ci.reportUrl");
+    if ("error" in target) throw new WorkspaceReadError("declaration-invalid", target.error, at("/ci/reportUrl"));
+    reportUrl = target.url;
+  }
+  if (block.green === undefined) return { green: null, reportUrl };
   const g = block.green;
   const phases: CiPhase[] = Object.entries(g.phases).map(([name, p]) => ({
     name,
@@ -1104,7 +1120,7 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/require/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" } };
+  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, reportUrl };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {