@intentius/chant 0.124.30 → 0.124.32

package/src/workspace/ci-serve.ts

@@ -15,12 +15,34 @@
  *   the one `chant operator` holds) named for `prApplyGroup`, renews it while
  *   it runs and releases it after. An apply that finds it held waits for a
  *   later poll, as a forge's concurrency group queues it.
+ * - Merged pull request. An apply asks the forge for the pull request whose
+ *   merge commit the new head is (`pullRequestFor`, as pr-apply does) and
+ *   passes it as `--pr`, so its commit status link and run index use
+ *   `<pr>/<commit>`. With none found it runs without `--pr`.
  * - Resume records. Each apply gets `<state>/resume/<prApplyRecordKey>.json`
  *   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
@@ -32,18 +54,20 @@
  * 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 { isAbsolute, join, resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { prApplyGroup, prApplyRecordKey } from "../components/pr-pipeline";
 import { forgeFromEnv, type OpenPullRequest } from "../pr-forge";
 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, ciRun, 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";
 
 /** The forges `ci serve` polls. GitLab is later. */
 export type CiServeForgeKind = "github" | "forgejo";
@@ -52,6 +76,8 @@ export type CiServeForgeKind = "github" | "forgejo";
 export interface CiServeForge {
   openPullRequests(base: string): Promise<OpenPullRequest[]>;
   branchHead(branch: string): Promise<string | undefined>;
+  /** The merged pull request that produced a commit, as pr-apply finds it (`pullRequestFor`). Without it an apply gets no `--pr`. */
+  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. */
@@ -85,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. */
@@ -98,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. */
@@ -152,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"]);
@@ -202,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)]);
@@ -219,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 });
@@ -245,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 };
@@ -309,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)}`;
@@ -347,17 +483,20 @@ async function runJob(
   t: CiServeTrigger,
   paths: { runId: string; report: string; resume?: string },
   held: { lease: LeaseRecord; holder: string; ttlMs: number; now: () => Date } | undefined,
-): Promise<Pick<CiServeJobState, "status" | "failure" | "report">> {
+): Promise<Pick<CiServeJobState, "status" | "failure" | "report" | "pr">> {
   const renew = held
     ? setInterval(() => {
         void acquireLease(place.group, held.holder, { cwd: opts.cwd, ttlMs: held.ttlMs, mode: "renew", token: held.lease.token, now: held.now }).catch(() => undefined);
       }, Math.max(1000, Math.floor(held.ttlMs / 3)))
     : undefined;
   renew?.unref?.();
+  let merged: number | undefined;
   try {
     // The pull request's head is on the forge's refs/pull/<n>/head, the target's on the branch.
     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;
     const run = opts.run ?? ciRun;
     const r = await run({
       ...opts.job,
@@ -367,16 +506,16 @@ async function runJob(
       env: opts.env,
       forge: opts.forge,
       base: t.base,
-      ...(t.job === "plan" ? { pr: t.pr } : {}),
+      ...(t.job === "plan" ? { pr: t.pr } : merged !== undefined ? { pr: merged } : {}),
       commit: t.commit,
       output: paths.report,
       runId: paths.runId,
       ...(paths.resume ? { resumeRecord: paths.resume } : {}),
     });
     const why = r.record.failure ? `${r.record.failure.code}: ${r.record.failure.reason}` : r.failure ? `${r.failure.phase}: ${r.failure.error.split("\n")[0]}` : undefined;
-    return { status: r.status === "ok" ? "ok" : "fail", ...(why && r.status !== "ok" ? { failure: why } : {}), ...(r.report ? { report: r.report } : {}) };
+    return { status: r.status === "ok" ? "ok" : "fail", ...(merged !== undefined ? { pr: merged } : {}), ...(why && r.status !== "ok" ? { failure: why } : {}), ...(r.report ? { report: r.report } : {}) };
   } catch (err) {
-    return { status: "fail", failure: message(err) };
+    return { status: "fail", ...(merged !== undefined ? { pr: merged } : {}), failure: message(err) };
   } finally {
     if (renew) clearInterval(renew);
     if (held) await releaseLease(place.group, held.holder, held.lease.token, { cwd: opts.cwd }).catch(() => false);
@@ -432,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}`;
   }
@@ -439,10 +586,37 @@ export function formatCiServeEvent(e: CiServeEvent): string {
 
 // ── The command ──────────────────────────────────────────────────────────────
 
+/**
+ * `chant ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]` (#4099):
+ * make the host's runner key when there is none, print its public half on
+ * stdout, and say whether the target's head lists it. With --trust, commit
+ * the runner entry on a branch of its own and push it for review.
+ */
+export function runnerKeySetupCommand(ctx: CommandContext): number {
+  const { args } = ctx;
+  const cwd = process.cwd();
+  const top = gitTop(cwd);
+  if (!top) throw new CiRunError("the runner key is kept in the repository's git directory, and this directory is not in a git repository");
+  if (args.ciPrincipal !== undefined && !args.trustKey) throw new CiRunError("--principal names who --trust lists the key for; give --trust with it");
+  const branch = args.branch ?? "main";
+  const setup = setupRunnerKey({
+    top,
+    stateDir: args.statePath ? resolve(args.statePath) : defaultCiServeStateDir(cwd),
+    branch,
+    ...(args.ciPrincipal ? { principal: args.ciPrincipal } : {}),
+    ...(args.trustKey ? { trust: true } : {}),
+    ...(args.by ? { by: args.by } : {}),
+  });
+  console.log(setup.key.publicKey);
+  console.error(formatRunnerKeySetup(setup, branch));
+  return 0;
+}
+
 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>] " +
-  "[--image <image>] [--before-script <line>]... [--pr-build] [--pr-build-command <line>] [--chant <command>] [--pass-env <NAME>]... [--key <runner key.pem>]";
+  "[--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_]*$/;
 
@@ -458,46 +632,69 @@ export function ciServeInterval(value: string | undefined): number {
 export async function runCiServe(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   try {
+    if (args.setupKey) return runnerKeySetupCommand(ctx);
     const forge = args.forge;
     if (forge !== "forgejo" && forge !== "github") throw new CiRunError(`--forge names the forge ci serve polls: --forge forgejo|github${forge ? `, not ${JSON.stringify(forge)}` : ""}`);
     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)}`);
     const intervalMs = ciServeInterval(args.interval);
-    const fromFlag = args.key !== undefined;
-    const runnerKey = fromFlag ? readFileSync(resolve(args.key!), "utf-8") : process.env[RUNNER_KEY_ENV] || undefined;
+    const cwd = process.cwd();
+    const top = gitTop(cwd);
+    if (!top) throw new CiRunError("ci serve runs in a clone of the repository it serves, and this directory is not in a git repository");
+    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.
+    // #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;
+    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 });
+    if (warning) console.error(formatWarning({ message: warning }));
     if (!client.openPullRequests || !client.branchHead) throw new CiRunError(`the ${forge} client cannot list pull requests`);
     const opts: CiServeOptions = {
-      cwd: process.cwd(),
+      cwd,
       forge,
       repo: args.ciRepo,
       env: args.env,
-      client: { openPullRequests: client.openPullRequests.bind(client), branchHead: client.branchHead.bind(client) },
-      ...(args.statePath ? { stateDir: isAbsolute(args.statePath) ? args.statePath : resolve(args.statePath) } : {}),
+      client: { openPullRequests: client.openPullRequests.bind(client), branchHead: client.branchHead.bind(client), pullRequestFor: client.pullRequestFor.bind(client) },
+      stateDir,
       ...(args.maxJobs ? { maxJobs: args.maxJobs } : {}),
       ...(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 } : {}),
         ...(args.ciChant ? { chant: args.ciChant } : {}),
         ...(args.passEnv?.length ? { passEnv: args.passEnv } : {}),
+        ...(status ? { status } : {}),
+        ...(secrets ? { secrets } : {}),
         ...(runnerKey !== undefined ? { runnerKey, runnerKeyFromEnv: !fromFlag } : {}),
         ...(args.eventsJson ? { runEvents: (line: string) => void process.stdout.write(line) } : {}),
         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[] {

package/src/workspace/export.ts

@@ -44,6 +44,7 @@ import { parseJsonText } from "./jsonc";
 import { fileHash, LOCK_FILE, LockError, parseLock, renderLock, type Lineage, type LineageLock } from "./lineage-lock";
 import { loadRecordKind } from "./records";
 import { workingTree } from "./tree";
+import { isWorkDir } from "../lifecycle/work-dir";
 
 /** The role that marks the member an export is written into. */
 export const EXPORT_ROLE = "export";
@@ -142,7 +143,7 @@ export function gitTopOf(dir: string): string | undefined {
 /**
  * The files under `dir` (absolute) that git tracks or would track, relative
  * to `dir`, that exist in the working tree. Outside git, every file, leaving
- * out `.git` and `node_modules`.
+ * out `.git`, `node_modules` and `.chant/work`.
  */
 export function listFiles(dir: string): string[] {
   if (!existsSync(dir)) return [];
@@ -167,8 +168,10 @@ export function listFiles(dir: string): string[] {
     for (const d of readdirSync(join(dir, rel), { withFileTypes: true })) {
       if (d.name === ".git" || d.name === "node_modules") continue;
       const p = rel ? `${rel}/${d.name}` : d.name;
-      if (d.isDirectory()) walk(p);
-      else if (d.isFile()) out.push(p);
+      // `.chant/work` holds work worktrees, each a copy of the checkout (#2893).
+      if (d.isDirectory()) {
+        if (!isWorkDir(p)) walk(p);
+      } else if (d.isFile()) out.push(p);
     }
   };
   walk("");

package/src/workspace/ls.schema.json

@@ -103,7 +103,13 @@
             {
               "type": "object",
               "required": ["green"],
-              "properties": { "green": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/ciGreen" }] } }
+              "properties": {
+                "green": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/ciGreen" }] },
+                "reportUrl": {
+                  "type": "string",
+                  "description": "Added in contract 1 by chant 0.124.32 (#4160). The declaration's ci.reportUrl, an s3:// or file:// URL without a trailing slash, present only when it is set. The run index is at <reportUrl>/runs/index.json (ci-run-index), and each job's report under <reportUrl>/<pr>/<commit>[/<member>]/."
+                }
+              }
             }
           ]
         },

package/src/workspace/ls.ts

@@ -186,8 +186,12 @@ export type LsDocument =
       groups: LsGroup[];
       /** Every declared diagram, the workspace's own first, then each member's, in file order (#2764). */
       diagrams: LsDiagram[];
-      /** What the workspace's CI decides about its commits (#3573), or null with no `ci` block. */
-      ci: { green: LsCiGreen | null } | null;
+      /**
+       * What the workspace's CI decides about its commits (#3573), or null
+       * with no `ci` block. `reportUrl` (#4160) is the declared report URL,
+       * where the run index is kept, present only when it is set.
+       */
+      ci: { green: LsCiGreen | null; reportUrl?: string } | null;
       summary: { members: number; unreadable: number; groups: number; matches: number };
     }
   | {
@@ -330,6 +334,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
                   ...(declaration.ci.green.source === "runs" ? { source: "runs" as const } : {}),
                 }
               : null,
+            ...(declaration.ci.reportUrl !== null ? { reportUrl: declaration.ci.reportUrl } : {}),
           }
         : null,
       summary: {

package/src/workspace/pin-integrity.test.ts

@@ -51,6 +51,11 @@ describe("integrityOf", () => {
     expect(integrityOf(join(dir({ "d/a": "1", "d/b": "2", "d/e": "" }), "d")).integrity).not.toBe(base);
   });
 
+  test("a work worktree under .chant/work is left out, and the rest of .chant is hashed (#2893)", () => {
+    const root = dir({ "d/a": "1", "d/.chant/work/W-1/a": "copy", "d/.chant/work/m/W-2/a": "copy", "d/.chant/notes": "n" });
+    expect(pinnedFiles(join(root, "d"))).toEqual([".chant/notes", "a"]);
+  });
+
   test("node_modules and .git are left out, and a symbolic link is refused", () => {
     const root = dir({ "d/a": "1", "d/node_modules/x/index.js": "x", "d/.git/HEAD": "ref" });
     expect(pinnedFiles(join(root, "d"))).toEqual(["a"]);