@intentius/chant 0.124.32 → 0.124.33

package/src/workspace/ci-run-index.schema.json

@@ -23,7 +23,7 @@
       "if": { "properties": { "status": { "const": "fail" } } },
       "then": { "required": ["failure"], "properties": { "failure": { "type": "object" } } },
       "properties": {
-        "job": { "enum": ["plan", "apply"] },
+        "job": { "enum": ["plan", "apply", "record"], "description": "record (#4168, chant 0.124.33 and newer): the merge record job." },
         "pr": { "type": ["integer", "null"], "minimum": 1, "description": "The pull or merge request number: the one the job's report names, else --pr. null when neither has one." },
         "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit the job ran at." },
         "status": { "enum": ["ok", "fail"] },

package/src/workspace/ci-run-index.ts

@@ -44,7 +44,7 @@ export const CI_RUN_INDEX_LIMIT = 200;
 
 /** One job the runner ran. */
 export interface CiRunIndexEntry {
-  job: "plan" | "apply";
+  job: "plan" | "apply" | "record";
   /** The pull request, or null when the job found none. */
   pr: number | null;
   commit: string;

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

@@ -206,7 +206,11 @@ describe("the job as an Op (#4094)", () => {
       expect(ciLoopOptions(args)).toEqual({ gate: "infra", waveGate: "release" });
     }
     const [plan, apply] = prLoopJobs("forgejo", "prod", ciLoopOptions(parseArgs(["ci", "run", "apply", "--env", "prod", "--wave-gate", "release"])));
-    expect(apply!.command).toContain("--require-review --wave-gate release --resume .chant/pr-resume/pr-apply.json");
+    // #4168: no --require-review unless asked for.
+    expect(apply!.command).toContain(" --wave-gate release --resume .chant/pr-resume/pr-apply.json");
+    expect(apply!.command).not.toContain("--require-review");
+    const reviewed = prLoopJobs("forgejo", "prod", ciLoopOptions(parseArgs(["ci", "run", "apply", "--env", "prod", "--wave-gate", "release", "--require-review"])))[1]!;
+    expect(reviewed.command).toContain("--require-review --wave-gate release --resume .chant/pr-resume/pr-apply.json");
     expect(apply!.command).not.toContain("--wave ");
     expect(plan!.command).toContain("--wave-gate release");
     expect(plan!.command).not.toContain("--wave ");
@@ -294,7 +298,7 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
 
     expect(apply.status).toBe("ok");
     const applyArgs = readFileSync(join(reports, "apply", "pr-apply.args"), "utf-8").trimEnd().split("\n");
-    expect(applyArgs).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--require-review", "--resume", ".chant/pr-resume/pr-apply.json"]);
+    expect(applyArgs).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--resume", ".chant/pr-resume/pr-apply.json"]);
     expect(formatCiRun(apply)).toContain("signed by chant-runner");
   });
 
@@ -310,6 +314,17 @@ describe("chant ci run, then ci tick from runs (#4094)", () => {
     expect(record.phases.apply![0]).toMatchObject({ name: "pr-apply", opRun: { id: apply.record.id, signer: "chant-runner" } });
   });
 
+  test("under the isolated-runners security group an apply job requires a runner-start statement, and a plan job does not (#4168)", async () => {
+    const { root, app, base } = workspace();
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app", security: ["isolated-runners"] }], { ci: { green: GREEN } }) });
+    git(root, "commit", "-qam", "isolated-runners");
+    git(root, "push", "-q", "origin", "main");
+    const job = (j: "plan" | "apply") =>
+      ciRun({ image: JOB_IMAGE, cwd: app, job: j, env: "prod", forge: "github", base, ...(j === "plan" ? { pr: 7 } : {}), chant: fakeChant(), hostEnv: HOST, output: join(scratchDir("chant-ci-run-out-"), "pr"), push: false });
+    await expect(job("apply")).rejects.toThrow(/--require-runner-start needs a forge job to check/);
+    expect((await job("plan")).status).toBe("ok");
+  });
+
   test("a failing job is recorded failed, and a key from the environment that trust.json does not list leaves it unsigned, quietly", async () => {
     const { root, app, base } = workspace();
     const stranger = runnerKey();
@@ -746,12 +761,14 @@ describe("a generated forge job runs ci run --in-place (#4156)", () => {
   // What a GitHub or Forgejo job has in its environment: the forge's run, job and attempt, and the secret.
   const FORGE = { GITHUB_RUN_ID: "4242", GITHUB_RUN_ATTEMPT: "2", GITHUB_JOB: "apply", GITHUB_REPOSITORY: "acme/estate", GITHUB_SERVER_URL: "http://forgejo.localhost" };
 
-  test("the generated job's line parses to the same job, and --in-place, --no-push, --no-require-review and --wave reach it", () => {
-    const [plan, apply] = prLoopJobs("forgejo", "prod", { events: true, reportUrl: "s3://b/p", requireReview: false, waveGate: "release", branch: "trunk" });
+  test("the generated job's line parses to the same job, and --in-place, --no-push, --require-review and --wave reach it", () => {
+    const [plan, apply] = prLoopJobs("forgejo", "prod", { events: true, reportUrl: "s3://b/p", requireReview: true, waveGate: "release", branch: "trunk" });
     expect(plan!.run.command).toBe('chant ci run plan --in-place --no-push --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --forge forgejo --wave-gate release --events-json --report-url "s3://b/p"');
     const args = parseArgs(apply!.run.command.replace(/"\$BASE_SHA"/, "b".repeat(40)).replace(/"/g, "").split(" ").slice(1).concat(["--wave", "2"]));
-    expect(args).toMatchObject({ ciInPlace: true, requireReview: false, wave: 2, waveGate: "release", branch: "trunk", eventsJson: true, reportUrl: "s3://b/p" });
-    expect(ciLoopOptions(args)).toEqual({ gate: "pr-apply", branch: "trunk", events: true, reportUrl: "s3://b/p", waveGate: "release", requireReview: false });
+    expect(args).toMatchObject({ ciInPlace: true, requireReview: true, wave: 2, waveGate: "release", branch: "trunk", eventsJson: true, reportUrl: "s3://b/p" });
+    expect(ciLoopOptions(args)).toEqual({ gate: "pr-apply", branch: "trunk", events: true, reportUrl: "s3://b/p", waveGate: "release", requireReview: true });
+    // --no-require-review, which pipelines generated before #4168 pass, is the default now.
+    expect(ciLoopOptions(parseArgs(["ci", "run", "apply", "--no-require-review"]))).toEqual({});
     expect(parseArgs(["ci", "run", "plan", "--no-push"]).noPush).toBe(true);
     // ci run rebuilds pr-apply from those options: the very command the job ran before #4156.
     expect(prLoopJobs("forgejo", "prod", ciLoopOptions(args))[1]!.command).toBe(apply!.command);
@@ -774,7 +791,7 @@ describe("a generated forge job runs ci run --in-place (#4156)", () => {
     expect(r.report).toBe(join(realpathSync(app), ".chant/pr"));
     expect(r.record.phases.map((p) => p.name)).toEqual(["apply"]);
     const argv = readFileSync(join(app, ".chant/pr/pr-apply.args"), "utf-8").trimEnd().split("\n");
-    expect(argv).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--require-review", "--resume", ".chant/pr-resume/pr-apply.json"]);
+    expect(argv).toEqual(["components", "pr-apply", "--base", base, "--env", "prod", "--gate", "pr-apply", "--output", ".chant/pr", "--forge", "forgejo", "--member", "app", "--resume", ".chant/pr-resume/pr-apply.json"]);
     // The forge job's whole environment reaches the step, but never the runner key.
     const env = envFile(join(app, ".chant/pr"), "pr-apply");
     expect(env).toMatchObject({ NOT_FOR_JOBS: "leak", GITHUB_RUN_ID: "4242", BASE_SHA: base, GITHUB_SHA: sha });

package/src/workspace/ci-run.ts

@@ -1,5 +1,5 @@
 /**
- * `chant ci run plan|apply` (#4094, epic #4101): run one pull-request job as
+ * `chant ci run plan|record|apply` (#4094, epic #4101, record #4168): run one pull-request job as
  * a pipeline Op, the first slice of the chant runner.
  *
  * The job is the typed value `prLoopJobs` (../components/pr-pipeline.ts)
@@ -99,13 +99,22 @@ import { resolveMemberContext } from "./member-pipeline";
 import { signOpRunRecord } from "./trust/op-run-statement";
 import { gitTop } from "./tree";
 import { hostRunnerKey } from "./ci-runner-key";
+import { requireRunnerStart } from "./ci-runner-start";
+import { securityGroupsAt } from "./security";
 
-/** The two jobs a pull-request pipeline has. */
+/** The jobs a pull-request pipeline has: plan, and on merge record (#4168) or, opted in, apply. */
 export type CiJobName = PrLoopJob["jobName"];
-export const CI_JOB_NAMES: readonly CiJobName[] = ["plan", "apply"];
+export const CI_JOB_NAMES: readonly CiJobName[] = ["plan", "apply", "record"];
 
 /** The Op each job is recorded as, which `ci.green` phases match. */
-export const CI_JOB_OPS: Record<CiJobName, string> = { plan: "pr-plan", apply: "pr-apply" };
+export const CI_JOB_OPS: Record<CiJobName, string> = { plan: "pr-plan", apply: "pr-apply", record: "pr-record" };
+
+/** What each job's Op says it does. */
+const CI_JOB_OVERVIEWS: Record<CiJobName, string> = {
+  plan: "Plan the members this pull request reaches",
+  apply: "Apply the plan a reviewer approved",
+  record: "Record the plan on the merged commit; nothing applies",
+};
 
 /** Where a job the chant runner ran says it ran (#4094). */
 export const CHANT_RUNNER_ORIGIN: RunOrigin = { forge: "chant" };
@@ -255,7 +264,7 @@ export function ciJobOp(input: CiJobOpInput): OpConfig {
   const op = CI_JOB_OPS[input.job.jobName];
   return {
     name: op,
-    overview: input.job.jobName === "plan" ? "Plan the members this pull request reaches" : "Apply the plan a reviewer approved",
+    overview: CI_JOB_OVERVIEWS[input.job.jobName],
     labels: { Env: input.env, Pipeline: "pr", Job: input.job.jobName },
     phases,
   };
@@ -353,12 +362,12 @@ const STATUS_DESCRIPTION = 140;
 const cut = (text: string, max = STATUS_DESCRIPTION): string => (text.length > max ? `${text.slice(0, max - 3)}...` : text);
 
 /**
- * A job's status context: `chant/pr-plan` for the plan, and for the apply
+ * A job's status context: `chant/pr-plan` for the plan, `chant/pr-record` for the record (#4168), and for the apply
  * `chant/<gate>`, which is `chant/pr-apply` unless `--gate` renamed the gate.
  * pr-plan's own status is `chant/plan` (../pr-loop.ts), a different context.
  */
 export function ciStatusContext(job: CiJobName, gate?: string): string {
-  return job === "apply" ? `chant/${gate ?? PR_APPLY_GATE}` : `chant/${CI_JOB_OPS.plan}`;
+  return job === "apply" ? `chant/${gate ?? PR_APPLY_GATE}` : `chant/${CI_JOB_OPS[job]}`;
 }
 
 /**
@@ -483,6 +492,12 @@ export interface CiRunRequest {
    * `runOrigin: { forge: "local" }` and `runtime: "local"`.
    */
   local?: boolean;
+  /**
+   * `--require-runner-start` (#4147): refuse the job before its first step
+   * unless a runner-start statement, signed by a runner key
+   * `.chant/trust.json` at `base` lists, names this forge job.
+   */
+  requireRunnerStart?: boolean;
   /**
    * `--wave <k>` (#4003, #4156): the one wave a generated apply job runs, as
    * `pr-apply --wave <k>`. Needs `--wave-gate`.
@@ -648,6 +663,10 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const found = jobs.find((j) => j.jobName === req.job);
   if (!found) throw new CiRunError(`the pull-request pipeline has no ${req.job} job; it has ${jobs.map((j) => j.jobName).join(" and ")}`);
   if (req.wave !== undefined && (req.job !== "apply" || !req.loop?.waveGate)) throw new CiRunError("--wave names the one wave an apply runs, and takes --wave-gate: ci run apply --wave-gate <gate> --wave <k>");
+  // #4147: before anything runs or any secret reaches a step, the provisioner's word that this runner was started for this job.
+  // #4168: under the isolated-runners security group an apply job requires the statement too, unless it runs on this machine.
+  const isolated = !req.requireRunnerStart && !req.local && req.job === "apply" && securityGroupsAt(cwd).has("isolated-runners");
+  const started = req.requireRunnerStart || isolated ? runnerStartFor(req, { top, commit, hostEnv }) : undefined;
   // A generated wave job's command, as prLoopWaveJobs writes it. #4161: a local job's command posts no status or note.
   const command = `${found.command}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${req.local ? " --no-status" : ""}`;
   const job = { ...found, command, ...(req.wave !== undefined ? { wave: req.wave } : {}) };
@@ -666,7 +685,8 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   // In place the forge's own variables come too; one whose value is short, such as a flag, is left out, so it can't blank common words.
   const redact = ciRedactor(req.inPlace ? { ...longValues(jobEnv), ...own } : jobEnv, req.secrets);
   try {
-    const result = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
+    const ran = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
+    const result = started ? { ...ran, notes: [started, ...ran.notes] } : ran;
     return redact ? { ...result, warnings: result.warnings.map(redact), notes: result.notes.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result;
   } catch (err) {
     if (redact && err instanceof Error) err.message = redact(err.message);
@@ -674,6 +694,22 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   }
 }
 
+/**
+ * `--require-runner-start` (#4147): the runner-start statement for this
+ * forge job, checked against `.chant/trust.json` at `--base` (the commit
+ * before the change, as a push's `before` is), or at the job's commit
+ * without one. Throws {@link CiRunError} unless it verifies.
+ */
+function runnerStartFor(req: CiRunRequest, at: { top: string; commit: string; hostEnv: Record<string, string | undefined> }): string {
+  if (req.local) throw new CiRunError("--require-runner-start checks a forge job's runner, and --local runs the job on this machine");
+  const base = req.base ? resolveJobCommit(at.top, req.base) : at.commit;
+  try {
+    return requireRunnerStart({ top: at.top, base, commit: at.commit, env: at.hostEnv }).reason;
+  } catch (err) {
+    throw new CiRunError(message(err));
+  }
+}
+
 /** The generator's options for a `--local` job (#4161): the same, with no report URL. */
 function localLoop(loop: PrLoopPipelineOptions | undefined): PrLoopPipelineOptions {
   const { reportUrl: _dropped, ...rest } = loop ?? {};
@@ -899,8 +935,8 @@ export function formatCiRun(r: CiRunResult): string {
  * The generator's options from `ci run`'s and `ci serve`'s flags, as `chant
  * build --components --generate <lexicon> --pr-loop` takes them: `--gate`,
  * `--branch`, `--events-json`, `--report-url`, `--pr-build`,
- * `--pr-build-command`, `--wave-gate` (#4003) and `--no-require-review`
- * (#4156).
+ * `--pr-build-command`, `--wave-gate` (#4003) and `--require-review`
+ * (#4168; `--no-require-review`, the default, is still accepted).
  */
 export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptions {
   return {
@@ -911,15 +947,15 @@ export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptio
     ...(args.prBuild ? { build: true } : {}),
     ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
     ...(args.waveGate ? { waveGate: args.waveGate } : {}),
-    ...(args.requireReview === false ? { requireReview: false } : {}),
+    ...(args.requireReview === true ? { requireReview: true } : {}),
   };
 }
 
 const USAGE =
-  "chant ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
+  "chant ci run plan|record|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
   "[--gate <name>] [--wave-gate <name>] [--wave <k>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
-  "[--pr-build] [--pr-build-command <line>] [--no-require-review] [--no-status] [--status-url <url template>] " +
-  "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
+  "[--pr-build] [--pr-build-command <line>] [--require-review] [--no-status] [--status-url <url template>] " +
+  "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --at <sha> | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -942,13 +978,38 @@ export function ciSecretsOf(flag: string | undefined, env: Record<string, string
   return file === undefined ? undefined : readCiSecrets(resolve(file));
 }
 
-/** `chant ci run plan|apply` (#4094). */
+/**
+ * `chant ci run --at <sha>` (#4169): ask for every required phase to be built
+ * at a commit of the green branch. On GitHub, with a token in the
+ * environment, the workflows holding the phases start at once.
+ */
+async function requestBuildCommand(at: string): Promise<number> {
+  const { requestBuild } = await import("./ci-green");
+  const { ciForgeFromEnv } = await import("./ci-green-forge");
+  let forge: Awaited<ReturnType<typeof ciForgeFromEnv>> | undefined;
+  try {
+    forge = process.env.GITHUB_REPOSITORY ? ciForgeFromEnv("github") : undefined;
+  } catch {
+    forge = undefined;
+  }
+  const r = await requestBuild({ cwd: process.cwd(), at, ...(forge ? { forge } : {}) });
+  for (const w of r.warnings) console.error(formatWarning({ message: w }));
+  const what = `${r.request.phases.join(", ")} at ${r.request.commit.slice(0, 12)}`;
+  console.log(
+    `${r.existed ? `${r.request.tag} already asks for a build` : `Asked for ${what}: ${r.request.tag}`}. ` +
+      (r.dispatched.length > 0 ? `Started ${r.dispatched.join(", ")}.` : "The next ci tick starts it on GitHub, and ci serve --build-command serves it for chant runs."),
+  );
+  return 0;
+}
+
+/** `chant ci run plan|record|apply` (#4094, #4168). */
 export async function runCiRun(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   try {
     if (args.setupKey) return (await import("./ci-serve")).runnerKeySetupCommand(ctx);
+    if (args.at !== undefined && args.extraPositional === undefined) return await requestBuildCommand(args.at);
     const job = args.extraPositional;
-    if (job !== "plan" && job !== "apply") throw new CiRunError(`ci run takes the job to run, plan or apply${job ? `, not ${JSON.stringify(job)}` : ""}`);
+    if (job !== "plan" && job !== "apply" && job !== "record") throw new CiRunError(`ci run takes the job to run, plan, record or apply${job ? `, not ${JSON.stringify(job)}` : ""}`);
     if (!args.env) throw new CiRunError("--env names the environment the pipeline is for, as chant build --components --generate <lexicon> --pr-loop took it: --env <env>");
     const forge = args.forge ?? detectForge(process.env);
     if (!forge) throw new CiRunError("--forge names the forge the job posts to: --forge github|gitlab|forgejo");
@@ -980,6 +1041,7 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
       ...(args.local ? { local: true } : {}),
       ...(args.noPush ? { push: false } : {}),
       ...(args.wave !== undefined ? { wave: args.wave } : {}),
+      ...(args.requireRunnerStart ? { requireRunnerStart: true } : {}),
       ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),
       ...(args.image ? { image: args.image } : {}),
       ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),

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