@intentius/chant 0.124.26 → 0.124.28

package/src/workspace/ci-green-signed.test.ts

@@ -0,0 +1,302 @@
+/**
+ * #4031: signed ci tags. With `ci.green.signedSince` declared, a green or
+ * revoked tag on a commit made since counts only when its annotation
+ * carries a statement signed by a runner key `.chant/trust.json` lists for
+ * a principal holding the `runner` role. The tick signs what it makes;
+ * `ci tick`, `ci list`, `ci last-green` and the release cut ignore and
+ * report a hand-pushed tag. A tag on an older commit counts unsigned.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createPrivateKey, createPublicKey, generateKeyPairSync } from "node:crypto";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { ciList, ciTick, formatList, formatTick, greenAnnotation, lastGreen, revokedAnnotation, evaluateCommit, type LastGreenDocument } from "./ci-green";
+import type { CheckRun, CiForge } from "./ci-green-forge";
+import type { CiGreen } from "./declaration";
+import { sshFromEd25519 } from "./trust/dsse";
+import { verifyCiTagStatement } from "./trust/ci-tag-statement";
+import lastGreenSchema from "./ci-last-green.schema.json";
+import listSchema from "./ci-list.schema.json";
+
+afterAll(cleanScratch);
+
+const NOW = new Date("2026-10-06T12:00:00Z");
+const hoursAgo = (h: number) => new Date(NOW.getTime() - h * 3_600_000).toISOString();
+const GREEN = { branch: "main", phases: { lint: ["lint"], test: ["test"] }, require: ["lint", "test"] };
+const run = (id: number, name: string, conclusion: string): CheckRun => ({ id, name, status: "completed", conclusion, completedAt: null, url: null });
+const PASSING = [run(1, "lint", "success"), run(2, "test", "success")];
+const FAILING = [run(1, "lint", "success"), run(9, "test", "failure")];
+
+function fakeForge(runs: Map<string, CheckRun[]>): CiForge {
+  return { kind: "github", checkRuns: async (sha) => runs.get(sha) ?? [] };
+}
+
+/** A throwaway runner key: its PEM and its ssh public key line. */
+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 gitAt(cwd: string, date: string, ...args: string[]): string {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false", ...args], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date },
+  }).trim();
+}
+
+function commitAt(root: string, hours: number, file: string): string {
+  writeFiles(root, { [file]: `${file} ${hours}\n` });
+  gitAt(root, hoursAgo(hours), "add", "-A");
+  gitAt(root, hoursAgo(hours), "commit", "-q", "-m", file);
+  return git(root, "rev-parse", "HEAD");
+}
+
+const BOT = runnerKey();
+
+/**
+ * A checkout on main with a bare origin, declaring `ci.green` and listing
+ * BOT as the runner `ci-bot`, which holds the runner role unless `roles`
+ * says otherwise. Unless `unsigned`, history then reads: an init commit 23
+ * hours ago, whatever `before` commits, a pivot commit 15 hours ago, and a
+ * commit 14 hours ago that sets `signedSince` to the pivot. Tags on the
+ * pivot's strict first-parent ancestors count unsigned; tags on the pivot
+ * and everything after it need a statement.
+ */
+function workspace(opts: { roles?: Record<string, string[]>; unsigned?: boolean; before?: (root: string) => void } = {}): { root: string; origin: string; pivot: string | null } {
+  const origin = scratchDir("chant-ci-signed-origin-");
+  git(origin, "init", "-q", "--bare");
+  const root = scratchDir("chant-ci-signed-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  const decl = (green: unknown) => declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green } });
+  writeFiles(root, {
+    "chant.workspace.json": decl(GREEN),
+    ".chant/trust.json": JSON.stringify({ schema: 1, runners: [{ principal: "ci-bot", class: "runner", key: BOT.ssh }], roles: opts.roles ?? { runner: ["ci-bot"] } }),
+    "app/a.txt": "a\n",
+  });
+  git(root, "remote", "add", "origin", origin);
+  commitAt(root, 23, "app/init.txt");
+  if (opts.unsigned) return { root, origin, pivot: null };
+  opts.before?.(root);
+  const pivot = commitAt(root, 15, "app/pivot.txt");
+  writeFiles(root, { "chant.workspace.json": decl({ ...GREEN, signedSince: pivot }) });
+  gitAt(root, hoursAgo(14), "commit", "-q", "-am", "require signed ci tags from the pivot on");
+  return { root, origin, pivot };
+}
+
+/** The listed commits among `shas`, in list order. */
+const only = <T extends { sha: string }>(commits: T[], ...shas: string[]) => commits.filter((c) => shas.includes(c.sha));
+
+/** Push a tag made by hand, the way someone with push rights could go around CI. */
+function handTag(root: string, tag: string, sha: string, message: string, hours = 0): void {
+  gitAt(root, hoursAgo(hours), "tag", "-a", "-m", message, tag, sha);
+  git(root, "push", "-q", "origin", `refs/tags/${tag}`);
+}
+
+const greenOf = (sha: string) => greenAnnotation(GREEN_DECL, sha, evaluateCommit(GREEN_DECL, PASSING), NOW);
+const GREEN_DECL: CiGreen = {
+  branch: "main",
+  window: "24h",
+  phases: [
+    { name: "lint", runs: ["lint"], skipped: "fail", pointer: "" },
+    { name: "test", runs: ["test"], skipped: "fail", pointer: "" },
+  ],
+  require: ["lint", "test"],
+  signedSince: null,
+  source: "checks",
+  pointer: "/ci/green",
+};
+
+describe("signed ci tags (#4031)", () => {
+  const readLast = contract(lastGreenSchema);
+  const readList = contract(listSchema);
+
+  test("a hand-pushed green tag is ignored and reported by ci tick, ci list and ci last-green", async () => {
+    const { root } = workspace();
+    const a = commitAt(root, 5, "app/a.txt");
+    const b = commitAt(root, 3, "app/b.txt");
+    git(root, "push", "-q", "origin", "main");
+    // b never passed, and someone pushes a green tag for it by hand, with the record a tick would write.
+    handTag(root, `ci/green/${b}`, b, greenOf(b));
+    const runs = new Map([
+      [a, PASSING],
+      [b, FAILING],
+    ]);
+
+    const tick = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW, runnerKey: BOT.pem });
+    expect(tick.made).toEqual([`ci/green/${a}`]);
+    expect(tick.signer).toBe("ci-bot");
+    const atB = tick.commits.find((c) => c.sha === b)!;
+    expect(atB.before).toBe("none");
+    expect(atB.ignored).toEqual([{ tag: `ci/green/${b}`, status: "unsigned", reason: expect.stringContaining("carries no statement signed by a runner key") }]);
+    expect(formatTick(tick)).toContain(`ignored ci/green/${b} (unsigned)`);
+
+    // The tick's own tag carries a statement that verifies for ci-bot.
+    const note = git(root, "tag", "-l", "--format=%(contents)", `ci/green/${a}`);
+    const record = JSON.parse(note.slice(note.indexOf("{")));
+    expect(record.statement.signatures).toHaveLength(1);
+    expect(verifyCiTagStatement(record, { sha: a, kind: "green", branch: "main" }, [{ principal: "ci-bot", class: "runner", key: BOT.ssh }], { runner: ["ci-bot"] })).toMatchObject({ status: "signed", signer: "ci-bot" });
+
+    const last = lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>;
+    readLast.expectValid(last);
+    expect(last.commit?.sha).toBe(a);
+    expect(last.ignored.map((t) => [t.tag, t.status])).toEqual([[`ci/green/${b}`, "unsigned"]]);
+
+    const list = await ciList({ cwd: root, now: NOW });
+    readList.expectValid(list);
+    const listed = (list as Extract<typeof list, { commits: unknown }>).commits;
+    expect(only(listed, a, b).map((c) => [c.sha, c.state, c.green?.signer ?? null, c.ignored.map((t) => t.status)])).toEqual([
+      [b, "undecided", null, ["unsigned"]],
+      [a, "green", "ci-bot", []],
+    ]);
+    expect(formatList(list as Extract<typeof list, { commits: unknown }>)).toContain(`ignored ci/green/${b} (unsigned)`);
+  });
+
+  test("a tag on a strict first-parent ancestor of ci.green.signedSince is accepted unsigned", async () => {
+    let old = "";
+    const { root, pivot } = workspace({ before: (r) => void (old = commitAt(r, 20, "app/old.txt")) });
+    const fresh = commitAt(root, 2, "app/fresh.txt");
+    git(root, "push", "-q", "origin", "main");
+    // A tag made the way every tag was made before #4031: no statement.
+    handTag(root, `ci/green/${old}`, old, greenOf(old), 19);
+
+    const last = lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>;
+    expect(last.commit?.sha).toBe(old);
+    expect(last.ignored).toEqual([]);
+    const list = (await ciList({ cwd: root, now: NOW })) as Extract<Awaited<ReturnType<typeof ciList>>, { commits: unknown }>;
+    expect(only(list.commits, fresh, pivot!, old).map((c) => [c.sha, c.state, c.green?.signer ?? null])).toEqual([
+      [fresh, "undecided", null],
+      [pivot, "undecided", null],
+      [old, "green", null],
+    ]);
+    // The pivot itself is not a strict ancestor: its unsigned tag is ignored.
+    handTag(root, `ci/green/${pivot}`, pivot!, greenOf(pivot!), 14);
+    const after = lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>;
+    expect(after.commit?.sha).toBe(old);
+    expect(after.ignored.map((t) => [t.tag, t.status])).toEqual([[`ci/green/${pivot}`, "unsigned"]]);
+  });
+
+  test("a backdated commit outside the ancestry, with an unsigned tag, is ignored", async () => {
+    let old = "";
+    const { root } = workspace({ before: (r) => void (old = commitAt(r, 20, "app/old.txt")) });
+    handTag(root, `ci/green/${old}`, old, greenOf(old), 19);
+    // Committed after signedSince, but with its author and committer times set 40 hours back, before every other commit.
+    const backdated = commitAt(root, 40, "app/backdated.txt");
+    git(root, "push", "-q", "origin", "main");
+    handTag(root, `ci/green/${backdated}`, backdated, greenOf(backdated), 40);
+
+    const last = lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>;
+    expect(last.commit?.sha).toBe(old);
+    expect(last.ignored).toEqual([{ tag: `ci/green/${backdated}`, status: "unsigned", reason: expect.stringContaining("not a strict first-parent ancestor") }]);
+  });
+
+  test("a signedSince that names no commit here is refused as declaration-invalid", async () => {
+    const { root } = workspace({ unsigned: true });
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green: { ...GREEN, signedSince: "f".repeat(40) } } }) });
+    expect(lastGreen({ cwd: root })).toMatchObject({ error: { code: "declaration-invalid", message: expect.stringContaining("is not a commit in this repository") } });
+    expect(await ciList({ cwd: root, now: NOW })).toMatchObject({ error: { code: "declaration-invalid" } });
+    git(root, "push", "-q", "origin", "main");
+    await expect(ciTick({ cwd: root, forge: fakeForge(new Map()), now: NOW, runnerKey: BOT.pem })).rejects.toThrow(/signedSince names f{40}, which is not a commit/);
+  });
+
+  test("a hand-pushed revoked tag without a valid statement is ignored and reported, and the tick's own revocation is signed", async () => {
+    const { root } = workspace();
+    const a = commitAt(root, 4, "app/a.txt");
+    git(root, "push", "-q", "origin", "main");
+    const runs = new Map([[a, PASSING]]);
+    await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW, runnerKey: BOT.pem });
+
+    // Someone revokes the green commit by hand.
+    handTag(root, `ci/revoked/${a}`, a, revokedAnnotation(GREEN_DECL, a, { phase: "test", run: { name: "test", id: 9, status: "completed", conclusion: "failure", url: null, verdict: "fail" } }, NOW));
+    const last = lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>;
+    expect(last.commit?.sha).toBe(a);
+    expect(last.ignored.map((t) => [t.tag, t.status])).toEqual([[`ci/revoked/${a}`, "unsigned"]]);
+    const list = (await ciList({ cwd: root, now: NOW })) as Extract<Awaited<ReturnType<typeof ciList>>, { commits: unknown }>;
+    expect(only(list.commits, a)[0]).toMatchObject({ sha: a, state: "green", revoked: null, ignored: [{ tag: `ci/revoked/${a}`, status: "unsigned" }] });
+
+    // When a really goes red, the tick can't revoke it while the hand-made tag holds the name, and says so.
+    runs.set(a, FAILING);
+    const blocked = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW, runnerKey: BOT.pem });
+    expect(blocked.made).toEqual([]);
+    expect(blocked.commits[0]).toMatchObject({ sha: a, before: "green", blocked: `ci/revoked/${a}` });
+    expect(formatTick(blocked)).toContain(`did not make ci/revoked/${a}: an ignored tag holds the name`);
+
+    // Once a person deletes it, the tick revokes a with a signed tag, which counts.
+    git(root, "push", "-q", "origin", `:refs/tags/ci/revoked/${a}`);
+    const revoked = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW, runnerKey: BOT.pem });
+    expect(revoked.made).toEqual([`ci/revoked/${a}`]);
+    const why = git(root, "tag", "-l", "--format=%(contents)", `ci/revoked/${a}`);
+    expect(JSON.parse(why.slice(why.indexOf("{"))).statement).toBeDefined();
+    expect((lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>).commit).toBeNull();
+  });
+
+  test("a statement by another key, by a runner without the role, or for another commit does not count", async () => {
+    const { root } = workspace({ roles: { runner: ["ci-bot"] } });
+    const a = commitAt(root, 5, "app/a.txt");
+    const b = commitAt(root, 4, "app/b.txt");
+    const c = commitAt(root, 3, "app/c.txt");
+    git(root, "push", "-q", "origin", "main");
+    const mallory = runnerKey();
+    const signer = (key: { pem: string; ssh: string }, principal: string) => ({ principal, key: createPrivateKey(key.pem), publicKey: key.ssh });
+    // a: signed by a key trust.json does not list.
+    handTag(root, `ci/green/${a}`, a, greenAnnotation(GREEN_DECL, a, evaluateCommit(GREEN_DECL, PASSING), NOW, signer(mallory, "ci-bot")));
+    // b: ci-bot's real signature over c's record, copied onto b's tag.
+    const forC = greenAnnotation(GREEN_DECL, c, evaluateCommit(GREEN_DECL, PASSING), NOW, signer(BOT, "ci-bot"));
+    handTag(root, `ci/green/${b}`, b, forC);
+    const list = (await ciList({ cwd: root, now: NOW })) as Extract<Awaited<ReturnType<typeof ciList>>, { commits: unknown }>;
+    expect(only(list.commits, a, b, c).map((x) => [x.sha, x.state, x.ignored.map((t) => t.status)])).toEqual([
+      [c, "undecided", []],
+      [b, "undecided", ["mismatch"]],
+      [a, "undecided", ["untrusted"]],
+    ]);
+
+    // A runner the trust file lists but grants no runner role is not trusted either.
+    const unroled = workspace({ roles: {} });
+    const d = commitAt(unroled.root, 2, "app/d.txt");
+    git(unroled.root, "push", "-q", "origin", "main");
+    handTag(unroled.root, `ci/green/${d}`, d, greenAnnotation(GREEN_DECL, d, evaluateCommit(GREEN_DECL, PASSING), NOW, signer(BOT, "ci-bot")));
+    const last = lastGreen({ cwd: unroled.root }) as Extract<LastGreenDocument, { branch: string }>;
+    expect(last.commit).toBeNull();
+    expect(last.ignored[0]).toMatchObject({ status: "untrusted", reason: expect.stringContaining("holds no runner role") });
+    // And the tick refuses to sign with it, before it tags anything.
+    await expect(ciTick({ cwd: unroled.root, forge: fakeForge(new Map([[d, PASSING]])), now: NOW, runnerKey: BOT.pem })).rejects.toThrow(/holds no runner role/);
+  });
+
+  test("the tick needs a runner key once signedSince is set, and refuses one trust.json does not list", async () => {
+    const { root } = workspace();
+    const a = commitAt(root, 2, "app/a.txt");
+    git(root, "push", "-q", "origin", "main");
+    const forge = fakeForge(new Map([[a, PASSING]]));
+    await expect(ciTick({ cwd: root, forge, now: NOW })).rejects.toThrow(/needs a statement signed by a runner key, and none was given/);
+    await expect(ciTick({ cwd: root, forge, now: NOW, runnerKey: runnerKey().pem })).rejects.toThrow(/lists no runner with this key/);
+    expect(git(root, "tag", "-l")).toBe("");
+    // A dry run decides without a key.
+    expect((await ciTick({ cwd: root, forge, now: NOW, dryRun: true })).made).toEqual([`ci/green/${a}`]);
+  });
+
+  test("without signedSince every tag counts, as before", async () => {
+    const { root } = workspace({ unsigned: true });
+    const a = commitAt(root, 2, "app/a.txt");
+    git(root, "push", "-q", "origin", "main");
+    git(root, "tag", `ci/green/${a}`, a);
+    const last = lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>;
+    expect(last.commit?.sha).toBe(a);
+    expect(last.ignored).toEqual([]);
+  });
+
+  test("last-green --from walks from another revision", async () => {
+    const { root } = workspace();
+    const a = commitAt(root, 4, "app/a.txt");
+    const b = commitAt(root, 3, "app/b.txt");
+    git(root, "push", "-q", "origin", "main");
+    await ciTick({ cwd: root, forge: fakeForge(new Map([[a, PASSING], [b, PASSING]])), now: NOW, runnerKey: BOT.pem });
+    expect((lastGreen({ cwd: root }) as Extract<LastGreenDocument, { branch: string }>).commit?.sha).toBe(b);
+    const from = lastGreen({ cwd: root, from: a }) as Extract<LastGreenDocument, { branch: string }>;
+    expect(from).toMatchObject({ ref: a, commit: { sha: a } });
+    expect(lastGreen({ cwd: root, from: "nope" })).toMatchObject({ error: { code: "revision-unknown" } });
+  });
+});

package/src/workspace/ci-green-workflow.test.ts

@@ -135,6 +135,14 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     expect(text.replace("          token: ${{ secrets.CI_GREEN_TOKEN || github.token }}\n", "")).toBe(plain);
   });
 
+  test("--runner-key-secret hands the tick its runner key from the secret, and nothing else changes (#4031)", () => {
+    const plain = renderCiGreenWorkflow(base);
+    const text = renderCiGreenWorkflow({ ...base, runnerKeySecret: "CHANT_RUNNER_KEY" });
+    const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
+    expect(steps[2].env).toMatchObject({ GITHUB_TOKEN: "${{ github.token }}", CHANT_RUNNER_KEY: "${{ secrets.CHANT_RUNNER_KEY }}" });
+    expect(text.replace("          CHANT_RUNNER_KEY: ${{ secrets.CHANT_RUNNER_KEY }}\n", "")).toBe(plain);
+  });
+
   test("--app-id-var and --app-key-secret mint an App token before the checkout and check out with it", () => {
     const steps = (parseYAMLDocument(renderCiGreenWorkflow({ ...base, push: { appIdVar: "CI_GREEN_APP_ID", appKeySecret: "CI_GREEN_APP_KEY" } })) as Yaml).jobs.tick.steps;
     expect(steps[0]).toMatchObject({
@@ -237,6 +245,12 @@ describe("chant ci workflow (#3573)", () => {
         `# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --app-id-var CI_GREEN_APP_ID --app-key-secret CI_GREEN_APP_KEY (in the workspace root)`,
       );
 
+      // #4031: the runner key's secret goes into the env of the tick and the header.
+      expect(await runCiWorkflow({ args: { ciTokenSecret: "CI_GREEN_TOKEN", ciRunnerKeySecret: "CI_RUNNER_KEY" } } as unknown as CommandContext)).toBe(0);
+      const withKey = readFileSync(file, "utf-8");
+      expect(withKey.split("\n")[0]).toBe(`# ${GENERATED_MARKER}. Regenerate with: chant ci workflow --token-secret CI_GREEN_TOKEN --runner-key-secret CI_RUNNER_KEY (in the workspace root)`);
+      expect((parseYAMLDocument(withKey) as Yaml).jobs.tick.steps[2].env.CHANT_RUNNER_KEY).toBe("${{ secrets.CI_RUNNER_KEY }}");
+
       // Dropping the flag writes the bytes chant 0.108.0 wrote.
       expect(await runCiWorkflow({ args: {} } as unknown as CommandContext)).toBe(0);
       expect(readFileSync(file, "utf-8")).toBe(plain);
@@ -262,6 +276,8 @@ describe("chant ci workflow (#3573)", () => {
       expect(errors.pop()).toMatch(/one or the other/);
       expect(await run({ ciTokenSecret: "ci-green token" })).toBe(1);
       expect(errors.pop()).toMatch(/--token-secret takes a secret or variable name/);
+      expect(await run({ ciRunnerKeySecret: "runner key" })).toBe(1);
+      expect(errors.pop()).toMatch(/--runner-key-secret takes a secret or variable name/);
       expect(existsSync(join(root, CI_GREEN_WORKFLOW_FILE))).toBe(false);
     } finally {
       cwd.mockRestore();

package/src/workspace/ci-green-workflow.ts

@@ -34,6 +34,11 @@
  * tick's own `GITHUB_TOKEN`, which reads check runs, stays the Actions token:
  * a fine-grained personal access token can't call the Checks API.
  *
+ * `--runner-key-secret <NAME>` (#4031) hands the tick the runner key it
+ * signs its tags with, from `secrets.<NAME>` as `CHANT_RUNNER_KEY`. A
+ * declaration that sets `ci.green.signedSince` needs it: a tag outside that
+ * commit's strict first-parent ancestry without a statement is ignored.
+ *
  * Like a member's pipelines (./member-pipeline.ts), the file starts with the
  * generated-file header naming the command, and the member whose directory
  * the command runs in records it in its generated-file record, so `WSP081`
@@ -158,6 +163,12 @@ export interface WorkflowInput {
   workspaceRoot: string;
   /** How the tag push authenticates, when not with the Actions token. */
   push?: PushToken;
+  /**
+   * The repository secret holding the runner key the tick signs its tags
+   * with, as PEM (#4031). The tick step reads it from `CHANT_RUNNER_KEY`.
+   * The key's principal needs the `runner` role in `.chant/trust.json`.
+   */
+  runnerKeySecret?: string;
 }
 
 /**
@@ -237,6 +248,7 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     "          GITHUB_TOKEN: ${{ github.token }}",
     "          GIT_COMMITTER_NAME: github-actions[bot]",
     "          GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com",
+    ...(input.runnerKeySecret ? [`          CHANT_RUNNER_KEY: \${{ secrets.${input.runnerKeySecret} }}`] : []),
     `        run: ${tick}`,
   ];
   return lines.join("\n") + "\n";

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

@@ -10,10 +10,11 @@ import { join } from "node:path";
 import { afterAll, describe, expect, test, vi } from "vitest";
 import { parseDeclaration, type CiPhase } from "./declaration";
 import { cleanScratch, contract, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
-import { ciTick, pushRefusalCause, evaluateCommit, evaluatePhase, latestAttempts, lastGreen, matchesCheckRun, windowMs, type LastGreenDocument } from "./ci-green";
+import { ciList, ciTick, pushRefusalCause, evaluateCommit, evaluatePhase, latestAttempts, lastGreen, matchesCheckRun, windowMs, type LastGreenDocument } from "./ci-green";
 import type { CheckRun, CiForge } from "./ci-green-forge";
-import { runCiLastGreen } from "./ci-green-cli";
+import { runCiLastGreen, runCiList } from "./ci-green-cli";
 import lastGreenSchema from "./ci-last-green.schema.json";
+import listSchema from "./ci-list.schema.json";
 import lsSchema from "./ls.schema.json";
 import { listWorkspace, type LsDocument } from "./ls";
 import type { CommandContext } from "../cli/registry";
@@ -44,8 +45,11 @@ describe("the ci.green block (#3573)", () => {
         { name: "macos", runs: ["macos (test)"], skipped: "pass", pointer: "/ci/green/phases/macos" },
       ],
       require: ["lint", "test", "macos"],
+      signedSince: null,
+      source: "checks",
       pointer: "/ci/green",
     });
+    expect(parseDeclaration(decl({ green: { ...GREEN, signedSince: "a".repeat(40) } }), "chant.workspace.json").ci!.green!.signedSince).toBe("a".repeat(40));
     expect(parseDeclaration(decl({ green: { ...GREEN, window: "90m" } }), "chant.workspace.json").ci!.green!.window).toBe("90m");
     expect(parseDeclaration(decl({}), "chant.workspace.json").ci).toEqual({ green: null });
     expect(parseDeclaration(JSON.stringify({ name: "w", schema: 1, members: [] }), "chant.workspace.json").ci).toBeNull();
@@ -61,6 +65,9 @@ describe("the ci.green block (#3573)", () => {
       { ...GREEN, require: [] },
       { phases: GREEN.phases, require: GREEN.require },
       { ...GREEN, branch: "has space" },
+      { ...GREEN, signedSince: "yesterday" },
+      { ...GREEN, signedSince: "2026-10-16T00:00:00Z" },
+      { ...GREEN, signedSince: "abc1234" },
     ]) {
       expect(() => parseDeclaration(decl({ green: bad }), "chant.workspace.json"), JSON.stringify(bad)).toThrow();
     }
@@ -399,3 +406,125 @@ describe("chant ci last-green (#3573)", () => {
     });
   });
 });
+
+// ── list ─────────────────────────────────────────────────────────────────────
+
+describe("chant ci list (#4021)", () => {
+  const readList = contract(listSchema);
+  type Listed = Extract<Awaited<ReturnType<typeof ciList>>, { branch: string }>;
+
+  /** a green, b revoked (test went red), c undecided, d and e outside the 24h window. */
+  async function scenario() {
+    const { root, origin } = workspace();
+    const e = commitAt(root, 40, "app/e.txt");
+    const d = commitAt(root, 30, "app/d.txt");
+    const a = commitAt(root, 5, "app/a.txt");
+    const b = commitAt(root, 4, "app/b.txt");
+    const c = commitAt(root, 1, "app/c.txt");
+    push(root);
+    const runs = new Map([
+      [a, PASSING],
+      [b, PASSING],
+      [c, [run(1, "lint", "success")]],
+    ]);
+    await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
+    runs.set(b, [...PASSING, run(9, "test", "failure")]);
+    await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
+    return { root, origin, a, b, c, d, e, runs };
+  }
+
+  test("lists the window newest first with each commit's state and phase results, from local tags alone", async () => {
+    const { root, a, b, c } = await scenario();
+    const doc = (await ciList({ cwd: root, now: NOW })) as Listed;
+    readList.expectValid(doc);
+    expect(doc).toMatchObject({ contract: 1, branch: "main", ref: "refs/remotes/origin/main", window: "24h", since: null, require: ["lint", "test", "macos"] });
+    expect(doc.commits.map((x) => [x.sha, x.state])).toEqual([
+      [c, "undecided"],
+      [b, "revoked"],
+      [a, "green"],
+    ]);
+
+    const green = doc.commits[2];
+    expect(green.committed).toBe(hoursAgo(5).replace(/\.\d{3}Z$/, "Z"));
+    expect(green.green).toMatchObject({ tag: `ci/green/${a}` });
+    expect(green.green!.tagged).toMatch(/^\d{4}-\d\d-\d\dT/);
+    expect(green.revoked).toBeNull();
+    expect(green.phases.map((p) => [p.phase, p.result])).toEqual([["lint", "pass"], ["test", "pass"], ["macos", "pass"]]);
+    expect(green.phases[1].runs.map((r) => r.name)).toEqual(["test", "e2e (chromium)"]);
+
+    // The revoked commit keeps what its green tag recorded, and shows the failed phase and run.
+    const revoked = doc.commits[1];
+    expect(revoked.green).not.toBeNull();
+    expect(revoked.revoked).toMatchObject({ tag: `ci/revoked/${b}`, phase: "test", run: { name: "test", id: 9, conclusion: "failure" } });
+    expect(revoked.phases.map((p) => [p.phase, p.result])).toEqual([["lint", "pass"], ["test", "fail"], ["macos", "pass"]]);
+    expect(revoked.phases[1].runs).toEqual([expect.objectContaining({ name: "test", id: 9 })]);
+
+    // No tag, no forge: nothing is recorded, and nothing is guessed.
+    expect(doc.commits[0].phases.map((p) => [p.phase, p.result, p.runs.length])).toEqual([["lint", "unrecorded", 0], ["test", "unrecorded", 0], ["macos", "unrecorded", 0]]);
+    expect(doc.commits[0]).toMatchObject({ green: null, revoked: null });
+  });
+
+  test("--forge judges the undecided commits only, and --limit and --since narrow the walk", async () => {
+    const { root, a, b, c, d, e, runs } = await scenario();
+    const forge = fakeForge(runs);
+    const live = (await ciList({ cwd: root, now: NOW, forge })) as Listed;
+    readList.expectValid(live);
+    expect(forge.asked).toEqual([c]);
+    expect(live.commits[0].phases.map((p) => [p.phase, p.result])).toEqual([["lint", "pass"], ["test", "pending"], ["macos", "pending"]]);
+    expect(live.commits[0].phases[0].runs).toEqual([expect.objectContaining({ name: "lint", id: 1, conclusion: "success" })]);
+
+    const two = (await ciList({ cwd: root, now: NOW, limit: 2 })) as Listed;
+    expect(two.commits.map((x) => x.sha)).toEqual([c, b]);
+
+    const after = (await ciList({ cwd: root, now: NOW, since: a })) as Listed;
+    readList.expectValid(after);
+    expect(after).toMatchObject({ window: null, since: a });
+    expect(after.commits.map((x) => x.sha)).toEqual([c, b]);
+    // --since replaces the window, so a commit older than 24h is listed when the range reaches it.
+    const all = (await ciList({ cwd: root, now: NOW, since: e })) as Listed;
+    expect(all.commits.map((x) => x.sha)).toEqual([c, b, a, d]);
+  });
+
+  test("an unknown --since, no ci.green and an unknown branch are failures in the schema", async () => {
+    const { root } = await scenario();
+    const bad = await ciList({ cwd: root, now: NOW, since: "no-such-rev" });
+    readList.expectValid(bad);
+    expect(bad).toMatchObject({ error: { code: "revision-unknown" } });
+
+    const plain = scratchDir("chant-ci-plain-");
+    git(plain, "init", "-q");
+    writeFiles(plain, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "x" }]), "app/a.txt": "a\n" });
+    const undeclared = await ciList({ cwd: plain });
+    readList.expectValid(undeclared);
+    expect(undeclared).toMatchObject({ error: { code: "ci-green-undeclared" } });
+
+    const none = workspace();
+    readList.expectValid(await ciList({ cwd: none.root }));
+  });
+
+  test("the command prints the document under --json and a line per commit otherwise", async () => {
+    const { root, a, b, c, e } = await scenario();
+    const cwd = vi.spyOn(process, "cwd").mockReturnValue(root);
+    try {
+      // The command reads the real clock, so these commits sit outside its window: --since names them.
+      const text = await captured(() => runCiList({ args: { limit: 3, since: e } } as unknown as CommandContext));
+      expect(text.code).toBe(0);
+      expect(text.out).toContain(`${c.slice(0, 12)}  undecided  lint=unrecorded test=unrecorded macos=unrecorded`);
+      expect(text.out).toContain(`${b.slice(0, 12)}  revoked    lint=pass test=fail macos=pass`);
+      expect(text.out).toContain(`${a.slice(0, 12)}  green      lint=pass test=pass macos=pass`);
+
+      const json = await captured(() => runCiList({ args: { json: true, since: a } } as unknown as CommandContext));
+      expect(json.code).toBe(0);
+      readList.expectValid(JSON.parse(json.out));
+      expect((JSON.parse(json.out) as Listed).commits).toHaveLength(2);
+
+      expect((await captured(() => runCiList({ args: { limit: 0 } } as unknown as CommandContext))).code).toBe(1);
+      const refused = await captured(() => runCiList({ args: { json: true, since: "no-such-rev" } } as unknown as CommandContext));
+      expect(refused.code).toBe(1);
+      expect(JSON.parse(refused.out)).toMatchObject({ error: { code: "revision-unknown" } });
+      expect((await captured(() => runCiList({ args: { forge: "gitlab" } } as unknown as CommandContext))).code).toBe(1);
+    } finally {
+      cwd.mockRestore();
+    }
+  });
+});