@intentius/chant 0.124.32 → 0.124.33

package/src/workspace/ci-builds.ts

@@ -0,0 +1,385 @@
+/**
+ * Which commits get built, and what each one ends with (#4169).
+ *
+ * A `ci.green` phase declares `build: "every"` (the default) or
+ * `build: "newest"`. Under `newest` the phase's workflow keeps one run
+ * waiting and drops the rest, so only the newest commit is built when a
+ * runner frees. This module does the tick's part of that, given the
+ * verdicts {@link planTick} (./ci-green.ts) judged:
+ *
+ * - Superseded. A commit with no run of a `newest` phase, below a newer
+ *   commit that has one, is `unbuilt` for that phase, covered by the newer
+ *   commit. A cancelled run makes any phase `unbuilt` (`phaseVerdictOf`).
+ * - Retry. A failed run with one attempt is run again once before the
+ *   commit counts red: through the forge's re-run (`CiForge.rerun`) for
+ *   check runs, or a build request for chant runs. A retry that has not
+ *   started an hour on counts as the failure it was.
+ * - Bisect. When the newest built commit of a `newest` phase is red, the
+ *   unbuilt commits back to the last one the phase passed on are built, one
+ *   request per tick: the commit halfway when more than four are left, else
+ *   the one just below the red. The first red commit found is the culprit,
+ *   and it and every commit after it name it.
+ * - Requests. A build is asked for with an annotated tag,
+ *   `ci/build/<sha>`, whose record names the phases and why. The tick
+ *   starts a workflow at that tag on GitHub (`CiForge.dispatch`), and `ci
+ *   serve --build-command` serves it for chant runs. A phase a request
+ *   waits on is `pending`. A request no runner served in six hours leaves
+ *   the phase `unbuilt`, and once its phases are decided the tick deletes
+ *   the tag.
+ * - Records. Every first-parent commit the tick judged gets
+ *   `_ci/<sha>.json` on `chant/lifecycle`, rewritten only when what it says
+ *   changes: `green`, `red`, `unbuilt` or `pending`, with each required
+ *   phase's verdict, runs, reason, the commit that covers it and the culprit.
+ *   A commit that leaves the window still `pending` is rewritten `unbuilt`,
+ *   for the reason `aged-out`. The `ci/green` and `ci/revoked` tags stay
+ *   what decides a release; the records say what happened to the rest.
+ */
+
+import { execFileSync } from "node:child_process";
+import type { CiBuild, CiGreen } from "./declaration";
+import type { CheckRun } from "./ci-green-forge";
+import { commitVerdictOf, phaseVerdictOf, type PhaseReason, type PhaseVerdict, type TickCommit, type Verdict } from "./ci-green";
+
+export const CI_BUILD_TAG_PREFIX = "ci/build/";
+/** The directory on `chant/lifecycle` holding one record per commit. */
+export const CI_RECORDS_DIR = "_ci";
+const LEDGER_REF = "refs/heads/chant/lifecycle";
+
+/** How long a build request may wait for a runner before its phases count as unbuilt. */
+export const BUILD_REQUEST_TTL_MS = 6 * 3_600_000;
+/** How long a retry may take to start before the failure it was counts. */
+export const RETRY_TTL_MS = 3_600_000;
+/** Above this many unbuilt commits a bisect halves the range; at or below it, it steps back one commit at a time. */
+export const BISECT_HALVE_ABOVE = 4;
+
+export type BuildRequestReason = "bisect" | "retry" | "requested";
+
+/** A `ci/build/<sha>` tag's record: the phases to build at the commit, and why. */
+export interface BuildRequest {
+  schema: 1;
+  tag: string;
+  commit: string;
+  branch: string;
+  phases: string[];
+  reason: BuildRequestReason;
+  /** When it was asked for, ISO 8601. */
+  at: string;
+}
+
+/** One record, `_ci/<sha>.json` on `chant/lifecycle`. */
+export interface CiRecord {
+  schema: 1;
+  commit: string;
+  branch: string;
+  /** `green` and `red` follow the tags: a green tag, or a failed phase or a revoked tag. */
+  state: "green" | "red" | "unbuilt" | "pending";
+  /** When this content was written, ISO 8601. Not compared when deciding whether to write again. */
+  at: string;
+  /** Set when the commit has a revoked tag. */
+  revoked?: true;
+  phases: Record<string, CiRecordPhase>;
+  /** The first required phase that failed, and its run, when the state is red. */
+  failure?: { phase: string; run: CiRecordRun };
+  /** The retries asked for, by run name: the run that failed and when. */
+  retried?: Record<string, { run: number; at: string }>;
+  /** The build request waiting on this commit, when there is one. */
+  request?: { tag: string; reason: BuildRequestReason; phases: string[]; at: string; dispatched?: true };
+}
+
+export interface CiRecordRun {
+  name: string;
+  id: number | null;
+  conclusion: string | null;
+  url: string | null;
+}
+
+export interface CiRecordPhase {
+  verdict: Verdict;
+  build: CiBuild;
+  runs: CiRecordRun[];
+  reason?: PhaseReason | "aged-out";
+  coveredBy?: string;
+  culprit?: string;
+}
+
+const iso = (d: Date) => d.toISOString().replace(/\.\d{3}Z$/, "Z");
+
+/** How a tick can run a failed job again: the forge's re-run, a build request, or not at all. */
+export type RetryVia = "forge" | "request" | null;
+
+export interface BuildsInput {
+  green: CiGreen;
+  /** Newest first, as {@link planTick} returns them. */
+  commits: TickCommit[];
+  /** Every attempt of every run, by commit. */
+  runs: ReadonlyMap<string, readonly CheckRun[]>;
+  requests: ReadonlyMap<string, BuildRequest>;
+  records: ReadonlyMap<string, CiRecord>;
+  now: Date;
+  retryVia: RetryVia;
+}
+
+export interface BuildsPlan {
+  /** Requests to make: bisect steps, and retries of chant runs. */
+  requests: BuildRequest[];
+  /** Failed check runs to run again through the forge, by commit. */
+  retries: { sha: string; run: CheckRun }[];
+  /** Request tags whose phases are decided, or that waited too long, or whose commit left the window. */
+  resolved: string[];
+}
+
+const phaseOf = (green: CiGreen, name: string) => green.phases.find((p) => p.name === name)!;
+const buildOf = (green: CiGreen, name: string): CiBuild => phaseOf(green, name).build ?? "every";
+const decided = (v: Verdict | undefined) => v === "pass" || v === "fail";
+const age = (at: string, now: Date) => now.getTime() - Date.parse(at);
+
+function setPhase(c: TickCommit, phase: string, fn: (p: PhaseVerdict) => PhaseVerdict): void {
+  const v = c.verdict;
+  if (!v) return;
+  c.verdict = commitVerdictOf(v.phases.map((p) => (p.phase === phase ? fn(p) : p)));
+}
+
+const phaseIn = (c: TickCommit, phase: string) => c.verdict?.phases.find((p) => p.phase === phase);
+
+/**
+ * Apply supersession, retries, requests and bisection to the judged commits,
+ * in place, and say what the tick has to ask for. Pure: it reads and writes
+ * nothing but its input.
+ */
+export function planBuilds(input: BuildsInput): BuildsPlan {
+  const { green, commits, now } = input;
+  const plan: BuildsPlan = { requests: [], retries: [], resolved: [] };
+  const inWindow = new Set(commits.map((c) => c.sha));
+  const live = (sha: string, phase: string): BuildRequest | undefined => {
+    const r = input.requests.get(sha);
+    return r && r.phases.includes(phase) && age(r.at, now) < BUILD_REQUEST_TTL_MS ? r : undefined;
+  };
+
+  // A request waits on a phase with no run yet; one no runner served in time leaves it unbuilt.
+  for (const c of commits) {
+    const r = input.requests.get(c.sha);
+    if (!r || !c.verdict) continue;
+    for (const name of r.phases) {
+      const p = phaseIn(c, name);
+      if (!p || p.runs.length > 0) continue;
+      setPhase(c, name, (q) => (live(c.sha, name) ? { ...q, verdict: "pending", reason: "requested" } : { ...q, verdict: "unbuilt", reason: "request-unserved" }));
+    }
+  }
+
+  // Superseded: newest first, a newest phase with no run below a commit with one.
+  for (const name of green.require) {
+    if (buildOf(green, name) !== "newest") continue;
+    let cover: string | undefined;
+    for (const c of commits) {
+      const p = phaseIn(c, name);
+      if (!p) continue;
+      if (p.runs.length > 0) {
+        cover = c.sha;
+        continue;
+      }
+      if (cover && p.reason !== "requested" && p.reason !== "request-unserved") setPhase(c, name, (q) => ({ ...q, verdict: "unbuilt", reason: "superseded", coveredBy: cover }));
+    }
+  }
+
+  // Retry once: a commit with no tag whose failed run has one attempt.
+  if (input.retryVia) {
+    for (const c of commits) {
+      if (c.before !== "none" || c.verdict?.verdict !== "fail") continue;
+      const all = input.runs.get(c.sha) ?? [];
+      const retried = input.records.get(c.sha)?.retried ?? {};
+      for (const p of c.verdict.phases) {
+        for (const run of p.runs.filter((r) => r.verdict === "fail")) {
+          if (all.filter((r) => r.name === run.name).length > 1) continue;
+          const asked = retried[run.name];
+          if (asked && asked.run === run.id && age(asked.at, now) >= RETRY_TTL_MS) continue;
+          if (!asked || asked.run !== run.id) {
+            const checkRun = all.find((r) => r.name === run.name && r.id === run.id)!;
+            if (input.retryVia === "forge") plan.retries.push({ sha: c.sha, run: checkRun });
+            else if (!input.requests.has(c.sha) && !plan.requests.some((q) => q.commit === c.sha)) plan.requests.push(request(green, c.sha, [p.phase], "retry", now));
+          }
+          setPhase(c, p.phase, (q) => {
+            const runs = q.runs.map((r) => (r.name === run.name && r.id === run.id ? { ...r, verdict: "pending" as const } : r));
+            return { ...q, runs, ...phaseVerdictOf(runs, q.unmatched), reason: "retrying" };
+          });
+        }
+      }
+    }
+  }
+
+  // Culprits for every phase, and a bisect request for a newest one.
+  for (const name of green.require) {
+    const verdicts = commits.map((c) => phaseIn(c, name));
+    const top = verdicts.findIndex((p) => decided(p?.verdict));
+    if (top < 0 || verdicts[top]!.verdict !== "fail") continue;
+    let oldestRed = top;
+    let between: number[] = [];
+    let passed = -1;
+    for (let i = top + 1; i < commits.length; i++) {
+      const v = verdicts[i]?.verdict;
+      if (v === "fail") {
+        oldestRed = i;
+        between = [];
+      } else if (v === "pass") {
+        passed = i;
+        break;
+      } else if (v !== undefined) between.push(i);
+    }
+    if (between.length === 0) {
+      if (passed < 0) continue;
+      const culprit = commits[oldestRed].sha;
+      for (let i = oldestRed; i >= 0; i--) {
+        if (verdicts[i]?.verdict === "pass") break;
+        if (verdicts[i]) setPhase(commits[i], name, (q) => ({ ...q, culprit }));
+      }
+      continue;
+    }
+    if (buildOf(green, name) !== "newest") continue;
+    if (between.some((i) => live(commits[i].sha, name))) continue;
+    const pick = between.length > BISECT_HALVE_ABOVE ? between[Math.floor(between.length / 2)] : between[0];
+    const sha = commits[pick].sha;
+    if (input.requests.has(sha) || plan.requests.some((q) => q.commit === sha)) continue;
+    plan.requests.push(request(green, sha, [name], "bisect", now));
+    setPhase(commits[pick], name, (q) => ({ ...q, verdict: "pending", reason: "requested", coveredBy: undefined }));
+  }
+
+  // A request is done once its phases are decided, it has waited too long, or its commit left the window.
+  for (const [sha, r] of input.requests) {
+    const c = commits.find((x) => x.sha === sha);
+    const done = !inWindow.has(sha) || age(r.at, now) >= BUILD_REQUEST_TTL_MS || (c !== undefined && (c.before === "revoked" || r.phases.every((name) => decided(phaseIn(c, name)?.verdict))));
+    if (done) plan.resolved.push(r.tag);
+  }
+  return plan;
+}
+
+function request(green: CiGreen, commit: string, phases: string[], reason: BuildRequestReason, now: Date): BuildRequest {
+  return { schema: 1, tag: `${CI_BUILD_TAG_PREFIX}${commit}`, commit, branch: green.branch, phases, reason, at: iso(now) };
+}
+
+// ── Records ──────────────────────────────────────────────────────────────────
+
+const recordRun = (r: { name: string; id: number; conclusion: string | null; url: string | null; opRun?: unknown }): CiRecordRun => ({ name: r.name, id: r.opRun ? null : r.id, conclusion: r.conclusion, url: r.url });
+
+/** The record a judged commit gets, carrying the retries asked for before and now. */
+export function recordOf(input: { green: CiGreen; commit: TickCommit; previous?: CiRecord; retries: readonly { sha: string; run: CheckRun }[]; requests: ReadonlyMap<string, BuildRequest>; now: Date }): CiRecord {
+  const { green, commit: c, previous, now } = input;
+  const retried = { ...(previous?.retried ?? {}) };
+  for (const r of input.retries) if (r.sha === c.sha) retried[r.run.name] = { run: r.run.id, at: iso(now) };
+  const req = input.requests.get(c.sha);
+  const extras = {
+    ...(Object.keys(retried).length > 0 ? { retried } : {}),
+    ...(req ? { request: { tag: req.tag, reason: req.reason, phases: req.phases, at: req.at } } : {}),
+  };
+  if (c.before === "revoked" || !c.verdict) {
+    return { schema: 1, commit: c.sha, branch: green.branch, state: "red", at: iso(now), revoked: true, phases: previous?.phases ?? {}, ...(previous?.failure ? { failure: previous.failure } : {}), ...extras };
+  }
+  const v = c.verdict;
+  // A pass whose tag an ignored tag blocks (#4031) is not green until a person clears the name.
+  const state: CiRecord["state"] =
+    c.before === "green" ? (v.verdict === "fail" ? "red" : "green") : v.verdict === "pass" ? (c.made ? "green" : "pending") : v.verdict === "fail" ? "red" : v.verdict;
+  const phases: Record<string, CiRecordPhase> = {};
+  for (const p of v.phases) {
+    phases[p.phase] = {
+      verdict: p.verdict,
+      build: buildOf(green, p.phase),
+      runs: p.runs.map(recordRun),
+      ...(p.reason ? { reason: p.reason } : {}),
+      ...(p.coveredBy ? { coveredBy: p.coveredBy } : {}),
+      ...(p.culprit ? { culprit: p.culprit } : {}),
+    };
+  }
+  return {
+    schema: 1,
+    commit: c.sha,
+    branch: green.branch,
+    state,
+    at: iso(now),
+    phases,
+    ...(v.failure ? { failure: { phase: v.failure.phase, run: recordRun(v.failure.run) } } : {}),
+    ...extras,
+  };
+}
+
+/** The record a commit that left the window still pending gets: each pending phase `unbuilt`, `aged-out`. */
+export function agedOut(record: CiRecord, now: Date): CiRecord {
+  const phases = Object.fromEntries(Object.entries(record.phases).map(([k, p]) => [k, p.verdict === "pending" ? { ...p, verdict: "unbuilt" as const, reason: "aged-out" as const } : p]));
+  const { request: _request, ...rest } = record;
+  return { ...rest, state: "unbuilt", at: iso(now), phases };
+}
+
+/** Whether two records say the same thing, the time each was written aside. */
+export function sameRecord(a: CiRecord | undefined, b: CiRecord): boolean {
+  if (!a) return false;
+  const { at: _a, ...x } = a;
+  const { at: _b, ...y } = b;
+  return JSON.stringify(x) === JSON.stringify(y);
+}
+
+export const recordPath = (sha: string) => `${CI_RECORDS_DIR}/${sha}.json`;
+
+function tryGit(top: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 }).trimEnd();
+  } catch {
+    return null;
+  }
+}
+
+function parseRecord(text: string | null): CiRecord | undefined {
+  if (!text) return undefined;
+  try {
+    const r = JSON.parse(text) as CiRecord;
+    return r && r.schema === 1 && typeof r.commit === "string" && typeof r.state === "string" ? r : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** One commit's record, from the local `chant/lifecycle`. */
+export function readCiRecord(top: string, sha: string): CiRecord | undefined {
+  return parseRecord(tryGit(top, ["show", `${LEDGER_REF}:${recordPath(sha)}`]));
+}
+
+/** Every record on the local `chant/lifecycle`, by commit. Empty when the branch or the directory is missing. */
+export function readCiRecords(top: string): Map<string, CiRecord> {
+  const out = new Map<string, CiRecord>();
+  const names = tryGit(top, ["ls-tree", "--name-only", `${LEDGER_REF}:${CI_RECORDS_DIR}`]);
+  if (!names) return out;
+  for (const name of names.split("\n")) {
+    const m = /^([0-9a-f]{40,64})\.json$/.exec(name);
+    if (!m) continue;
+    const r = readCiRecord(top, m[1]);
+    if (r) out.set(m[1], r);
+  }
+  return out;
+}
+
+// ── Requests ─────────────────────────────────────────────────────────────────
+
+/** Every `ci/build/<sha>` tag with a record this reads, from local refs, by commit. */
+export function readBuildRequests(top: string): Map<string, BuildRequest> {
+  const out = new Map<string, BuildRequest>();
+  const raw = tryGit(top, ["for-each-ref", "--format=%(refname:lstrip=2)%00%(objecttype)%00%(contents)%01", `refs/tags/${CI_BUILD_TAG_PREFIX}`]);
+  if (!raw) return out;
+  for (const entry of raw.split("\u0001")) {
+    const [tag, type, contents] = entry.replace(/^\n/, "").split("\u0000");
+    if (!tag || type !== "tag" || !contents?.includes("{")) continue;
+    try {
+      const r = JSON.parse(contents.slice(contents.indexOf("{"))) as BuildRequest;
+      const sha = tag.slice(CI_BUILD_TAG_PREFIX.length);
+      if (r.schema === 1 && r.commit === sha && Array.isArray(r.phases) && typeof r.at === "string") out.set(sha, { ...r, tag });
+    } catch {
+      // A tag whose record does not parse asks for nothing.
+    }
+  }
+  return out;
+}
+
+/** The annotation of a request tag: a subject line, then the record. */
+export function buildRequestAnnotation(r: BuildRequest): string {
+  return `ci: build ${r.phases.join(", ")} at this commit (${r.reason})\n\n${JSON.stringify(r, null, 2)}\n`;
+}
+
+/** A request for `ci run --at <sha>`: every required phase, asked for by a person. */
+export function requestedBuild(green: CiGreen, commit: string, phases: readonly string[], now: Date): BuildRequest {
+  return request(green, commit, [...phases], "requested", now);
+}

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

@@ -0,0 +1,180 @@
+/**
+ * #4169 — the tick against a real remote with a fake forge, for a phase that
+ * builds only the newest commit: the records it writes on chant/lifecycle,
+ * the build requests it pushes and starts, the retries it asks for, and what
+ * `ci list`, `ci last-green` and `ci run --at` read and do.
+ */
+
+import { execFileSync } from "node:child_process";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { ciList, ciTick, lastGreen, requestBuild } from "./ci-green";
+import type { CheckRun, CiForge } from "./ci-green-forge";
+import { readBuildRequests, readCiRecord } from "./ci-builds";
+
+afterAll(cleanScratch);
+
+const NOW = new Date("2026-10-20T12:00:00Z");
+const hoursAgo = (h: number) => new Date(NOW.getTime() - h * 3_600_000).toISOString();
+
+const GREEN = {
+  branch: "main",
+  phases: { check: { runs: ["check"], build: "every" }, suites: { runs: ["suites"], build: "newest" } },
+  require: ["check", "suites"],
+};
+
+const SUITES_WORKFLOW = "name: release-suites\non:\n  push:\n    branches: [main]\n  workflow_dispatch: {}\njobs:\n  suites:\n    runs-on: ubuntu-latest\n    steps:\n      - run: true\n";
+
+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", ...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");
+}
+
+function workspace(): { root: string; origin: string } {
+  const origin = scratchDir("chant-builds-origin-");
+  git(origin, "init", "-q", "--bare");
+  const root = scratchDir("chant-builds-work-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  writeFiles(root, {
+    "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green: GREEN } }),
+    "app/a.txt": "a\n",
+    ".github/workflows/release-suites.yml": SUITES_WORKFLOW,
+  });
+  git(root, "remote", "add", "origin", origin);
+  return { root, origin };
+}
+
+let id = 1;
+const run = (name: string, conclusion: string | null, status = "completed"): CheckRun => ({ id: id++, name, status, conclusion: status === "completed" ? conclusion : null, completedAt: null, url: null });
+
+/** A forge whose runs the test sets per commit, recording the re-runs and the workflows started. */
+function fakeForge(runs: Map<string, CheckRun[]>): CiForge & { reruns: number[]; dispatched: string[] } {
+  const reruns: number[] = [];
+  const dispatched: string[] = [];
+  return {
+    kind: "github",
+    reruns,
+    dispatched,
+    checkRuns: async (sha) => runs.get(sha) ?? [],
+    rerun: async (r) => void reruns.push(r.id),
+    dispatch: async (w, ref) => void dispatched.push(`${w}@${ref}`),
+  };
+}
+
+const remoteRecord = (origin: string, sha: string) => JSON.parse(git(origin, "show", `refs/heads/chant/lifecycle:_ci/${sha}.json`));
+const remoteTags = (origin: string) => git(origin, "for-each-ref", "--format=%(refname:lstrip=2)", "refs/tags/").split("\n").filter(Boolean).sort();
+
+describe("the tick for a newest phase (#4169)", () => {
+  test("records each commit, and asks for a bisect step at a ci/build tag and starts the workflow there once", async () => {
+    const { root, origin } = workspace();
+    const base = commitAt(root, 6, "app/base.txt");
+    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 runs = new Map<string, CheckRun[]>([
+      [base, [run("check", "success"), run("suites", "success")]],
+      [a, [run("check", "success")]],
+      [b, [run("check", "success")]],
+      [c, [run("check", "success"), run("suites", "failure"), run("suites", "failure")]],
+    ]);
+    const forge = fakeForge(runs);
+
+    const first = await ciTick({ cwd: root, forge, now: NOW });
+    expect(first.made).toEqual([`ci/green/${base}`]);
+    // The newest red asks for the commit just below it.
+    expect(first.requested.map((r) => [r.commit, r.reason])).toEqual([[b, "bisect"]]);
+    expect(remoteTags(origin)).toEqual([`ci/build/${b}`, `ci/green/${base}`].sort());
+    expect(forge.dispatched).toEqual([`release-suites.yml@ci/build/${b}`]);
+    expect(remoteRecord(origin, a)).toMatchObject({ state: "unbuilt", phases: { suites: { verdict: "unbuilt", reason: "superseded", coveredBy: c } } });
+    expect(remoteRecord(origin, b)).toMatchObject({ state: "pending", request: { tag: `ci/build/${b}`, reason: "bisect", dispatched: true }, phases: { suites: { reason: "requested" } } });
+    expect(remoteRecord(origin, c)).toMatchObject({ state: "red", failure: { phase: "suites" } });
+
+    // A second tick asks for nothing more and starts nothing again while b's build waits.
+    const second = await ciTick({ cwd: root, forge, now: NOW });
+    expect(second.requested).toEqual([]);
+    expect(forge.dispatched).toHaveLength(1);
+
+    // ci list and ci last-green read the records. (The walk to the culprit is ci-builds.e2e.test.ts.)
+    const list = await ciList({ cwd: root, now: NOW });
+    if ("error" in list) throw new Error(list.error.message);
+    expect(list.commits.find((x) => x.sha === a)!.record).toEqual({ state: "unbuilt", reason: "superseded", coveredBy: c });
+    const last = lastGreen({ cwd: root });
+    if ("error" in last) throw new Error(last.error.message);
+    expect(last.commit!.sha).toBe(base);
+    expect(last.newer.map((n) => [n.sha, n.record?.state])).toEqual([
+      [c, "red"],
+      [b, "pending"],
+      [a, "unbuilt"],
+    ]);
+  });
+
+  test("runs a failed job again once before the commit counts red", async () => {
+    const { root, origin } = workspace();
+    const a = commitAt(root, 2, "app/a.txt");
+    git(root, "push", "-q", "origin", "main");
+    const failed = run("check", "failure");
+    const runs = new Map([[a, [failed, run("suites", "success")]]]);
+    const forge = fakeForge(runs);
+    const tick = await ciTick({ cwd: root, forge, now: NOW });
+    expect(tick.retried).toEqual([{ sha: a, run: "check" }]);
+    expect(forge.reruns).toEqual([failed.id]);
+    expect(remoteRecord(origin, a)).toMatchObject({ state: "pending", retried: { check: { run: failed.id } } });
+    // Asked once: the next tick waits for the attempt and does not ask again.
+    await ciTick({ cwd: root, forge, now: NOW });
+    expect(forge.reruns).toEqual([failed.id]);
+    runs.set(a, [failed, run("check", "success"), run("suites", "success")]);
+    expect((await ciTick({ cwd: root, forge, now: NOW })).made).toEqual([`ci/green/${a}`]);
+  });
+
+  test("a dry run writes no record and pushes no request", async () => {
+    const { root, origin } = workspace();
+    const base = commitAt(root, 4, "app/base.txt");
+    const a = commitAt(root, 3, "app/a.txt");
+    const b = commitAt(root, 2, "app/b.txt");
+    git(root, "push", "-q", "origin", "main");
+    const runs = new Map([
+      [base, [run("check", "success"), run("suites", "success")]],
+      [a, [run("check", "success")]],
+      [b, [run("check", "success"), run("suites", "failure"), run("suites", "failure")]],
+    ]);
+    const tick = await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW, dryRun: true });
+    expect(tick.requested.map((r) => r.commit)).toEqual([a]);
+    expect(tick.recorded).toEqual([]);
+    expect(remoteTags(origin)).toEqual([]);
+    expect(() => git(origin, "rev-parse", "--verify", "refs/heads/chant/lifecycle")).toThrow();
+  });
+});
+
+describe("chant ci run --at (#4169)", () => {
+  test("pushes a request for every required phase and starts the workflows holding them", async () => {
+    const { root, origin } = workspace();
+    const a = commitAt(root, 2, "app/a.txt");
+    commitAt(root, 1, "app/b.txt");
+    git(root, "push", "-q", "origin", "main");
+    const forge = fakeForge(new Map());
+    const r = await requestBuild({ cwd: root, at: a, forge, now: NOW });
+    expect(r.request).toMatchObject({ commit: a, phases: ["check", "suites"], reason: "requested", tag: `ci/build/${a}` });
+    expect(r.existed).toBe(false);
+    expect(r.dispatched).toEqual(["release-suites.yml"]);
+    expect(remoteTags(origin)).toEqual([`ci/build/${a}`]);
+    expect(readBuildRequests(root).get(a)).toMatchObject({ reason: "requested" });
+    expect((await requestBuild({ cwd: root, at: a, now: NOW })).existed).toBe(true);
+    await expect(requestBuild({ cwd: root, at: "nope", now: NOW })).rejects.toThrow(/names no commit/);
+    // The tick takes the run already going at the commit as started, and records the request.
+    await ciTick({ cwd: root, forge: fakeForge(new Map([[a, [run("check", "success"), run("suites", null, "in_progress")]]])), now: NOW });
+    expect(readCiRecord(root, a)).toMatchObject({ state: "pending", request: { reason: "requested", dispatched: true } });
+  });
+});

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

@@ -0,0 +1,54 @@
+/**
+ * `chant ci tick` under the who-ran-it security group (#4168): no key, no tick.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, describe, expect, test, vi } from "vitest";
+import { runCiTick } from "./ci-green-cli";
+import { RUNNER_KEY_ENV } from "./ci-green";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+});
+
+function repo(extra: Record<string, unknown>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-ci-tick-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  writeFileSync(
+    join(root, "chant.workspace.json"),
+    JSON.stringify({ name: "acme", schema: 1, members: [], ci: { green: { branch: "main", phases: { test: ["test"] }, require: ["test"], source: "runs" } }, ...extra }),
+  );
+  return root;
+}
+
+const ctx = (args: Record<string, unknown> = {}) => ({ args: { command: "ci", path: "tick", ...args }, plugins: [] }) as never;
+
+describe("ci tick and who-ran-it", () => {
+  test("under who-ran-it a tick with no runner key is refused before it reads anything", async () => {
+    vi.stubEnv(RUNNER_KEY_ENV, "");
+    vi.spyOn(process, "cwd").mockReturnValue(repo({ security: ["who-ran-it"] }));
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => void errors.push(m.map(String).join(" ")));
+    expect(await runCiTick(ctx())).toBe(1);
+    expect(errors.join("\n")).toContain("the workspace opts into who-ran-it, so the tick signs every tag it makes and needs a runner key");
+  });
+
+  test("without the group the same tick is not refused for its key", async () => {
+    vi.stubEnv(RUNNER_KEY_ENV, "");
+    vi.spyOn(process, "cwd").mockReturnValue(repo({}));
+    const errors: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => void errors.push(m.map(String).join(" ")));
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    await runCiTick(ctx());
+    expect(errors.join("\n")).not.toContain("who-ran-it");
+  });
+});