@intentius/chant 0.124.31 → 0.124.33

package/src/workspace/ci-last-green.schema.json

@@ -104,6 +104,55 @@
             }
           ]
         },
+        "newer": {
+          "type": "array",
+          "description": "Added within contract version 1 by #4169, written by chant 0.124.33 and newer. The first-parent commits walked past, newest first and above the one found, each with what its _ci/<sha>.json record on the local chant/lifecycle says (null when it has none), so a reader can say why the newest commits are not green. At most 50.",
+          "items": {
+            "type": "object",
+            "required": [
+              "sha",
+              "record"
+            ],
+            "properties": {
+              "sha": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{40,64}$"
+              },
+              "record": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "state"
+                    ],
+                    "properties": {
+                      "state": {
+                        "enum": [
+                          "green",
+                          "red",
+                          "unbuilt",
+                          "pending"
+                        ]
+                      },
+                      "reason": {
+                        "type": "string"
+                      },
+                      "coveredBy": {
+                        "type": "string"
+                      },
+                      "culprit": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
         "ignored": {
           "type": "array",
           "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The tags on the commits walked, newest first and down to the one found, that do not count for want of a valid statement. Empty when ci.green.signedSince is not set.",

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."
@@ -281,9 +284,10 @@
                         "pass",
                         "fail",
                         "pending",
+                        "unbuilt",
                         "unrecorded"
                       ],
-                      "description": "pass and fail come from the tags (a green tag records the phases that passed, a revoked tag the one that failed) or, for an undecided commit, from the forge under --forge, or from the signed Op runs on the local chant/lifecycle when the source is chant runs (#4044). pending is such a read with runs still going or not yet reported. unrecorded means no tag holds the result and nothing was read."
+                      "description": "pass and fail come from the tags (a green tag records the phases that passed, a revoked tag the one that failed) or, for an undecided commit, from the forge under --forge, or from the signed Op runs on the local chant/lifecycle when the source is chant runs (#4044). pending is such a read with runs still going or not yet reported. unbuilt (#4169, chant 0.124.33 and newer) is such a read whose runs were cancelled. unrecorded means no tag holds the result and nothing was read."
                     },
                     "runs": {
                       "type": "array",
@@ -334,8 +338,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."
@@ -400,6 +407,39 @@
                   }
                 ]
               },
+              "record": {
+                "description": "Added within contract version 1 by #4169, written by chant 0.124.33 and newer. What the commit's _ci/<sha>.json record on the local chant/lifecycle says, the tick's last word on it, or null when it has none. state is green, red, unbuilt or pending. reason, coveredBy and culprit come from the required phases: why a phase is unbuilt or still pending (cancelled, superseded, retrying, requested, request-unserved or aged-out), the newer commit whose run covers a superseded phase, and the commit a bisect found broke a phase. Each is absent when no phase has one.",
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "state"
+                    ],
+                    "properties": {
+                      "state": {
+                        "enum": [
+                          "green",
+                          "red",
+                          "unbuilt",
+                          "pending"
+                        ]
+                      },
+                      "reason": {
+                        "type": "string"
+                      },
+                      "coveredBy": {
+                        "type": "string"
+                      },
+                      "culprit": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                ]
+              },
               "ignored": {
                 "type": "array",
                 "description": "Added within contract version 1 by #4031, written by chant 0.124.28 and newer. The commit's ci tags that do not count for want of a valid statement signed by a runner key. A tag on any commit that is not a strict first-parent ancestor of ci.green.signedSince needs one; empty when signedSince is not set. state, green and revoked count only the tags that are not ignored.",
@@ -432,7 +472,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 +500,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));
+}

package/src/workspace/ci-run-index.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json",
   "title": "chant ci run index",
-  "description": "The runs the chant runner has run, kept at <report-url>/runs/index.json (#4098, epic #4101) so a reader outside CI finds them without a forge or a workflow file. `chant ci run` adds an entry to the front after each job settles when --report-url is set, so the list is newest first, and keeps the newest 200 entries unless --run-index-limit says otherwise. `chant ci runs --json` prints the same document. An entry's `key` is the folder the job's report is under, below the report URL. The update is a read, a change and a write of the whole file, through the same s3:// and file:// paths the report upload uses; a file:// write goes through a temporary name and a rename. Two runners updating one index at once can lose an entry. That is out of scope, because `chant ci serve` is one host. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version. Written by chant 0.124.31 and newer.",
+  "description": "The runs the chant runner has run, kept at <report-url>/runs/index.json (#4098, epic #4101) so a reader outside CI finds them without a forge or a workflow file. `chant ci run` adds an entry to the front after each job settles when --report-url is set, so the list is newest first, and keeps the newest 200 entries unless --run-index-limit says otherwise. `chant ci runs --json` prints the same document. An entry's `key` is the folder the job's report is under, below the report URL. The update is a read, a change and a write of the whole file, through the same s3:// and file:// paths the report upload uses; a file:// write goes through a temporary name and a rename. Two runners updating one index at once can lose an entry. That is out of scope, because `chant ci serve` is one host. Version 1 of the workspace read contract. Readers ignore fields they do not know; a field is only ever added within a version. Written by chant 0.124.31 and newer. Added within contract 1 at chant 0.124.32: an entry's signer (#4156) and exitCode (#4165); an entry from an older chant lacks them.",
   "type": "object",
   "required": ["$schema", "contract", "chant", "updated", "runs"],
   "properties": {
@@ -23,7 +23,7 @@
       "if": { "properties": { "status": { "const": "fail" } } },
       "then": { "required": ["failure"], "properties": { "failure": { "type": "object" } } },
       "properties": {
-        "job": { "enum": ["plan", "apply"] },
+        "job": { "enum": ["plan", "apply", "record"], "description": "record (#4168, chant 0.124.33 and newer): the merge record job." },
         "pr": { "type": ["integer", "null"], "minimum": 1, "description": "The pull or merge request number: the one the job's report names, else --pr. null when neither has one." },
         "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The full commit the job ran at." },
         "status": { "enum": ["ok", "fail"] },
@@ -38,11 +38,13 @@
         "ended": { "type": "string", "description": "ISO-8601 instant the job settled." },
         "runId": { "type": "string", "description": "The Op run id, as in the run ledger on chant/lifecycle." },
         "key": { "type": "string", "description": "reportKey(pr, commit): <pr>/<commit>, with /<member> after for a member, and unknown for a missing pr. The job's report is <report-url>/<key>/pr-<job>.json." },
+        "signer": { "type": ["string", "null"], "description": "Added within contract 1 by #4156, written by chant 0.124.32 and newer. The runner whose key signed the run's record, or null for an unsigned run. Signing is optional, and an unsigned run is listed like any other." },
+        "exitCode": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Added within contract 1 by #4165, written by chant 0.124.32 and newer. The code chant ci run exited with for the job: 0 for a passed job, else the command's own code when it is 1 to 255, such as 3 for a plan that moved after review or a wave waiting at its gate, else 1. A reader tells a held run from a failed one by it when the report carries no refusal. An entry from an older chant lacks it." },
         "runOrigin": {
           "type": "object",
           "required": ["forge"],
-          "description": "Where the run says it ran. { forge: \"chant\" } for a job the chant runner ran.",
-          "properties": { "forge": { "type": "string" } }
+          "description": "Where the run says it ran. { forge: \"chant\" } for a job the chant runner ran. From chant 0.124.32 a forge job that runs chant ci run names the forge's run (#4156): forge github (GitHub and Forgejo) or gitlab, with repo, url, jobId and attempt when the forge gives them.",
+          "properties": { "forge": { "type": "string" }, "repo": { "type": "string" }, "url": { "type": "string" }, "jobId": { "type": "string" }, "attempt": { "type": "integer", "minimum": 1 } }
         }
       }
     }

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

@@ -12,7 +12,7 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, contract, declaration, git, repoFixture, scratchDir, validSchema, writeFiles } from "./__fixtures__/contract-repo";
-import { ciRun } from "./ci-run";
+import { ciJobExitCode, ciRun } from "./ci-run";
 import { readCiSecrets } from "./ci-secrets";
 import {
   addRunEntry,
@@ -123,6 +123,13 @@ describe("the ci-run-index schema (#4098)", () => {
     expect(contract(schema).validate(doc)).toBe(false);
     expectValid({ ...doc, runs: [{ ...ENTRY, status: "fail", failure: { code: "command-failed" } }] });
   });
+
+  test("exitCode is an integer from 0 to 255, and an index whose older entries lack it validates (#4165)", () => {
+    const doc = { $schema: CI_RUN_INDEX_SCHEMA_ID, contract: 1, chant: "0.124.32", updated: "2026-10-18T12:00:00.000Z" };
+    // A newer entry beside two from chant 0.124.31, which wrote neither signer nor exitCode.
+    expectValid({ ...doc, runs: [{ ...ENTRY, runId: "r2", signer: null, exitCode: 0 }, { ...ENTRY, runId: "r1" }, { ...ENTRY, status: "fail", failure: { code: "command-failed" } }] });
+    for (const exitCode of [-1, 256, 1.5, "3"]) expect(contract(schema).validate({ ...doc, runs: [{ ...ENTRY, exitCode }] })).toBe(false);
+  });
 });
 
 describe("chant ci run with --report-url keeps the run index (#4098)", () => {
@@ -149,6 +156,10 @@ describe("chant ci run with --report-url keeps the run index (#4098)", () => {
       key: `7/${w.sha}/app`,
       member: "app",
       runOrigin: { forge: "chant" },
+      // #4156: no key, and the run is listed all the same, with no signer.
+      signer: null,
+      // #4165: the code ci run exited with.
+      exitCode: 0,
     });
     // The apply found its pull request in its own report.
     expect(index.runs[0]).toMatchObject({ job: "apply", pr: 7, key: `7/${w.sha}/app` });
@@ -179,7 +190,7 @@ describe("chant ci run with --report-url keeps the run index (#4098)", () => {
     const failed = await job(w, dir, { runId: "run-fail", hostEnv: { ...HOST, FAKE_EXIT: "3" }, passEnv: ["FAKE_EXIT"] });
     expect(failed.status).toBe("fail");
     const [run] = indexOf(dir).runs;
-    expect(run).toMatchObject({ status: "fail", failure: { code: "command-failed" }, runId: "run-fail" });
+    expect(run).toMatchObject({ status: "fail", failure: { code: "command-failed" }, runId: "run-fail", exitCode: 3 });
     expectValid(indexOf(dir));
 
     const refused = await job(w, dir, {
@@ -189,7 +200,35 @@ describe("chant ci run with --report-url keeps the run index (#4098)", () => {
       passEnv: ["FAKE_EXIT", "FAKE_REPORT"],
     });
     expect(refused.status).toBe("fail");
-    expect(indexOf(dir).runs[0]).toMatchObject({ failure: { code: "not-approved" } });
+    expect(indexOf(dir).runs[0]).toMatchObject({ failure: { code: "not-approved" }, exitCode: 1 });
+  });
+
+  test("each entry records the code ci run exited with: 0, 1, and 3 for a moved plan or a waiting wave (#4165)", async () => {
+    const w = workspace();
+    const dir = reportsDir();
+    const run = (runId: string, exit: string, report: object) =>
+      job(w, dir, { job: "apply", runId, hostEnv: { ...HOST, FAKE_EXIT: exit, FAKE_REPORT: JSON.stringify({ pr: 7, ...report }) }, passEnv: ["FAKE_EXIT", "FAKE_REPORT"] });
+    const passed = await run("run-ok", "0", { status: "applied" });
+    const failed = await run("run-failed", "1", { status: "failed" });
+    const moved = await run("run-moved", "3", { status: "refused", refusal: "plan-changed", message: "the plan changed after review" });
+    const waiting = await run("run-waiting", "3", { status: "waiting", waves: [{ wave: 2, status: "waiting" }] });
+    expect([passed, failed, moved, waiting].map((r) => ciJobExitCode(r))).toEqual([0, 1, 3, 3]);
+    const index = indexOf(dir);
+    expectValid(index);
+    expect(index.runs.map((r) => [r.runId, r.status, r.exitCode])).toEqual([
+      ["run-waiting", "fail", 3],
+      ["run-moved", "fail", 3],
+      ["run-failed", "fail", 1],
+      ["run-ok", "ok", 0],
+    ]);
+    expect(index.runs[1]!.failure).toEqual({ code: "plan-changed" });
+  });
+
+  test("a fail with no code from its command, or one outside 1 to 255, is 1, and a pass is 0 (#4165)", () => {
+    expect(ciJobExitCode({ status: "fail" })).toBe(1);
+    expect(ciJobExitCode({ status: "fail", exitCode: 0 })).toBe(1);
+    expect(ciJobExitCode({ status: "fail", exitCode: 300 })).toBe(1);
+    expect(ciJobExitCode({ status: "ok", exitCode: 3 })).toBe(0);
   });
 
   test("a secret the job's report names as its failure never reaches the index (#4096)", async () => {

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

@@ -29,6 +29,7 @@
 import type { RunOrigin } from "../lifecycle/release-ledger";
 import type { CommandContext } from "../cli/registry";
 import { formatError } from "../cli/format";
+import { reportUrlOf } from "./ci-report-url";
 import { parseReportUrl, reportGet, reportPut, type ReportGet, type ReportPut, type ReportTarget } from "../pr-report-url";
 import { readerVersion } from "./declaration";
 
@@ -43,7 +44,7 @@ export const CI_RUN_INDEX_LIMIT = 200;
 
 /** One job the runner ran. */
 export interface CiRunIndexEntry {
-  job: "plan" | "apply";
+  job: "plan" | "apply" | "record";
   /** The pull request, or null when the job found none. */
   pr: number | null;
   commit: string;
@@ -57,6 +58,18 @@ export interface CiRunIndexEntry {
   /** The folder the job's report is under, below the report URL: `<pr>/<commit>[/<member>]`. */
   key: string;
   runOrigin: RunOrigin;
+  /**
+   * The runner whose key signed the run's record, or null for an unsigned
+   * run (#4156). Written by chant 0.124.32 and newer; an entry from an older
+   * chant lacks it.
+   */
+  signer?: string | null;
+  /**
+   * The code `chant ci run` exited with for the job: 0, its command's own
+   * code such as 3 for a moved plan or a waiting wave, else 1 (#4165).
+   * Written by chant 0.124.32 and newer; an entry from an older chant lacks it.
+   */
+  exitCode?: number;
 }
 
 export interface CiRunIndex {
@@ -167,18 +180,19 @@ export function formatCiRunIndex(index: CiRunIndex): string {
     .map((r) => {
       const pr = r.pr === null ? "no PR" : `PR ${r.pr}`;
       const why = r.status === "fail" ? ` (${r.failure?.code ?? "failed"})` : "";
-      return `${r.ended}  ${r.job.padEnd(5)}  ${r.status}${why}  ${pr}  ${r.commit.slice(0, 12)}  ${r.runId}  ${r.key}`;
+      return `${r.ended}  ${r.job.padEnd(5)}  ${r.status}${why}  ${pr}  ${r.commit.slice(0, 12)}  ${r.runId}  ${r.key}${r.signer ? `  signed by ${r.signer}` : ""}`;
     })
     .join("\n");
 }
 
-const RUNS_USAGE = "chant ci runs --report-url <s3://<bucket>/<prefix> | file://<directory>> [--json]";
+const RUNS_USAGE = "chant ci runs [--report-url <s3://<bucket>/<prefix> | file://<directory>>] [--json]";
 
 /** `chant ci runs` (#4098): list the index at the report URL. */
 export async function runCiRuns(ctx: CommandContext): Promise<number> {
   try {
-    const raw = ctx.args.reportUrl;
-    if (!raw) throw new Error("--report-url names where the index is kept");
+    // #4160: without --report-url, the declaration's ci.reportUrl.
+    const raw = await reportUrlOf(ctx.args.reportUrl, process.cwd());
+    if (!raw) throw new Error("--report-url names where the index is kept, unless the workspace declares ci.reportUrl");
     const target = parseReportUrl(raw);
     if ("error" in target) throw new Error(target.error);
     const index = await readCiRunIndex(target);