@intentius/chant 0.124.30 → 0.124.31

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

@@ -10,15 +10,16 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { afterAll, describe, expect, test } from "vitest";
-import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, declaration, git, repoFixture, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
 import { ciServeInterval, ciServeKey, ciServePass, formatCiServeEvent, readCiServeState, type CiServeEvent, type CiServeForge, type CiServeOptions } from "./ci-serve";
+import { ciRun } from "./ci-run";
 import { acquireLease, releaseLease } from "../lifecycle/lease";
 import { prApplyGroup, prApplyRecordKey } from "../components/pr-pipeline";
 import { parseArgs } from "../cli/parse-args";
-import type { OpenPullRequest } from "../pr-forge";
+import { forgejoForge, githubForge, type ForgeFetch, type OpenPullRequest } from "../pr-forge";
 
 afterAll(cleanScratch);
 
@@ -30,11 +31,14 @@ function commit(root: string, file: string): string {
   return git(root, "rev-parse", "HEAD");
 }
 
-/** A clone on main with a bare origin and member `app`. */
-function workspace(): { root: string; app: string; main: string } {
-  const origin = scratchDir("chant-ci-serve-origin-");
+/** The repository every test starts from, built once: a checkout on main with a bare origin and member `app`. */
+const workspaceTemplate = repoFixture(() => {
+  const top = scratchDir("chant-ci-serve-template-");
+  const origin = join(top, "origin");
+  const root = join(top, "root");
+  mkdirSync(origin);
+  mkdirSync(root);
   git(origin, "init", "-q", "--bare");
-  const root = scratchDir("chant-ci-serve-");
   git(root, "init", "-q");
   git(root, "symbolic-ref", "HEAD", "refs/heads/main");
   writeFiles(root, {
@@ -43,9 +47,17 @@ function workspace(): { root: string; app: string; main: string } {
     "app/a.txt": "a\n",
   });
   git(root, "remote", "add", "origin", origin);
-  const main = commit(root, "app/init.txt");
+  commit(root, "app/init.txt");
   git(root, "push", "-q", "origin", "main");
-  return { root, app: join(root, "app"), main };
+  return top;
+}, "chant-ci-serve-");
+
+/** A copy of the template, its origin pointed at the copy of the bare one. */
+function workspace(): { root: string; app: string; main: string } {
+  const top = workspaceTemplate();
+  const root = join(top, "root");
+  git(root, "remote", "set-url", "origin", join(top, "origin"));
+  return { root, app: join(root, "app"), main: git(root, "rev-parse", "HEAD") };
 }
 
 /** A pull request's head commit, on a branch off main, pushed to the forge's refs/pull/<n>/head. */
@@ -86,9 +98,17 @@ function fakeChant(): string {
 }
 
 /** A forge whose open pull requests and branch head the test sets. */
-function fakeForge(head: string): CiServeForge & { head: string; prs: OpenPullRequest[]; polls: number } {
+function fakeForge(head: string): CiServeForge & { head: string; prs: OpenPullRequest[]; polls: number; merges: Map<string, number | "throw">; asked: string[] } {
   const f = {
     head,
+    merges: new Map<string, number | "throw">(),
+    asked: [] as string[],
+    async pullRequestFor(sha: string) {
+      f.asked.push(sha);
+      const n = f.merges.get(sha);
+      if (n === "throw") throw new Error("forge unavailable");
+      return n ?? null;
+    },
     prs: [] as OpenPullRequest[],
     polls: 0,
     async openPullRequests(base: string) {
@@ -185,6 +205,70 @@ describe("chant ci serve (#4095)", () => {
     expect((await ciServePass(opts)).jobs).toEqual([]);
   });
 
+  test("an apply gets the number of the pull request whose merge commit it is (#4112)", async () => {
+    const { root, app, main } = workspace();
+    const forge = fakeForge(main);
+    const seen: Array<number | undefined> = [];
+    const { opts } = serve(app, forge, { run: (req) => (seen.push(req.pr), ciRun(req)) });
+    await ciServePass(opts);
+    const merged = commit(root, "app/merged.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = merged;
+    forge.merges.set(merged, 17);
+
+    const pass = await ciServePass(opts);
+    expect(forge.asked).toEqual([merged]);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "apply", commit: merged, pr: 17, status: "ok" })]);
+    expect(seen).toEqual([17]);
+  });
+
+  /** A serve over a repository whose baseline pass is done, with the `pr` each run was asked for in `seen`. */
+  async function mergeWithoutPr() {
+    const { root, app, main } = workspace();
+    const forge = fakeForge(main);
+    const seen: Array<number | undefined> = [];
+    const { opts } = serve(app, forge, { run: (req) => (seen.push(req.pr), ciRun(req)) });
+    await ciServePass(opts);
+    return { root, forge, seen, opts };
+  }
+
+  test("an apply with no pull request found runs without --pr (#4112)", async () => {
+    const { root, forge, seen, opts } = await mergeWithoutPr();
+    const direct = commit(root, "app/direct.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = direct;
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "apply", commit: direct, status: "ok" })]);
+    expect(pass.jobs[0]!.pr).toBeUndefined();
+    expect(seen).toEqual([undefined]);
+  });
+
+  test("an apply whose pull request lookup fails runs without --pr (#4112)", async () => {
+    const { root, forge, seen, opts } = await mergeWithoutPr();
+    const broken = commit(root, "app/broken.txt");
+    git(root, "push", "-q", "origin", "main");
+    forge.head = broken;
+    forge.merges.set(broken, "throw");
+    const pass = await ciServePass(opts);
+    expect(pass.jobs).toEqual([expect.objectContaining({ job: "apply", commit: broken, status: "ok" })]);
+    expect(pass.jobs[0]!.pr).toBeUndefined();
+    expect(seen).toEqual([undefined]);
+  });
+
+  test("the forge clients look a merge commit up with one GET each (#4112)", async () => {
+    const sha = "c".repeat(40);
+    const calls: string[] = [];
+    const fetch = (body: unknown): ForgeFetch => async (url, init) => {
+      calls.push(`${init.method} ${new URL(url).pathname}`);
+      return { ok: true, status: 200, text: async () => JSON.stringify(body) };
+    };
+    const gh: CiServeForge = githubForge({ apiBase: "https://api.github.com", repo: "demo/estate", token: "t", fetch: fetch([{ number: 5, merged_at: "2026-10-01T00:00:00Z", merge_commit_sha: sha }]) }) as unknown as CiServeForge;
+    expect(await gh.pullRequestFor!(sha)).toBe(5);
+    const fj: CiServeForge = forgejoForge({ apiBase: "http://forgejo.localhost/api/v1", host: "forgejo.localhost", repo: "demo/estate", token: "t", fetch: fetch({ number: 6 }) }) as unknown as CiServeForge;
+    expect(await fj.pullRequestFor!(sha)).toBe(6);
+    expect(calls).toEqual([`GET /repos/demo/estate/commits/${sha}/pulls`, `GET /api/v1/repos/demo/estate/commits/${sha}/pull`]);
+  });
+
   test("the group's lease held elsewhere holds the apply until it is released", async () => {
     const { root, app, main } = workspace();
     const forge = fakeForge(main);
@@ -209,33 +293,48 @@ describe("chant ci serve (#4095)", () => {
     expect((await acquireLease(group, "after", { cwd: app, mode: "claim" })).acquired).toBe(true);
   });
 
-  test("a failed apply stays failed, and --rerun-failed runs it again with its resume record", async () => {
-    const { root, app, main } = workspace();
-    const forge = fakeForge(main);
-    const failing = serve(app, forge, { hostEnv: { FAKE_EXIT: "3", FAKE_ATTEMPT: "1" } });
-    await ciServePass(failing.opts);
-    const merged = commit(root, "app/merged.txt");
-    git(root, "push", "-q", "origin", "main");
-    forge.head = merged;
+  describe("a failed apply", () => {
+    // The failing apply runs once in beforeAll, and the two tests read what it left, so no test
+    // runs two jobs. A file's beforeAll is not counted in the unit budget (#2817).
+    let w: ReturnType<typeof workspace>;
+    let forge: ReturnType<typeof fakeForge>;
+    let failing: ReturnType<typeof serve>;
+    let merged: string;
+    let failed: Awaited<ReturnType<typeof ciServePass>>;
+    let record: string;
+
+    beforeAll(async () => {
+      w = workspace();
+      forge = fakeForge(w.main);
+      failing = serve(w.app, forge, { hostEnv: { FAKE_EXIT: "3", FAKE_ATTEMPT: "1" } });
+      await ciServePass(failing.opts);
+      merged = commit(w.root, "app/merged.txt");
+      git(w.root, "push", "-q", "origin", "main");
+      forge.head = merged;
+      failed = await ciServePass(failing.opts);
+      record = join(failing.state, "resume", `${prApplyRecordKey("prod", merged, "app")}.json`);
+    });
+
+    test("stays failed, and keeps its resume record", async () => {
+      expect(failed.jobs).toEqual([expect.objectContaining({ job: "apply", status: "fail", attempts: 1, failure: expect.stringContaining("command-failed") })]);
+      expect(JSON.parse(readFileSync(record, "utf-8"))).toEqual({ attempt: "1" });
+      expect(existsSync(join(failed.jobs[0]!.report!, "resume-in.json"))).toBe(false);
+
+      // Without --rerun-failed the failed apply is not run again.
+      expect((await ciServePass(failing.opts)).jobs).toEqual([]);
+    });
 
-    const failed = await ciServePass(failing.opts);
-    expect(failed.jobs).toEqual([expect.objectContaining({ job: "apply", status: "fail", attempts: 1, failure: expect.stringContaining("command-failed") })]);
-    const record = join(failing.state, "resume", `${prApplyRecordKey("prod", merged, "app")}.json`);
-    expect(JSON.parse(readFileSync(record, "utf-8"))).toEqual({ attempt: "1" });
-    expect(existsSync(join(failed.jobs[0]!.report!, "resume-in.json"))).toBe(false);
-
-    // Without --rerun-failed the failed apply is not run again.
-    expect((await ciServePass(failing.opts)).jobs).toEqual([]);
-
-    const retry = serve(app, forge, { stateDir: failing.state, rerunFailed: true, hostEnv: { FAKE_EXIT: "0", FAKE_ATTEMPT: "2" } });
-    const again = await ciServePass(retry.opts);
-    expect(again.jobs).toEqual([expect.objectContaining({ job: "apply", commit: merged, base: main, status: "ok", attempts: 2 })]);
-    expect(ofType(retry.events, "started")[0]).toMatchObject({ attempt: 2, resume: record });
-    // The job read the first attempt's record, and left its own.
-    expect(JSON.parse(readFileSync(join(again.jobs[0]!.report!, "resume-in.json"), "utf-8"))).toEqual({ attempt: "1" });
-    expect(JSON.parse(readFileSync(record, "utf-8"))).toEqual({ attempt: "2" });
-    // A passed apply is not run again, --rerun-failed or not.
-    expect((await ciServePass(retry.opts)).jobs).toEqual([]);
+    test("--rerun-failed runs it again with its resume record", async () => {
+      const retry = serve(w.app, forge, { stateDir: failing.state, rerunFailed: true, hostEnv: { FAKE_EXIT: "0", FAKE_ATTEMPT: "2" } });
+      const again = await ciServePass(retry.opts);
+      expect(again.jobs).toEqual([expect.objectContaining({ job: "apply", commit: merged, base: w.main, status: "ok", attempts: 2 })]);
+      expect(ofType(retry.events, "started")[0]).toMatchObject({ attempt: 2, resume: record });
+      // The job read the first attempt's record, and left its own.
+      expect(JSON.parse(readFileSync(join(again.jobs[0]!.report!, "resume-in.json"), "utf-8"))).toEqual({ attempt: "1" });
+      expect(JSON.parse(readFileSync(record, "utf-8"))).toEqual({ attempt: "2" });
+      // A passed apply is not run again, --rerun-failed or not.
+      expect((await ciServePass(retry.opts)).jobs).toEqual([]);
+    });
   });
 
   test("--max-jobs holds the jobs over the limit for the next poll", async () => {

package/src/workspace/ci-serve.ts

@@ -15,6 +15,10 @@
  *   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
@@ -34,16 +38,17 @@
 
 import { execFileSync } 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 { CI_JOB_OPS, ciJobPlace, ciSecretsOf, ciRun, ciStatusFromEnv, CiRunError, type CiJobName, type CiRunRequest, type CiRunResult } from "./ci-run";
 import { RUNNER_KEY_ENV } from "./ci-green";
 import { 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 +57,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. */
@@ -347,17 +354,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 +377,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);
@@ -439,10 +449,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>] [--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,24 +495,37 @@ 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.
+    const keyed = ciServeRunnerKey({ top, stateDir, branch, ...(args.key !== undefined ? { keyFile: resolve(args.key) } : {}), envKey: process.env[RUNNER_KEY_ENV] || undefined, unsigned: args.unsigned });
+    const fromFlag = keyed.fromFlag;
+    const runnerKey = keyed.pem;
+    console.error(`ci serve: ${runnerKey === undefined ? "runs are not signed (--unsigned)" : `signing runs with the runner key from ${keyed.source}`}`);
+    // #4096: read once, so a loose or broken secrets file stops the serve before its first poll.
+    const secrets = ciSecretsOf(args.ciSecrets);
     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 } : {}),
@@ -488,10 +538,13 @@ export async function runCiServe(ctx: CommandContext): Promise<number> {
           ...(args.prBuild ? { build: true } : {}),
           ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
         },
+        ...(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,

package/src/workspace/reason-codes.test.ts

@@ -44,6 +44,7 @@ import { PLANTABLE_REASON_CODES } from "./box-factory";
 import { BOX_FACTORY_ERROR_CODES } from "./box-factory-write";
 import { BOX_LISTING_ERROR_CODES } from "./box-listing";
 import { DECLARATION_WRITE_ERROR_CODES } from "./declaration-write";
+import { TRUST_WRITE_ERROR_CODES } from "./trust/trust-write";
 import { BOX_PUBLISH_ERROR_CODES } from "./box-publish";
 import { WRITE_LOCK_ERROR_CODES } from "./write-lock-cli";
 import { WIP_ERROR_CODES, WIP_WRITE_ERROR_CODES } from "./wip";
@@ -115,6 +116,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   PLANTABLE_REASON_CODES,
   BOX_LISTING_ERROR_CODES,
   DECLARATION_WRITE_ERROR_CODES,
+  TRUST_WRITE_ERROR_CODES,
   BOX_FACTORY_ERROR_CODES,
   BOX_PUBLISH_ERROR_CODES,
   WRITE_LOCK_ERROR_CODES,

package/src/workspace/reason-codes.ts

@@ -271,6 +271,11 @@ export const REASONS = {
   // A declaration's members and hosts written through chant (member add|remove, host set, #3596): why the write was refused. Nothing is written.
   "member-exists": "member add names a member the declaration already has, with an entry other than the one given.",
   "member-unknown": "member remove names a member the declaration does not declare.",
+  // A runner entry of .chant/trust.json written through chant (trust runner add|remove, #3510): why the write was refused. Nothing is written.
+  "trust-config-invalid": ".chant/trust.json in the working tree is not JSON or does not match its schema, or the write would make it so.",
+  "trust-conflict": "--expect named a digest .chant/trust.json no longer has: another write changed it after the caller read it. The refusal names the digest it has now.",
+  "runner-exists": "trust runner add names a principal .chant/trust.json already lists with another key or class, or gives a key it lists for another principal.",
+  "runner-unknown": "trust runner remove names a principal .chant/trust.json lists no runner for.",
   // A box's factory written through chant (box factory set, #3600): why the write was refused. Nothing is written.
   "factory-member-unknown": "box factory set names a member the declaration does not declare.",
   "factory-box-missing": "box factory set names a member whose entry declares no box block, so it has no factory.",
@@ -314,8 +319,8 @@ export const REASONS = {
   "evidence-payload-type": "The envelope's payload type is not application/vnd.in-toto+json.",
   "evidence-statement-invalid": "The payload is not an in-toto Statement v1 with chant's runner-evidence predicate, or has a field the predicate does not define.",
   "evidence-runner-mismatch": "The statement names a runner other than the one whose key signed it.",
-  "runner-key-invalid": "The key given to evidence sign or runs sign is not an Ed25519 private key in PEM.",
-  "runner-key-is-signer": "The key given to evidence sign or runs sign is a person's key in the signers file. Evidence and run statements are signed by a service or CI identity.",
+  "runner-key-invalid": "The key given to evidence sign or runs sign is not an Ed25519 private key in PEM, or the key given to trust runner add is not an ssh-ed25519 public key or an Ed25519 key in PEM.",
+  "runner-key-is-signer": "The key given to evidence sign, runs sign or trust runner add is a person's key in the signers file, or trust runner add names a signer. Evidence and run statements are signed by a service or CI identity.",
   "runner-key-unlisted": "The policy at base lists no runner with the key given to evidence sign or runs sign.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",

package/src/workspace/trust/trust-write.test.ts

@@ -0,0 +1,179 @@
+/**
+ * #3510: a runner entry of `.chant/trust.json` written through chant, with
+ * `--by` and `--expect` as the other working-tree writes take them, and read
+ * back by the readers that use runners: `readTrustPolicy`, `ciTagSigner` and
+ * `ci tick --source runs`.
+ *
+ * Each test works in its own temp repository (a bare origin where it pushes),
+ * and every key is a throwaway one. Nothing is written in process.cwd().
+ */
+
+import { execFileSync } from "node:child_process";
+import { createPublicKey, generateKeyPairSync } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { parseArgs } from "../../cli/parse-args";
+import { cleanScratch, contract, declaration, git, scratchDir, writeFiles } from "../__fixtures__/contract-repo";
+import { ciTagSigner, ciTick, opRunSigner } from "../ci-green";
+import { workingTreeSource } from "../record-source";
+import schema from "../trust-write.schema.json";
+import { runOpLocally } from "../../op/local-executor";
+import type { ActivityFn } from "../../op/activity-registry";
+import { sshFromEd25519 } from "./dsse";
+import { readTrustPolicy } from "./policy";
+import { trustDigest, trustWrite, type TrustWriteDocument, type TrustWriteRequest } from "./trust-write";
+
+afterAll(cleanScratch);
+
+const { expectValid } = contract(schema);
+
+function runnerKey(): { pem: string; ssh: string } {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const jwk = createPublicKey(privateKey).export({ format: "jwk" }) as { x: string };
+  return { pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(), ssh: sshFromEd25519(Buffer.from(jwk.x, "base64url")) };
+}
+
+function emptyRepo(files: Record<string, string> = {}): string {
+  const root = scratchDir("chant-trust-write-");
+  git(root, "init", "-q");
+  writeFiles(root, files);
+  return root;
+}
+
+function run(root: string, req: Omit<TrustWriteRequest, "cwd">): TrustWriteDocument {
+  const doc = trustWrite({ ...req, cwd: root });
+  expectValid(doc);
+  return doc;
+}
+
+const code = (doc: TrustWriteDocument) => ("error" in doc ? doc.error.code : null);
+const trustOf = (root: string) => JSON.parse(readFileSync(join(root, ".chant/trust.json"), "utf-8")) as Record<string, unknown>;
+const ok = (doc: TrustWriteDocument) => {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+};
+
+describe("trust runner add and remove (#3510)", () => {
+  test("add writes the entry and the runner role, remove takes both away, and a stale --expect is refused", () => {
+    const root = emptyRepo();
+    const bot = runnerKey();
+    writeFiles(root, { "keys/bot.pub": `${bot.ssh} bot@host\n` });
+
+    const added = ok(run(root, { action: "runner add", name: "ci:acme/app", key: "keys/bot.pub", by: "github:alex" }));
+    expect(added).toMatchObject({ action: "runner add", changed: true, previous: null, entry: { principal: "ci:acme/app", class: "runner", key: bot.ssh }, runnerRole: true, paths: [".chant/trust.json"] });
+    expect(added.previousDigest).toBe(trustDigest(null));
+    expect(added.digest).toBe(trustDigest(readFileSync(join(root, ".chant/trust.json"), "utf-8")));
+    expect(trustOf(root)).toEqual({ schema: 1, runners: [{ principal: "ci:acme/app", class: "runner", key: bot.ssh }], roles: { runner: ["ci:acme/app"] } });
+
+    // The same entry again changes nothing, and says so.
+    const again = ok(run(root, { action: "runner add", name: "ci:acme/app", key: bot.ssh, expect: added.digest }));
+    expect(again).toMatchObject({ changed: false, paths: [], digest: added.digest });
+
+    // A second runner, from a PEM private key, as a lobby holds it.
+    const lobby = runnerKey();
+    writeFileSync(join(root, "lobby.pem"), lobby.pem);
+    const second = ok(run(root, { action: "runner add", name: "studio:lobby", key: "lobby.pem", runnerClass: "service", expect: added.digest }));
+    expect(second).toMatchObject({ entry: { principal: "studio:lobby", class: "service", key: lobby.ssh }, runnerRole: false });
+
+    // The policy reads both, with the role for the runner only.
+    const policy = readTrustPolicy(workingTreeSource(root), null);
+    expect(policy.problems).toEqual([]);
+    expect(policy.runners.map((r) => r.principal)).toEqual(["ci:acme/app", "studio:lobby"]);
+    expect(policy.roles.runner).toEqual(["ci:acme/app"]);
+
+    const removed = ok(run(root, { action: "runner remove", name: "ci:acme/app", by: "github:alex", expect: second.digest }));
+    expect(removed).toMatchObject({ changed: true, previous: { principal: "ci:acme/app" }, entry: null, runnerRole: false });
+    expect(trustOf(root)).toEqual({ schema: 1, runners: [{ principal: "studio:lobby", class: "service", key: lobby.ssh }], roles: { runner: [] } });
+
+    // The digest the caller read is the one before the remove: refused, naming the last write.
+    const stale = run(root, { action: "runner remove", name: "studio:lobby", expect: second.digest });
+    expect(code(stale)).toBe("trust-conflict");
+    expect("conflict" in stale && stale.conflict).toMatchObject({ expected: second.digest, digest: removed.digest, lastWrite: { verb: "trust runner remove", by: "github:alex" } });
+    expect(trustOf(root).runners).toHaveLength(1);
+
+    expect(code(run(root, { action: "runner remove", name: "ci:acme/app" }))).toBe("runner-unknown");
+  });
+
+  test("an existing file is edited in place, keeping its other keys and layout", () => {
+    const text = `{\n  "schema": 1,\n  "roles": {\n    "admin": ["alex"]\n  },\n  "adopted": []\n}\n`;
+    const root = emptyRepo({ ".chant/trust.json": text });
+    const bot = runnerKey();
+    const doc = ok(run(root, { action: "runner add", name: "ci-bot", key: bot.ssh, expect: trustDigest(text) }));
+    const after = readFileSync(join(root, ".chant/trust.json"), "utf-8");
+    expect(after.startsWith(`{\n  "schema": 1,\n  "roles": {\n    "admin": ["alex"],`)).toBe(true);
+    expect(JSON.parse(after)).toEqual({ schema: 1, roles: { admin: ["alex"], runner: ["ci-bot"] }, adopted: [], runners: [{ principal: "ci-bot", class: "runner", key: bot.ssh }] });
+    expect(doc.digest).toBe(trustDigest(after));
+    // --dry-run reports the same and writes nothing.
+    const dry = ok(run(root, { action: "runner remove", name: "ci-bot", dryRun: true }));
+    expect(dry.changed).toBe(true);
+    expect(readFileSync(join(root, ".chant/trust.json"), "utf-8")).toBe(after);
+  });
+
+  test("refusals: a key that is not ssh-ed25519, a person's key, a taken key or principal, a broken file", () => {
+    const bot = runnerKey();
+    const person = runnerKey();
+    const root = emptyRepo({ ".chant/allowed_signers": `alex ${person.ssh}\n` });
+    expect(code(run(root, { action: "runner add", name: "x", key: "ssh-rsa AAAAB3NzaC1yc2E=" }))).toBe("runner-key-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: "ssh-ed25519 AAAA" }))).toBe("runner-key-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: "no-such-file.pub" }))).toBe("runner-key-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: person.ssh }))).toBe("runner-key-is-signer");
+    expect(code(run(root, { action: "runner add", name: "alex", key: bot.ssh }))).toBe("runner-key-is-signer");
+    expect(code(run(root, { action: "runner add", name: "x" }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: bot.ssh, runnerClass: "person" }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "runner add", name: "x", key: bot.ssh, expect: "abc" }))).toBe("write-usage-invalid");
+    expect(code(run(root, { action: "runner remove", name: "x", key: bot.ssh }))).toBe("write-usage-invalid");
+
+    ok(run(root, { action: "runner add", name: "ci-bot", key: bot.ssh }));
+    expect(code(run(root, { action: "runner add", name: "other", key: bot.ssh }))).toBe("runner-exists");
+    expect(code(run(root, { action: "runner add", name: "ci-bot", key: runnerKey().ssh }))).toBe("runner-exists");
+    expect(code(run(root, { action: "runner add", name: "ci-bot", key: bot.ssh, runnerClass: "service" }))).toBe("runner-exists");
+
+    writeFileSync(join(root, ".chant/trust.json"), `{ "schema": 2 }`);
+    expect(code(run(root, { action: "runner add", name: "y", key: runnerKey().ssh }))).toBe("trust-config-invalid");
+    expect(code(trustWrite({ cwd: scratchDir("chant-trust-nogit-"), action: "runner add", name: "y", key: bot.ssh }))).toBe("not-a-git-repository");
+  });
+
+  test("the command line takes --class, --key, --by and --expect", () => {
+    const args = parseArgs(["workspace", "trust", "runner", "add", "ci-bot", "--key", "k.pub", "--class", "service", "--by", "github:alex", "--expect", "a".repeat(64)]);
+    expect(args).toMatchObject({ key: "k.pub", runnerClass: "service", by: "github:alex", expect: "a".repeat(64) });
+  });
+});
+
+describe("a runner added through the write is trusted by the readers (#3510)", () => {
+  test("ci tick --source runs tags a commit from a run signed by a runner the write listed", async () => {
+    const bot = runnerKey();
+    const origin = scratchDir("chant-trust-write-origin-");
+    git(origin, "init", "-q", "--bare");
+    const root = scratchDir("chant-trust-write-ci-");
+    git(root, "init", "-q");
+    git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+    git(root, "remote", "add", "origin", origin);
+    const green = { branch: "main", phases: { test: ["test"] }, require: ["test"], source: "runs" };
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green } }), "app/a.txt": "a\n", "runner.pem": bot.pem });
+    writeFiles(root, { ".gitignore": "runner.pem\n" });
+
+    // Before the write, the key is refused.
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "init");
+    expect(() => ciTagSigner(root, git(root, "rev-parse", "HEAD"), bot.pem)).toThrow(/lists no runner with this key/);
+
+    ok(run(root, { action: "runner add", name: "ci-bot", key: "runner.pem", by: "t" }));
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "trust the ci-bot runner");
+    const head = git(root, "rev-parse", "HEAD");
+    expect(ciTagSigner(root, head, bot.pem).principal).toBe("ci-bot");
+
+    const pass = new Map<string, ActivityFn>([["step", async () => ({})]]);
+    const op = { name: "test", overview: "run test", labels: { Env: "ci" }, phases: [{ name: "Run", steps: [{ kind: "activity" as const, fn: "step", args: {} }] }] };
+    const { record } = await runOpLocally(op, pass, {}, undefined, { cwd: root, ledger: { cwd: root }, signRecord: opRunSigner(root, bot.pem) });
+    expect(record.gitSha).toBe(head);
+    git(root, "push", "-q", "origin", "main");
+    git(root, "push", "-q", "origin", "chant/lifecycle");
+
+    const tick = await ciTick({ cwd: root, runnerKey: bot.pem, now: new Date() });
+    expect(tick.made).toEqual([`ci/green/${head}`]);
+    expect(tick.signer).toBe("ci-bot");
+    expect(execFileSync("git", ["ls-remote", "--tags", origin], { encoding: "utf-8" })).toContain(`refs/tags/ci/green/${head}`);
+  });
+});