@intentius/chant 0.124.31 → 0.124.33

package/src/workspace/ci-runner-key.test.ts

@@ -2,9 +2,10 @@
  * #4099: the runner key on a `chant ci serve` or `chant ci run` host. The
  * key is made in the state directory with mode 0600, `--setup-key --trust`
  * proposes its runner entry on a branch through `trust runner add` (#3510)
- * and never writes the target branch, and `ci serve` refuses to start when
- * `.chant/trust.json` at the target's head does not list its key, unless
- * `--unsigned`.
+ * and never writes the target branch. Signing is opt-in (#4156): `ci serve`
+ * starts with no key and says nothing about it, and serves unsigned with one
+ * warning when `.chant/trust.json` at the target's head does not list its
+ * key. With `ci.green.signedSince` it refuses to start in either case.
  *
  * Every test works in its own temp repository with a bare origin and its own
  * state directory. The jobs' `chant` is a stub script, and no job runs: the
@@ -126,9 +127,12 @@ describe("the host's runner key (#4099)", () => {
     expect(trust.roles.runner).toEqual(["chant-runner:demo"]);
     expect(git(origin, "rev-parse", `${branch}^`)).toBe(main);
 
-    // Until it merges, ci serve refuses the key; once it has, the key signs as the principal.
+    // Until it merges, ci serve serves unsigned with a warning (refuses with the opt-in); once it has, the key signs as the principal.
     const key = hostRunnerKey(state)!;
-    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main" })).toThrow(/not trusted at main/);
+    const pending = ciServeRunnerKey({ top: root, stateDir: state, branch: "main" });
+    expect(pending.pem).toBeUndefined();
+    expect(pending.warning).toMatch(/not trusted at main/);
+    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main", required: main })).toThrow(/not trusted at main/);
     git(root, "push", "-q", "origin", `refs/remotes/origin/${branch}:refs/heads/main`);
     expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main" })).toMatchObject({ pem: key.pem, source: join(state, RUNNER_KEY_FILE) });
     expect(ciTagSigner(root, git(root, "rev-parse", "refs/remotes/origin/main"), key.pem).principal).toBe("chant-runner:demo");
@@ -138,29 +142,63 @@ describe("the host's runner key (#4099)", () => {
     expect(listed.err).toContain("lists it for chant-runner:demo, with the runner role");
   });
 
-  test("ci serve refuses to start with a key trust.json does not list at the target's head, and --unsigned starts without one", async () => {
+  test("ci serve starts with no key and says nothing, and serves unsigned with one warning for a key trust.json does not list (#4156)", async () => {
     const { root } = workspace();
     const state = scratchDir("chant-runner-key-state-");
 
+    // No key: nothing about keys is printed. The serve goes on to the forge, which this test has no token for.
     const none = await cli(root, SERVE(state));
-    expect(none.code).toBe(1);
-    expect(none.err).toContain("there is no runner key");
-
+    expect(none.err.split("\n")).toHaveLength(2);
+    expect(none.err.split("\n")[0]).toContain("chant ci serve: --forge forgejo needs GITHUB_TOKEN");
+    const keyless = ciServeRunnerKey({ top: root, stateDir: state, branch: "main" });
+    expect(keyless.pem).toBeUndefined();
+    expect(keyless.warning).toBeUndefined();
+    expect(keyless.note).toContain("not signed");
+    // --verbose prints that one line.
+    const verbose = await cli(root, [...SERVE(state), "--verbose"]);
+    expect(verbose.err).toContain("ci serve: runs are not signed: there is no runner key");
+
+    // A key the head does not list: one warning at startup, and no key goes to the jobs.
     ensureHostRunnerKey(state);
     const unlisted = await cli(root, SERVE(state));
-    expect(unlisted.code).toBe(1);
-    expect(unlisted.err).toMatch(/not trusted at main [0-9a-f]{12}/);
+    expect(unlisted.err.match(/not trusted at main [0-9a-f]{12}/g)).toHaveLength(1);
+    expect(unlisted.err).toContain("Runs are not signed until it is");
     expect(unlisted.err).toContain("chant ci serve --setup-key --trust");
-    expect(unlisted.err).toContain("chant workspace trust runner add");
+    expect(unlisted.err).not.toContain("signing runs with");
 
-    // A key listed only in the working tree, not at the head, is still refused.
+    // A key listed only in the working tree, not at the head, is not trusted either.
     const other = generateKeyPairSync("ed25519").privateKey.export({ type: "pkcs8", format: "pem" }).toString();
     writeFileSync(join(state, "other.pem"), other, { mode: 0o600 });
     expect(trustWrite({ cwd: root, action: "runner add", name: "ci-bot", key: join(state, "other.pem") })).toMatchObject({ changed: true });
-    const flagged = await cli(root, [...SERVE(state), "--key", join(state, "other.pem")]);
-    expect(flagged.code).toBe(1);
-    expect(flagged.err).toContain("lists no runner with this key");
+    const flagged = ciServeRunnerKey({ top: root, stateDir: state, branch: "main", keyFile: join(state, "other.pem") });
+    expect(flagged.pem).toBeUndefined();
+    expect(flagged.warning).toContain("lists no runner with this key");
+
+    // A key file that is not a key is an error either way.
+    writeFileSync(join(state, "bad.pem"), "not a key", { mode: 0o600 });
+    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main", keyFile: join(state, "bad.pem") })).toThrow(/not an Ed25519 private key in PEM/);
+
+    // --unsigned is accepted and serves unsigned.
+    expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main", unsigned: true })).toMatchObject({ fromFlag: false, source: "none (--unsigned)" });
+  });
+
+  test("with ci.green.signedSince, ci serve refuses to start without a trusted key, --unsigned or not (#4156)", async () => {
+    const { root, main } = workspace();
+    const state = scratchDir("chant-runner-key-state-");
+    const green = { branch: "main", phases: { plan: ["pr-plan"] }, require: ["plan"], source: "runs", signedSince: main };
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green } }) });
 
-    expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main", unsigned: true })).toEqual({ fromFlag: false, source: "none (--unsigned)" });
+    const none = await cli(root, SERVE(state));
+    expect(none.code).toBe(1);
+    expect(none.err).toContain(`ci.green.signedSince is ${main}, so every run must be signed, and there is no runner key`);
+    const unsigned = await cli(root, [...SERVE(state), "--unsigned"]);
+    expect(unsigned.code).toBe(1);
+    expect(unsigned.err).toContain("there is no runner key");
+
+    ensureHostRunnerKey(state);
+    const unlisted = await cli(root, SERVE(state));
+    expect(unlisted.code).toBe(1);
+    expect(unlisted.err).toMatch(/not trusted at main [0-9a-f]{12}/);
+    expect(unlisted.err).toContain("chant workspace trust runner add");
   });
 });

package/src/workspace/ci-runner-key.ts

@@ -217,17 +217,38 @@ export function formatRunnerKeySetup(s: RunnerKeySetup, branch: string): string
 /**
  * The key `ci serve` signs with, checked before its first poll (#4099): the
  * `--key` file, else `CHANT_RUNNER_KEY`, else the host's key in the state
- * directory. Throws, with the command that lists it, when there is none or
- * `.chant/trust.json` at the target's head does not list it with the runner
- * role. With `unsigned` there is no key and nothing is checked.
+ * directory. Signing is opt-in (#4156):
+ *
+ * - With no key, `ci serve` serves unsigned and says so only in `note`.
+ * - A key `.chant/trust.json` at the target's head does not list with the
+ *   runner role, or a target branch it can't find to check against, leaves
+ *   it serving unsigned, with one `warning`.
+ * - With `required` (the declaration's `ci.green.signedSince`) each of
+ *   those refuses to start, as before #4156.
+ *
+ * A key that is not an Ed25519 private key in PEM, or a `--key` file that
+ * can't be read, refuses either way. `unsigned` (`--unsigned`) skips the
+ * key without `required` and is ignored with it.
  */
-export function ciServeRunnerKey(req: { top: string; stateDir: string; branch: string; keyFile?: string; envKey?: string; unsigned?: boolean }): { pem?: string; fromFlag: boolean; source: string } {
-  if (req.unsigned) return { fromFlag: false, source: "none (--unsigned)" };
+export function ciServeRunnerKey(req: {
+  top: string;
+  stateDir: string;
+  branch: string;
+  keyFile?: string;
+  envKey?: string;
+  unsigned?: boolean;
+  /** The declaration's `ci.green.signedSince`, when it sets one: every run must then be signed. */
+  required?: string | null;
+}): { pem?: string; fromFlag: boolean; source: string; warning?: string; note?: string } {
+  const required = req.required ?? null;
+  const optIn = `ci.green.signedSince is ${required}, so every run must be signed`;
+  if (req.unsigned && !required) return { fromFlag: false, source: "none (--unsigned)", note: "runs are not signed (--unsigned)" };
   const host = req.keyFile === undefined && !req.envKey ? hostRunnerKey(req.stateDir) : undefined;
   const pem = req.keyFile !== undefined ? readFileSync(req.keyFile, "utf-8") : req.envKey || host?.pem;
   const source = req.keyFile !== undefined ? req.keyFile : req.envKey ? "CHANT_RUNNER_KEY" : (host?.path ?? join(req.stateDir, RUNNER_KEY_FILE));
   if (pem === undefined) {
-    throw new CiRunError(`there is no runner key: no --key, no CHANT_RUNNER_KEY and no ${source}. Make one with chant ci serve --setup-key, list it with --trust, or start with --unsigned`);
+    if (!required) return { fromFlag: false, source: "none", note: "runs are not signed: there is no runner key. To verify who ran a job, add one with chant ci serve --setup-key --trust" };
+    throw new CiRunError(`${optIn}, and there is no runner key: no --key, no CHANT_RUNNER_KEY and no ${source}. Make one with chant ci serve --setup-key and list it with --trust`);
   }
   let publicKey: string;
   try {
@@ -236,13 +257,17 @@ export function ciServeRunnerKey(req: { top: string; stateDir: string; branch: s
     throw new CiRunError(`the runner key from ${source} is not an Ed25519 private key in PEM: ${message(err)}`);
   }
   const head = targetHead(req.top, req.branch);
-  if (!head) throw new CiRunError(`there is no branch ${req.branch} here or on origin, so the runner key can't be checked against its .chant/trust.json; fetch it, or start with --unsigned`);
+  if (!head) {
+    const why = `there is no branch ${req.branch} here or on origin, so the runner key can't be checked against its .chant/trust.json`;
+    if (required) throw new CiRunError(`${optIn}, and ${why}; fetch it`);
+    return { fromFlag: false, source, warning: `${why}, so runs are not signed; fetch it to sign them` };
+  }
   const listed = runnerKeyListed(req.top, head.commit, pem);
   if (!listed.ok) {
-    throw new CiRunError(
-      `the runner key from ${source} is not trusted at ${branchAt(req.branch, head.commit)}: ${listed.reason}\n` +
-        `  List it on a branch for review with chant ci serve --setup-key --trust, or run ${trustCommand(defaultRunnerPrincipal(), publicKey)} in a checkout of ${req.branch} and merge the change. Start with --unsigned to serve without signing.`,
-    );
+    const why = `the runner key from ${source} is not trusted at ${branchAt(req.branch, head.commit)}: ${listed.reason}`;
+    const fix = `List it on a branch for review with chant ci serve --setup-key --trust, or run ${trustCommand(defaultRunnerPrincipal(), publicKey)} in a checkout of ${req.branch} and merge the change.`;
+    if (required) throw new CiRunError(`${optIn}, and ${why}\n  ${fix}`);
+    return { fromFlag: false, source, warning: `${why}. Runs are not signed until it is. ${fix}` };
   }
   return { pem, fromFlag: req.keyFile !== undefined, source };
 }

package/src/workspace/ci-runner-start.test.ts

@@ -0,0 +1,151 @@
+/**
+ * `chant ci runner-start` and `chant ci run --require-runner-start` (#4147):
+ * the statement checked against `.chant/trust.json` at base, and the
+ * readiness the isolated-runners security group reads (#4168).
+ */
+
+import { createPublicKey, generateKeyPairSync } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test, vi } from "vitest";
+import { parseArgs } from "../cli/parse-args";
+import type { CommandContext } from "../cli/registry";
+import { signRunnerStart, type CiJobIdentity } from "../runner-start";
+import { cleanScratch, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { checkRunnerStart, parseJobSpec, requireRunnerStart, runCiRunnerStart, runnerStartReadiness, runnerStartReadinessAt } from "./ci-runner-start";
+import { ciRun, CiRunError } from "./ci-run";
+import { sshFromEd25519 } from "./trust/dsse";
+import { emptyPolicy } from "./trust/policy";
+
+afterAll(cleanScratch);
+
+function key(principal: string): { principal: string; pem: string; ssh: string; signer: Parameters<typeof signRunnerStart>[1] } {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const jwk = createPublicKey(privateKey).export({ format: "jwk" }) as { x: string };
+  const ssh = sshFromEd25519(Buffer.from(jwk.x, "base64url"));
+  return { principal, pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(), ssh, signer: { principal, key: privateKey, publicKey: ssh } };
+}
+
+const PROVISIONER = key("provisioner");
+const LATER = key("late-provisioner");
+
+/** A repository whose first commit lists PROVISIONER as a runner, and whose second adds LATER. */
+function repo(): { root: string; base: string; head: string } {
+  const root = scratchDir("chant-runner-start-");
+  git(root, "init", "-q", "-b", "main");
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "config", "commit.gpgsign", "false");
+  const trust = (runners: Array<{ principal: string; ssh: string }>) =>
+    JSON.stringify({ schema: 1, runners: runners.map((r) => ({ principal: r.principal, class: "runner", key: r.ssh })), roles: { runner: runners.map((r) => r.principal) } });
+  writeFiles(root, { ".chant/trust.json": trust([PROVISIONER]) });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "trust");
+  const base = git(root, "rev-parse", "HEAD");
+  writeFiles(root, { ".chant/trust.json": trust([PROVISIONER, LATER]) });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "a pull request adds its own provisioner");
+  return { root, base, head: git(root, "rev-parse", "HEAD") };
+}
+
+const R = repo();
+
+const job = (commit: string): CiJobIdentity => ({ system: "github", repo: "acme/infra", run: "4242", attempt: "1", job: "apply", commit, runner: "jit-1" });
+const env = (commit: string, statement?: unknown): Record<string, string> => ({
+  GITHUB_ACTIONS: "true",
+  GITHUB_REPOSITORY: "acme/infra",
+  GITHUB_RUN_ID: "4242",
+  GITHUB_RUN_ATTEMPT: "1",
+  GITHUB_JOB: "apply",
+  GITHUB_SHA: commit,
+  RUNNER_NAME: "jit-1",
+  CHANT_RUNNER_START_FILE: "/nonexistent/runner-start.json",
+  ...(statement ? { CHANT_RUNNER_START: JSON.stringify(statement) } : {}),
+});
+
+describe("checkRunnerStart reads the runner keys at base", () => {
+  test("a statement by a provisioner listed at base verifies", () => {
+    const v = checkRunnerStart({ top: R.root, base: R.base, env: env(R.head, signRunnerStart(job(R.head), PROVISIONER.signer)) });
+    expect(v).toMatchObject({ status: "verified", signer: "provisioner" });
+  });
+
+  test("a provisioner the change itself lists does not count at the base before it", () => {
+    const statement = signRunnerStart(job(R.head), LATER.signer);
+    expect(checkRunnerStart({ top: R.root, base: R.base, env: env(R.head, statement) }).status).toBe("untrusted");
+    expect(checkRunnerStart({ top: R.root, base: R.head, env: env(R.head, statement) }).status).toBe("verified");
+  });
+
+  test("the job's commit stands in for the forge's variable, so a statement for another commit is refused", () => {
+    const statement = signRunnerStart(job(R.head), PROVISIONER.signer);
+    expect(checkRunnerStart({ top: R.root, base: R.base, env: env(R.head, statement), commit: R.base }).status).toBe("mismatch");
+  });
+
+  test("requireRunnerStart throws with the reason, and a missing statement is named", () => {
+    expect(() => requireRunnerStart({ top: R.root, base: R.base, commit: R.head, env: env(R.head) })).toThrow(/--require-runner-start: missing: .*has no runner-start statement/);
+    expect(() => requireRunnerStart({ top: R.root, base: R.base, commit: R.head, env: {} })).toThrow(/needs a forge job to check/);
+    expect(requireRunnerStart({ top: R.root, base: R.base, commit: R.head, env: env(R.head, signRunnerStart(job(R.head), PROVISIONER.signer)) }).signer).toBe("provisioner");
+  });
+});
+
+describe("runnerStartReadiness, for the isolated-runners group", () => {
+  test("a policy with a runner key whose principal holds the runner role is configured", () => {
+    expect(runnerStartReadinessAt(R.root, R.base)).toEqual({ configured: true, gaps: [] });
+  });
+
+  test("no runner key, a key with no runner role, and an unreadable policy each name their gap", () => {
+    expect(runnerStartReadiness(emptyPolicy("x")).gaps.map((g) => g.gap)).toEqual(["no-runner-key"]);
+    const noRole = { ...emptyPolicy("x"), runners: [{ principal: "p", class: "runner" as const, key: PROVISIONER.ssh }] };
+    expect(runnerStartReadiness(noRole)).toMatchObject({ configured: false, gaps: [{ gap: "no-runner-role" }] });
+    expect(runnerStartReadiness(emptyPolicy("x", ["bad json"])).gaps.map((g) => g.gap)).toEqual(["trust-unreadable"]);
+  });
+});
+
+describe("chant ci runner-start sign and verify", () => {
+  test("--job takes JSON or @file, and refuses fields chant does not know", () => {
+    const dir = scratchDir("chant-runner-start-job-");
+    writeFiles(dir, { "job.json": JSON.stringify(job(R.head)) });
+    expect(parseJobSpec(`@${join(dir, "job.json")}`)).toEqual(job(R.head));
+    expect(parseJobSpec('{"system":"gitlab","repo":"g/s/p","run":9,"job":77,"commit":"x"}')).toEqual({ system: "gitlab", repo: "g/s/p", run: "9", attempt: "1", job: "77", commit: "x" });
+    expect(() => parseJobSpec('{"system":"github","pr":7}')).toThrow(/fields chant does not know: pr/);
+    expect(parseArgs(["ci", "runner-start", "sign", "--key", "k.pem", "--principal", "provisioner", "--job", "@job.json"])).toMatchObject({ path: "runner-start", extraPositional: "sign", key: "k.pem", ciPrincipal: "provisioner", ciJob: "@job.json" });
+    expect(parseArgs(["ci", "run", "apply", "--env", "prod", "--require-runner-start"])).toMatchObject({ requireRunnerStart: true });
+  });
+
+  test("sign writes an envelope the job then verifies, and verify exits 1 for another attempt", async () => {
+    const dir = scratchDir("chant-runner-start-cli-");
+    writeFiles(dir, { "key.pem": PROVISIONER.pem, "job.json": JSON.stringify(job(R.head)) });
+    const out = join(dir, "runner-start.json");
+    const ctx = (argv: string[]) => ({ args: parseArgs(argv) }) as unknown as CommandContext;
+    const quiet = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      expect(await runCiRunnerStart(ctx(["ci", "runner-start", "sign", "--key", join(dir, "key.pem"), "--principal", "provisioner", "--job", `@${join(dir, "job.json")}`, "-o", out]))).toBe(0);
+      const statement = JSON.parse(readFileSync(out, "utf8"));
+      const cwd = process.cwd();
+      process.chdir(R.root);
+      try {
+        vi.stubEnv("GITHUB_ACTIONS", "true");
+        for (const [k, v] of Object.entries(env(R.head))) vi.stubEnv(k, v);
+        vi.stubEnv("CHANT_RUNNER_START_FILE", out);
+        expect(await runCiRunnerStart(ctx(["ci", "runner-start", "verify", "--base", R.base]))).toBe(0);
+        vi.stubEnv("GITHUB_RUN_ATTEMPT", "2");
+        expect(await runCiRunnerStart(ctx(["ci", "runner-start", "verify", "--base", R.base]))).toBe(1);
+      } finally {
+        vi.unstubAllEnvs();
+        process.chdir(cwd);
+      }
+      expect(statement.payloadType).toBe("application/vnd.in-toto+json");
+      expect(await runCiRunnerStart(ctx(["ci", "runner-start", "nope"]))).toBe(1);
+    } finally {
+      quiet.mockRestore();
+    }
+  });
+});
+
+describe("ci run --require-runner-start", () => {
+  test("a job with no statement is refused before anything runs, and --local is refused with it", async () => {
+    const run = (extra: Partial<Parameters<typeof ciRun>[0]>) => ciRun({ cwd: R.root, job: "apply", env: "prod", forge: "github", base: R.base, hostEnv: env(R.head), push: false, requireRunnerStart: true, ...extra });
+    await expect(run({})).rejects.toThrow(CiRunError);
+    await expect(run({})).rejects.toThrow(/has no runner-start statement/);
+    await expect(run({ local: true, hostEnv: {} })).rejects.toThrow(/--local runs the job on this machine/);
+  });
+});

package/src/workspace/ci-runner-start.ts

@@ -0,0 +1,193 @@
+/**
+ * `chant ci runner-start sign|verify` and `chant ci run --require-runner-start`
+ * (#4147): the runner-start statement (../runner-start.ts) checked against
+ * `.chant/trust.json` at base.
+ *
+ * - `sign` is for the provisioner that starts a runner for one job: it signs
+ *   the job's ids with a runner key the job never holds and prints the
+ *   envelope, which the provisioner puts where the job looks for it.
+ * - `verify` is for the job: it names itself from the forge's variables,
+ *   reads the statement, and fails unless a runner key `.chant/trust.json`
+ *   at base lists, whose principal holds the `runner` role, signed it for
+ *   this job.
+ * - `ci run --require-runner-start` makes the same check before the job's
+ *   first step, so an apply refuses before it trades for any credentials.
+ *
+ * Requiring the statement is opt-in (#4156). With nothing asking for it,
+ * nothing reads it, and a runner with none never refuses, warns or hides
+ * anything.
+ *
+ * {@link runnerStartReadiness} says whether a repository could require it
+ * at base, and what is missing, for the isolated-runners security group
+ * (#4168, section 8), whose WSP165 check reports these gaps.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { CommandContext } from "../cli/registry";
+import { formatError } from "../cli/format";
+import {
+  ciJobFromEnv,
+  RUNNER_START_SIGNER_ROLE,
+  signRunnerStart,
+  verifyRunnerStartForJob,
+  type CiJobIdentity,
+  type CiSystem,
+  type RunnerStartVerdict,
+} from "../runner-start";
+import { gitRevisionSource } from "./record-source";
+import { gitTop } from "./tree";
+import { loadRunnerKey } from "./trust/dsse";
+import { emptyPolicy, readTrustPolicy, type TrustPolicy } from "./trust/policy";
+
+/** The policy at `base` in the repository around `cwd`. */
+function policyAt(top: string, base: string): TrustPolicy {
+  return readTrustPolicy(gitRevisionSource(top, base), base);
+}
+
+/**
+ * Check this job's runner-start statement against `.chant/trust.json` at
+ * `base`. `commit` is the commit the job runs, in place of the forge's
+ * variable. Never throws.
+ */
+export function checkRunnerStart(input: { top: string; base: string; env?: Record<string, string | undefined>; commit?: string; readFile?: (path: string) => string }): RunnerStartVerdict {
+  const policy = policyAt(input.top, input.base);
+  if (policy.problems.length > 0) return { status: "untrusted", reason: `.chant/trust.json at ${input.base.slice(0, 12)} cannot be read: ${policy.problems.join("; ")}` };
+  return verifyRunnerStartForJob({
+    runners: policy.runners,
+    roles: policy.roles,
+    ...(input.env ? { env: input.env } : {}),
+    ...(input.commit ? { commit: input.commit } : {}),
+    ...(input.readFile ? { readFile: input.readFile } : {}),
+  });
+}
+
+/** One thing a repository lacks before it can require runner-start statements. */
+export interface RunnerStartGap {
+  /** Not a read-contract reason code: the isolated-runners group (#4168) maps each to its own security code. */
+  gap: "no-runner-key" | "no-runner-role" | "trust-unreadable";
+  reason: string;
+}
+
+/**
+ * Whether `.chant/trust.json` in `policy` lets a job require a runner-start
+ * statement: a key under `runners` whose principal holds the `runner` role.
+ * `configured` is true when there are no gaps. For the isolated-runners
+ * security group (#4168); nothing here refuses or warns.
+ */
+export function runnerStartReadiness(policy: TrustPolicy): { configured: boolean; gaps: RunnerStartGap[] } {
+  const gaps: RunnerStartGap[] = [];
+  if (policy.problems.length > 0) {
+    gaps.push({ gap: "trust-unreadable", reason: `.chant/trust.json cannot be read: ${policy.problems.join("; ")}` });
+    return { configured: false, gaps };
+  }
+  if (policy.runners.length === 0) {
+    gaps.push({ gap: "no-runner-key", reason: ".chant/trust.json lists no key under runners for a provisioner to sign with: chant workspace trust runner add <principal> --key <ssh-ed25519 line>" });
+  } else {
+    const holders = new Set((policy.roles[RUNNER_START_SIGNER_ROLE] ?? []).map((p) => p.normalize("NFKC").trim().toLowerCase()));
+    if (!policy.runners.some((r) => holders.has(r.principal.normalize("NFKC").trim().toLowerCase()))) {
+      gaps.push({ gap: "no-runner-role", reason: `no principal under runners holds the ${RUNNER_START_SIGNER_ROLE} role in .chant/trust.json: "roles": { "${RUNNER_START_SIGNER_ROLE}": ["<principal>"] }` });
+    }
+  }
+  return { configured: gaps.length === 0, gaps };
+}
+
+/** {@link runnerStartReadiness} for the repository around `cwd` at `base` (default `HEAD`). */
+export function runnerStartReadinessAt(cwd: string, base = "HEAD"): { configured: boolean; gaps: RunnerStartGap[] } {
+  const top = gitTop(cwd);
+  if (!top) return runnerStartReadiness(emptyPolicy(null, [`${cwd} is not in a git repository`]));
+  const commit = revParse(top, base);
+  return runnerStartReadiness(commit ? policyAt(top, commit) : emptyPolicy(null, [`${base} is not a commit`]));
+}
+
+function revParse(top: string, rev: string): string | undefined {
+  try {
+    return execFileSync("git", ["rev-parse", "--verify", "-q", `${rev}^{commit}`], { cwd: top, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The base `verify` reads trust at: `--base`, else the remote's default branch, else `HEAD`. */
+function verifyBase(top: string, base?: string): string {
+  const rev = base ?? (revParse(top, "refs/remotes/origin/HEAD") ? "refs/remotes/origin/HEAD" : "HEAD");
+  const commit = revParse(top, rev);
+  if (!commit) throw new Error(`--base ${rev} is not a commit in this repository`);
+  return commit;
+}
+
+/** The job named by `--job`: JSON, or `@<file>` holding it. */
+export function parseJobSpec(spec: string): CiJobIdentity {
+  const text = spec.startsWith("@") ? readFileSync(resolve(spec.slice(1)), "utf8") : spec;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw new Error("--job takes the job as JSON, or @<file> holding it: {\"system\":\"github\",\"repo\":\"owner/name\",\"run\":\"<id>\",\"attempt\":\"1\",\"job\":\"apply\",\"commit\":\"<sha>\",\"runner\":\"<name>\"}");
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("--job takes a JSON object");
+  const o = raw as Record<string, unknown>;
+  const str = (k: string): string | undefined => (o[k] === undefined ? undefined : String(o[k]));
+  const known = ["system", "repo", "run", "attempt", "job", "commit", "runner"];
+  const extra = Object.keys(o).filter((k) => !known.includes(k));
+  if (extra.length > 0) throw new Error(`--job has fields chant does not know: ${extra.join(", ")}`);
+  return {
+    system: (str("system") ?? "") as CiSystem,
+    repo: str("repo") ?? "",
+    run: str("run") ?? "",
+    attempt: str("attempt") ?? "1",
+    job: str("job") ?? "",
+    commit: str("commit") ?? "",
+    ...(str("runner") ? { runner: str("runner")! } : {}),
+  };
+}
+
+const USAGE = "chant ci runner-start sign --key <runner key.pem> --principal <name> --job <json|@file> [-o <file>]\n  chant ci runner-start verify [--base <rev>] [--commit <sha>] [--json]";
+
+/** `chant ci runner-start sign|verify`. */
+export async function runCiRunnerStart(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const action = args.extraPositional;
+  try {
+    if (action === "sign") {
+      if (!args.key) throw new Error("--key names the provisioner's runner key, an Ed25519 private key in PEM, which the job never holds");
+      if (!args.ciPrincipal) throw new Error("--principal names the principal .chant/trust.json lists the key for under runners");
+      if (!args.ciJob) throw new Error("--job names the job the runner was started for, as JSON or @<file>");
+      const job = parseJobSpec(args.ciJob);
+      const pem = readFileSync(resolve(args.key), "utf8");
+      const loaded = loadRunnerKey(pem);
+      const envelope = signRunnerStart(job, { principal: args.ciPrincipal, key: loaded.key, publicKey: loaded.publicKey });
+      const text = `${JSON.stringify(envelope)}\n`;
+      if (args.output) writeFileSync(resolve(args.output), text, { mode: 0o644 });
+      else process.stdout.write(text);
+      return 0;
+    }
+    if (action === "verify") {
+      const top = gitTop(process.cwd());
+      if (!top) throw new Error("verify reads .chant/trust.json at a commit, and this directory is not in a git repository");
+      const base = verifyBase(top, args.base);
+      const verdict = checkRunnerStart({ top, base, ...(args.commit ? { commit: args.commit } : {}) });
+      if (args.json) process.stdout.write(`${JSON.stringify({ ...verdict, base })}\n`);
+      else console.error(`ci runner-start: ${verdict.status}: ${verdict.reason}`);
+      return verdict.status === "verified" ? 0 : 1;
+    }
+    throw new Error(`ci runner-start takes sign or verify${action ? `, not ${JSON.stringify(action)}` : ""}`);
+  } catch (err) {
+    console.error(formatError({ message: `chant ci runner-start: ${err instanceof Error ? err.message : String(err)}`, hint: USAGE }));
+    return 1;
+  }
+}
+
+/**
+ * The check `ci run --require-runner-start` makes before the job's first
+ * step: the statement for this job, verified against `.chant/trust.json` at
+ * `base`. Throws with the verdict's reason unless it verified.
+ */
+export function requireRunnerStart(input: { top: string; base: string; commit: string; env: Record<string, string | undefined> }): Extract<RunnerStartVerdict, { status: "verified" }> {
+  const named = ciJobFromEnv(input.env);
+  if (!named.ok) throw new Error(`--require-runner-start needs a forge job to check: ${named.reason}`);
+  const verdict = checkRunnerStart({ top: input.top, base: input.base, env: input.env, commit: input.commit });
+  if (verdict.status !== "verified") throw new Error(`--require-runner-start: ${verdict.status}: ${verdict.reason}`);
+  return verdict;
+}

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);
+  });
+});