@intentius/chant 0.124.31 → 0.124.32

package/dist/workspace/ci-run.js

@@ -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";
 import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
@@ -53,14 +77,17 @@ import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prLoopJobs, prLoopSetup, PR_LOOP_I
 import { detectForge, ForgeEnvironmentError, forgeFromEnv, FORGE_KINDS } from "../pr-forge.js";
 import { PR_APPLY_GATE } from "../pr-loop.js";
 import { formatError, formatWarning } from "../cli/format.js";
-import { pushLifecycleReport } from "../lifecycle/git.js";
+import { resolveCiJob } from "../lifecycle/release-ledger.js";
+import { fetchLifecycleStatus, pushLifecycleReport } from "../lifecycle/git.js";
 import { ACTIVITY_PROFILES } from "../op/activity-profiles.js";
 import { shellCmd } from "../op/activities/shell.js";
 import { OpRunFailure, runOpLocally } from "../op/local-executor.js";
 import { redactText } from "../op/redact.js";
 import { findWorkspaceRoot } from "../project-root.js";
 import { parseReportUrl, reportKey } from "../pr-report-url.js";
-import { ciTagSigner, RUNNER_KEY_ENV } from "./ci-green.js";
+import { reportUrlOf } from "./ci-report-url.js";
+import { ciTagSigner, RUNNER_KEY_ENV, signedRunsRequired } from "./ci-green.js";
+import { loadRunnerKey } from "./trust/dsse.js";
 import { ciRedactor, ciSecretsFor, CI_SECRETS_ENV, readCiSecrets } from "./ci-secrets.js";
 import { updateCiRunIndex } from "./ci-run-index.js";
 import { resolveMemberContext } from "./member-pipeline.js";
@@ -72,6 +99,8 @@ export const CI_JOB_NAMES = ["plan", "apply"];
 export const CI_JOB_OPS = { plan: "pr-plan", apply: "pr-apply" };
 /** Where a job the chant runner ran says it ran (#4094). */
 export const CHANT_RUNNER_ORIGIN = { forge: "chant" };
+/** Where a job `chant ci run --local` ran says it ran (#4161): this machine, outside CI. */
+export const CHANT_LOCAL_ORIGIN = { 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"];
 /**
@@ -190,6 +219,17 @@ function exitCodeOf(error) {
     const m = /command exited (\d+)/.exec(error ?? "");
     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) {
+    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) => text.split("\n").find((l) => l.trim() !== "")?.trim() ?? text;
 /**
@@ -396,7 +436,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 });
 }
@@ -413,12 +455,21 @@ export async function ciRun(req) {
     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)
+    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 ")}`);
-    const jobEnv = ciJobEnv(job, {
+    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 },
@@ -426,11 +477,15 @@ export async function ciRun(req) {
         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)
@@ -438,23 +493,72 @@ export async function ciRun(req) {
         throw err;
     }
 }
+/** The generator's options for a `--local` job (#4161): the same, with no report URL. */
+function localLoop(loop) {
+    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) {
+    return Object.fromEntries(Object.entries(env).filter(([, value]) => value.length >= 8));
+}
+/** The variables of `env` that have a value. */
+function definedEnv(env) {
+    const out = {};
+    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, at) {
+    // #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) => (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, commit, inPlace) {
+    return inPlace ? { dir: top, remove() { } } : freshCheckout(top, commit);
+}
 /** {@link ciRun} once the job and its environment are known. */
 async function runCiJob(req, at) {
     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;
-    const early = [];
-    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 = 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({
@@ -462,7 +566,7 @@ async function runCiJob(req, at) {
             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 } : {}),
         });
@@ -474,14 +578,14 @@ async function runCiJob(req, at) {
             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, description) => {
-            if (!req.status)
+            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)}`);
@@ -498,7 +602,7 @@ async function runCiJob(req, at) {
                 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 } : {}),
@@ -533,28 +637,40 @@ async function runCiJob(req, at) {
         let report = null;
         if (existsSync(written)) {
             report = resolve(cwd, req.output ?? PR_LOOP_REPORT_DIR);
-            cpSync(written, report, { recursive: true });
-            if (redact)
-                redactTree(report, redact);
+            // 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 (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) });
+        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) });
         }
-        if (ledgerError)
+        // 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 = 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 pushed = 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 } : {}),
         };
     }
     finally {
@@ -592,18 +708,39 @@ export function formatCiRun(r) {
         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)
+    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) {
+    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_]*$/;
 /** The host's runner key in `--state`, or in ci serve's default state directory, when `--setup-key` made one there (#4099). */
 function hostRunnerKeyAt(cwd, statePath) {
@@ -647,10 +784,14 @@ export async function runCiRun(ctx) {
         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, 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, 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 } : {}),
@@ -660,14 +801,11 @@ export async function runCiRun(ctx) {
             ...(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 } : {}),
@@ -681,8 +819,12 @@ export async function runCiRun(ctx) {
         });
         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 }));

package/dist/workspace/ci-runner-key.d.ts

@@ -101,9 +101,18 @@ export declare function formatRunnerKeySetup(s: RunnerKeySetup, branch: 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 declare function ciServeRunnerKey(req: {
     top: string;
@@ -112,9 +121,13 @@ export declare function ciServeRunnerKey(req: {
     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;
 };
 //# sourceMappingURL=ci-runner-key.d.ts.map

package/dist/workspace/ci-runner-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci-runner-key.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-runner-key.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ci-runner-key.d.ts","sourceRoot":"","sources":["../../src/workspace/ci-runner-key.ts"],"names":[],"mappings":"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"}

package/dist/workspace/ci-runner-key.js

@@ -184,18 +184,31 @@ export function formatRunnerKeySetup(s, branch) {
 /**
  * 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) {
-    if (req.unsigned)
-        return { fromFlag: false, source: "none (--unsigned)" };
+    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;
     try {
@@ -205,12 +218,19 @@ export function ciServeRunnerKey(req) {
         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 };
 }

package/dist/workspace/ci-serve.d.ts

@@ -23,8 +23,26 @@
  *   as its `--resume` record, so a re-run of a failed apply at the same
  *   commit finishes under the approval it has. This replaces the forge's CI
  *   cache.
+ * - A gate per wave (#4003). With `--wave-gate` the apply job runs
+ *   `pr-apply --wave-gate`, which applies the waves in order and stops at
+ *   the first whose moved plan waits on its own gate. The job fails, and the
+ *   resume record keeps the waves that applied; once the wave's plan is
+ *   approved, `rerunFailed` runs the apply again and it carries on from
+ *   that wave.
  * - Capacity. At most `maxJobs` jobs run at once. A job over the limit is not
  *   recorded, so a later poll starts it.
+ * - Fast-forwards only (#4122). An apply runs only when the target's new head
+ *   descends from the head seen before it. Any other move, such as a force
+ *   push back to an older commit, is recorded as seen and not applied.
+ * - `[skip ci]` (#4122). A target head or pull request head whose commit
+ *   message says `[skip ci]` or `[ci skip]` is recorded as seen and not run,
+ *   as Actions does.
+ * - The forge's ledger (#4121). Before each job, when no other job of this
+ *   serve runs, the clone's `chant/lifecycle` follows the forge's: it is
+ *   deleted when the forge has none, and reset to the forge's when neither
+ *   contains the other. Each is a warning. A local branch ahead of the
+ *   forge's keeps its facts, and the job's push sends them. Nothing here
+ *   pushes the ledger.
  *
  * Host mode only: each job runs in a fresh worktree on this host as this
  * user, with the clean environment `ciRun` gives it. A pull request from a
@@ -85,9 +103,11 @@ export interface CiServeState {
     env: string;
     branch: string;
     member?: string;
-    /** The target branch's head the last apply was measured to, or the head the first poll found. */
+    /** The target branch's head the last apply was measured to, or the last head seen and not applied. */
     target?: string;
     jobs: Record<string, CiServeJobState>;
+    /** Plans seen and not run, by state key, with why (#4122). */
+    skipped?: Record<string, "skip-ci">;
 }
 /** What a pass did, in order, for the log. */
 export type CiServeEvent = {
@@ -125,6 +145,19 @@ export type CiServeEvent = {
     status: "ok" | "fail";
     failure?: string;
     report?: string;
+} | {
+    type: "not-run";
+    job: CiJobName;
+    commit: string;
+    pr?: number;
+    reason: "not-fast-forward" | "skip-ci";
+    branch?: string;
+    from?: string;
+} | {
+    type: "ledger";
+    action: "deleted" | "reset";
+    local: string;
+    forge?: string;
 } | {
     type: "error";
     message: string;
@@ -168,17 +201,34 @@ export declare function ciServeKey(t: {
     commit: string;
     pr?: number;
 }): string;
+/**
+ * Make the clone's `chant/lifecycle` follow the forge's (#4121). The clone's
+ * branch outlives the forge's, so a ledger the forge deleted or rewrote would
+ * make the next pr-apply find the two diverged and stall.
+ *
+ * - The forge has none: the local branch and its remote-tracking ref go.
+ * - Neither contains the other: the local branch and its remote-tracking ref
+ *   are reset to the forge's tip.
+ * - The local branch is ahead of the forge's, or behind it, or the same: it
+ *   is left, and an apply's push sends what it holds that the forge lacks.
+ *
+ * Nothing is pushed, so a rewritten ledger never goes back to the forge. A
+ * forge that can't be reached leaves everything as it is; the job's own
+ * fetch says why.
+ */
+export declare function reconcileCiServeLedger(top: string): CiServeEvent | undefined;
 /** Where a serve keeps its state when `--state` names nowhere: beside the run events, in the repository's common git directory. */
 export declare function defaultCiServeStateDir(cwd: string): string;
 /** The state file, or a new one. */
 export declare function readCiServeState(file: string, fresh: Omit<CiServeState, "schema" | "jobs">): CiServeState;
 /**
  * One poll of the forge, as triggers: an apply when the target's head moved
- * since the last apply (none on the first poll, which only notes the head),
+ * since the last apply by a fast-forward (none on the first poll, which only
+ * notes the head, and none for a head whose message says `[skip ci]`),
  * then a plan for each open pull request head not yet planned, oldest pull
  * request first. A job already in the state file is left out unless it
- * failed and `rerunFailed` is set. The first poll's head is written to the
- * state file.
+ * failed and `rerunFailed` is set. The first poll's head, and a head seen
+ * and not applied, are written to the state file.
  */
 export declare function ciServeObserve(opts: CiServeOptions, rt?: CiServeRuntime): Promise<{
     triggers: CiServeTrigger[];