@intentius/chant 0.124.32 → 0.124.34

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

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

@@ -8,7 +8,8 @@
  *                                        tag the commits that turned green, revoke the ones that turned red
  *   ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>]
  *               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>] [--runner-key-secret <NAME>]
- *                                        write the root CI file that runs the tick
+ *                                        write the root CI file that runs the tick, and the triggers and
+ *                                        concurrency of the workflows holding a phase that sets build (#4169)
  *
  * The tick signs its tags with a runner key (#4031) from `--key <file>` or
  * the PEM in `CHANT_RUNNER_KEY`, which the generated workflow sets from the
@@ -30,7 +31,7 @@ import type { CommandContext } from "../cli/registry";
 import { findWorkspaceRoot } from "../project-root";
 import { ciList, ciTick, CiGreenError, formatList, formatTick, lastGreen, RUNNER_KEY_ENV } from "./ci-green";
 import { ciForgeFromEnv } from "./ci-green-forge";
-import { ACTIONS_NAME, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, type PushToken, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
+import { ACTIONS_NAME, buildTriggerEdits, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, type PushToken, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
 import { readDeclaration, readerVersion, WorkspaceReadError, type CiSource } from "./declaration";
 import { recordGeneratedFiles, resolveMemberContext, shellArg } from "./member-pipeline";
 import { gitTop, workingTree } from "./tree";
@@ -105,6 +106,13 @@ export async function runCiTick(ctx: CommandContext): Promise<number> {
     // The forge is made only when the source is check runs, so a tick from chant runs needs no forge token.
     const forge = () => ciForgeFromEnv(ctx.args.forge ?? "github");
     const runnerKey = ctx.args.key !== undefined ? readFileSync(resolve(ctx.args.key), "utf-8") : process.env[RUNNER_KEY_ENV] || undefined;
+    // #4168: under who-ran-it every tag the tick makes is signed, so a tick without a key makes none.
+    if (runnerKey === undefined && ctx.args.dryRun !== true) {
+      const { securityGroupsAt } = await import("./security");
+      if (securityGroupsAt(process.cwd()).has("who-ran-it")) {
+        throw new Error(`the workspace opts into who-ran-it, so the tick signs every tag it makes and needs a runner key; pass --key <runner key.pem> or set ${RUNNER_KEY_ENV}`);
+      }
+    }
     const result = await ciTick({ cwd: process.cwd(), forge, dryRun: ctx.args.dryRun === true, ...(source ? { source } : {}), ...(runnerKey !== undefined ? { runnerKey } : {}) });
     console.log(formatTick(result, ctx.args.dryRun === true));
     return 0;
@@ -143,7 +151,10 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const target = ctx.args.output ? resolve(realpathSync(cwd), ctx.args.output) : join(repoRoot, CI_GREEN_WORKFLOW_FILE);
     const fromRepo = relative(repoRoot, target).split(sep).join("/");
 
-    const scan = workflowsHolding(green, readWorkflowSources(repoRoot, fromRepo));
+    const sources = readWorkflowSources(repoRoot, fromRepo);
+    const scan = workflowsHolding(green, sources);
+    // #4169: the triggers and concurrency of the workflows holding a phase that sets build. Refused before anything is written.
+    const edits = buildTriggerEdits(green, sources);
     const extra = ctx.args.ciWorkflows ?? [];
     const workflows = [...new Set([...scan.workflows, ...extra])].sort();
     for (const f of scan.unreadable) console.error(`warning: ${f} is not valid YAML, so its jobs were not read`);
@@ -161,8 +172,9 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     if (push && "appIdVar" in push) parts.push("--app-id-var", push.appIdVar, "--app-key-secret", push.appKeySecret);
     const runnerKeySecret = ctx.args.ciRunnerKeySecret;
     if (runnerKeySecret) parts.push("--runner-key-secret", runnerKeySecret);
-    if (green.signedSince && !runnerKeySecret) {
-      console.error(`warning: ci.green.signedSince is set, so the tick needs a runner key; pass --runner-key-secret <NAME> naming the repository secret that holds it, or every tick will fail`);
+    const { securityGroupsAt } = await import("./security");
+    if ((green.signedSince || securityGroupsAt(root).has("who-ran-it")) && !runnerKeySecret) {
+      console.error(`warning: ci.green.signedSince is set or the workspace opts into who-ran-it, so the tick needs a runner key; pass --runner-key-secret <NAME> naming the repository secret that holds it, or every tick will fail`);
     }
     const command = parts.map(shellArg).join(" ");
     const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
@@ -172,6 +184,15 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
     if (member) recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
     console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${green.branch}, and every 15 minutes.`);
+    for (const e of edits) {
+      if (!e.changed) continue;
+      const path = writeWorkflowFile(join(repoRoot, e.path), e.text);
+      console.log(
+        e.build === "newest"
+          ? `Wrote ${path}'s triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} the newest commit on ${green.branch} when a run ends, and a ci/build/<sha> tag by hand.`
+          : `Wrote ${path}'s concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} every commit on ${green.branch}, none cancelled.`,
+      );
+    }
     return 0;
   } catch (err) {
     console.error(formatError({ message: `chant ci workflow: ${describe(err)}`, hint: USAGE }));

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

@@ -55,6 +55,18 @@ export interface CiForge {
   kind: ForgeKind;
   /** Every check run on `sha`, every attempt. */
   checkRuns(sha: string): Promise<CheckRun[]>;
+  /**
+   * Run a failed check run's job again (#4169), so a flake costs one more
+   * run before the commit counts red. Absent on a forge chant can't ask.
+   */
+  rerun?(run: CheckRun): Promise<void>;
+  /**
+   * Start a workflow at a ref (#4169), for a build the tick asks for: a
+   * bisect step, or `chant ci run --at`. `workflow` is the file's name in
+   * `.github/workflows/`, and `ref` a branch or tag. Absent on a forge chant
+   * can't ask.
+   */
+  dispatch?(workflow: string, ref: string): Promise<void>;
 }
 
 export interface GithubCiForgeOptions {
@@ -103,7 +115,19 @@ export function githubCiForge(opts: GithubCiForgeOptions): CiForge {
       }
       return out;
     },
+    // An Actions job's check run has the job's id, so the job is re-run by it. Both need `actions: write`.
+    async rerun(run) {
+      await post(`${root}/repos/${opts.repo}/actions/jobs/${run.id}/rerun`, {});
+    },
+    async dispatch(workflow, ref) {
+      await post(`${root}/repos/${opts.repo}/actions/workflows/${encodeURIComponent(workflow)}/dispatches`, { ref });
+    },
   };
+
+  async function post(url: string, body: unknown): Promise<void> {
+    const res = await fetchImpl(url, { method: "POST", headers: { ...headers, "Content-Type": "application/json" }, body: JSON.stringify(body) });
+    if (!res.ok) throw new ForgeApiError("POST", url, res.status, await res.text());
+  }
 }
 
 /** Thrown for a forge `chant ci tick` has no check-run client for yet. */

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

@@ -11,7 +11,7 @@ import { GENERATED_MARKER } from "../discovery/files";
 import type { CommandContext } from "../cli/registry";
 import { parseYAMLDocument } from "../yaml";
 import { runCiWorkflow } from "./ci-green-cli";
-import { CI_GREEN_WORKFLOW_FILE, jobCheckRuns, renderCiGreenWorkflow, workflowsHolding } from "./ci-green-workflow";
+import { BUILD_BLOCK_MARKER, buildTriggerEdits, CI_GREEN_WORKFLOW_FILE, dispatchableWorkflows, jobCheckRuns, renderCiGreenWorkflow, workflowsHolding, writeTopLevel } from "./ci-green-workflow";
 import { parseDeclaration } from "./declaration";
 import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
 
@@ -302,3 +302,86 @@ describe("chant ci workflow (#3573)", () => {
     }
   });
 });
+
+// ── A phase's triggers (#4169) ───────────────────────────────────────────────
+
+const BUILD_GREEN = { branch: "main", phases: { lint: { runs: ["lint"], build: "every" }, suites: { runs: ["suites"], build: "newest" } }, require: ["lint", "suites"] };
+const LINT_WF = `name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Comments above a block stay.
+concurrency:
+  group: ci-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+`;
+const SUITES_WF = `name: suites
+on:
+  schedule:
+    - cron: "0 */3 * * *"
+  workflow_dispatch: {}
+permissions:
+  contents: read
+jobs:
+  suites:
+    runs-on: ubuntu-latest
+`;
+
+describe("the triggers of a phase that sets build (#4169)", () => {
+  const green = () => parseDeclaration(JSON.stringify({ name: "w", schema: 1, members: [], ci: { green: BUILD_GREEN } }), "chant.workspace.json").ci!.green!;
+
+  test("newest: pushes to the branch and by hand, no schedule, one group per ref that never cancels; every: the commit's own group on the branch", () => {
+    const edits = buildTriggerEdits(green(), [
+      { path: ".github/workflows/ci.yml", text: LINT_WF },
+      { path: ".github/workflows/suites.yml", text: SUITES_WF },
+    ]);
+    expect(edits.map((e) => [e.path, e.build, e.phases, e.changed])).toEqual([
+      [".github/workflows/ci.yml", "every", ["lint"], true],
+      [".github/workflows/suites.yml", "newest", ["suites"], true],
+    ]);
+    const ci = parseYAMLDocument(edits[0].text) as Yaml;
+    // The triggers of an every phase stay, pull requests included.
+    expect(ci.on).toEqual({ push: { branches: ["main"] }, pull_request: null });
+    expect(ci.concurrency).toEqual({ group: "chant-build-lint-${{ github.ref == 'refs/heads/main' && github.sha || github.ref }}", "cancel-in-progress": "${{ github.ref != 'refs/heads/main' }}" });
+    expect(edits[0].text).toContain(`# Comments above a block stay.\n${BUILD_BLOCK_MARKER}\nconcurrency:`);
+    const suites = parseYAMLDocument(edits[1].text) as Yaml;
+    expect(suites.on).toEqual({ push: { branches: ["main"] }, workflow_dispatch: {} });
+    expect(suites.concurrency).toEqual({ group: "chant-build-suites-${{ github.ref }}", "cancel-in-progress": false });
+    // A file without the block gets it before permissions:, and writing again changes nothing.
+    expect(edits[1].text.indexOf("concurrency:")).toBeLessThan(edits[1].text.indexOf("permissions:"));
+    const again = buildTriggerEdits(green(), edits.map((e) => ({ path: e.path, text: e.text })));
+    expect(again.map((e) => e.changed)).toEqual([false, false]);
+  });
+
+  test("a phase without build leaves its workflow alone, and one workflow holding both builds is refused", () => {
+    const plain = parseDeclaration(JSON.stringify({ name: "w", schema: 1, members: [], ci: { green: { branch: "main", phases: { lint: ["lint"] }, require: ["lint"] } } }), "chant.workspace.json").ci!.green!;
+    expect(buildTriggerEdits(plain, [{ path: ".github/workflows/ci.yml", text: LINT_WF }])).toEqual([]);
+    const both = LINT_WF.replace("jobs:\n", "jobs:\n  suites:\n    runs-on: ubuntu-latest\n");
+    expect(() => buildTriggerEdits(green(), [{ path: ".github/workflows/ci.yml", text: both }])).toThrow(/holds runs of lint \(build: every\) and suites \(build: newest\)/);
+  });
+
+  test("writeTopLevel replaces a block up to the next top-level line, or adds one before jobs", () => {
+    expect(writeTopLevel("a: 1\nconcurrency:\n  group: x\n\njobs: {}\n", "concurrency", { group: "y" })).toBe(`a: 1\n${BUILD_BLOCK_MARKER}\nconcurrency:\n  group: y\n\njobs: {}\n`);
+    expect(writeTopLevel("a: 1\njobs: {}\n", "concurrency", { group: "y" })).toBe(`a: 1\n${BUILD_BLOCK_MARKER}\nconcurrency:\n  group: y\n\njobs: {}\n`);
+  });
+
+  test("the tick may re-run jobs and start workflows, and ticks on a build tag's runs, only when a phase sets build", () => {
+    const tick = parseYAMLDocument(renderCiGreenWorkflow({ green: green(), workflows: ["ci"], chantVersion: "0.124.33", workspaceRoot: "." })) as Yaml;
+    expect(tick.permissions).toEqual({ contents: "write", checks: "read", actions: "write" });
+    expect(tick.on.workflow_run.branches).toEqual(["main", "ci/build/**"]);
+    const plain = parseDeclaration(JSON.stringify({ name: "w", schema: 1, members: [], ci: { green: { branch: "main", phases: { lint: ["lint"] }, require: ["lint"] } } }), "chant.workspace.json").ci!.green!;
+    const before = parseYAMLDocument(renderCiGreenWorkflow({ green: plain, workflows: ["ci"], chantVersion: "0.124.33", workspaceRoot: "." })) as Yaml;
+    expect(before.permissions).toEqual({ contents: "write", checks: "read" });
+    expect(before.on.workflow_run.branches).toEqual(["main"]);
+  });
+
+  test("the workflows a build request can start are the ones holding its phases with workflow_dispatch", () => {
+    expect(dispatchableWorkflows(green(), ["lint", "suites"], [{ path: ".github/workflows/ci.yml", text: LINT_WF }, { path: ".github/workflows/suites.yml", text: SUITES_WF }])).toEqual({ dispatchable: ["suites.yml"], without: ["ci.yml"] });
+  });
+});

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

@@ -48,8 +48,8 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { GENERATED_MARKER } from "../discovery/files";
-import { parseYAMLDocument } from "../yaml";
-import type { CiGreen } from "./declaration";
+import { emitYAMLEntry, parseYAMLDocument } from "../yaml";
+import type { CiBuild, CiGreen } from "./declaration";
 import { matchesCheckRun } from "./ci-green";
 import { githubSecretOrJobToken } from "../ci-jobs";
 
@@ -129,6 +129,31 @@ export function workflowsHolding(green: CiGreen, sources: readonly WorkflowSourc
   };
 }
 
+/**
+ * The workflow files that hold a check run of one of `phases` and can be
+ * started by hand (`workflow_dispatch`), by file name, for a build the tick
+ * asks for (#4169). Files that can't be parsed are left out.
+ */
+export function dispatchableWorkflows(green: CiGreen, phases: readonly string[], sources: readonly WorkflowSource[]): { dispatchable: string[]; without: string[] } {
+  const patterns = phases.flatMap((name) => green.phases.find((p) => p.name === name)?.runs ?? []);
+  const dispatchable: string[] = [];
+  const without: string[] = [];
+  for (const s of sources) {
+    let doc: unknown;
+    try {
+      doc = parseYAMLDocument(s.text);
+    } catch {
+      continue;
+    }
+    const runs = jobCheckRuns(doc);
+    if (!patterns.some((p) => runs.some((r) => meet(p, r)))) continue;
+    const on = isObject(doc) ? doc.on : undefined;
+    const file = s.path.slice(s.path.lastIndexOf("/") + 1);
+    (isObject(on) && "workflow_dispatch" in on ? dispatchable : without).push(file);
+  }
+  return { dispatchable: dispatchable.sort(), without: without.sort() };
+}
+
 /** The repository's GitHub workflow files, other than `skip`. */
 export function readWorkflowSources(repoRoot: string, skip: string): WorkflowSource[] {
   const dir = join(repoRoot, ".github", "workflows");
@@ -213,6 +238,8 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     "      - completed",
     "    branches:",
     `      - ${q(green.branch)}`,
+    // #4169: a build the tick asked for runs at a ci/build/<sha> tag, and its completion ticks too.
+    ...(newestPhases(green) ? [`      - ${q("ci/build/**")}`] : []),
     "  schedule:",
     "    - cron: \"*/15 * * * *\"",
     "  workflow_dispatch: {}",
@@ -225,6 +252,8 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     "permissions:",
     "  contents: write",
     "  checks: read",
+    // #4169: re-running a failed job and starting a workflow at a ci/build/<sha> tag.
+    ...(declaresBuild(green) ? ["  actions: write"] : []),
     "",
     "jobs:",
     "  tick:",
@@ -254,6 +283,114 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
   return lines.join("\n") + "\n";
 }
 
+/** Whether any phase sets `build` (#4169): then the tick may re-run jobs and start workflows. */
+export const declaresBuild = (green: CiGreen) => green.phases.some((p) => p.build !== undefined);
+/** Whether a required phase builds only the newest commit (#4169). */
+export const newestPhases = (green: CiGreen) => green.phases.some((p) => p.build === "newest" && green.require.includes(p.name));
+
+// ── A phase's triggers (#4169) ───────────────────────────────────────────────
+
+/** The comment line above each top-level block `ci workflow` writes into a phase's workflow. */
+export const BUILD_BLOCK_MARKER = "# Written by chant ci workflow from ci.green's build (#4169); edit ci.green and run it again.";
+
+/** What `ci workflow` writes into one workflow holding a phase that sets `build`. */
+export interface BuildTriggerEdit {
+  /** Relative to the repository root. */
+  path: string;
+  build: CiBuild;
+  phases: string[];
+  /** The file with its triggers and concurrency written. */
+  text: string;
+  changed: boolean;
+}
+
+/**
+ * The workflows holding the check runs of phases that set `build`, each with
+ * its triggers and concurrency written for that build (#4169):
+ *
+ * - `newest`: on pushes to the branch, and by hand (`workflow_dispatch`),
+ *   which is how the tick starts a bisect step or a requested build at a
+ *   `ci/build/<sha>` tag. A `schedule` goes: a runner freeing up, not a
+ *   clock, picks the commit. Other triggers stay. One concurrency group per
+ *   ref that never cancels a run in progress, so GitHub keeps the newest
+ *   push waiting and drops the ones between, and each tag's build runs in a
+ *   group of its own.
+ * - `every`: the triggers stay, and the group is the commit itself on the
+ *   branch, so no push cancels or replaces another's run; elsewhere, such as
+ *   a pull request, a new push cancels the run it supersedes.
+ *
+ * Only the top-level `on:` (for `newest`) and `concurrency:` blocks change,
+ * each under {@link BUILD_BLOCK_MARKER}; the rest of the file is kept as it
+ * is. Throws when one workflow holds a phase of each build, which no one
+ * concurrency group can serve.
+ */
+export function buildTriggerEdits(green: CiGreen, sources: readonly WorkflowSource[]): BuildTriggerEdit[] {
+  const out: BuildTriggerEdit[] = [];
+  for (const s of sources) {
+    let doc: unknown;
+    try {
+      doc = parseYAMLDocument(s.text);
+    } catch {
+      continue;
+    }
+    const runs = jobCheckRuns(doc);
+    const held = green.phases.filter((p) => p.build !== undefined && p.runs.some((pattern) => runs.some((r) => meet(pattern, r))));
+    if (held.length === 0) continue;
+    const builds = [...new Set(held.map((p) => p.build!))];
+    if (builds.length > 1) {
+      throw new Error(`${s.path} holds runs of ${held.map((p) => `${p.name} (build: ${p.build})`).join(" and ")}, and one workflow can't run on every commit and only the newest; move the jobs into a workflow per build`);
+    }
+    const build = builds[0];
+    const phases = held.map((p) => p.name);
+    const tag = phases.map((p) => p.replace(/[^A-Za-z0-9_-]/g, "-")).join("-");
+    let text = s.text;
+    if (build === "newest") {
+      const on = isObject(doc) && isObject(doc.on) ? { ...doc.on } : {};
+      delete on.schedule;
+      const push = isObject(on.push) ? { ...on.push } : {};
+      const branches = Array.isArray(push.branches) ? push.branches.filter((b): b is string => typeof b === "string") : [];
+      push.branches = branches.includes(green.branch) ? branches : [...branches, green.branch];
+      const { push: _push, workflow_dispatch: dispatch, ...rest } = on;
+      text = writeTopLevel(text, "on", { push, workflow_dispatch: dispatch ?? {}, ...rest });
+      text = writeTopLevel(text, "concurrency", { group: `chant-build-${tag}-\${{ github.ref }}`, "cancel-in-progress": false });
+    } else {
+      const main = `refs/heads/${green.branch}`;
+      // Written as lines: the emitter would quote the expression, and GitHub reads it the same either way.
+      text = writeTopLevel(text, "concurrency", [
+        "concurrency:",
+        `  group: chant-build-${tag}-\${{ github.ref == '${main}' && github.sha || github.ref }}`,
+        `  cancel-in-progress: \${{ github.ref != '${main}' }}`,
+      ]);
+    }
+    out.push({ path: s.path, build, phases, text, changed: text !== s.text });
+  }
+  return out;
+}
+
+/**
+ * Replace the top-level `key:` block of a YAML file with `value` (or with
+ * `value`'s lines, the key's own line first), under
+ * {@link BUILD_BLOCK_MARKER}, or add it before `permissions:` or `jobs:`
+ * when the file has none. The block runs from its key's line to the next
+ * line at column 0 that is not blank; comments above the key stay.
+ */
+export function writeTopLevel(text: string, key: string, value: Record<string, unknown> | string[]): string {
+  const lines = text.split("\n");
+  const block = [BUILD_BLOCK_MARKER, ...(Array.isArray(value) ? value : emitYAMLEntry(key, value).split("\n"))];
+  const at = lines.findIndex((l) => l === `${key}:` || l.startsWith(`${key}: `) || l.startsWith(`${key}:#`));
+  if (at < 0) {
+    const before = lines.findIndex((l) => /^(permissions|jobs):/.test(l));
+    const where = before < 0 ? lines.length : before;
+    return [...lines.slice(0, where), ...block, "", ...lines.slice(where)].join("\n");
+  }
+  let end = at + 1;
+  while (end < lines.length && (lines[end] === "" || /^\s/.test(lines[end]))) end++;
+  // A blank line ending the block belongs to what follows it.
+  while (end > at + 1 && lines[end - 1] === "") end--;
+  const start = at > 0 && lines[at - 1] === BUILD_BLOCK_MARKER ? at - 1 : at;
+  return [...lines.slice(0, start), ...block, ...lines.slice(end)].join("\n");
+}
+
 /** The header line naming the command that regenerates the file, and where to run it. */
 export function ciGreenHeader(command: string, where: "member" | "root"): string {
   return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the ${where === "member" ? "member's directory" : "workspace root"})\n`;

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

@@ -117,10 +117,13 @@ describe("judging a phase from check runs (#3573)", () => {
     const runs = [run(1, "macos (test)", "skipped")];
     expect(evaluatePhase(phase(["macos (test)"]), runs).verdict).toBe("fail");
     expect(evaluatePhase(phase(["macos (test)"], "pass"), runs).verdict).toBe("pass");
-    // Neither counts any other conclusion as a pass.
-    for (const c of ["neutral", "cancelled", "timed_out", "action_required", "stale"]) {
+    // Neither counts any other conclusion as a pass, and a stopped run is no failure either (#4169).
+    for (const c of ["neutral", "timed_out", "action_required"]) {
       expect(evaluatePhase(phase(["x"], "pass"), [run(1, "x", c)]).verdict, c).toBe("fail");
     }
+    for (const c of ["cancelled", "stale"]) {
+      expect(evaluatePhase(phase(["x"], "pass"), [run(1, "x", c)]), c).toMatchObject({ verdict: "unbuilt", reason: "cancelled" });
+    }
   });
 
   test("a run in progress, or a pattern nothing matches yet, leaves the phase undecided; a failure decides it", () => {