@intentius/chant 0.124.45 → 0.124.48

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

@@ -0,0 +1,153 @@
+/**
+ * #4325: `ci.green` names several branches when `ci.branches` routes members
+ * to branches of their own. Each is judged as the single branch always was, a
+ * one-branch declaration reads as before, and `release cut` takes a commit of
+ * any of them.
+ */
+
+import { afterAll, describe, expect, test } from "vitest";
+import { greenBranches, parseDeclaration } from "./declaration";
+import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { ciList, ciTick, formatTick, greenOn, lastGreen } from "./ci-green";
+import type { CheckRun, CiForge } from "./ci-green-forge";
+import { buildTriggerEdits, renderCiGreenWorkflow } from "./ci-green-workflow";
+import { checkOnGreenBranches, checkOnTrunk, resolveTrunk, WorkstationCheckError } from "../lifecycle/release-workstation";
+
+afterAll(cleanScratch);
+
+const PHASES = { test: ["test"] };
+const decl = (green: unknown) => JSON.stringify({ name: "w", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "x" }], ci: { green } });
+const parse = (branch: unknown) => parseDeclaration(decl({ branch, phases: PHASES, require: ["test"] }), "chant.workspace.json").ci!.green!;
+
+describe("ci.green.branch as one branch or several (#4325)", () => {
+  test("a string reads exactly as it did: no branches field", () => {
+    const g = parse("main");
+    expect(g.branch).toBe("main");
+    expect("branches" in g).toBe(false);
+    expect(greenBranches(g)).toEqual(["main"]);
+    // A list of one is the same declaration.
+    expect(parse(["main"])).toEqual(g);
+  });
+
+  test("a list judges each branch, and the first is the trunk readers use", () => {
+    const g = parse(["main", "release"]);
+    expect(g.branch).toBe("main");
+    expect(g.branches).toEqual(["main", "release"]);
+    expect(greenBranches(g)).toEqual(["main", "release"]);
+  });
+
+  test("an empty list, a repeated branch and a malformed name are refused", () => {
+    for (const bad of [[], ["main", "main"], ["main", "has space"], [3]]) {
+      expect(() => parse(bad), JSON.stringify(bad)).toThrow();
+    }
+  });
+
+  test("greenOn picks a branch ci.green names and refuses one it doesn't", () => {
+    const g = parse(["main", "release"]);
+    expect(greenOn(g, undefined).branch).toBe("main");
+    expect(greenOn(g, "release").branch).toBe("release");
+    expect("branches" in greenOn(g, "release")).toBe(false);
+    expect(() => greenOn(g, "staging")).toThrow(/judges main, release, not staging/);
+  });
+});
+
+// ── The tick, against a real remote ──────────────────────────────────────────
+
+const NOW = new Date();
+const run = (id: number, name: string, conclusion: string): CheckRun => ({ id, name, status: "completed", conclusion, completedAt: null, url: `https://example.com/runs/${id}` });
+
+function commit(root: string, file: string): string {
+  writeFiles(root, { [file]: `${file}\n` });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", file);
+  return git(root, "rev-parse", "HEAD");
+}
+
+/** A checkout with `main` and `release` pushed to a bare origin, one commit each past a shared base. */
+function twoBranches(green: unknown): { root: string; origin: string; main: string; release: string } {
+  const origin = scratchDir("chant-ci-branches-origin-");
+  git(origin, "init", "-q", "--bare");
+  const root = scratchDir("chant-ci-branches-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 } }) });
+  git(root, "remote", "add", "origin", origin);
+  commit(root, "app/base.txt");
+  git(root, "checkout", "-q", "-b", "release");
+  const release = commit(root, "app/release.txt");
+  git(root, "checkout", "-q", "main");
+  const main = commit(root, "app/main.txt");
+  git(root, "push", "-q", "origin", "main", "release");
+  return { root, origin, main, release };
+}
+
+const remoteTags = (origin: string) => git(origin, "for-each-ref", "--format=%(refname:lstrip=2)", "refs/tags/").split("\n").filter(Boolean).sort();
+const forge = (shas: string[]): CiForge => ({ kind: "github", checkRuns: async (sha) => (shas.includes(sha) ? [run(1, "test", "success")] : []) });
+
+describe("the tick judges each branch ci.green names (#4325)", () => {
+  test("a commit of a routed branch gets a green tag, and last-green reads each branch", async () => {
+    const { root, origin, main, release } = twoBranches({ branch: ["main", "release"], phases: PHASES, require: ["test"] });
+    const result = await ciTick({ cwd: root, forge: forge([main, release]), now: NOW });
+    expect(result.branch).toBe("main");
+    expect(result.routed?.map((r) => r.branch)).toEqual(["release"]);
+    expect(result.made.sort()).toEqual([`ci/green/${main}`, `ci/green/${release}`].sort());
+    expect(remoteTags(origin)).toEqual([`ci/green/${main}`, `ci/green/${release}`].sort());
+    // The tag says which branch it judged.
+    const note = git(origin, "tag", "-l", "--format=%(contents)", `ci/green/${release}`);
+    expect(JSON.parse(note.slice(note.indexOf("{")))).toMatchObject({ tag: "green", commit: release, branch: "release" });
+
+    expect((lastGreen({ cwd: root }) as { commit: { sha: string } }).commit.sha).toBe(main);
+    const onRelease = lastGreen({ cwd: root, branch: "release" }) as { branch: string; commit: { sha: string } };
+    expect([onRelease.branch, onRelease.commit.sha]).toEqual(["release", release]);
+    expect(lastGreen({ cwd: root, branch: "staging" })).toMatchObject({ error: { code: "ci-branch-unknown" } });
+
+    const listed = await ciList({ cwd: root, branch: "release", now: NOW });
+    expect("commits" in listed && listed.commits.filter((c) => c.state === "green").map((c) => c.sha)).toEqual([release]);
+
+    const text = formatTick(result);
+    expect(text).toContain("main, commits within 24h");
+    expect(text).toContain("release, commits within 24h");
+  });
+
+  test("a one-branch declaration ticks one branch, with no routed results", async () => {
+    const { root, main, release } = twoBranches({ branch: "main", phases: PHASES, require: ["test"] });
+    const result = await ciTick({ cwd: root, forge: forge([main, release]), now: NOW });
+    expect(result.routed).toBeUndefined();
+    expect(result.made).toEqual([`ci/green/${main}`]);
+    expect(lastGreen({ cwd: root, branch: "release" })).toMatchObject({ error: { code: "ci-branch-unknown" } });
+  });
+});
+
+describe("the generated tick workflow follows the branches (#4325)", () => {
+  const green = (branch: string | string[]) => parse(branch);
+
+  test("workflow_run lists every branch, and one branch renders as before", () => {
+    const render = (g: ReturnType<typeof green>) => renderCiGreenWorkflow({ green: g, workflows: ["ci"], chantVersion: "0.0.0", workspaceRoot: ".", install: undefined, chant: undefined, npmLock: undefined, push: undefined });
+    const many = render(green(["main", "release"]));
+    expect(many).toMatch(/branches:\n\s+- "?main"?\n\s+- "?release"?\n/);
+    // The checkout stays on the first branch, which holds the declaration the tick reads.
+    expect(many).toMatch(/ref: "?main"?/);
+    expect(render(green("main"))).not.toContain("release");
+  });
+
+  test("a push-triggered build lists every branch", () => {
+    const sources = [{ path: ".github/workflows/ci.yml", text: "name: ci\non:\n  push:\n    branches: [main]\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps: []\n" }];
+    const g = parseDeclaration(decl({ branch: ["main", "release"], phases: { test: { runs: ["test"], build: "newest" } }, require: ["test"] }), "chant.workspace.json").ci!.green!;
+    const [edit] = buildTriggerEdits(g, sources as never, { compose: false });
+    expect(edit!.text).toMatch(/branches:\n\s+- main\n\s+- release/);
+  });
+});
+
+describe("release cut takes a commit of any branch ci.green names (#4325)", () => {
+  test("a routed branch's commit is on trunk for the cut, and an unrelated one is not", () => {
+    const { root, main, release } = twoBranches({ branch: ["main", "release"], phases: PHASES, require: ["test"] });
+    git(root, "fetch", "-q", "origin");
+    const trunk = resolveTrunk(root, "main");
+    expect(() => checkOnTrunk(root, main, trunk)).not.toThrow();
+    expect(() => checkOnTrunk(root, release, trunk)).toThrow(WorkstationCheckError);
+    expect(checkOnGreenBranches(root, main, trunk, ["release"]).branch).toBe("main");
+    expect(checkOnGreenBranches(root, release, trunk, ["release"]).branch).toBe("release");
+    // Without the routed branch listed, the first branch's refusal stands.
+    expect(() => checkOnGreenBranches(root, release, trunk, [])).toThrow(WorkstationCheckError);
+  });
+});

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

@@ -32,12 +32,12 @@ 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, 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 { greenBranches, readDeclaration, readerVersion, WorkspaceReadError, type CiSource } from "./declaration";
 import { recordGeneratedFiles, resolveMemberContext, shellArg } from "./member-pipeline";
 import { gitTop, workingTree } from "./tree";
 
 const USAGE =
-  "chant ci last-green [--json] [--from <rev>] | ci list [--json] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs] | ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>] | " +
+  "chant ci last-green [--json] [--from <rev>] [--branch <branch>] | ci list [--json] [--branch <branch>] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs] | ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>] | " +
   "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>]";
 
 export { RUNNER_KEY_ENV };
@@ -56,7 +56,7 @@ function warnIgnored(ignored: readonly { tag: string; status: string; reason: st
 }
 
 export async function runCiLastGreen(ctx: CommandContext): Promise<number> {
-  const doc = lastGreen({ cwd: process.cwd(), ...(ctx.args.migrateFrom !== undefined ? { from: ctx.args.migrateFrom } : {}) });
+  const doc = lastGreen({ cwd: process.cwd(), ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}), ...(ctx.args.migrateFrom !== undefined ? { from: ctx.args.migrateFrom } : {}) });
   if (ctx.args.json) {
     console.log(JSON.stringify(doc, null, 2));
     return "error" in doc ? 1 : 0;
@@ -81,7 +81,7 @@ export async function runCiList(ctx: CommandContext): Promise<number> {
     // Only an explicit --forge reaches the network; without it the list reads local refs and tags.
     const forge = ctx.args.forge !== undefined ? ciForgeFromEnv(ctx.args.forge) : undefined;
     const source = sourceOf(ctx.args);
-    const doc = await ciList({ cwd: process.cwd(), limit, since: ctx.args.since, forge, ...(source ? { source } : {}) });
+    const doc = await ciList({ cwd: process.cwd(), ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}), limit, since: ctx.args.since, forge, ...(source ? { source } : {}) });
     if (ctx.args.json) {
       console.log(JSON.stringify(doc, null, 2));
       return "error" in doc ? 1 : 0;
@@ -185,14 +185,14 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
     const yaml = renderCiGreenWorkflow({ green, workflows, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock, push, ...(runnerKeySecret ? { runnerKeySecret } : {}), ...(compose ? { compose } : {}) });
     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}${compose ? " or a chant/compose/ branch" : ""}, and every 15 minutes.`);
+    console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${greenBranches(green).join(", ")}${compose ? " or a chant/compose/ 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 triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} every commit on ${green.branch}, none cancelled, and a ci/build/<sha> tag by hand when the forge ran nothing.`,
+          ? `Wrote ${path}'s triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} the newest commit on ${greenBranches(green).join(", ")} when a run ends, and a ci/build/<sha> tag by hand.`
+          : `Wrote ${path}'s triggers and concurrency: ${e.phases.join(", ")} build${e.phases.length === 1 ? "s" : ""} every commit on ${greenBranches(green).join(", ")}, none cancelled, and a ci/build/<sha> tag by hand when the forge ran nothing.`,
       );
     }
     return 0;

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

@@ -14,6 +14,7 @@ import { runCiWorkflow } from "./ci-green-cli";
 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";
+import { ACTION_PINS, usesRef } from "../action-pins";
 
 afterAll(cleanScratch);
 
@@ -82,7 +83,7 @@ describe("the workflows that hold required check runs (#3573)", () => {
     expect(doc.concurrency).toEqual({ group: "chant-ci-green", "cancel-in-progress": false });
     expect(doc.permissions).toEqual({ contents: "write", checks: "read" });
     const steps = doc.jobs.tick.steps;
-    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0 } });
+    expect(steps[0]).toEqual({ uses: usesRef(ACTION_PINS.checkout6), with: { ref: "main", "fetch-depth": 0 } });
     expect(steps[2].run).toBe("npx --yes @intentius/chant@0.108.0 ci tick");
     expect(steps[2]["working-directory"]).toBeUndefined();
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
@@ -128,7 +129,7 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     const plain = renderCiGreenWorkflow(base);
     const text = renderCiGreenWorkflow({ ...base, push: { secret: "CI_GREEN_TOKEN" } });
     const steps = (parseYAMLDocument(text) as Yaml).jobs.tick.steps;
-    expect(steps[0]).toEqual({ uses: "actions/checkout@v6", with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN || github.token }}" } });
+    expect(steps[0]).toEqual({ uses: usesRef(ACTION_PINS.checkout6), with: { ref: "main", "fetch-depth": 0, token: "${{ secrets.CI_GREEN_TOKEN || github.token }}" } });
     // Check runs are still read with the Actions token: a fine-grained token can't call the Checks API.
     expect(steps[2].env.GITHUB_TOKEN).toBe("${{ github.token }}");
     expect((parseYAMLDocument(text) as Yaml).permissions).toEqual({ contents: "write", checks: "read" });
@@ -147,7 +148,7 @@ describe("the token the tick pushes its tags with (#3573)", () => {
     const steps = (parseYAMLDocument(renderCiGreenWorkflow({ ...base, push: { appIdVar: "CI_GREEN_APP_ID", appKeySecret: "CI_GREEN_APP_KEY" } })) as Yaml).jobs.tick.steps;
     expect(steps[0]).toMatchObject({
       id: "app-token",
-      uses: "actions/create-github-app-token@v2",
+      uses: usesRef(ACTION_PINS.createGithubAppToken2),
       with: { "app-id": "${{ vars.CI_GREEN_APP_ID }}", "private-key": "${{ secrets.CI_GREEN_APP_KEY }}" },
     });
     expect(steps[1].with.token).toBe("${{ steps.app-token.outputs.token }}");

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

@@ -48,8 +48,9 @@
 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 { ACTION_PINS, tagComments, usesRef } from "../action-pins";
 import { emitYAMLEntry, parseYAMLDocument } from "../yaml";
-import type { CiBuild, CiGreen } from "./declaration";
+import { greenBranches, type CiBuild, type CiGreen } from "./declaration";
 import { matchesCheckRun } from "./ci-green";
 import { githubSecretOrJobToken } from "../ci-jobs";
 import { COMPOSE_BRANCH_PREFIX } from "../lifecycle/compose-refs";
@@ -228,7 +229,7 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
       ? [
           "      - name: Mint a GitHub App token that may push tags to commits that change workflows",
           "        id: app-token",
-          "        uses: actions/create-github-app-token@v2",
+          `        uses: ${usesRef(ACTION_PINS.createGithubAppToken2)}`,
           "        with:",
           `          app-id: \${{ vars.${push.appIdVar} }}`,
           `          private-key: \${{ secrets.${push.appKeySecret} }}`,
@@ -247,7 +248,7 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     "    types:",
     "      - completed",
     "    branches:",
-    `      - ${q(green.branch)}`,
+    ...greenBranches(green).map((b) => `      - ${q(b)}`),
     // #4169: a build the tick asked for runs at a ci/build/<sha> tag, and its completion ticks too.
     ...(newestPhases(green) ? [`      - ${q("ci/build/**")}`] : []),
     // #4220: a composed commit's phases run on its chant/compose/<name> branch, and their completion ticks too.
@@ -273,12 +274,12 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     "    timeout-minutes: 15",
     "    steps:",
     ...mint,
-    "      - uses: actions/checkout@v6",
+    `      - uses: ${usesRef(ACTION_PINS.checkout6)}`,
     "        with:",
     `          ref: ${q(green.branch)}`,
     "          fetch-depth: 0",
     ...token,
-    "      - uses: actions/setup-node@v6",
+    `      - uses: ${usesRef(ACTION_PINS.setupNode6)}`,
     "        with:",
     "          node-version: \"24\"",
     ...cache,
@@ -292,7 +293,7 @@ export function renderCiGreenWorkflow(input: WorkflowInput): string {
     ...(input.runnerKeySecret ? [`          CHANT_RUNNER_KEY: \${{ secrets.${input.runnerKeySecret} }}`] : []),
     `        run: ${tick}`,
   ];
-  return lines.join("\n") + "\n";
+  return tagComments(lines.join("\n") + "\n");
 }
 
 /** Whether any phase sets `build` (#4169): then the tick may re-run jobs and start workflows. */
@@ -370,7 +371,7 @@ export function buildTriggerEdits(green: CiGreen, sources: readonly WorkflowSour
       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") : [];
-      const withBranch = branches.includes(green.branch) ? branches : [...branches, green.branch];
+      const withBranch = [...branches, ...greenBranches(green).filter((b) => !branches.includes(b))];
       push.branches = compose && !withBranch.includes(COMPOSE_BRANCHES) ? [...withBranch, COMPOSE_BRANCHES] : withBranch;
       const { push: _push, workflow_dispatch: dispatch, ...rest } = on;
       text = writeTopLevel(text, "on", { push, workflow_dispatch: dispatch ?? {}, ...rest });
@@ -388,8 +389,11 @@ export function buildTriggerEdits(green: CiGreen, sources: readonly WorkflowSour
       if (!("workflow_dispatch" in next)) next = { ...next, workflow_dispatch: {} };
       if (next !== on) text = writeTopLevel(text, "on", next);
       // #4220: a compose branch's commits each get a verdict, so its runs are keyed by commit, as the trunk branch's are.
-      const keyed = compose ? `(github.ref == '${main}' || startsWith(github.ref, 'refs/heads/${COMPOSE_BRANCH_PREFIX}'))` : `github.ref == '${main}'`;
-      const unkeyed = compose ? `!${keyed}` : `github.ref != '${main}'`;
+      // #4325: each branch ci.green judges is keyed by commit.
+      const heads = greenBranches(green).map((b) => `github.ref == 'refs/heads/${b}'`);
+      const several = heads.length > 1;
+      const keyed = compose ? `(${[...heads, `startsWith(github.ref, 'refs/heads/${COMPOSE_BRANCH_PREFIX}')`].join(" || ")})` : several ? `(${heads.join(" || ")})` : `github.ref == '${main}'`;
+      const unkeyed = compose || several ? `!${keyed}` : `github.ref != '${main}'`;
       // Written as lines: the emitter would quote the expression, and GitHub reads it the same either way.
       text = writeTopLevel(text, "concurrency", [
         "concurrency:",

package/src/workspace/ci-green.ts

@@ -55,7 +55,7 @@
 
 import { judgeCommits, mergeCommits, readWorkIndex, type CommitLink } from "./commit-links";
 import { execFileSync } from "node:child_process";
-import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type CiGreen, type CiPhase, type CiSource } from "./declaration";
+import { greenBranches, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type CiGreen, type CiPhase, type CiSource } from "./declaration";
 import type { CheckRun, CiForge, OpRunRef } from "./ci-green-forge";
 import type { OpRunRecord } from "../op/runtime";
 import { readRunLedger } from "../lifecycle/run-ledger";
@@ -514,8 +514,25 @@ export function readGreen(cwd: string): { green: CiGreen; top: string; workspace
   return { green, top, workspace: { name: declaration.name, root: located.root, file: declaration.file } };
 }
 
+/**
+ * `green` judging `branch` (#4325): `ci.green` names several branches when
+ * `ci.branches` routes members to branches of their own, and each is judged
+ * as the single branch always was. Without `branch` the first is judged.
+ * Refuses a branch `ci.green` does not name.
+ */
+export function greenOn(green: CiGreen, branch: string | undefined): CiGreen {
+  const { branches: _all, ...rest } = green;
+  if (branch === undefined || branch === green.branch) return rest;
+  if (!greenBranches(green).includes(branch)) {
+    throw new CiGreenError("ci-branch-unknown", `ci.green judges ${greenBranches(green).join(", ")}, not ${branch}; add it to ci.green.branch to give it a green verdict`);
+  }
+  return { ...rest, branch };
+}
+
 export interface TickRequest {
   cwd: string;
+  /** Judge this one branch of `ci.green.branch` (#4325). Without it a tick judges every branch the declaration names. */
+  branch?: string;
   /**
    * Where check runs come from. A function is called only when the source
    * is `checks`, so a tick from runs needs no forge token. Required for
@@ -547,6 +564,8 @@ export interface ComposedBranchTick {
 
 export interface TickResult {
   branch: string;
+  /** The other branches `ci.green` names (#4325), each judged as this one is. Their tags are in `made`. Absent for a one-branch declaration. */
+  routed?: TickResult[];
   window: string;
   /** The ref the commits were read from. */
   ref: string;
@@ -601,7 +620,16 @@ export function ciTagSigner(top: string, base: string, pem: string, what = "the
 export async function ciTick(req: TickRequest): Promise<TickResult> {
   const read = readGreen(req.cwd);
   const top = read.top;
-  const green: CiGreen = { ...read.green, source: req.source ?? read.green.source };
+  const names = greenBranches(read.green);
+  if (req.branch === undefined && names.length > 1) {
+    const first = await ciTick({ ...req, branch: names[0]! });
+    const routed: TickResult[] = [];
+    for (const b of names.slice(1)) routed.push(await ciTick({ ...req, branch: b }));
+    return { ...first, routed, made: [...first.made, ...routed.flatMap((r) => r.made)] };
+  }
+  const green: CiGreen = { ...greenOn(read.green, req.branch), source: req.source ?? read.green.source };
+  // Compose branches are walked from trunk, so only the first branch's tick walks them.
+  const walksCompose = green.branch === read.green.branch;
   const forge = green.source === "checks" ? (typeof req.forge === "function" ? req.forge() : req.forge) : undefined;
   if (green.source === "checks" && !forge) throw new Error("ci.green.source is checks, so the tick reads check runs and needs a forge");
   const remote = req.remote ?? "origin";
@@ -671,7 +699,7 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
   if (links) for (const c of planned) c.work = links.get(c.sha);
   // Compose branches (#4168 4.3): each composed commit within the window is judged as trunk's are, and its tags name its branch.
   const composed: ComposedBranchTick[] = [];
-  for (const b of remoteComposeBranches(top, remote)) {
+  for (const b of walksCompose ? remoteComposeBranches(top, remote) : []) {
     const own = git(top, ["log", "--first-parent", `--max-age=${cutoff}`, "--format=%H %ct", b.ref, `^${tracking}`])
       .split("\n")
       .filter(Boolean)
@@ -904,18 +932,20 @@ export interface RequestBuildResult {
  */
 export async function requestBuild(req: { cwd: string; at: string; remote?: string; forge?: CiForge; now?: Date }): Promise<RequestBuildResult> {
   const read = readGreen(req.cwd);
-  const { green, top } = read;
+  const { top } = read;
+  const green = greenOn(read.green, undefined);
+  const names = greenBranches(read.green);
   const remote = req.remote ?? "origin";
-  const tracking = `refs/remotes/${remote}/${green.branch}`;
+  const trackingOf = (b: string): string => `refs/remotes/${remote}/${b}`;
   try {
-    git(top, ["fetch", "--quiet", "--no-tags", remote, `+refs/heads/${green.branch}:${tracking}`, `+refs/tags/${CI_BUILD_TAG_PREFIX}*:refs/tags/${CI_BUILD_TAG_PREFIX}*`]);
+    git(top, ["fetch", "--quiet", "--no-tags", remote, ...names.map((b) => `+refs/heads/${b}:${trackingOf(b)}`), `+refs/tags/${CI_BUILD_TAG_PREFIX}*:refs/tags/${CI_BUILD_TAG_PREFIX}*`]);
   } catch (err) {
-    throw new Error(`could not fetch ${green.branch} and the build requests from ${remote}: ${stderrOf(err)}`);
+    throw new Error(`could not fetch ${names.join(", ")} and the build requests from ${remote}: ${stderrOf(err)}`);
   }
   if (req.at.startsWith("-") || tryGit(top, ["rev-parse", "--verify", "--quiet", `${req.at}^{commit}`]) === null) throw new WorkspaceReadError("revision-unknown", `--at ${req.at} names no commit in this repository`);
   const sha = git(top, ["rev-parse", `${req.at}^{commit}`]);
-  const onBranch = git(top, ["rev-list", "--first-parent", tracking]).split("\n").includes(sha);
-  if (!onBranch) throw new Error(`${sha.slice(0, 12)} is not a first-parent commit of ${remote}/${green.branch}, and only those are judged green`);
+  const onBranch = names.some((b) => tryGit(top, ["rev-list", "--first-parent", trackingOf(b)])?.split("\n").includes(sha));
+  if (!onBranch) throw new Error(`${sha.slice(0, 12)} is not a first-parent commit of ${names.map((b) => `${remote}/${b}`).join(" or ")}, and only those are judged green`);
   const existing = readBuildRequests(top).get(sha);
   const request = existing ?? requestedBuild(green, sha, green.require, req.now ?? new Date());
   const warnings: string[] = [];
@@ -1101,6 +1131,7 @@ export function whyWorkUnknown(work: CommitLink | null | undefined): string | un
 
 /** The text `chant ci tick` prints. */
 export function formatTick(r: TickResult, dryRun = false): string {
+  if (r.routed) return [formatTick({ ...r, routed: undefined }, dryRun), ...r.routed.map((b) => formatTick(b, dryRun))].join("\n");
   const lines = [`${r.branch}, commits within ${r.window}${r.source === "runs" ? ", judged from chant runs" : ""}: ${r.commits.length}`];
   for (const c of r.commits) {
     const short = c.sha.slice(0, 12);
@@ -1187,10 +1218,12 @@ export const LAST_GREEN_NEWER = 50;
  * green tag and no revoked tag. It reads local refs and tags and never
  * fetches, so a reader fetches first (`git fetch origin --tags`).
  */
-export function lastGreen(req: { cwd: string; remote?: string; from?: string }): LastGreenDocument {
+export function lastGreen(req: { cwd: string; remote?: string; from?: string; branch?: string }): LastGreenDocument {
   const head = { $schema: CI_LAST_GREEN_SCHEMA_ID, contract: CI_LAST_GREEN_CONTRACT_VERSION, chant: readerVersion() };
   try {
-    const { green, top, workspace } = readGreen(req.cwd);
+    const read = readGreen(req.cwd);
+    const { top, workspace } = read;
+    const green = greenOn(read.green, req.branch);
     const branchRef = branchRefOf(top, green, req.remote);
     let ref = branchRef;
     if (req.from !== undefined) {
@@ -1355,6 +1388,8 @@ function recordedPhase(green: CountedCiTag | undefined, phase: string): CiListPh
 
 export interface ListRequest {
   cwd: string;
+  /** List this branch of `ci.green.branch` (#4325). The first when absent. */
+  branch?: string;
   remote?: string;
   /** Keep only the newest n commits. */
   limit?: number;
@@ -1380,7 +1415,9 @@ export interface ListRequest {
 export async function ciList(req: ListRequest): Promise<CiListDocument> {
   const head = { $schema: CI_LIST_SCHEMA_ID, contract: CI_LIST_CONTRACT_VERSION, chant: readerVersion() };
   try {
-    const { green, top, workspace } = readGreen(req.cwd);
+    const read = readGreen(req.cwd);
+    const { top, workspace } = read;
+    const green = greenOn(read.green, req.branch);
     const ref = branchRefOf(top, green, req.remote);
 
     const logArgs = ["log", "--first-parent", "--format=%H %ct"];

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

@@ -17,7 +17,7 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { cleanScratch, declaration, git, repoFixture, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
 import { checkRunEventLines } from "./__fixtures__/run-event-check";
-import { ciJobCommand, ciJobEnv, ciJobFailure, ciJobOp, ciLoopOptions, ciRun, CiRunError, ciStatusContext, ciStatusFromEnv, ciStatusUrl, formatCiRun } from "./ci-run";
+import { chantNodeModules, ciJobCommand, ciJobEnv, ciJobFailure, ciJobOp, ciLoopOptions, ciRun, CiRunError, ciStatusContext, ciStatusFromEnv, ciStatusUrl, formatCiRun } from "./ci-run";
 import type { CommitStatus, ForgeStatus, PrForge } from "../pr-forge";
 import { FORGE_TOKEN_VARS } from "../ci-handover";
 import { ciList, ciTick, evaluateCommit, readOpRunSource, revokedAnnotation } from "./ci-green";
@@ -1040,6 +1040,77 @@ describe("the plan's steps hold no forge token (#4295)", () => {
   });
 });
 
+/** A scheduled watch Op's file, shaped as discovery reads one (entity.props = OpConfig), importing nothing. */
+const WATCH_OP = (name: string): string =>
+  `export default { props: { name: ${JSON.stringify(name)}, overview: "t", schedule: { cron: "0 * * * *" }, labels: { Watch: "true" }, phases: [{ name: "Run", steps: [] }] } };\n`;
+
+describe("chant ci run plan checks the scheduled Ops at --base for the note (#4328)", () => {
+  /**
+   * The base declares watch Op `drift`, with its generated workflow. The
+   * change deletes it and adds `sneaky`. The note names the Op the base has,
+   * since the check reads the Ops at --base, and never the change's own.
+   */
+  function stale(): { app: string; base: string; sha: string } {
+    const { root, app } = workspace();
+    writeFiles(root, {
+      "app/chant.config.json": "{}",
+      "app/ops/drift.op.ts": WATCH_OP("drift"),
+      ".forgejo/workflows/app-drift.yml": "on: schedule\n",
+    });
+    const base = commitAt(root, 1, "app/b.txt");
+    execFileSync("git", ["rm", "-q", "app/ops/drift.op.ts"], { cwd: root });
+    writeFiles(root, { "app/ops/sneaky.op.ts": WATCH_OP("sneaky"), ".forgejo/workflows/app-sneaky.yml": "on: schedule\n" });
+    const sha = commitAt(root, 0.5, "app/c.txt");
+    return { app, base, sha };
+  }
+
+  function overdueForge(): { forge: PrForge; notes: string[]; asked: string[] } {
+    const notes: string[] = [];
+    const asked: string[] = [];
+    const forge = {
+      kind: "forgejo",
+      host: "forgejo.localhost",
+      async setStatus() {},
+      async upsertNote(_pr: number, _marker: string, body: string) {
+        notes.push(body);
+        return "1";
+      },
+      // Every Op last ran a year ago: overdue whichever is asked about.
+      async scheduledRuns(q: { op: string }) {
+        asked.push(q.op);
+        return { last: "2025-10-01T00:00:00Z" };
+      },
+    } as unknown as PrForge;
+    return { forge, notes, asked };
+  }
+
+  test("on the runner, the note warns of the base's overdue Op and not of one the change added", async () => {
+    const { app, base, sha } = stale();
+    const forge = overdueForge();
+    const r = await ciRun({ image: JOB_IMAGE, cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), hostEnv: { ...HOST, FAKE_REPORT: planReport(sha) }, passEnv: ["FAKE_REPORT"], planForge: forge.forge, push: false, output: join(scratchDir("chant-ci-overdue-"), "pr") });
+    expect(r.status).toBe("ok");
+    expect(forge.asked).toEqual(["drift"]);
+    expect(forge.notes).toHaveLength(1);
+    expect(forge.notes[0]).toContain("Op `drift` is overdue");
+    expect(forge.notes[0]).not.toContain("sneaky");
+    expect(r.warnings).toEqual([expect.stringMatching(/Op `drift` is overdue/)]);
+  });
+
+  test("in place, the check still reads the base, not the checkout the change runs in", async () => {
+    const { app, base, sha } = stale();
+    const forge = overdueForge();
+    const r = await ciRun({ cwd: app, job: "plan", env: "prod", forge: "forgejo", base, pr: 7, chant: fakeChant(), hostEnv: { ...HOST, GITHUB_JOB: "plan", FAKE_REPORT: planReport(sha) }, inPlace: true, push: false, planForge: forge.forge });
+    expect(r.status).toBe("ok");
+    expect(forge.asked).toEqual(["drift"]);
+    expect(forge.notes[0]).toContain("Op `drift` is overdue");
+  });
+
+  test("the base checkout resolves packages from the node_modules the running chant is installed in", () => {
+    expect(chantNodeModules("/opt/ci/node_modules/@intentius/chant/dist/workspace/ci-run.js")).toBe("/opt/ci/node_modules");
+    expect(chantNodeModules("/src/chant/packages/core/src/workspace/ci-run.ts")).toBeUndefined();
+  });
+});
+
 /**
  * #4330: a pull request environment's jobs run through `ci run` too. The
  * stand-in chant keeps each action's arguments, environment, directory and