@intentius/chant 0.124.31 → 0.124.32

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,8 +45,10 @@ 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 {

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.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();
   });
 

package/src/workspace/ci-green.ts

@@ -41,12 +41,16 @@
  * pipelines run as chant Ops, such as one on GitLab or Forgejo, gets green
  * and revoked tags with no forge check runs. A phase's patterns then match
  * Op names, a run counts for the commit its record names as `gitSha`, and
- * the latest run of each Op decides, by its end time. A run counts only when
- * its record carries a statement signed by a runner key whose principal
- * holds the `runner` role at base (`./trust/op-run-statement.ts`); the tick
- * ignores and reports any other, so it neither greens nor revokes a commit.
- * A tick from runs signs every tag it makes, and each run in the tag's
- * record names the Op run's id and carries its statement.
+ * the latest run of each Op decides, by its end time. Signing is opt-in
+ * (#4156): an unsigned run counts, with no signer, and a run whose statement
+ * a runner key holding the `runner` role at base signed counts with that
+ * signer (`./trust/op-run-statement.ts`). A run whose statement is there and
+ * does not verify is ignored and reported, so it neither greens nor revokes
+ * a commit. With `ci.green.signedSince`, an unsigned run counts only on a
+ * strict first-parent ancestor of that commit, as an unsigned tag does. A
+ * tick given a runner key signs the tags it makes, and each run in the
+ * tag's record names the Op run's id and carries its statement when it has
+ * one.
  */
 
 import { judgeCommits, mergeCommits, readWorkIndex, type CommitLink } from "./commit-links";
@@ -237,7 +241,7 @@ export function windowMs(window: string): number {
  */
 const runRecord = (r: RunVerdict) =>
   r.opRun
-    ? { name: r.name, id: null, conclusion: r.conclusion, url: r.url, opRun: { id: r.opRun.id, env: r.opRun.env, signer: r.opRun.signer, statement: r.opRun.statement } }
+    ? { name: r.name, id: null, conclusion: r.conclusion, url: r.url, opRun: { id: r.opRun.id, env: r.opRun.env, signer: r.opRun.signer, ...(r.opRun.statement ? { statement: r.opRun.statement } : {}) } }
     : { name: r.name, id: r.id, conclusion: r.conclusion, url: r.url };
 
 /** `source: "runs"` on a record made from chant runs (#4044); nothing for check runs, so their records read as before. */
@@ -443,6 +447,21 @@ export function readCiTags(top: string, green: CiGreen | null = null, base: stri
   return out;
 }
 
+/**
+ * Whether the workspace at `cwd` requires signed runs (#4156): its
+ * `ci.green.signedSince`, or null when it sets none, declares no
+ * `ci.green`, or has no declaration chant can read. Signing is opt-in, so
+ * only this makes `ci serve` refuse to start without a trusted runner key
+ * and `ci run` and `chant run` warn about a run they leave unsigned.
+ */
+export function signedRunsRequired(cwd: string): string | null {
+  try {
+    return readDeclaration(locateWorkspace(cwd).tree).ci?.green?.signedSince ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /** The declaration's `ci.green`, read where `cwd` is, and the git top. */
 function readGreen(cwd: string): { green: CiGreen; top: string; workspace: { name: string; root: string; file: string } } {
   const located = locateWorkspace(cwd);
@@ -553,9 +572,6 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
       `ci.green.signedSince is ${green.signedSince}, so every tag the tick makes needs a statement signed by a runner key, and none was given: pass --key <runner key.pem> or set CHANT_RUNNER_KEY`,
     );
   }
-  if (green.source === "runs" && req.runnerKey === undefined && !req.dryRun) {
-    throw new Error("the tick reads chant runs (source runs), and every tag it makes from them is signed by a runner key, and none was given: pass --key <runner key.pem> or set CHANT_RUNNER_KEY");
-  }
   const signer = req.runnerKey !== undefined ? ciTagSigner(top, base, req.runnerKey) : undefined;
   const links = await commitLinks(req.cwd, top, tracking, commits.map((c) => c.sha));
   const tags = readCiTags(top, green, base);
@@ -566,7 +582,7 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
     if (fetched.status === "diverged" || fetched.status === "unreachable") {
       throw new Error(`could not fetch chant/lifecycle, where the Op runs are recorded, from ${fetched.remote}: ${fetched.status === "diverged" ? "the local branch and the remote's have diverged" : fetched.stderr}`);
     }
-    runs = await readOpRunSource(req.cwd, top, base);
+    runs = await readOpRunSource(req.cwd, top, base, green.signedSince);
   }
   const planned = await planTick({
     green,
@@ -605,7 +621,7 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
 
 /** The Op runs on the ledger, judged, as check runs by commit. */
 export interface OpRunSource {
-  /** The signed runs on `sha`, each as a check run named for its Op. */
+  /** The runs on `sha` that count, each as a check run named for its Op. */
   checkRuns(sha: string): CheckRun[];
   /** The runs on each commit that do not count, by commit. */
   ignored: Map<string, IgnoredOpRun[]>;
@@ -619,7 +635,7 @@ const RUN_LEDGER_FILE = /^runs__(.+)\.jsonl$/;
  * going. The id is the run's end time in milliseconds, so the latest run of
  * an Op is its latest attempt.
  */
-export function opRunCheckRun(record: OpRunRecord, signer: string): CheckRun {
+export function opRunCheckRun(record: OpRunRecord, signer: string | null): CheckRun {
   const settled = record.status === "ok" || record.status === "fail";
   const ended = Date.parse(record.ended);
   return {
@@ -629,7 +645,7 @@ export function opRunCheckRun(record: OpRunRecord, signer: string): CheckRun {
     conclusion: settled ? (record.status === "ok" ? "success" : "failure") : null,
     completedAt: settled ? record.ended : null,
     url: record.runOrigin?.url ?? null,
-    opRun: { id: record.id, env: record.env, signer, statement: record.statement! },
+    opRun: { id: record.id, env: record.env, signer, ...(signer !== null && record.statement ? { statement: record.statement } : {}) },
     ...(record.status === "fail" && record.failure ? { failureCode: record.failure.code } : {}),
   };
 }
@@ -637,11 +653,16 @@ export function opRunCheckRun(record: OpRunRecord, signer: string): CheckRun {
 /**
  * Judge every Op run record that names a commit against `.chant/trust.json`
  * at `base` (#4044), from the run ledger the project at `cwd` writes to. A
- * record with a valid statement becomes a check run on its `gitSha`; any
- * other is kept as an ignored run. Reads local refs only.
+ * record with a valid statement becomes a check run on its `gitSha` with
+ * its signer, and an unsigned one becomes a check run with signer null
+ * (#4156). A record whose statement does not verify is kept as an ignored
+ * run. With `signedSince` (`ci.green.signedSince`) an unsigned record counts
+ * only on a strict first-parent ancestor of that commit, and is ignored
+ * elsewhere. Reads local refs only.
  */
-export async function readOpRunSource(cwd: string, top: string, base: string): Promise<OpRunSource> {
+export async function readOpRunSource(cwd: string, top: string, base: string, signedSince: string | null = null): Promise<OpRunSource> {
   const policy = readTrustPolicy(gitRevisionSource(top, base), base);
+  const before = signedSince ? unsignedHistory(top, signedSince) : null;
   const byCommit = new Map<string, CheckRun[]>();
   const ignored = new Map<string, IgnoredOpRun[]>();
   for (const env of await listLedgerTrees({ cwd })) {
@@ -651,9 +672,15 @@ export async function readOpRunSource(cwd: string, top: string, base: string): P
       const { records } = await readRunLedger(env, op, { cwd });
       for (const record of records) {
         if (!record.gitSha) continue;
+        // #4161: a job `ci run --local` ran stays on the machine that ran it, and is never CI's verdict.
+        if (record.runOrigin?.forge === "local") continue;
         const v = verifyOpRunStatement(record, policy.runners, policy.roles);
-        if (v.status === "signed") byCommit.set(record.gitSha, [...(byCommit.get(record.gitSha) ?? []), opRunCheckRun(record, v.signer)]);
-        else ignored.set(record.gitSha, [...(ignored.get(record.gitSha) ?? []), { run: record.id, op: record.op, env: record.env, status: v.status, reason: v.reason }]);
+        const counts = v.status === "signed" || (v.status === "unsigned" && (before === null || before.has(record.gitSha)));
+        if (counts) byCommit.set(record.gitSha, [...(byCommit.get(record.gitSha) ?? []), opRunCheckRun(record, v.status === "signed" ? v.signer : null)]);
+        else {
+          const reason = v.status === "unsigned" ? `${v.reason}; ci.green.signedSince is ${signedSince}, so a run on a commit that is not a strict first-parent ancestor of it needs one` : v.reason;
+          ignored.set(record.gitSha, [...(ignored.get(record.gitSha) ?? []), { run: record.id, op: record.op, env: record.env, status: v.status, reason }]);
+        }
       }
     }
   }
@@ -836,7 +863,7 @@ export interface CiListRun {
   conclusion: string | null;
   url: string | null;
   /** The Op run, when the run is a chant run (#4044): its id, env and the runner whose statement it carries. Absent for a check run. */
-  opRun?: { id: string; env: string; signer: string };
+  opRun?: { id: string; env: string; signer: string | null };
 }
 
 export interface CiListPhase {
@@ -895,7 +922,8 @@ const asRun = (r: unknown): CiListRun | null => {
   const o = r as Record<string, unknown>;
   if (typeof o.name !== "string") return null;
   const op = o.opRun as Record<string, unknown> | undefined;
-  const opRun = op && typeof op === "object" && typeof op.id === "string" && typeof op.env === "string" && typeof op.signer === "string" ? { opRun: { id: op.id, env: op.env, signer: op.signer } } : {};
+  const signer = op && typeof op === "object" ? (typeof op.signer === "string" ? op.signer : op.signer === null ? null : undefined) : undefined;
+  const opRun = op && typeof op === "object" && typeof op.id === "string" && typeof op.env === "string" && signer !== undefined ? { opRun: { id: op.id, env: op.env, signer } } : {};
   return { name: o.name, id: typeof o.id === "number" ? o.id : null, conclusion: typeof o.conclusion === "string" ? o.conclusion : null, url: typeof o.url === "string" ? o.url : null, ...opRun };
 };
 
@@ -973,7 +1001,7 @@ export async function ciList(req: ListRequest): Promise<CiListDocument> {
     const tags = readCiTags(top, green, base);
     const source = req.source ?? green.source;
     if (source === "runs" && req.forge) throw new Error("--forge reads check runs, and the source is chant runs (ci.green.source or --source runs); drop one");
-    const runs = source === "runs" ? await readOpRunSource(req.cwd, top, base) : undefined;
+    const runs = source === "runs" ? await readOpRunSource(req.cwd, top, base, green.signedSince) : undefined;
     const out: CiListCommit[] = [];
     for (const c of commits) {
       const g = tags.green.get(c.sha);

package/src/workspace/ci-list.schema.json

@@ -240,8 +240,11 @@
                                     "description": "The env the run is recorded under."
                                   },
                                   "signer": {
-                                    "type": "string",
-                                    "description": "The runner principal whose statement the run carries."
+                                    "type": [
+                                      "string",
+                                      "null"
+                                    ],
+                                    "description": "The runner principal whose statement the run carries. null for an unsigned run, which counts unless ci.green.signedSince asks for a statement (#4156, chant 0.124.32 and newer)."
                                   }
                                 },
                                 "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the run is a chant Op run (ci.green.source runs): name is then the Op's name and id is null. Absent for a check run."
@@ -334,8 +337,11 @@
                                 "description": "The env the run is recorded under."
                               },
                               "signer": {
-                                "type": "string",
-                                "description": "The runner principal whose statement the run carries."
+                                "type": [
+                                  "string",
+                                  "null"
+                                ],
+                                "description": "The runner principal whose statement the run carries. null for an unsigned run, which counts unless ci.green.signedSince asks for a statement (#4156, chant 0.124.32 and newer)."
                               }
                             },
                             "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the run is a chant Op run (ci.green.source runs): name is then the Op's name and id is null. Absent for a check run."
@@ -432,7 +438,7 @@
               },
               "ignoredRuns": {
                 "type": "array",
-                "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the source is chant runs (ci.green.source or --source runs): the Op runs on the commit that do not count for want of a valid statement signed by a runner key whose principal holds the runner role. They neither green nor revoke the commit.",
+                "description": "Added within contract version 1 by #4044, written by chant 0.124.28 and newer. Present only when the source is chant runs (ci.green.source or --source runs): the Op runs on the commit that do not count: a statement that does not verify (invalid, untrusted or mismatch), or, under ci.green.signedSince, no statement on a commit that needs one (#4156). They neither green nor revoke the commit.",
                 "items": {
                   "type": "object",
                   "required": [
@@ -460,7 +466,7 @@
                         "untrusted",
                         "mismatch"
                       ],
-                      "description": "unsigned: the record carries no statement. invalid: the statement is not an op-run statement, or names another signer than the key's. untrusted: no runner key .chant/trust.json lists at base signed it, or its principal holds no runner role. mismatch: it signs another run, commit or record than the ledger holds."
+                      "description": "unsigned: the record carries no statement, on a commit ci.green.signedSince asks one for (#4156: without signedSince an unsigned run counts). invalid: the statement is not an op-run statement, or names another signer than the key's. untrusted: no runner key .chant/trust.json lists at base signed it, or its principal holds no runner role. mismatch: it signs another run, commit or record than the ledger holds."
                     },
                     "reason": {
                       "type": "string"

package/src/workspace/ci-report-url.test.ts

@@ -0,0 +1,220 @@
+/**
+ * #4160: the report URL a workspace declares as `ci.reportUrl`. `chant ci
+ * run`, `ci serve` and `ci runs` use it when `--report-url` is not given, the
+ * flag wins, and `chant workspace ls --json` carries it for readers.
+ *
+ * The jobs are real `ci run` jobs in a temp repository with a stub chant and
+ * file:// report URLs in other temp directories. Nothing is pushed and no
+ * test makes a network call: `ci serve` is stopped by its first poll, which
+ * has no forge to reach.
+ */
+
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import { cleanScratch, contract, declaration, git, repoFixture, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
+import { parseArgs } from "../cli/parse-args";
+import type { CommandContext } from "../cli/registry";
+import { declaredReportUrl, reportUrlOf } from "./ci-report-url";
+import { runCiRun } from "./ci-run";
+import { runCiServe } from "./ci-serve";
+import { CI_RUN_INDEX_KEY, runCiRuns, type CiRunIndex } from "./ci-run-index";
+import { listWorkspace, type LsDocument } from "./ls";
+import lsSchema from "./ls.schema.json";
+
+const home = process.cwd();
+afterEach(() => {
+  process.chdir(home);
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  cleanScratch();
+});
+
+const MEMBERS = [{ name: "app", dir: "app", kind: "other", because: "the app" }];
+const urlOf = (dir: string) => pathToFileURL(dir).href;
+const reportsDir = () => scratchDir("chant-report-url-reports-");
+const indexOf = (dir: string): CiRunIndex => JSON.parse(readFileSync(join(dir, CI_RUN_INDEX_KEY), "utf-8"));
+
+/** One member and two commits. The declaration in the working tree is rewritten per test. */
+const repoTemplate = repoFixture(() => {
+  const root = scratchDir("chant-report-url-template-");
+  git(root, "init", "-q");
+  git(root, "symbolic-ref", "HEAD", "refs/heads/main");
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  writeFiles(root, { "chant.workspace.json": declaration(MEMBERS), ".gitignore": ".chant/pr/\n", "app/a.txt": "a\n" });
+  const commit = (msg: string) => {
+    execFileSync("git", ["-c", "commit.gpgsign=false", "add", "-A"], { cwd: root, stdio: "ignore" });
+    execFileSync("git", ["-c", "commit.gpgsign=false", "commit", "-q", "-m", msg], { cwd: root, stdio: "ignore" });
+  };
+  commit("init");
+  writeFiles(root, { "app/a.txt": "b\n" });
+  commit("change");
+  return root;
+}, "chant-report-url-");
+
+/** A copy of the repository whose declaration sets `ci` as given, and a stub chant that writes an empty report. */
+function workspace(ci?: Record<string, unknown>): { root: string; app: string; base: string; chant: string } {
+  const root = repoTemplate();
+  writeFiles(root, { "chant.workspace.json": declaration(MEMBERS, ci ? { ci } : {}) });
+  const chant = join(scratchDir("chant-report-url-bin-"), "chant");
+  writeFileSync(chant, ["#!/bin/sh", "mkdir -p .chant/pr", 'echo "{}" > ".chant/pr/$2.json"', "exit 0", ""].join("\n"));
+  chmodSync(chant, 0o755);
+  return { root, app: join(root, "app"), base: git(root, "rev-parse", "HEAD~1"), chant };
+}
+
+/** Run a ci command line in `cwd`, with what it printed. */
+async function cli(cwd: string, argv: string[], run: (ctx: CommandContext) => Promise<number>) {
+  process.chdir(cwd);
+  const out: string[] = [];
+  const err: string[] = [];
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(String(s)));
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(String(s)));
+  vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+  const code = await run({ args: parseArgs(argv) } as unknown as CommandContext);
+  return { code, out: out.join("\n"), err: err.join("\n") };
+}
+
+const runPlan = (w: ReturnType<typeof workspace>, extra: string[] = []) =>
+  cli(
+    w.app,
+    ["ci", "run", "plan", "--env", "prod", "--base", w.base, "--pr", "7", "--forge", "forgejo", "--no-status", "--chant", w.chant, "-o", join(scratchDir("chant-report-url-out-"), "pr"), ...extra],
+    runCiRun,
+  );
+
+describe("reportUrlOf", () => {
+  test("the flag wins, else the declared URL, else none", async () => {
+    const w = workspace({ reportUrl: "s3://acme-reports/prod/" });
+    expect(await declaredReportUrl(w.app)).toBe("s3://acme-reports/prod");
+    expect(await reportUrlOf(undefined, w.root)).toBe("s3://acme-reports/prod");
+    expect(await reportUrlOf("file:///elsewhere", w.app)).toBe("file:///elsewhere");
+    expect(await reportUrlOf(undefined, workspace().app)).toBeUndefined();
+  });
+
+  test("a directory outside any workspace reads nothing", async () => {
+    expect(await reportUrlOf(undefined, scratchDir("chant-report-url-plain-"))).toBeUndefined();
+  });
+
+  test("a declared URL no job can upload to fails with its place and reason code, unless the flag is given", async () => {
+    const w = workspace({ reportUrl: "https://reports.example/acme" });
+    await expect(declaredReportUrl(w.app)).rejects.toThrow(/chant\.workspace\.json:\d+:\d+: ci\.reportUrl https:\/\/reports\.example\/acme: takes an s3:\/\/<bucket>\/<prefix> or file:\/\/<directory> URL \[declaration-invalid\]/);
+    expect(await reportUrlOf("file:///elsewhere", w.app)).toBe("file:///elsewhere");
+  });
+});
+
+describe("chant workspace ls --json carries ci.reportUrl", () => {
+  const { expectValid } = contract(lsSchema);
+  const ciOf = (doc: LsDocument) => {
+    if ("error" in doc) throw new Error(doc.error.message);
+    return doc.ci;
+  };
+
+  test("present when declared, and the document validates", () => {
+    const doc = listWorkspace({ cwd: workspace({ reportUrl: "s3://acme-reports/prod" }).root });
+    expectValid(doc);
+    expect(ciOf(doc)).toEqual({ green: null, reportUrl: "s3://acme-reports/prod" });
+  });
+
+  test("absent when the ci block sets none, and ci stays null with no ci block", () => {
+    const green = { branch: "main", phases: { build: ["build"] }, require: ["build"] };
+    const withGreen = listWorkspace({ cwd: workspace({ green }).root });
+    expectValid(withGreen);
+    expect(ciOf(withGreen)).not.toHaveProperty("reportUrl");
+    expect(ciOf(listWorkspace({ cwd: workspace().root }))).toBeNull();
+  });
+
+  test("an invalid one is the declaration-invalid failure", () => {
+    const doc = listWorkspace({ cwd: workspace({ reportUrl: "ftp://x/y" }).root });
+    expectValid(doc);
+    expect(doc).toMatchObject({ error: { code: "declaration-invalid", location: { file: "chant.workspace.json" } } });
+  });
+});
+
+describe("chant ci run", () => {
+  // The two whole jobs run once, in beforeAll, and the tests below read what
+  // they left, as ci-run.test.ts does (#4115, #4124). The first job of a file
+  // pays for loading the job's modules, which on a loaded CI shard came to
+  // over the unit budget (#2817); a file's beforeAll is not counted in it.
+  const ran: Record<"declared" | "flag", { code: number; err: string; declared: CiRunIndex | null; flag: CiRunIndex | null }> = {} as never;
+  beforeAll(async () => {
+    const read = (dir: string) => (existsSync(join(dir, CI_RUN_INDEX_KEY)) ? indexOf(dir) : null);
+    for (const kind of ["declared", "flag"] as const) {
+      const declared = reportsDir();
+      const flag = reportsDir();
+      const w = workspace({ reportUrl: urlOf(declared) });
+      const r = await runPlan(w, kind === "flag" ? ["--report-url", urlOf(flag)] : []);
+      ran[kind] = { code: r.code, err: r.err, declared: read(declared), flag: read(flag) };
+      process.chdir(home);
+      vi.restoreAllMocks();
+    }
+  }, 60_000);
+
+  test("without --report-url the job's run index goes to the declared URL", () => {
+    const r = ran.declared;
+    expect(r.code, r.err).toBe(0);
+    expect(r.declared?.runs).toHaveLength(1);
+    expect(r.declared?.runs[0]).toMatchObject({ job: "plan", pr: 7 });
+  });
+
+  test("--report-url wins over the declared URL", () => {
+    const r = ran.flag;
+    expect(r.code, r.err).toBe(0);
+    expect(r.flag?.runs).toHaveLength(1);
+    expect(r.declared).toBeNull();
+  });
+
+  test("an invalid declared URL stops the job before it runs", async () => {
+    const w = workspace({ reportUrl: "https://reports.example/acme" });
+    const r = await runPlan(w);
+    expect(r.code).toBe(1);
+    expect(r.err).toMatch(/\[declaration-invalid\]/);
+  });
+});
+
+describe("chant ci runs", () => {
+  test("lists the index at the declared URL, and --report-url wins", async () => {
+    const declared = reportsDir();
+    const w = workspace({ reportUrl: urlOf(declared) });
+    expect((await runPlan(w)).code).toBe(0);
+
+    const listed = await cli(w.app, ["ci", "runs", "--json"], runCiRuns);
+    expect(listed.code, listed.err).toBe(0);
+    expect((JSON.parse(listed.out) as CiRunIndex).runs).toHaveLength(1);
+
+    const other = reportsDir();
+    const flagged = await cli(w.app, ["ci", "runs", "--report-url", urlOf(other)], runCiRuns);
+    expect(flagged.code).toBe(1);
+    expect(flagged.err).toContain(`there is no run index at ${urlOf(other)}`);
+  });
+
+  test("with neither a flag nor a declared URL it says how to name one", async () => {
+    const r = await cli(workspace().root, ["ci", "runs"], runCiRuns);
+    expect(r.code).toBe(1);
+    expect(r.err).toContain("--report-url names where the index is kept, unless the workspace declares ci.reportUrl");
+  });
+});
+
+describe("chant ci serve", () => {
+  // No token and no server: the first poll fails, so the serve stops without reaching a forge.
+  beforeEach(() => {
+    for (const name of ["CHANT_FORGE_TOKEN", "GITHUB_TOKEN", "GH_TOKEN", "GITHUB_SERVER_URL", "CHANT_RUNNER_KEY"]) vi.stubEnv(name, undefined);
+  });
+  const SERVE = ["ci", "serve", "--forge", "forgejo", "--repo", "demo/estate", "--env", "local", "--once", "--unsigned", "--image", "node:22-bookworm"];
+
+  test("says it uses the declared URL when --report-url is not given", async () => {
+    const declared = reportsDir();
+    const w = workspace({ reportUrl: urlOf(declared) });
+    const state = join(scratchDir("chant-report-url-state-"), "ci-serve");
+    const r = await cli(w.root, [...SERVE, "--state", state], runCiServe);
+    expect(r.err).toContain(`ci serve: reports and the run index go to ${urlOf(declared)}, the declaration's ci.reportUrl`);
+  });
+
+  test("says nothing of the declaration when --report-url is given", async () => {
+    const w = workspace({ reportUrl: urlOf(reportsDir()) });
+    const state = join(scratchDir("chant-report-url-state-"), "ci-serve");
+    const r = await cli(w.root, [...SERVE, "--state", state, "--report-url", urlOf(reportsDir())], runCiServe);
+    expect(r.err).not.toContain("ci.reportUrl");
+  });
+});

package/src/workspace/ci-report-url.ts

@@ -0,0 +1,33 @@
+/**
+ * The report URL a command uses (#4160): `--report-url` when it is given,
+ * else the workspace declaration's `ci.reportUrl`, else none.
+ *
+ * `chant build --pr-loop`, `chant ci run`, `chant ci serve` and `chant ci
+ * runs` call this. The declaration is read from the working tree of the
+ * workspace that holds `cwd`. A directory with no declaration between it and
+ * the git root reads nothing and loads no declaration module, so a project
+ * outside a workspace behaves as before. A declaration that can't be read
+ * is an error naming its place and its reason code, such as
+ * `declaration-invalid`, since the command would otherwise run without the
+ * URL the workspace may declare.
+ */
+
+import { findWorkspaceRoot } from "../project-root";
+
+/** The declared `ci.reportUrl` of the workspace holding `cwd`, or undefined. */
+export async function declaredReportUrl(cwd: string): Promise<string | undefined> {
+  const found = findWorkspaceRoot(cwd);
+  if (!found) return undefined;
+  const [{ readDeclaration, WorkspaceReadError }, { workingTree }] = await Promise.all([import("./declaration"), import("./tree")]);
+  try {
+    return readDeclaration(workingTree(found.dir)).ci?.reportUrl ?? undefined;
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    throw Object.assign(new Error(`${err.describe()} [${err.code}]`), { code: err.code });
+  }
+}
+
+/** `flag` when given, else the declared `ci.reportUrl` (#4160). */
+export async function reportUrlOf(flag: string | undefined, cwd: string): Promise<string | undefined> {
+  return flag ?? (await declaredReportUrl(cwd));
+}