@intentius/chant 0.124.31 → 0.124.33

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

@@ -32,8 +32,8 @@ export interface CheckRun {
   url: string | null;
   /**
    * Set when the "check run" is a chant Op run (#4044, `ci.green.source:
-   * "runs"`): the run's id and env, the runner whose statement it carries,
-   * and that statement. `name` is then the Op's name and `id` the run's end
+   * "runs"`): the run's id and env, and the runner whose statement it
+   * carries with that statement, or a null signer for an unsigned run. `name` is then the Op's name and `id` the run's end
    * time in milliseconds, which orders a re-run after the run it replaced.
    */
   opRun?: OpRunRef;
@@ -45,14 +45,28 @@ export interface CheckRun {
 export interface OpRunRef {
   id: string;
   env: string;
-  signer: string;
-  statement: NonNullable<OpRunRecord["statement"]>;
+  /** The runner whose statement the run carries, or null for an unsigned run, which counts unless `ci.green.signedSince` asks for one (#4156). */
+  signer: string | null;
+  /** The run's statement, when it has one. */
+  statement?: NonNullable<OpRunRecord["statement"]>;
 }
 
 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 {
@@ -101,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-runs.test.ts

@@ -1,11 +1,13 @@
 /**
  * #4044: chant run results as a status source for `ci tick`. With
  * `ci.green.source: "runs"` (or `--source runs`) the tick reads Op runs from
- * the run ledger on `chant/lifecycle` instead of a forge's check runs. A run
- * counts only when its record carries a statement signed by a runner key
- * `.chant/trust.json` lists for a principal holding the `runner` role; the
- * tick ignores and reports any other. Every tag it makes is signed, and names
- * the runs behind it.
+ * the run ledger on `chant/lifecycle` instead of a forge's check runs.
+ * Signing is opt-in (#4156): an unsigned run counts with no signer, and a run
+ * whose statement a runner key `.chant/trust.json` lists for a principal
+ * holding the `runner` role signed counts with that signer. A statement that
+ * does not verify is ignored and reported. With `ci.green.signedSince` an
+ * unsigned run on that commit or after it is ignored too. A tick given a
+ * runner key signs its tags, and every tag names the runs behind it.
  *
  * Each test works in its own temp repository with a bare origin, and every
  * key is a throwaway one. Nothing is written in process.cwd().
@@ -149,19 +151,61 @@ describe("chant runs as the ci tick's status source (#4044)", () => {
     expect((await ciTick({ cwd: root, now: NOW, runnerKey: BOT.pem })).made).toEqual([]);
   });
 
-  test("an unsigned run is refused: it neither greens nor revokes a commit, and is reported", async () => {
+  test("an unsigned run counts with no signer: with no key anywhere the tick tags the commit and ci list shows it (#4156)", async () => {
     const { root } = workspace();
     const a = commitAt(root, 3, "app/a.txt");
+    const lint = await runOp(root, "lint");
+    await runOp(root, "test");
+    expect(lint.statement).toBeUndefined();
+    push(root);
+
+    const list = (await ciList({ cwd: root, now: NOW })) as Extract<Awaited<ReturnType<typeof ciList>>, { commits: unknown }>;
+    readList.expectValid(list);
+    const listed = list.commits.find((c) => c.sha === a)!;
+    expect(listed.phases.map((p) => [p.phase, p.result])).toEqual([
+      ["lint", "pass"],
+      ["test", "pass"],
+    ]);
+    expect(listed.phases[0]!.runs[0]).toMatchObject({ name: "lint", id: null, opRun: { id: lint.id, env: "ci", signer: null } });
+    expect(listed.ignoredRuns).toEqual([]);
+
+    // No runner key: the tick still tags, unsigned, and the tag names the unsigned runs.
+    const tick = await ciTick({ cwd: root, now: NOW });
+    expect(tick.made).toEqual([`ci/green/${a}`]);
+    expect(tick.signer).toBeNull();
+    const record = recordOf(root, `ci/green/${a}`) as { statement?: unknown; phases: Record<string, { opRun: Record<string, unknown> }[]> };
+    expect(record.statement).toBeUndefined();
+    expect(record.phases.lint![0]!.opRun).toEqual({ id: lint.id, env: "ci", signer: null });
+
+    // A signed run beside them shows its signer.
+    const signed = await runOp(root, "lint", { pem: BOT.pem });
+    const source = await readOpRunSource(root, root, git(root, "rev-parse", "HEAD"));
+    expect(source.checkRuns(a).map((r) => [r.opRun!.id, r.opRun!.signer])).toEqual([
+      [lint.id, null],
+      [signed.id, "ci-bot"],
+      [expect.any(String), null],
+    ]);
+    expect(source.ignored.size).toBe(0);
+  });
+
+  test("with ci.green.signedSince an unsigned run neither greens nor revokes a commit from that one on, and is reported", async () => {
+    const { root } = workspace();
+    const a = commitAt(root, 3, "app/a.txt");
+    git(root, "push", "-q", "origin", "main");
+    // The opt-in: every run on a, and after it, must be signed.
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green: { ...GREEN, signedSince: a } } }) });
     await runOp(root, "lint", { pem: BOT.pem });
     const unsigned = await runOp(root, "test");
     expect(unsigned.statement).toBeUndefined();
     push(root);
 
+    // The opt-in also asks for signed tags, so the tick needs the key.
+    await expect(ciTick({ cwd: root, now: NOW })).rejects.toThrow(/needs a statement signed by a runner key, and none was given/);
     const tick = await ciTick({ cwd: root, now: NOW, runnerKey: BOT.pem });
     expect(tick.made).toEqual([]);
     const at = tick.commits.find((c) => c.sha === a)!;
     expect(at.verdict?.verdict).toBe("pending");
-    expect(at.ignoredRuns).toEqual([{ run: unsigned.id, op: "test", env: "ci", status: "unsigned", reason: expect.stringContaining("carries no statement signed by a runner key") }]);
+    expect(at.ignoredRuns).toEqual([{ run: unsigned.id, op: "test", env: "ci", status: "unsigned", reason: expect.stringContaining("ci.green.signedSince is") }]);
     expect(formatTick(tick)).toContain(`ignored run ${unsigned.id} of test in ci (unsigned)`);
     expect(git(root, "tag", "-l")).toBe("");
 
@@ -173,7 +217,6 @@ describe("chant runs as the ci tick's status source (#4044)", () => {
       ["test", "pending"],
     ]);
     expect(listed.ignoredRuns?.map((r) => r.status)).toEqual(["unsigned"]);
-    expect(formatList(list)).toContain(`ignored run ${unsigned.id} of test in ci (unsigned)`);
 
     // Signed now, the commit goes green; a later unsigned failure does not revoke it.
     await runOp(root, "test", { pem: BOT.pem });
@@ -186,7 +229,7 @@ describe("chant runs as the ci tick's status source (#4044)", () => {
     expect(after.commits.find((c) => c.sha === a)!.ignoredRuns?.map((r) => r.status)).toEqual(["unsigned", "unsigned"]);
   });
 
-  test("a run signed by an unlisted key, or whose record changed after signing, does not count", async () => {
+  test("a run signed by an unlisted key, or whose record changed after signing, does not count, with or without the opt-in", async () => {
     const { root } = workspace();
     const a = commitAt(root, 3, "app/a.txt");
     // A key trust.json does not list can't sign a run here at all.
@@ -219,13 +262,12 @@ describe("chant runs as the ci tick's status source (#4044)", () => {
     expect(record).toMatchObject({ source: "runs", phase: "test", run: { name: "test", id: null, conclusion: "failure", opRun: { id: red.id, signer: "ci-bot" } } });
   });
 
-  test("a tick from runs needs a runner key unless it is a dry run, --source overrides the declaration, and ci list refuses --forge", async () => {
+  test("a tick from runs without a runner key makes unsigned tags, --source overrides the declaration, and ci list refuses --forge", async () => {
     const { root } = workspace({ ...GREEN, source: "checks" });
     const a = commitAt(root, 3, "app/a.txt");
     await runOp(root, "lint", { pem: BOT.pem });
     await runOp(root, "test", { pem: BOT.pem });
     push(root);
-    await expect(ciTick({ cwd: root, now: NOW, source: "runs" })).rejects.toThrow(/every tag it makes from them is signed by a runner key, and none was given/);
     expect((await ciTick({ cwd: root, now: NOW, source: "runs", dryRun: true })).made).toEqual([`ci/green/${a}`]);
     expect(git(root, "tag", "-l")).toBe("");
     // The declaration says checks, so without --source the tick wants a forge.

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

@@ -51,7 +51,7 @@ describe("the ci.green block (#3573)", () => {
     });
     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(decl({}), "chant.workspace.json").ci).toEqual({ green: null, reportUrl: null });
     expect(parseDeclaration(JSON.stringify({ name: "w", schema: 1, members: [] }), "chant.workspace.json").ci).toBeNull();
   });
 
@@ -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", () => {