@intentius/chant 0.124.30 → 0.124.31

package/src/cli/main.ts

@@ -254,7 +254,9 @@ CI:
               [--events-json] [--report-url <url>] [--image <image>]
               [--before-script <line>]... [--pr-build]
               [--pr-build-command <line>] [--chant <command>]
-              [--pass-env <NAME>]... [--key <runner key.pem>] [-o <dir>]
+              [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>]
+              [-o <dir>]
+              [--no-status] [--status-url <url template>]
                         Run the pull-request pipeline's plan or apply job as
                         a pipeline Op in a fresh worktree of --commit (default
                         HEAD) with a clean environment. --base and --pr stand
@@ -262,10 +264,23 @@ CI:
                         the job's build and lint lines first. Records the run as
                         pr-plan or pr-apply on chant/lifecycle, signed with
                         --key or CHANT_RUNNER_KEY, so ci tick from runs counts
-                        it, and copies the report to -o (default .chant/pr).
+                        it, and copies the report to -o (default .chant/pr). With a forge
+                        token it sets a chant/pr-plan or chant/pr-apply commit
+                        status (pending, then success or failure); --no-status
+                        turns that off, and --status-url links it.
+                        --secrets (or CHANT_CI_SECRETS) names a dotenv or
+                        JSON file only its owner can read whose values the
+                        job gets, and which are shown as *** in the events,
+                        the record, the report and the output.
+                        With --report-url it also adds the run to
+                        <url>/runs/index.json, newest first, cut to the
+                        newest --run-index-limit entries (default 200).
+  ci runs --report-url <url> [--json]
+                        List the runs in the index at the report URL, newest
+                        first.
   ci serve --forge forgejo|github --repo <owner/repo> --env <env>
               [--interval <s>] [--max-jobs <n>] [--state <dir>]
-              [--author <login>]... [--once] [--rerun-failed]
+              [--author <login>]... [--once] [--rerun-failed] [--unsigned]
               [ci run's job flags]
                         Poll the forge for open pull requests and the target
                         branch's head, and run ci run plan for each new pull
@@ -275,7 +290,15 @@ CI:
                         each apply's resume record there, and runs at most
                         --max-jobs (default 1) jobs at once. --once runs one
                         poll and waits for its jobs. --rerun-failed runs a
-                        failed apply or plan again.
+                        failed apply or plan again. Refuses to start when its
+                        runner key is not listed in .chant/trust.json at the
+                        target's head, unless --unsigned
+  ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]
+                        Make the host's runner key (Ed25519, mode 0600) in the
+                        state directory when there is none and print its public
+                        key. --trust commits its runner entry on a branch of its
+                        own and pushes it for review; the target branch is never
+                        written
   ci workflow [--workflow <name>]... [--output <file>]  Write
               [--chant <command>] [--install <command>]
               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
@@ -701,6 +724,13 @@ Workspace (level 1, #2524):
                         threshold of the old one. A commit an agent run made
                         is attested by the run's signed statement; with
                         attested-runs, only those commits must be
+  workspace trust runner add <principal> --key <ssh-ed25519 line or file> [--class runner|service] [--by <principal>] [--expect <digest>] [--dry-run]
+  workspace trust runner remove <principal> [--by <principal>] [--expect <digest>] [--dry-run]
+                        List a runner's key under runners in .chant/trust.json,
+                        granting a runner the runner role, or take both away,
+                        editing the file in place. --expect refuses the write
+                        when the file's digest has changed. Prints the
+                        trust-write document and the new digest; never commits
   workspace signers [--json] [rotate [--threshold <n>] | sign --key <file>]
                         Show the signer history at base, or propose the next
                         signer set and sign it with a current signer's key
@@ -1335,6 +1365,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiWorkflow(ctx) },
   // #4094: one pull-request job as a pipeline Op in a fresh checkout, the chant runner's first slice.
   { name: "ci run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run")).runCiRun(ctx) },
+  // #4098: the run index at the report URL.
+  { name: "ci runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run-index")).runCiRuns(ctx) },
   { name: "ci serve", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-serve")).runCiServe(ctx) },
   // #4026: the release cut from a green commit (ws-104). Imported on first use.
   { name: "release cut", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCut(ctx) },
@@ -1439,6 +1471,8 @@ export const commandRegistry: CommandDef[] = [
   // #2548 — an agent session's member, write scope and spec, for a session that resumes.
   { name: "workspace agent", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/agent-cli")).runWorkspaceAgent(ctx) },
   { name: "workspace verify", handler: async (ctx) => (await import("../workspace/trust/verify-cli")).runWorkspaceVerify(ctx) },
+  // #3510 — a runner entry of .chant/trust.json, written through chant so a box repo never edits it by hand (ws-074).
+  { name: "workspace trust", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/trust/trust-write")).runWorkspaceTrust(ctx) },
   { name: "workspace signers", handler: async (ctx) => (await import("../workspace/trust/signers-cli")).runWorkspaceSigners(ctx) },
   { name: "workspace evidence", handler: async (ctx) => (await import("../workspace/trust/evidence-cli")).runWorkspaceEvidence(ctx) },
 

package/src/cli/parse-args.ts

@@ -66,6 +66,9 @@ const BOOLEAN_FLAGS = new Set([
   "--confirm-prod",
   "--once",
   "--rerun-failed",
+  "--setup-key",
+  "--trust",
+  "--unsigned",
   "--expire",
   "--check-live",
   "--check-snapshot",
@@ -388,6 +391,13 @@ export function parseArgs(args: string[]): ParsedArgs {
       const url = args[++i];
       if (!url || url.startsWith("-")) throw new Error("--report-url needs a URL: --report-url s3://<bucket>/<prefix> or file://<directory>");
       result.reportUrl = url;
+    } else if (arg === "--no-status") {
+      // `chant ci run|serve --no-status` (#4097): post no commit status for the job.
+      result.noStatus = true;
+    } else if (arg === "--status-url") {
+      // `chant ci run|serve --status-url <template>` (#4097): the link a job's status carries, in place of an https --report-url.
+      result.statusUrl = args[++i];
+      if (!result.statusUrl || result.statusUrl.startsWith("-")) throw new Error("--status-url needs a URL template: --status-url https://host/reports/{key}");
     } else if (arg === "--allow-unsigned") {
       // `chant release publish --allow-unsigned` (#4049).
       result.allowUnsigned = true;
@@ -536,10 +546,19 @@ export function parseArgs(args: string[]): ParsedArgs {
       const name = args[++i];
       if (!name || name.startsWith("-")) throw new Error("--pass-env needs a variable's name, such as AWS_PROFILE: --pass-env <NAME>");
       (result.passEnv ??= []).push(name);
+    } else if (arg === "--secrets") {
+      // `chant ci run|serve --secrets <file>` (#4096): the host's secrets file, readable only by its owner.
+      result.ciSecrets = args[++i];
+      if (!result.ciSecrets || result.ciSecrets.startsWith("-")) throw new Error("--secrets needs the host's secrets file, a dotenv or JSON file only its owner can read: --secrets <file>");
     } else if (arg === "--repo") {
       // `chant ci serve --repo <owner/repo>` (#4095): the repository whose pull requests and target branch it polls.
       result.ciRepo = args[++i];
       if (!result.ciRepo || !/^[^/\s-][^/\s]*\/[^/\s]+$/.test(result.ciRepo)) throw new Error("--repo needs the repository as owner/name: --repo <owner/repo>");
+    } else if (arg === "--run-index-limit") {
+      // `chant ci run --run-index-limit <n>` (#4098): how many runs the index at the report URL keeps.
+      const n = Number(args[++i]);
+      if (!Number.isInteger(n) || n < 1) throw new Error("--run-index-limit needs a whole number of runs, 1 or more: --run-index-limit <n>");
+      result.runIndexLimit = n;
     } else if (arg === "--max-jobs") {
       // `chant ci serve --max-jobs <n>` (#4095): how many jobs run at once.
       const n = Number(args[++i]);
@@ -576,6 +595,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
       if (!result.verdict || result.verdict.startsWith("-")) throw new Error("--verdict needs agree, dissent or abstain");
+    } else if (arg === "--class") {
+      // `chant workspace trust runner add <principal> --class runner|service` (#3510).
+      result.runnerClass = args[++i];
+      if (!result.runnerClass || result.runnerClass.startsWith("-")) throw new Error("--class needs runner or service: --class <class>");
     } else if (arg === "--by") {
       // `chant workspace records review <id> --by <principal>` (#2670): whoever the caller says.
       result.by = args[++i];
@@ -748,6 +771,19 @@ export function parseArgs(args: string[]): ParsedArgs {
       }
     } else if (arg === "--once") {
       result.once = true;
+    } else if (arg === "--setup-key") {
+      // `chant ci serve|run --setup-key` (#4099): make the host's runner key and print its public half.
+      result.setupKey = true;
+    } else if (arg === "--trust") {
+      // `chant ci serve|run --setup-key --trust` (#4099): list the key in .chant/trust.json on a branch.
+      result.trustKey = true;
+    } else if (arg === "--unsigned") {
+      // `chant ci serve --unsigned` (#4099): serve without a runner key listed at the target's head.
+      result.unsigned = true;
+    } else if (arg === "--principal") {
+      // `chant ci serve|run --setup-key --trust --principal <name>` (#4099): the runner's principal.
+      result.ciPrincipal = args[++i];
+      if (!result.ciPrincipal || result.ciPrincipal.startsWith("-")) throw new Error("--principal needs the runner's principal: --principal <name>");
     } else if (arg === "--work") {
       // `chant run <op> --work <id>` (#2748)
       const value = args[++i];

package/src/cli/registry.ts

@@ -462,8 +462,16 @@ export interface ParsedArgs {
   commit?: string;
   /** `chant ci run --pass-env <NAME>`, repeatable (#4094): a variable of the runner's environment the job gets, beside the few it always gets. */
   passEnv?: string[];
+  /** `chant ci run|serve --secrets <file>` (#4096): the host's secrets file. Default the file `CHANT_CI_SECRETS` names. */
+  ciSecrets?: string;
   /** `chant ci workflow --chant <command>` (#3573): the command the tick step runs chant with, in place of the npx pin. Also `chant ci run --chant` (#4094): what runs chant in the job. */
   ciChant?: string;
+  /** `chant ci run|serve --no-status` (#4097): post no commit status for the job. */
+  noStatus?: boolean;
+  /** `chant ci run|serve --status-url <template>` (#4097): the link a job's status carries. `{key}` is `<pr>/<commit>[/<member>]`, as `--report-url` keys it. */
+  statusUrl?: string;
+  /** `chant ci run --run-index-limit <n>` (#4098): how many runs the index at the report URL keeps. Default 200. */
+  runIndexLimit?: number;
   /** `chant ci serve --repo <owner/repo>` (#4095): the repository it polls. */
   ciRepo?: string;
   /** `chant ci serve --max-jobs <n>` (#4095): how many jobs run at once. Default 1. */
@@ -490,6 +498,16 @@ export interface ParsedArgs {
    * `records-write.ts`.
    */
   by?: string;
+  /** `chant ci serve|run --setup-key` (#4099): make the host's runner key in the state directory and print its public half. */
+  setupKey?: boolean;
+  /** `chant ci serve|run --setup-key --trust` (#4099): list the runner key in .chant/trust.json on a branch pushed for review. */
+  trustKey?: boolean;
+  /** `chant ci serve --unsigned` (#4099): start without a runner key listed in .chant/trust.json at the target's head. */
+  unsigned?: boolean;
+  /** `chant ci serve|run --setup-key --trust --principal <name>` (#4099): the principal the runner key is listed for. */
+  ciPrincipal?: string;
+  /** `chant workspace trust runner add <principal> --class runner|service` (#3510): the runner entry's class. */
+  runnerClass?: string;
   /**
    * `chant workspace records review <id> --sign [<key file>]` (#2687): the key that seals the verdict, or true for git's user.signingkey.
    * On `records new` and `records amend`, the key that seals the record's author (#2688).

package/src/op/local-executor.ts

@@ -56,6 +56,7 @@ import { LiveRun, currentLiveRun, withLiveRun } from "./run-live";
 import { runEnvOf } from "../lifecycle/run-ledger";
 import { resolveCommitSha } from "../lifecycle/commit-sha";
 import { resolveCiRun, type RunOrigin } from "../lifecycle/release-ledger";
+import { redactDeep, redactText, type Redact } from "./redact";
 import { runEventsOfStepRecord, type RunEventKind, type RunEventRuntime, type RunEventSkipReason } from "../run-event";
 import { openRunEventStore, teeLines } from "../run-event-store";
 import { openRunEventStream, runEventRunOf, type RunEventSink, type RunEventStream } from "../run-event-stream";
@@ -1377,6 +1378,17 @@ export interface RunOpOptions {
    * needs one. The local runtime passes the configured lexicons' contracts.
    */
   contracts?: ReadonlyMap<string, ActivityContract>;
+  /**
+   * Redacts secret values (#4096) from what the run writes about itself:
+   * each {@link runEvents} line and each line kept on this host, each
+   * {@link stepOutput} line and step label, and the run record, its step
+   * records and its `failure`, before {@link signRecord} signs it and the
+   * ledger stores it. The step records on the result are redacted too. This
+   * is the one place a run's writes pass through, so a writer added here
+   * later is redacted with the rest. `chant ci run` passes one built from
+   * the host's secrets file (../workspace/ci-secrets.ts).
+   */
+  redact?: Redact;
 }
 
 /**
@@ -1437,7 +1449,11 @@ export async function runOpLocally(
   const events: { stream?: RunEventStream } = {};
   try {
     const stepConsole = options.stepOutput
-      ? { write: options.stepOutput, ...(options.stepHeartbeatMs !== undefined ? { heartbeatMs: options.stepHeartbeatMs } : {}) }
+      ? {
+          write: options.stepOutput,
+          ...(options.stepHeartbeatMs !== undefined ? { heartbeatMs: options.stepHeartbeatMs } : {}),
+          ...(options.redact ? { redact: options.redact } : {}),
+        }
       : undefined;
     return await withLiveRun(live, () =>
       withRunConsole(stepConsole, () =>
@@ -1478,7 +1494,10 @@ async function runOpInTurn(
   const store = options.ledger
     ? await openRunEventStore(options.ledger.cwd ?? options.cwd ?? process.cwd(), runId)
     : undefined;
-  const eventsWrite = teeLines(options.runEvents?.write, store?.write.bind(store));
+  const teed = teeLines(options.runEvents?.write, store?.write.bind(store));
+  // #4096: every event line, to the caller and to this host's store alike, is redacted once, here.
+  const redact = options.redact;
+  const eventsWrite = teed && redact ? (line: string) => teed(redactText(line, redact)) : teed;
   const stream = eventsWrite
     ? openRunEventStream(
         runEventRunOf({
@@ -1620,7 +1639,7 @@ async function runOpInTurn(
     point?: WaitingPoint,
   ): Promise<OpRunRecord> => {
     const ended = options.now ?? new Date().toISOString();
-    const input = buildRunRecord(config, settled, {
+    let input = buildRunRecord(config, settled, {
       started: startedAt,
       ended,
       status,
@@ -1638,6 +1657,15 @@ async function runOpInTurn(
       const failure = options.describeFailure(settled);
       if (failure) input.failure = failure;
     }
+    // #4096: the record is redacted before it is signed, so the stored record is the one the statement covers.
+    // The step records on the result are redacted in place, so a caller printing them prints no secret.
+    if (redact) {
+      input = redactDeep(input, redact);
+      for (const r of settled) {
+        if (r.error !== undefined) r.error = redact(r.error);
+        if (r.args) r.args = redactDeep(r.args, redact);
+      }
+    }
     let record: OpRunRecord = { version: 1, ...input, id: runId };
     if (options.signRecord) {
       try {

package/src/op/redact.ts

@@ -0,0 +1,93 @@
+/**
+ * Redaction of secret values (#4096): what a run writes about itself, with
+ * each secret value replaced by `***`.
+ *
+ * The executor (./local-executor.ts) takes a {@link Redact} and applies it
+ * where a run writes: each run-event line, each line a step prints, and the
+ * run record before it is signed and stored. `chant ci run` builds one from
+ * the host's secrets file and the job's secret-looking variables
+ * (../workspace/ci-secrets.ts).
+ *
+ * A value shorter than {@link REDACT_MIN_LENGTH} characters is not
+ * redacted: a two- or three-character value matches too much ordinary text.
+ */
+
+/** What every redacted value is replaced with. */
+export const REDACTED = "***";
+
+/** The shortest value redacted. Shorter values are left as they are. */
+export const REDACT_MIN_LENGTH = 4;
+
+/** A text with every secret value it contains replaced by {@link REDACTED}. */
+export type Redact = (text: string) => string;
+
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * The redactor for `values`, or undefined when none is long enough to
+ * redact. A value that spans lines is also redacted line by line, since
+ * step output reaches a reader one line at a time.
+ */
+export function redactorOf(values: Iterable<string>): Redact | undefined {
+  const all = new Set<string>();
+  const add = (v: string): void => {
+    if (v.length < REDACT_MIN_LENGTH) return;
+    all.add(v);
+    // As a JSON string spells it, for a value with a quote, a backslash or a control character in it.
+    all.add(JSON.stringify(v).slice(1, -1));
+  };
+  for (const value of values) {
+    add(value);
+    if (value.includes("\n")) for (const line of value.split(/\r?\n/)) add(line.trim());
+  }
+  if (all.size === 0) return undefined;
+  // Longest first, so a value that contains another is replaced whole.
+  const pattern = new RegExp([...all].sort((a, b) => b.length - a.length).map(escapeRegExp).join("|"), "g");
+  return (text) => (typeof text === "string" && text.length >= REDACT_MIN_LENGTH ? text.replace(pattern, REDACTED) : text);
+}
+
+/** `value` with `redact` applied to every string in it, keys included. Numbers, booleans and nulls are kept. */
+export function redactDeep<T>(value: T, redact: Redact): T {
+  if (typeof value === "string") return redact(value) as T;
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, redact)) as T;
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) out[redact(k)] = redactDeep(v, redact);
+    return out as T;
+  }
+  return value;
+}
+
+/**
+ * A JSON value's text, as `JSON.stringify` wrote it, with `redact` applied to
+ * its strings: parsed, redacted and written again, so a short value such as
+ * `true` that is also a secret doesn't break the document. Undefined when
+ * `text` is not JSON.
+ */
+function redactJsonText(text: string, redact: Redact): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const indent = /^[[{]\r?\n(\s+)/.exec(text)?.[1]?.length;
+  const trailing = /\s*$/.exec(text)?.[0] ?? "";
+  return `${JSON.stringify(redactDeep(parsed, redact), null, indent)}${trailing}`;
+}
+
+/**
+ * A file's or line's text redacted: a JSON document as JSON, each line of a
+ * JSON Lines text as JSON, and any other text, or line, as text. The text
+ * comes back unchanged when it holds no secret.
+ */
+export function redactText(text: string, redact: Redact): string {
+  if (redact(text) === text) return text;
+  const whole = redactJsonText(text, redact);
+  if (whole !== undefined) return whole;
+  return text
+    .split("\n")
+    .map((line) => (redact(line) === line ? line : (redactJsonText(line, redact) ?? redact(line))))
+    .join("\n");
+}

package/src/op/step-console.ts

@@ -41,6 +41,8 @@ interface StepConsole {
 export interface RunConsole {
   write: (line: string) => void;
   heartbeatMs?: number;
+  /** Applied to each line before it is written, and to a step's call before it is cut to a label (#4096). */
+  redact?: (text: string) => string;
 }
 
 const store = new AsyncLocalStorage<StepConsole>();
@@ -60,7 +62,10 @@ function formatArgs(args: Record<string, unknown>): string {
 /** The name a step's lines carry: its id, else `fn(args)` on one line, cut to {@link MAX_LABEL}. */
 export function stepLabel(fn: string, args: Record<string, unknown>, id?: string): string {
   if (id) return id;
-  const call = `${fn}(${formatArgs(args)})`.replace(/\s+/g, " ");
+  // A secret in the call is redacted before the label is cut, so a cut never leaves part of one.
+  const redact = runStore.getStore()?.redact;
+  const raw = `${fn}(${formatArgs(args)})`;
+  const call = (redact ? redact(raw) : raw).replace(/\s+/g, " ");
   return call.length > MAX_LABEL ? `${call.slice(0, MAX_LABEL - 4)}...)` : call;
 }
 
@@ -72,7 +77,7 @@ export function stepLabel(fn: string, args: Record<string, unknown>, id?: string
 export async function withStepConsole<T>(opts: { phase: string; label: string }, fn: () => Promise<T>): Promise<T> {
   const run = runStore.getStore();
   if (!run) return fn();
-  const { write } = run;
+  const write = run.redact ? (line: string) => run.write(run.redact!(line)) : run.write;
   const prefix = `[${opts.phase}] ${opts.label}`;
   const started = Date.now();
   let spoke = false;

package/src/pr-forge.test.ts

@@ -912,3 +912,32 @@ describe("pull requests over REST (#3798)", () => {
     await expect(forgejoForge({ ...fjOpts, fetch }).openPullRequest({ head: "h", title: "t", body: "b" })).rejects.toThrow(/no default branch.*pass base/);
   });
 });
+
+describe("setCommitStatus, a runner job's status (#4097)", () => {
+  const long = "x".repeat(300);
+
+  test("GitHub posts state, context, a description cut to 140 and target_url", async () => {
+    const { fetch, calls } = fakeFetch({ [`POST /repos/acme/infra/statuses/${SHA}`]: {} });
+    const forge = githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t0k", fetch });
+    await forge.setCommitStatus!(SHA, { context: "chant/pr-plan", state: "failure", description: long, targetUrl: "https://host/reports/7/abc/" });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toMatchObject({ method: "POST", url: `https://api.github.com/repos/acme/infra/statuses/${SHA}` });
+    expect(calls[0].headers.Authorization).toBe("Bearer t0k");
+    expect(calls[0].body).toEqual({ state: "failure", context: "chant/pr-plan", description: "x".repeat(140), target_url: "https://host/reports/7/abc/" });
+  });
+
+  test("Forgejo posts to /repos/{owner}/{repo}/statuses/{sha} under /api/v1, and omits target_url when there is none", async () => {
+    const { fetch, calls } = fakeFetch({ [`POST /api/v1/repos/acme/infra/statuses/${SHA}`]: {} });
+    const forge = forgejoForge({ apiBase: "https://codeberg.org/api/v1", repo: "acme/infra", token: "t0k", host: "codeberg.org", fetch });
+    await forge.setCommitStatus!(SHA, { context: "chant/pr-apply", state: "pending", description: "pr-apply running" });
+    expect(calls[0]).toMatchObject({ method: "POST", url: `https://codeberg.org/api/v1/repos/acme/infra/statuses/${SHA}` });
+    expect(calls[0].headers.Authorization).toBe("token t0k");
+    expect(calls[0].body).toEqual({ state: "pending", context: "chant/pr-apply", description: "pr-apply running" });
+  });
+
+  test("a refusal throws, and GitLab's client has none", async () => {
+    const { fetch } = fakeFetch({ [`POST /repos/acme/infra/statuses/${SHA}`]: 403 });
+    await expect(githubForge({ apiBase: "https://api.github.com", repo: "acme/infra", token: "t", fetch }).setCommitStatus!(SHA, { context: "c", state: "success", description: "d" })).rejects.toBeInstanceOf(ForgeApiError);
+    expect(gitlabForge({ apiBase: "https://gl/api/v4", project: "42", token: "t", fetch }).setCommitStatus).toBeUndefined();
+  });
+});

package/src/pr-forge.ts

@@ -61,6 +61,16 @@ export interface ForgeStatus {
   pipelineId?: number;
 }
 
+/** A runner job's commit status (#4097): the states GitHub and Forgejo both keep. */
+export interface CommitStatus {
+  context: string;
+  state: "pending" | "success" | "failure" | "error";
+  /** Cut to 140 characters. */
+  description: string;
+  /** Where the status links to. Omitted from the request when absent. */
+  targetUrl?: string;
+}
+
 /** A commit status's state, as a caller names it. */
 export type ForgeStatusState = "pending" | "running" | "success" | "failed" | "failure" | "canceled" | "error";
 
@@ -309,6 +319,14 @@ export interface PrForge {
    */
   addComment(pr: number, body: string): Promise<AddedComment>;
   setStatus(sha: string, status: ForgeStatus): Promise<void>;
+  /**
+   * GitHub and Forgejo (#4097): set a commit status from a runner's job, one
+   * of `pending`, `success`, `failure` or `error`. The request is the one
+   * {@link setStatus} sends (`POST /repos/{owner}/{repo}/statuses/{sha}`), with
+   * the description cut to 140 characters and `target_url` only when given.
+   * `chant ci run` posts a job's progress through it.
+   */
+  setCommitStatus?(sha: string, status: CommitStatus): Promise<void>;
   /**
    * Keep one OPEN tracking issue for `marker` in line with `finding`: open
    * it, update its title and body, or, when `finding` is `null` and
@@ -614,6 +632,14 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       await api.call("PATCH", `${repo}/issues/${n}`, { state: "closed" });
     },
   };
+  const postStatus = async (sha: string, state: ForgeStatusState, context: string, description: string, url?: string): Promise<void> => {
+    await api.call("POST", `${repo}/statuses/${sha}`, {
+      state: statusStateFor(kind, state),
+      context,
+      description: description.slice(0, GITHUB_DESCRIPTION),
+      ...(url ? { target_url: url } : {}),
+    });
+  };
   return {
     kind,
     host,
@@ -621,12 +647,10 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
     principalOf: (login) => forgePrincipalOf(kind, host, login),
     ...threadCalls(t),
     async setStatus(sha, status) {
-      await api.call("POST", `${repo}/statuses/${sha}`, {
-        state: statusStateFor(kind, status.state),
-        context: status.context,
-        description: status.description.slice(0, GITHUB_DESCRIPTION),
-        ...(status.url ? { target_url: status.url } : {}),
-      });
+      await postStatus(sha, status.state, status.context, status.description, status.url);
+    },
+    async setCommitStatus(sha, status) {
+      await postStatus(sha, status.state, status.context, status.description, status.targetUrl);
     },
     async approvers(pr) {
       // A reviewer's newest deciding review is their standing one. A comment

package/src/pr-report-url.ts

@@ -35,7 +35,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -120,6 +120,58 @@ export function reportPut(target: ReportTarget, aws: AwsCli = realAwsCli): Repor
   };
 }
 
+/** Reads one object: `key` below the URL. Resolves null for an object that is not there, and rejects with a line a person can read for any other failure. */
+export type ReportGet = (key: string) => Promise<string | null>;
+
+/** Runs the AWS CLI with `args` and resolves its stdout, rejecting with its error line on a non-zero exit. */
+export type AwsRead = (args: string[]) => Promise<string>;
+
+/** The AWS CLI on PATH, read for the body `aws s3 cp <s3 url> -` prints. */
+export const realAwsRead: AwsRead = (args) =>
+  new Promise((resolveRead, reject) => {
+    const child = spawn(AWS_BINARY, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const out: Buffer[] = [];
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => out.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (stderr.length < 4096) stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      reject(new Error(err.code === "ENOENT" ? "the AWS CLI (aws) is not on PATH; an s3 report URL is read with it" : err.message)),
+    );
+    child.on("close", (code) => {
+      if (code === 0) return resolveRead(Buffer.concat(out).toString("utf8"));
+      const line = stderr.trim().split("\n").filter(Boolean).at(-1) ?? "";
+      reject(new Error(`aws s3 cp exited ${code}${line ? `: ${line.slice(0, 300)}` : ""}`));
+    });
+  });
+
+/** What the AWS CLI says about an object that does not exist. */
+const S3_ABSENT = /\(404\)|Not Found|NoSuchKey|does not exist/i;
+
+/** A get for `target`. `aws` replaces the AWS CLI in a test. */
+export function reportGet(target: ReportTarget, aws: AwsRead = realAwsRead): ReportGet {
+  if (target.scheme === "file") {
+    return async (key) => {
+      try {
+        return readFileSync(join(target.dir, ...key.split("/")), "utf-8");
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw err;
+      }
+    };
+  }
+  return async (key) => {
+    const object = `s3://${target.bucket}/${target.prefix ? `${target.prefix}/` : ""}${key}`;
+    try {
+      return await aws(["s3", "cp", object, "-", "--only-show-errors"]);
+    } catch (err) {
+      if (S3_ABSENT.test(messageOf(err))) return null;
+      throw err;
+    }
+  };
+}
+
 /** A stage's upload: its events as they are written, and its files at the end. */
 export interface PrReportUpload {
   /** The folder the stage's files go to: `<url>/<key>`. */

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

@@ -0,0 +1,50 @@
+{
+  "$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.",
+  "type": "object",
+  "required": ["$schema", "contract", "chant", "updated", "runs"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/ci-run-index/v1/ci-run-index.schema.json" },
+    "contract": { "const": 1 },
+    "chant": { "type": "string", "description": "The chant that last wrote the index." },
+    "updated": { "type": "string", "description": "When the index was last written." },
+    "runs": {
+      "type": "array",
+      "description": "Newest first, at most the limit the writer was given (200 by default).",
+      "items": { "$ref": "#/$defs/run" }
+    }
+  },
+  "$defs": {
+    "run": {
+      "type": "object",
+      "required": ["job", "pr", "commit", "status", "started", "ended", "runId", "key", "runOrigin"],
+      "if": { "properties": { "status": { "const": "fail" } } },
+      "then": { "required": ["failure"], "properties": { "failure": { "type": "object" } } },
+      "properties": {
+        "job": { "enum": ["plan", "apply"] },
+        "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"] },
+        "failure": {
+          "type": "object",
+          "required": ["code"],
+          "description": "Present when status is fail. The same code the run record's failure carries: setup-failed, build-failed, a report's refusal or status, or command-failed.",
+          "properties": { "code": { "type": "string" } }
+        },
+        "member": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "description": "The workspace member whose pipeline the job ran for. Absent outside a member." },
+        "started": { "type": "string", "description": "ISO-8601 instant the job started." },
+        "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." },
+        "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" } }
+        }
+      }
+    }
+  }
+}