@intentius/chant 0.124.31 → 0.124.32

package/src/workspace/ci-run.ts

@@ -44,6 +44,30 @@
  * With a forge client (#4097) the job also sets a commit status at its
  * commit: `pending` when it starts, `success` or `failure` when it settles.
  * A status the forge refuses is a warning and never fails the job.
+ *
+ * Signing is opt-in (#4156). With no runner key the record is unsigned, and
+ * a reader counts it with no signer. A key `.chant/trust.json` does not list
+ * leaves it unsigned with a note `--verbose` prints, unless the declaration
+ * sets `ci.green.signedSince`; then a run left unsigned is a warning.
+ *
+ * In place (`--in-place`, #4156) the job runs in the checkout it is started
+ * in, as a generated forge job does: no worktree, no setup phase and no
+ * commit status of its own (the forge shows the job). The steps get the
+ * job's whole environment less `CHANT_RUNNER_KEY`, since the forge job is
+ * already the boundary, and the record's `runOrigin` names the forge's run,
+ * job and attempt (`resolveCiJob`).
+ *
+ * Local (`--local`, #4161) runs the job the same way on this machine and
+ * leaves nothing outside it. It implies `--no-push` and `--no-status`, and
+ * writes nothing under a report URL, given or declared: the command gets no
+ * `--report-url`, and gets `--no-status`, so pr-plan and pr-apply post no
+ * status or note either. The record is still written to the local
+ * `chant/lifecycle`, where a reader on this machine finds it beside CI's for
+ * the same commit. It says `runOrigin: { forge: "local" }` and its events say
+ * `runtime: "local"`. `ci tick --source runs` and `ci list` never count it.
+ * A pr-apply still pushes its own release records and gate facts, as the
+ * command always does, since a local apply changes the same infrastructure
+ * a CI one does.
  */
 
 import { execFileSync } from "node:child_process";
@@ -55,8 +79,8 @@ import { detectForge, ForgeEnvironmentError, forgeFromEnv, FORGE_KINDS, type Com
 import { PR_APPLY_GATE } from "../pr-loop";
 import type { CommandContext } from "../cli/registry";
 import { formatError, formatWarning } from "../cli/format";
-import type { RunOrigin } from "../lifecycle/release-ledger";
-import { pushLifecycleReport } from "../lifecycle/git";
+import { resolveCiJob, type RunOrigin } from "../lifecycle/release-ledger";
+import { fetchLifecycleStatus, pushLifecycleReport } from "../lifecycle/git";
 import { ACTIVITY_PROFILES } from "../op/activity-profiles";
 import type { ActivityFn, ActivityProfile } from "../op/activity-registry";
 import { shellCmd } from "../op/activities/shell";
@@ -66,7 +90,9 @@ import type { ActivityStep, OpConfig, PhaseDefinition } from "../op/types";
 import { redactText, type Redact } from "../op/redact";
 import { findWorkspaceRoot } from "../project-root";
 import { parseReportUrl, reportKey } from "../pr-report-url";
-import { ciTagSigner, RUNNER_KEY_ENV } from "./ci-green";
+import { reportUrlOf } from "./ci-report-url";
+import { ciTagSigner, RUNNER_KEY_ENV, signedRunsRequired } from "./ci-green";
+import { loadRunnerKey } from "./trust/dsse";
 import { ciRedactor, ciSecretsFor, CI_SECRETS_ENV, readCiSecrets, type CiSecrets } from "./ci-secrets";
 import { updateCiRunIndex, type CiRunIndexEntry } from "./ci-run-index";
 import { resolveMemberContext } from "./member-pipeline";
@@ -84,6 +110,9 @@ export const CI_JOB_OPS: Record<CiJobName, string> = { plan: "pr-plan", apply: "
 /** Where a job the chant runner ran says it ran (#4094). */
 export const CHANT_RUNNER_ORIGIN: RunOrigin = { forge: "chant" };
 
+/** Where a job `chant ci run --local` ran says it ran (#4161): this machine, outside CI. */
+export const CHANT_LOCAL_ORIGIN: RunOrigin = { forge: "local" };
+
 /** The runner's variables every job gets, when the runner has them. */
 export const CI_RUN_BASE_ENV = ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TZ"] as const;
 
@@ -241,6 +270,17 @@ function exitCodeOf(error: string | undefined): number | undefined {
   return m ? Number(m[1]) : undefined;
 }
 
+/**
+ * The code `chant ci run` exits with for a settled job: 0 when it passed,
+ * else its command's own code when that is 1 to 255, such as 3 for a moved
+ * plan or a waiting wave (#4156), else 1. The run index records the same
+ * code (#4165).
+ */
+export function ciJobExitCode(result: { status: OpRunResult["status"]; exitCode?: number }): number {
+  if (result.status === "ok") return 0;
+  return result.exitCode && result.exitCode > 0 && result.exitCode < 256 ? result.exitCode : 1;
+}
+
 /** The first line of a step's error, for a reason. */
 const firstLine = (text: string): string => text.split("\n").find((l) => l.trim() !== "")?.trim() ?? text;
 
@@ -378,7 +418,12 @@ export interface CiRunRequest {
   base?: string;
   pr?: number;
   commit?: string;
-  /** The generator's options: `--gate`, `--branch`, `--events-json`, `--report-url`, `--pr-build` and `--pr-build-command`. */
+  /**
+   * The generator's options: `--gate`, `--branch`, `--events-json`,
+   * `--report-url`, `--pr-build` and `--pr-build-command`, and `--wave-gate`
+   * (#4003), with which the apply job runs the waves in order and stops at
+   * the first whose moved plan waits on its own gate.
+   */
   loop?: PrLoopPipelineOptions;
   /** `--image`: the image a generated pipeline names. Only the default gets setup lines. */
   image?: string;
@@ -425,6 +470,24 @@ export interface CiRunRequest {
   resumeRecord?: string;
   /** Set a commit status at the job's commit (#4097). Absent: none is set. `chant ci run` builds it from the environment. */
   status?: CiStatusConfig;
+  /**
+   * `--in-place` (#4156): run in the checkout `cwd` is in, at its `HEAD`, as
+   * a generated forge job does, with the runner's whole environment less
+   * `CHANT_RUNNER_KEY`, no setup phase, and the forge's run as `runOrigin`.
+   */
+  inPlace?: boolean;
+  /**
+   * `--local` (#4161): run on this machine and write nothing beyond it. It
+   * implies `push: false` and no status (`status` is ignored), writes
+   * nothing under `loop.reportUrl`, and the record and events say
+   * `runOrigin: { forge: "local" }` and `runtime: "local"`.
+   */
+  local?: boolean;
+  /**
+   * `--wave <k>` (#4003, #4156): the one wave a generated apply job runs, as
+   * `pr-apply --wave <k>`. Needs `--wave-gate`.
+   */
+  wave?: number;
   signal?: AbortSignal;
 }
 
@@ -443,8 +506,14 @@ export interface CiRunResult {
   pushWarning?: string;
   /** What went wrong beside the job, such as a record the key could not sign. */
   warnings: string[];
+  /** What `--verbose` prints: such as a run left unsigned when nothing asks for a signature (#4156). */
+  notes: string[];
+  /** The exit code of the job's command when it failed with one, such as pr-apply's 3 for a moved plan. */
+  exitCode?: number;
   /** The checkout the job ran in, removed by now. */
   checkout: string;
+  /** The job ran with `local` (#4161): its record stays on this machine. */
+  local?: true;
 }
 
 const message = (err: unknown): string => (err instanceof Error ? err.message : String(err));
@@ -516,6 +585,11 @@ async function recordInIndex(input: {
   member?: string;
   pr?: number;
   record: OpRunRecord;
+  runOrigin: RunOrigin;
+  /** The runner that signed the record, or null (#4156). */
+  signer: string | null;
+  /** The code `chant ci run` exits with for the job (#4165). */
+  exitCode: number;
   reportDir: string;
   limit?: number;
   /** The run's redactor (#4096): every string written to the index goes through it, as the copied report does. */
@@ -547,7 +621,9 @@ async function recordInIndex(input: {
     ended: input.record.ended,
     runId: clean(input.record.id),
     key: clean(reportKey(pr, input.commit, input.member)),
-    runOrigin: CHANT_RUNNER_ORIGIN,
+    runOrigin: input.runOrigin,
+    signer: input.signer,
+    exitCode: input.exitCode,
   };
   await updateCiRunIndex({ target, entry, ...(input.limit ? { limit: input.limit } : {}), warn: input.warn });
 }
@@ -565,11 +641,17 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
   const top = gitTop(cwd);
   if (!top) throw new CiRunError("a job runs in a fresh checkout of a commit, and this directory is not in a git repository");
   const commit = resolveJobCommit(top, req.commit ?? "HEAD");
+  if (req.inPlace && commit !== resolveJobCommit(top, "HEAD")) throw new CiRunError(`--in-place runs the checkout's HEAD, and --commit names ${commit.slice(0, 12)}`);
+  if (req.local && req.inPlace) throw new CiRunError("--in-place runs a forge job in the forge's checkout, and --local runs one on this machine; pass one of them");
   const place = ciJobPlace(cwd, top);
-  const jobs = prLoopJobs(req.forge, req.env, req.loop ?? {}, place.member);
-  const job = jobs.find((j) => j.jobName === req.job);
-  if (!job) throw new CiRunError(`the pull-request pipeline has no ${req.job} job; it has ${jobs.map((j) => j.jobName).join(" and ")}`);
-  const jobEnv = ciJobEnv(job, {
+  const jobs = prLoopJobs(req.forge, req.env, req.local ? localLoop(req.loop) : (req.loop ?? {}), place.member);
+  const found = jobs.find((j) => j.jobName === req.job);
+  if (!found) throw new CiRunError(`the pull-request pipeline has no ${req.job} job; it has ${jobs.map((j) => j.jobName).join(" and ")}`);
+  if (req.wave !== undefined && (req.job !== "apply" || !req.loop?.waveGate)) throw new CiRunError("--wave names the one wave an apply runs, and takes --wave-gate: ci run apply --wave-gate <gate> --wave <k>");
+  // A generated wave job's command, as prLoopWaveJobs writes it. #4161: a local job's command posts no status or note.
+  const command = `${found.command}${req.wave !== undefined ? ` --wave ${req.wave}` : ""}${req.local ? " --no-status" : ""}`;
+  const job = { ...found, command, ...(req.wave !== undefined ? { wave: req.wave } : {}) };
+  const own = ciJobEnv(job, {
     forge: req.forge,
     env: req.env,
     values: { base: req.base, pr: req.pr, commit },
@@ -577,37 +659,90 @@ export async function ciRun(req: CiRunRequest): Promise<CiRunResult> {
     passEnv: req.passEnv,
     secrets: ciSecretsFor(req.secrets, req.job),
   });
+  // #4156: in place, the forge job's environment is the job's, less the runner key.
+  const jobEnv = req.inPlace ? { ...definedEnv(hostEnv), ...own } : own;
+  delete jobEnv[RUNNER_KEY_ENV];
   // #4096: the secrets and the job's secret-looking variables, redacted from everything the run writes and returns.
-  const redact = ciRedactor(jobEnv, req.secrets);
+  // In place the forge's own variables come too; one whose value is short, such as a flag, is left out, so it can't blank common words.
+  const redact = ciRedactor(req.inPlace ? { ...longValues(jobEnv), ...own } : jobEnv, req.secrets);
   try {
     const result = await runCiJob(req, { cwd, top, commit, place, job, jobEnv, ...(redact ? { redact } : {}) });
-    return redact ? { ...result, warnings: result.warnings.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result;
+    return redact ? { ...result, warnings: result.warnings.map(redact), notes: result.notes.map(redact), ...(result.pushWarning ? { pushWarning: redact(result.pushWarning) } : {}) } : result;
   } catch (err) {
     if (redact && err instanceof Error) err.message = redact(err.message);
     throw err;
   }
 }
 
+/** The generator's options for a `--local` job (#4161): the same, with no report URL. */
+function localLoop(loop: PrLoopPipelineOptions | undefined): PrLoopPipelineOptions {
+  const { reportUrl: _dropped, ...rest } = loop ?? {};
+  return rest;
+}
+
+/** The variables of `env` whose value is long enough to be a credential, 8 characters or more. */
+function longValues(env: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(env).filter(([, value]) => value.length >= 8));
+}
+
+/** The variables of `env` that have a value. */
+function definedEnv(env: Record<string, string | undefined>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [name, value] of Object.entries(env)) if (value !== undefined) out[name] = value;
+  return out;
+}
+
+/**
+ * Who signs the run (#4156): the runner key, checked against
+ * `.chant/trust.json` at the commit. A key that isn't an Ed25519 PEM is an
+ * error, and so is a `--key` the file does not list. A key from the
+ * environment that it does not list, and no key at all, leave the run
+ * unsigned: a warning when the declaration's `ci.green.signedSince` asks
+ * for signed runs, a note for `--verbose` otherwise.
+ */
+function ciRunSigner(req: CiRunRequest, at: { cwd: string; top: string; commit: string }): { signer?: ReturnType<typeof ciTagSigner>; warnings: string[]; notes: string[] } {
+  // #4161: a local run never counts, signed or not, so nothing about its signature warns.
+  const required = req.local ? null : signedRunsRequired(at.cwd);
+  const say = (text: string) => (required ? { warnings: [`${text}, and ci.green.signedSince is ${required}, so it will not count`], notes: [] } : { warnings: [], notes: [text] });
+  if (req.runnerKey === undefined) return say("there is no runner key, so the run's record is unsigned");
+  try {
+    loadRunnerKey(req.runnerKey);
+  } catch (err) {
+    throw new CiRunError(`the runner key${req.runnerKeyFromEnv ? ` in ${RUNNER_KEY_ENV}` : ""} is not an Ed25519 private key in PEM: ${message(err)}`);
+  }
+  try {
+    return { signer: ciTagSigner(at.top, at.commit, req.runnerKey, "the runs it signed"), warnings: [], notes: [] };
+  } catch (err) {
+    if (!req.runnerKeyFromEnv) throw new CiRunError(`the run would not be signed: ${message(err)}`);
+    return say(`${RUNNER_KEY_ENV} is set, and the run will not be signed: ${message(err)}`);
+  }
+}
+
+/** Where the job runs: a fresh worktree of the commit, or with `inPlace` the checkout itself, which is left as it is. */
+function jobCheckout(top: string, commit: string, inPlace?: boolean): { dir: string; remove(): void } {
+  return inPlace ? { dir: top, remove() {} } : freshCheckout(top, commit);
+}
+
 /** {@link ciRun} once the job and its environment are known. */
 async function runCiJob(
   req: CiRunRequest,
   at: { cwd: string; top: string; commit: string; place: { member?: string; dir: string }; job: PrLoopJob; jobEnv: Record<string, string>; redact?: Redact },
 ): Promise<CiRunResult> {
   const { cwd, top, commit, place, job, jobEnv, redact } = at;
-
-  // The record is signed against .chant/trust.json at the commit the job runs, so a key that commit does not list is refused before anything runs.
-  let signer: ReturnType<typeof ciTagSigner> | undefined;
-  const early: string[] = [];
-  if (req.runnerKey !== undefined) {
-    try {
-      signer = ciTagSigner(top, commit, req.runnerKey, "the runs it signed");
-    } catch (err) {
-      if (!req.runnerKeyFromEnv) throw new CiRunError(`the run would not be signed: ${message(err)}`);
-      early.push(`${RUNNER_KEY_ENV} is set, and the run will not be signed: ${message(err)}`);
-    }
-  }
-
-  const checkout = freshCheckout(top, commit);
+  const local = req.local === true;
+  const status = local ? undefined : req.status;
+  const reportUrl = local ? undefined : req.loop?.reportUrl;
+
+  // The record is signed against .chant/trust.json at the commit the job runs, so a --key that commit does not list is refused before anything runs.
+  const signing = ciRunSigner(req, { cwd, top, commit });
+  const signer = signing.signer;
+  const early = signing.warnings;
+  const notes = signing.notes;
+  const origin: RunOrigin = local ? CHANT_LOCAL_ORIGIN : req.inPlace ? (resolveCiJob(req.hostEnv ?? process.env)?.runOrigin ?? CHANT_RUNNER_ORIGIN) : CHANT_RUNNER_ORIGIN;
+  // In place, the job writes its record on the checkout's chant/lifecycle, which a forge checkout may not have fetched.
+  if (req.inPlace && req.push !== false) await fetchLifecycleStatus({ cwd: top }).catch(() => undefined);
+
+  const checkout = jobCheckout(top, commit, req.inPlace);
   try {
     const jobDir = place.dir === "." ? checkout.dir : join(checkout.dir, place.dir);
     const op = ciJobOp({
@@ -615,7 +750,7 @@ async function runCiJob(
       env: req.env,
       cwd: jobDir,
       jobEnv,
-      setup: prLoopSetup(req.image ?? PR_LOOP_IMAGE),
+      setup: req.inPlace ? [] : prLoopSetup(req.image ?? PR_LOOP_IMAGE),
       build: [...(req.beforeScript ?? []), ...(job.build ?? [])],
       ...(req.chant ? { chant: req.chant } : {}),
     });
@@ -627,13 +762,13 @@ async function runCiJob(
       copyFileSync(resume.host, resume.job);
     }
     const statusContext = ciStatusContext(req.job, req.loop?.gate);
-    const statusUrl = req.status
-      ? ciStatusUrl({ ...(req.status.urlTemplate ? { urlTemplate: req.status.urlTemplate } : {}), ...(req.loop?.reportUrl ? { reportUrl: req.loop.reportUrl } : {}), ...(req.pr !== undefined ? { pr: req.pr } : {}), commit, ...(place.member ? { member: place.member } : {}) })
+    const statusUrl = status
+      ? ciStatusUrl({ ...(status.urlTemplate ? { urlTemplate: status.urlTemplate } : {}), ...(reportUrl ? { reportUrl } : {}), ...(req.pr !== undefined ? { pr: req.pr } : {}), commit, ...(place.member ? { member: place.member } : {}) })
       : undefined;
     const postStatus = async (state: CommitStatus["state"], description: string): Promise<void> => {
-      if (!req.status) return;
+      if (!status) return;
       try {
-        await req.status.client.setCommitStatus(commit, { context: statusContext, state, description: cut(redact ? redact(description) : description), ...(statusUrl ? { targetUrl: statusUrl } : {}) });
+        await status.client.setCommitStatus(commit, { context: statusContext, state, description: cut(redact ? redact(description) : description), ...(statusUrl ? { targetUrl: statusUrl } : {}) });
       } catch (err) {
         warnings.push(`could not set the ${statusContext} status: ${message(err)}`);
       }
@@ -649,7 +784,7 @@ async function runCiJob(
         cwd: jobDir,
         commit,
         ledger: { cwd: jobDir },
-        runner: { kind: "pipeline", runtime: "ci", runOrigin: CHANT_RUNNER_ORIGIN },
+        runner: { kind: "pipeline", runtime: local ? "local" : "ci", runOrigin: origin },
         describeFailure: (records) => ciJobFailure({ job: req.job, op, records, reportDir: join(jobDir, PR_LOOP_REPORT_DIR) }),
         ...(req.runEvents ? { runEvents: { write: req.runEvents } } : {}),
         ...(req.stepOutput ? { stepOutput: req.stepOutput } : {}),
@@ -687,26 +822,37 @@ async function runCiJob(
     let report: string | null = null;
     if (existsSync(written)) {
       report = resolve(cwd, req.output ?? PR_LOOP_REPORT_DIR);
-      cpSync(written, report, { recursive: true });
-      if (redact) redactTree(report, redact);
-    }
-    if (req.loop?.reportUrl) {
-      await recordInIndex({ url: req.loop.reportUrl, job: req.job, commit, member: place.member, pr: req.pr, record: result.record, reportDir: written, limit: req.runIndexLimit, ...(redact ? { redact } : {}), warn: (w) => warnings.push(w) });
+      // In place the report is already where the forge keeps it, and stays as the command wrote it.
+      if (!(existsSync(report) && realpathSync(report) === realpathSync(written))) {
+        cpSync(written, report, { recursive: true });
+        if (redact) redactTree(report, redact);
+      }
     }
-    if (ledgerError) throw new CiRunError(ledgerError);
-    const pushed: { pushed: boolean; pushWarning?: string } = req.push === false ? { pushed: false, pushWarning: "chant/lifecycle was not pushed" } : await pushLifecycleReport({ cwd: top });
     const failed = result.records.find((r) => r.status === "fail");
+    const exitCode = failed?.phase === req.job ? exitCodeOf(failed.error) : undefined;
+    if (reportUrl) {
+      await recordInIndex({ url: reportUrl, job: req.job, commit, member: place.member, pr: req.pr, record: result.record, runOrigin: origin, signer: result.record.statement && signer ? signer.principal : null, exitCode: ciJobExitCode({ status: result.status, ...(exitCode !== undefined ? { exitCode } : {}) }), reportDir: written, limit: req.runIndexLimit, ...(redact ? { redact } : {}), warn: (w) => warnings.push(w) });
+    }
+    // In place the forge job's outcome is the command's, so a record that could not be written is a warning there.
+    if (ledgerError && req.inPlace) warnings.push(ledgerError);
+    else if (ledgerError) throw new CiRunError(ledgerError);
+    const pushed: { pushed: boolean; pushWarning?: string } = local
+      ? { pushed: false }
+      : req.push === false ? { pushed: false, pushWarning: "chant/lifecycle was not pushed" } : await pushLifecycleReport({ cwd: top });
     return {
       op: op.name,
       status: result.status,
       record: result.record,
       ...(failed ? { failure: { phase: failed.phase, error: failed.error ?? "the step failed" } } : {}),
+      ...(exitCode !== undefined ? { exitCode } : {}),
       report,
-      signer: signer?.principal ?? null,
+      signer: result.record.statement && signer ? signer.principal : null,
       pushed: pushed.pushed,
       ...(pushed.pushWarning ? { pushWarning: pushed.pushWarning } : {}),
       warnings,
+      notes,
       checkout: checkout.dir,
+      ...(local ? { local: true as const } : {}),
     };
   } finally {
     checkout.remove();
@@ -740,19 +886,40 @@ export function formatCiRun(r: CiRunResult): string {
   const why = r.record.failure;
   if (why) lines.push(`  failure: ${why.code}${why.phase ? ` in ${why.phase}` : ""}${why.exitCode !== undefined ? `, exit ${why.exitCode}` : ""}: ${why.reason}`);
   else if (r.failure) lines.push(`  ${r.failure.phase}: ${r.failure.error}`);
-  lines.push(`  record: ${r.record.env}/runs__${r.op}.jsonl on chant/lifecycle, ${r.signer ? `signed by ${r.signer}` : "unsigned, so ci tick from runs does not count it"}`);
+  lines.push(`  record: ${r.record.env}/runs__${r.op}.jsonl on chant/lifecycle, ${r.signer ? `signed by ${r.signer}` : "unsigned"}`);
   if (r.report) lines.push(`  report: ${r.report}`);
-  if (!r.pushed) lines.push(`  ${r.pushWarning ?? "chant/lifecycle was not pushed"}`);
+  if (r.local) lines.push("  local run: the record stays on this machine, with no push, commit status or report upload");
+  else if (!r.pushed) lines.push(`  ${r.pushWarning ?? "chant/lifecycle was not pushed"}`);
   return lines.join("\n");
 }
 
 // ── The command ──────────────────────────────────────────────────────────────
 
+/**
+ * The generator's options from `ci run`'s and `ci serve`'s flags, as `chant
+ * build --components --generate <lexicon> --pr-loop` takes them: `--gate`,
+ * `--branch`, `--events-json`, `--report-url`, `--pr-build`,
+ * `--pr-build-command`, `--wave-gate` (#4003) and `--no-require-review`
+ * (#4156).
+ */
+export function ciLoopOptions(args: CommandContext["args"]): PrLoopPipelineOptions {
+  return {
+    ...(args.gate ? { gate: args.gate } : {}),
+    ...(args.branch ? { branch: args.branch } : {}),
+    ...(args.eventsJson ? { events: true } : {}),
+    ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
+    ...(args.prBuild ? { build: true } : {}),
+    ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
+    ...(args.waveGate ? { waveGate: args.waveGate } : {}),
+    ...(args.requireReview === false ? { requireReview: false } : {}),
+  };
+}
+
 const USAGE =
   "chant ci run plan|apply --env <env> --base <sha> [--pr <n>] [--commit <sha>] [--forge github|gitlab|forgejo] " +
-  "[--gate <name>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
-  "[--pr-build] [--pr-build-command <line>] [--no-status] [--status-url <url template>] " +
-  "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
+  "[--gate <name>] [--wave-gate <name>] [--wave <k>] [--branch <name>] [--events-json] [--report-url <url>] [--run-index-limit <n>] [--image <image>] [--before-script <line>]... " +
+  "[--pr-build] [--pr-build-command <line>] [--no-require-review] [--no-status] [--status-url <url template>] " +
+  "[--chant <command>] [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>] [-o <dir>] [--in-place | --local] [--no-push] [--verbose] | chant ci run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]";
 
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -792,9 +959,13 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
     const hostKey = fromFlag || process.env[RUNNER_KEY_ENV] ? undefined : hostRunnerKeyAt(process.cwd(), args.statePath);
     const runnerKey = fromFlag ? readFileSync(resolve(args.key!), "utf-8") : process.env[RUNNER_KEY_ENV] || hostKey?.pem;
     const hostEnv = process.env;
-    const { status, warning } = ciStatusFromEnv({ forge: forge as ForgeKind, hostEnv, noStatus: args.noStatus, statusUrl: args.statusUrl });
+    // #4156: in place the forge shows the job, so ci run sets no status of its own.
+    // #4161: a local run sets no status, so it builds no client and warns about none.
+    const { status, warning } = ciStatusFromEnv({ forge: forge as ForgeKind, hostEnv, noStatus: args.noStatus || args.ciInPlace || args.local, statusUrl: args.statusUrl });
     if (warning) console.error(formatWarning({ message: warning }));
     const secrets = ciSecretsOf(args.ciSecrets);
+    // #4160: without --report-url, the declaration's ci.reportUrl.
+    const reportUrl = await reportUrlOf(args.reportUrl, process.cwd());
     const result = await ciRun({
       cwd: process.cwd(),
       ...(status ? { status } : {}),
@@ -804,14 +975,11 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
       ...(args.base ? { base: args.base } : {}),
       ...(args.pr !== undefined ? { pr: args.pr } : {}),
       ...(args.commit ? { commit: args.commit } : {}),
-      loop: {
-        ...(args.gate ? { gate: args.gate } : {}),
-        ...(args.branch ? { branch: args.branch } : {}),
-        ...(args.eventsJson ? { events: true } : {}),
-        ...(args.reportUrl ? { reportUrl: args.reportUrl } : {}),
-        ...(args.prBuild ? { build: true } : {}),
-        ...(args.prBuildCommand ? { buildCommand: args.prBuildCommand } : {}),
-      },
+      loop: ciLoopOptions(reportUrl ? { ...args, reportUrl } : args),
+      ...(args.ciInPlace ? { inPlace: true } : {}),
+      ...(args.local ? { local: true } : {}),
+      ...(args.noPush ? { push: false } : {}),
+      ...(args.wave !== undefined ? { wave: args.wave } : {}),
       ...(args.runIndexLimit ? { runIndexLimit: args.runIndexLimit } : {}),
       ...(args.image ? { image: args.image } : {}),
       ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
@@ -824,8 +992,10 @@ export async function runCiRun(ctx: CommandContext): Promise<number> {
       stepOutput: (line) => void process.stderr.write(`${line}\n`),
     });
     for (const w of result.warnings) console.error(formatWarning({ message: w }));
+    if (args.verbose) for (const n of result.notes) console.error(`ci run: ${n}`);
     console.error(formatCiRun(result));
-    return result.status === "ok" ? 0 : 1;
+    // #4156: a failed command's own exit code, such as 3 for a moved plan, is the job's, as it was before the job ran through ci run.
+    return ciJobExitCode(result);
   } catch (err) {
     console.error(formatError({ message: `chant ci run: ${message(err)}`, hint: USAGE }));
     return 1;

package/src/workspace/ci-runner-key.test.ts

@@ -2,9 +2,10 @@
  * #4099: the runner key on a `chant ci serve` or `chant ci run` host. The
  * key is made in the state directory with mode 0600, `--setup-key --trust`
  * proposes its runner entry on a branch through `trust runner add` (#3510)
- * and never writes the target branch, and `ci serve` refuses to start when
- * `.chant/trust.json` at the target's head does not list its key, unless
- * `--unsigned`.
+ * and never writes the target branch. Signing is opt-in (#4156): `ci serve`
+ * starts with no key and says nothing about it, and serves unsigned with one
+ * warning when `.chant/trust.json` at the target's head does not list its
+ * key. With `ci.green.signedSince` it refuses to start in either case.
  *
  * Every test works in its own temp repository with a bare origin and its own
  * state directory. The jobs' `chant` is a stub script, and no job runs: the
@@ -126,9 +127,12 @@ describe("the host's runner key (#4099)", () => {
     expect(trust.roles.runner).toEqual(["chant-runner:demo"]);
     expect(git(origin, "rev-parse", `${branch}^`)).toBe(main);
 
-    // Until it merges, ci serve refuses the key; once it has, the key signs as the principal.
+    // Until it merges, ci serve serves unsigned with a warning (refuses with the opt-in); once it has, the key signs as the principal.
     const key = hostRunnerKey(state)!;
-    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main" })).toThrow(/not trusted at main/);
+    const pending = ciServeRunnerKey({ top: root, stateDir: state, branch: "main" });
+    expect(pending.pem).toBeUndefined();
+    expect(pending.warning).toMatch(/not trusted at main/);
+    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main", required: main })).toThrow(/not trusted at main/);
     git(root, "push", "-q", "origin", `refs/remotes/origin/${branch}:refs/heads/main`);
     expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main" })).toMatchObject({ pem: key.pem, source: join(state, RUNNER_KEY_FILE) });
     expect(ciTagSigner(root, git(root, "rev-parse", "refs/remotes/origin/main"), key.pem).principal).toBe("chant-runner:demo");
@@ -138,29 +142,63 @@ describe("the host's runner key (#4099)", () => {
     expect(listed.err).toContain("lists it for chant-runner:demo, with the runner role");
   });
 
-  test("ci serve refuses to start with a key trust.json does not list at the target's head, and --unsigned starts without one", async () => {
+  test("ci serve starts with no key and says nothing, and serves unsigned with one warning for a key trust.json does not list (#4156)", async () => {
     const { root } = workspace();
     const state = scratchDir("chant-runner-key-state-");
 
+    // No key: nothing about keys is printed. The serve goes on to the forge, which this test has no token for.
     const none = await cli(root, SERVE(state));
-    expect(none.code).toBe(1);
-    expect(none.err).toContain("there is no runner key");
-
+    expect(none.err.split("\n")).toHaveLength(2);
+    expect(none.err.split("\n")[0]).toContain("chant ci serve: --forge forgejo needs GITHUB_TOKEN");
+    const keyless = ciServeRunnerKey({ top: root, stateDir: state, branch: "main" });
+    expect(keyless.pem).toBeUndefined();
+    expect(keyless.warning).toBeUndefined();
+    expect(keyless.note).toContain("not signed");
+    // --verbose prints that one line.
+    const verbose = await cli(root, [...SERVE(state), "--verbose"]);
+    expect(verbose.err).toContain("ci serve: runs are not signed: there is no runner key");
+
+    // A key the head does not list: one warning at startup, and no key goes to the jobs.
     ensureHostRunnerKey(state);
     const unlisted = await cli(root, SERVE(state));
-    expect(unlisted.code).toBe(1);
-    expect(unlisted.err).toMatch(/not trusted at main [0-9a-f]{12}/);
+    expect(unlisted.err.match(/not trusted at main [0-9a-f]{12}/g)).toHaveLength(1);
+    expect(unlisted.err).toContain("Runs are not signed until it is");
     expect(unlisted.err).toContain("chant ci serve --setup-key --trust");
-    expect(unlisted.err).toContain("chant workspace trust runner add");
+    expect(unlisted.err).not.toContain("signing runs with");
 
-    // A key listed only in the working tree, not at the head, is still refused.
+    // A key listed only in the working tree, not at the head, is not trusted either.
     const other = generateKeyPairSync("ed25519").privateKey.export({ type: "pkcs8", format: "pem" }).toString();
     writeFileSync(join(state, "other.pem"), other, { mode: 0o600 });
     expect(trustWrite({ cwd: root, action: "runner add", name: "ci-bot", key: join(state, "other.pem") })).toMatchObject({ changed: true });
-    const flagged = await cli(root, [...SERVE(state), "--key", join(state, "other.pem")]);
-    expect(flagged.code).toBe(1);
-    expect(flagged.err).toContain("lists no runner with this key");
+    const flagged = ciServeRunnerKey({ top: root, stateDir: state, branch: "main", keyFile: join(state, "other.pem") });
+    expect(flagged.pem).toBeUndefined();
+    expect(flagged.warning).toContain("lists no runner with this key");
+
+    // A key file that is not a key is an error either way.
+    writeFileSync(join(state, "bad.pem"), "not a key", { mode: 0o600 });
+    expect(() => ciServeRunnerKey({ top: root, stateDir: state, branch: "main", keyFile: join(state, "bad.pem") })).toThrow(/not an Ed25519 private key in PEM/);
+
+    // --unsigned is accepted and serves unsigned.
+    expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main", unsigned: true })).toMatchObject({ fromFlag: false, source: "none (--unsigned)" });
+  });
+
+  test("with ci.green.signedSince, ci serve refuses to start without a trusted key, --unsigned or not (#4156)", async () => {
+    const { root, main } = workspace();
+    const state = scratchDir("chant-runner-key-state-");
+    const green = { branch: "main", phases: { plan: ["pr-plan"] }, require: ["plan"], source: "runs", signedSince: main };
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green } }) });
 
-    expect(ciServeRunnerKey({ top: root, stateDir: state, branch: "main", unsigned: true })).toEqual({ fromFlag: false, source: "none (--unsigned)" });
+    const none = await cli(root, SERVE(state));
+    expect(none.code).toBe(1);
+    expect(none.err).toContain(`ci.green.signedSince is ${main}, so every run must be signed, and there is no runner key`);
+    const unsigned = await cli(root, [...SERVE(state), "--unsigned"]);
+    expect(unsigned.code).toBe(1);
+    expect(unsigned.err).toContain("there is no runner key");
+
+    ensureHostRunnerKey(state);
+    const unlisted = await cli(root, SERVE(state));
+    expect(unlisted.code).toBe(1);
+    expect(unlisted.err).toMatch(/not trusted at main [0-9a-f]{12}/);
+    expect(unlisted.err).toContain("chant workspace trust runner add");
   });
 });

package/src/workspace/ci-runner-key.ts

@@ -217,17 +217,38 @@ export function formatRunnerKeySetup(s: RunnerKeySetup, branch: string): string
 /**
  * The key `ci serve` signs with, checked before its first poll (#4099): the
  * `--key` file, else `CHANT_RUNNER_KEY`, else the host's key in the state
- * directory. Throws, with the command that lists it, when there is none or
- * `.chant/trust.json` at the target's head does not list it with the runner
- * role. With `unsigned` there is no key and nothing is checked.
+ * directory. Signing is opt-in (#4156):
+ *
+ * - With no key, `ci serve` serves unsigned and says so only in `note`.
+ * - A key `.chant/trust.json` at the target's head does not list with the
+ *   runner role, or a target branch it can't find to check against, leaves
+ *   it serving unsigned, with one `warning`.
+ * - With `required` (the declaration's `ci.green.signedSince`) each of
+ *   those refuses to start, as before #4156.
+ *
+ * A key that is not an Ed25519 private key in PEM, or a `--key` file that
+ * can't be read, refuses either way. `unsigned` (`--unsigned`) skips the
+ * key without `required` and is ignored with it.
  */
-export function ciServeRunnerKey(req: { top: string; stateDir: string; branch: string; keyFile?: string; envKey?: string; unsigned?: boolean }): { pem?: string; fromFlag: boolean; source: string } {
-  if (req.unsigned) return { fromFlag: false, source: "none (--unsigned)" };
+export function ciServeRunnerKey(req: {
+  top: string;
+  stateDir: string;
+  branch: string;
+  keyFile?: string;
+  envKey?: string;
+  unsigned?: boolean;
+  /** The declaration's `ci.green.signedSince`, when it sets one: every run must then be signed. */
+  required?: string | null;
+}): { pem?: string; fromFlag: boolean; source: string; warning?: string; note?: string } {
+  const required = req.required ?? null;
+  const optIn = `ci.green.signedSince is ${required}, so every run must be signed`;
+  if (req.unsigned && !required) return { fromFlag: false, source: "none (--unsigned)", note: "runs are not signed (--unsigned)" };
   const host = req.keyFile === undefined && !req.envKey ? hostRunnerKey(req.stateDir) : undefined;
   const pem = req.keyFile !== undefined ? readFileSync(req.keyFile, "utf-8") : req.envKey || host?.pem;
   const source = req.keyFile !== undefined ? req.keyFile : req.envKey ? "CHANT_RUNNER_KEY" : (host?.path ?? join(req.stateDir, RUNNER_KEY_FILE));
   if (pem === undefined) {
-    throw new CiRunError(`there is no runner key: no --key, no CHANT_RUNNER_KEY and no ${source}. Make one with chant ci serve --setup-key, list it with --trust, or start with --unsigned`);
+    if (!required) return { fromFlag: false, source: "none", note: "runs are not signed: there is no runner key. To verify who ran a job, add one with chant ci serve --setup-key --trust" };
+    throw new CiRunError(`${optIn}, and there is no runner key: no --key, no CHANT_RUNNER_KEY and no ${source}. Make one with chant ci serve --setup-key and list it with --trust`);
   }
   let publicKey: string;
   try {
@@ -236,13 +257,17 @@ export function ciServeRunnerKey(req: { top: string; stateDir: string; branch: s
     throw new CiRunError(`the runner key from ${source} is not an Ed25519 private key in PEM: ${message(err)}`);
   }
   const head = targetHead(req.top, req.branch);
-  if (!head) throw new CiRunError(`there is no branch ${req.branch} here or on origin, so the runner key can't be checked against its .chant/trust.json; fetch it, or start with --unsigned`);
+  if (!head) {
+    const why = `there is no branch ${req.branch} here or on origin, so the runner key can't be checked against its .chant/trust.json`;
+    if (required) throw new CiRunError(`${optIn}, and ${why}; fetch it`);
+    return { fromFlag: false, source, warning: `${why}, so runs are not signed; fetch it to sign them` };
+  }
   const listed = runnerKeyListed(req.top, head.commit, pem);
   if (!listed.ok) {
-    throw new CiRunError(
-      `the runner key from ${source} is not trusted at ${branchAt(req.branch, head.commit)}: ${listed.reason}\n` +
-        `  List it on a branch for review with chant ci serve --setup-key --trust, or run ${trustCommand(defaultRunnerPrincipal(), publicKey)} in a checkout of ${req.branch} and merge the change. Start with --unsigned to serve without signing.`,
-    );
+    const why = `the runner key from ${source} is not trusted at ${branchAt(req.branch, head.commit)}: ${listed.reason}`;
+    const fix = `List it on a branch for review with chant ci serve --setup-key --trust, or run ${trustCommand(defaultRunnerPrincipal(), publicKey)} in a checkout of ${req.branch} and merge the change.`;
+    if (required) throw new CiRunError(`${optIn}, and ${why}\n  ${fix}`);
+    return { fromFlag: false, source, warning: `${why}. Runs are not signed until it is. ${fix}` };
   }
   return { pem, fromFlag: req.keyFile !== undefined, source };
 }