@intentius/chant 0.124.31 → 0.124.33

package/src/cli/handlers/run-components-exit.test.ts

@@ -0,0 +1,99 @@
+/**
+ * `chant run --components` exits 3 when a step refuses a plan that moved
+ * since it was approved (#3997), on the single-component path and on the
+ * driver's `all` and list paths. Discovery and the capability registry are
+ * fakes; the run is the real `runComponents` on the local runtime.
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { Component } from "../../components/component";
+import type { ParsedArgs } from "../registry";
+
+const discoverComponentsMock = vi.fn();
+vi.mock("../../components/discover", () => ({
+  discoverComponents: (...args: unknown[]) => discoverComponentsMock(...args),
+}));
+
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfig: async () => ({ config: {} }) };
+});
+
+/** The error a component's step throws, in place of applying. */
+const refusal = new Map<string, Error>();
+
+vi.mock("../../op/runtimes/local", async () => {
+  const { CapabilityRegistry } = await import("../../components/capability");
+  const { runComponents } = await import("../../components/cli-support");
+  const { memoryGateLedgerPort } = await import("../../op/gate");
+  const registry = new CapabilityRegistry();
+  registry.register({
+    kind: "fake-apply",
+    async run(ctx: { component: string }) {
+      const err = refusal.get(ctx.component);
+      if (err) throw err;
+      return {};
+    },
+  } as never);
+  return {
+    createLocalOpRuntime: () => ({
+      name: "local",
+      runComponents: (path: string, selector: string, options: object) =>
+        runComponents(path, selector, { ...options, registry, config: {}, revision: null, gates: memoryGateLedgerPort() }),
+    }),
+  };
+});
+
+const { runOpComponents } = await import("./run");
+
+const component = (name: string, dependsOn: string[] = []): Component => ({
+  name,
+  dependsOn,
+  deploy: [{ phase: "Apply", steps: [{ kind: "fake-apply" }] }],
+});
+
+const ctx = (selector: string) =>
+  ({
+    args: { command: "run", path: selector, components: true, on: "local", format: "", fix: false, watch: false, verbose: false, help: false, live: false } as ParsedArgs,
+    plugins: [],
+  }) as never;
+
+beforeEach(() => {
+  refusal.clear();
+  const estate = [component("net"), component("app", ["net"])];
+  discoverComponentsMock.mockResolvedValue({
+    components: new Map(estate.map((c) => [c.name, { component: c, exportName: c.name, filePath: `${c.name}.component.ts` }])),
+    sourceFiles: [],
+    errors: [],
+  });
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+const marks: Array<[string, number, object]> = [
+  ["marked planMoved", 3, { planMoved: true }],
+  ["with exitCode 3", 3, { exitCode: 3 }],
+  ["with exitCode 7", 1, { exitCode: 7 }],
+  ["unmarked", 1, {}],
+];
+
+describe("chant run --components: a step that refuses a moved plan exits 3 (#3997)", () => {
+  test.each(marks)("one component, its step refusing %s: exit %i", async (_label, code, mark) => {
+    refusal.set("app", Object.assign(new Error("app: refusing to apply, the plan moved"), mark));
+    expect(await runOpComponents(ctx("app"))).toBe(code);
+  });
+
+  test.each(marks)("all, a step refusing %s: exit %i", async (_label, code, mark) => {
+    refusal.set("net", Object.assign(new Error("net: refusing to apply, the plan moved"), mark));
+    expect(await runOpComponents(ctx("all"))).toBe(code);
+  });
+
+  test("a list that pulls in a dependency whose step refuses a moved plan exits 3", async () => {
+    refusal.set("net", Object.assign(new Error("net: refusing to apply, the plan moved"), { planMoved: true }));
+    expect(await runOpComponents(ctx("app,net"))).toBe(3);
+  });
+});

package/src/cli/handlers/run-signer.test.ts

@@ -0,0 +1,79 @@
+/**
+ * #4156: `chant run`'s runner key is opt-in hardening. A `CHANT_RUNNER_KEY`
+ * that `.chant/trust.json` does not list leaves the run unsigned with no
+ * warning, unless the declaration sets `ci.green.signedSince`. A key that is
+ * not an Ed25519 PEM is an error either way.
+ */
+
+import { createPublicKey, generateKeyPairSync } from "node:crypto";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { cleanScratch, declaration, git, scratchDir, writeFiles } from "../../workspace/__fixtures__/contract-repo";
+import { sshFromEd25519 } from "../../workspace/trust/dsse";
+import type { CommandContext } from "../registry";
+import { runSignerFor } from "./run";
+
+const home = process.cwd();
+const saved = process.env.CHANT_RUNNER_KEY;
+afterEach(() => {
+  process.chdir(home);
+  if (saved === undefined) delete process.env.CHANT_RUNNER_KEY;
+  else process.env.CHANT_RUNNER_KEY = saved;
+  vi.restoreAllMocks();
+  cleanScratch();
+});
+
+function key(): { pem: string; ssh: string } {
+  const { privateKey } = generateKeyPairSync("ed25519");
+  const jwk = createPublicKey(privateKey).export({ format: "jwk" }) as { x: string };
+  return { pem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(), ssh: sshFromEd25519(Buffer.from(jwk.x, "base64url")) };
+}
+
+function repo(green?: Record<string, unknown>): string {
+  const root = scratchDir("chant-run-signer-");
+  git(root, "init", "-q");
+  for (const [k, v] of [["user.name", "t"], ["user.email", "t@example.com"], ["commit.gpgsign", "false"]]) git(root, "config", k!, v!);
+  writeFiles(root, {
+    "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], green ? { ci: { green } } : {}),
+    ".chant/trust.json": JSON.stringify({ schema: 1, runners: [{ principal: "ci-bot", class: "runner", key: key().ssh }], roles: { runner: ["ci-bot"] } }),
+    "app/a.txt": "a\n",
+  });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "init");
+  return root;
+}
+
+async function signer(root: string, pem: string, verbose = false) {
+  process.chdir(root);
+  process.env.CHANT_RUNNER_KEY = pem;
+  const err: string[] = [];
+  vi.spyOn(console, "error").mockImplementation((s: string) => void err.push(String(s)));
+  const result = await runSignerFor({ args: { verbose } } as unknown as CommandContext);
+  return { result, err: err.join("\n") };
+}
+
+describe("chant run's runner key from the environment (#4156)", () => {
+  test("a key trust.json does not list leaves the run unsigned and quiet, with one line under --verbose", async () => {
+    const root = repo();
+    const quiet = await signer(root, key().pem);
+    expect(quiet.result).toBeUndefined();
+    expect(quiet.err).toBe("");
+    const verbose = await signer(root, key().pem, true);
+    expect(verbose.result).toBeUndefined();
+    expect(verbose.err).toContain("CHANT_RUNNER_KEY is set, and the run is not signed");
+  });
+
+  test("with ci.green.signedSince the same key warns", async () => {
+    const root = repo();
+    const head = git(root, "rev-parse", "HEAD");
+    writeFiles(root, { "chant.workspace.json": declaration([{ name: "app", dir: "app", kind: "other", because: "the app" }], { ci: { green: { branch: "main", phases: { test: ["test"] }, require: ["test"], signedSince: head } } }) });
+    const r = await signer(root, key().pem);
+    expect(r.result).toBeUndefined();
+    expect(r.err).toContain(`ci.green.signedSince (${head}) will not count it`);
+  });
+
+  test("a key that is not an Ed25519 PEM is an error", async () => {
+    const r = await signer(repo(), "not a key");
+    expect(r.result).toBeNull();
+    expect(r.err).toContain("CHANT_RUNNER_KEY is not an Ed25519 private key in PEM");
+  });
+});

package/src/cli/handlers/run.ts

@@ -31,7 +31,7 @@ import type { RunEvent } from "../../run-event";
 import { openCliRunEvents, refusesBothStreams, stdoutLine } from "../run-events";
 import { maybeRecordAutoRelease } from "../../components/auto-release";
 import { maybePersistBuildManifest } from "../../components/manifest-persistence";
-import type { DriverComponentResult } from "../../components/driver";
+import { failedRunExitCode, type DriverComponentResult } from "../../components/driver";
 import { isComponentList, type ComponentRunPlan, type RunComponentsResult } from "../../components/cli-support";
 import { resolveCiRun, type ReleaseRecord, type RunOrigin } from "../../lifecycle/release-ledger";
 import { gateAdmission, gateApprover } from "../../components/promote";
@@ -730,9 +730,9 @@ type StewardTurnGate =
  * `chant run <op>` for an Op a declared steward lists is one of that
  * steward's turns, not a run beside it (#2750, follow-up to #2731).
  *
- * On fountain, the run belongs on the steward's thread: without `--on
+ * On fountain, the run belongs in the steward's conversation: without `--on
  * fountain` this refuses outright, naming the command that posts it there
- * instead (the fountain runtime's own turn already refuses a busy teammate,
+ * instead (the fountain runtime's own turn already refuses a busy steward,
  * unretried — see chant-fountain-ops).
  *
  * In the local form, the run takes the steward's turn lease
@@ -771,15 +771,15 @@ async function stewardTurnGate(opName: string, ctx: CommandContext): Promise<Ste
   const form = stewardFormFor(owner, env);
 
   if (form === "fountain") {
-    // `run.on: "fountain"` asks for the steward's thread as much as the flag
+    // `run.on: "fountain"` asks for the steward's conversation as much as the flag
     // does (#2523).
     if ((await chooseOpRuntime(ctx, true))?.on === "fountain") return { ok: true };
     return {
       ok: false,
       message: `Op "${opName}" is one of steward "${owner.name}"'s Ops, which runs on fountain in environment "${env}"`,
       hint:
-        `Run \`chant run ${opName} --on fountain\` so it posts to "${owner.name}"'s thread. ` +
-        `A plain \`chant run ${opName}\` would run it outside that thread, beside the steward instead of one of its turns.`,
+        `Run \`chant run ${opName} --on fountain\` so it posts to "${owner.name}"'s conversation. ` +
+        `A plain \`chant run ${opName}\` would run it outside that conversation, beside the steward instead of one of its turns.`,
     };
   }
 
@@ -1283,7 +1283,10 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
     }
   }
 
-  return result.success ? 0 : 1;
+  // A step that refused a plan that moved since it was approved exits 3
+  // (#3997). `--gated-exit` doesn't remap it: the run failed.
+  if (result.success) return 0;
+  return result.run ? failedRunExitCode(result.run.results) : 1;
 }
 
 /**
@@ -1359,9 +1362,10 @@ async function runOpOnResolvedRuntime(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  // #4044: a runner key signs the run's record as it settles, so `ci tick`
-  // can count the run. `--key` must be a runner key; the PEM in
-  // CHANT_RUNNER_KEY that is not one leaves the run unsigned, with a warning.
+  // #4044: a runner key signs the run's record as it settles, so a reader
+  // can see who ran it. `--key` must be a runner key; the PEM in
+  // CHANT_RUNNER_KEY that trust.json does not list leaves the run unsigned,
+  // with a warning only when ci.green.signedSince asks for signed runs (#4156).
   const signRecord = await runSignerFor(ctx);
   if (signRecord === null) {
     await stewardGate?.release?.();
@@ -1564,10 +1568,13 @@ const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
  * What signs the run's record (#4044): the runner key `--key` names, or the
  * PEM in `CHANT_RUNNER_KEY`, checked against `.chant/trust.json` at `HEAD`.
  * Undefined when neither is given. Null, after printing why, when `--key`
- * is not a runner key; an unusable `CHANT_RUNNER_KEY` only warns, since the
- * variable may be set for `ci tick` in a job that also runs Ops.
+ * is not a runner key, or either is not an Ed25519 PEM. A `CHANT_RUNNER_KEY`
+ * that trust.json does not list leaves the run unsigned (#4156): quietly,
+ * with a line under `--verbose`, unless `ci.green.signedSince` asks for
+ * signed runs, which warns. The variable may be set for `ci tick` in a job
+ * that also runs Ops.
  */
-async function runSignerFor(ctx: CommandContext): Promise<((record: OpRunRecord) => NonNullable<OpRunRecord["statement"]>) | undefined | null> {
+export async function runSignerFor(ctx: CommandContext): Promise<((record: OpRunRecord) => NonNullable<OpRunRecord["statement"]>) | undefined | null> {
   const fromFlag = ctx.args.key !== undefined;
   let pem: string | undefined;
   try {
@@ -1577,9 +1584,17 @@ async function runSignerFor(ctx: CommandContext): Promise<((record: OpRunRecord)
     return null;
   }
   if (pem === undefined) return undefined;
+  // Loaded only when a key is given, so a run without one loads no workspace code (level 0, #2525).
+  const { opRunSigner, signedRunsRequired } = await import("../../workspace/ci-green");
+  const { loadRunnerKey } = await import("../../workspace/trust/dsse");
+  try {
+    loadRunnerKey(pem);
+  } catch (err) {
+    // A key that is there and is not one is an error either way: the caller asked to sign (#4156).
+    console.error(formatError({ message: `${fromFlag ? `--key ${ctx.args.key}` : RUNNER_KEY_ENV} is not an Ed25519 private key in PEM: ${err instanceof Error ? err.message : String(err)}` }));
+    return null;
+  }
   try {
-    // Loaded only when a key is given, so a run without one loads no workspace code (level 0, #2525).
-    const { opRunSigner } = await import("../../workspace/ci-green");
     return opRunSigner(process.cwd(), pem);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -1587,7 +1602,10 @@ async function runSignerFor(ctx: CommandContext): Promise<((record: OpRunRecord)
       console.error(formatError({ message: `the run would not be signed: ${message}` }));
       return null;
     }
-    console.error(formatWarning({ message: `${RUNNER_KEY_ENV} is set, and the run will not be signed: ${message}` }));
+    // #4156: signing is opt-in, so a key trust.json does not list warns only when ci.green.signedSince asks for signed runs.
+    const required = signedRunsRequired(process.cwd());
+    if (required) console.error(formatWarning({ message: `${RUNNER_KEY_ENV} is set, and the run will not be signed, so ci.green.signedSince (${required}) will not count it: ${message}` }));
+    else if (ctx.args.verbose) console.error(`${RUNNER_KEY_ENV} is set, and the run is not signed: ${message}`);
     return undefined;
   }
 }

package/src/cli/main.test.ts

@@ -666,6 +666,18 @@ describe("resolveCommand", () => {
     expect(result!.compound).toBe(false);
   });
 
+  test("`sync` is an alias for `update` (#3988)", () => {
+    const result = resolveCommand(makeArgs({ command: "sync" }), [...testRegistry, { name: "update", handler: noop }]);
+    expect(result!.def.name).toBe("update");
+    expect(result!.compound).toBe(false);
+  });
+
+  test("`sync <path>` resolves to `update` with the path kept (#3988)", () => {
+    const result = resolveCommand(makeArgs({ command: "sync", path: "./proj" }), [...testRegistry, { name: "update", handler: noop }]);
+    expect(result!.def.name).toBe("update");
+    expect(result!.compound).toBe(false);
+  });
+
   test("resolves components status as compound command", () => {
     const result = resolveCommand(makeArgs({ command: "components", path: "status" }), testRegistry);
     expect(result!.def.name).toBe("components status");
@@ -1021,4 +1033,10 @@ describe("chant --help", () => {
     const commands = new Set(commandRegistry.map((def) => def.name.split(" ")[0]));
     expect([...commands].filter((name) => !listed.has(name))).toEqual([]);
   });
+
+  test("names `sync` as the alias of `update` (#3988)", () => {
+    const source = readFileSync(join(import.meta.dirname, "main.ts"), "utf-8");
+    const help = source.slice(source.indexOf("function printHelp("), source.indexOf("Options:", source.indexOf("function printHelp(")));
+    expect(help).toMatch(/^ {2}update \(alias: sync\)/m);
+  });
 });

package/src/cli/main.ts

@@ -238,33 +238,45 @@ CI:
                         its window, newest first, each green, revoked or
                         undecided with its required phases' results. Reads
                         local tags; --forge reads check runs for undecided
-                        commits, and source runs reads the signed Op runs on
-                        the local chant/lifecycle. --since replaces the window.
+                        commits, and source runs reads the Op runs on the
+                        local chant/lifecycle, signed or not. --since replaces the window.
   ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>]
                         Tag each commit within ci.green's window whose
                         required phases all passed ci/green/<sha>, and revoke
                         a green one that now fails ci/revoked/<sha>. Reads
                         check runs from the forge, or with source runs
                         (ci.green.source or --source) the Op runs on
-                        chant/lifecycle that a runner key signed. Pushes the
+                        chant/lifecycle; with ci.green.signedSince, the ones a
+                        runner key signed. Pushes the
                         tags. --key, or the PEM in CHANT_RUNNER_KEY, signs
-                        each tag with a runner key.
+                        each tag with a runner key. A cancelled run leaves a
+                        commit unbuilt, not red, and a failed run is run
+                        again once. A phase with build: newest leaves the
+                        commits a newer run superseded unbuilt, and a red
+                        one starts a bisect: a ci/build/<sha> tag the tick
+                        starts the phase's workflow at. Each commit judged
+                        gets a _ci/<sha>.json record on chant/lifecycle.
   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>] [--image <image>]
+              [--forge github|gitlab|forgejo] [--gate <name>] [--wave-gate <name>]
+              [--branch <name>] [--events-json] [--report-url <url>] [--image <image>]
               [--before-script <line>]... [--pr-build]
               [--pr-build-command <line>] [--chant <command>]
               [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>]
-              [-o <dir>]
+              [-o <dir>] [--wave <k>] [--require-review]
               [--no-status] [--status-url <url template>]
-                        Run the pull-request pipeline's plan or apply job as
+              [--in-place | --local] [--no-push] [--require-runner-start] [--verbose]
+                        Run the pull-request pipeline's plan, record or apply job as
                         a pipeline Op in a fresh worktree of --commit (default
                         HEAD) with a clean environment. --base and --pr stand
                         in for the forge's event values. --pr-build runs
                         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). With a forge
+                        pr-plan, pr-record or pr-apply on chant/lifecycle, which ci tick
+                        from runs counts, signed when --key or CHANT_RUNNER_KEY
+                        gives a runner key, and copies the report to -o
+                        (default .chant/pr). --in-place runs in this checkout
+                        at HEAD, as a generated forge job does, and names the
+                        forge's run in the record; --no-push keeps the record
+                        local. Exits with the command's code. 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.
@@ -275,24 +287,55 @@ CI:
                         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.
+                        Without --report-url, the workspace's ci.reportUrl.
+                        --local runs the job on this machine: the record is
+                        kept on the local chant/lifecycle with runOrigin
+                        local and is never pushed, no status is set, nothing
+                        goes under a report URL, and ci tick does not count it.
+                        --require-runner-start refuses the job before its
+                        first step unless a runner-start statement, signed by
+                        a runner key .chant/trust.json at --base lists, names
+                        this forge job.
+  ci runner-start sign --key <runner key.pem> --principal <name> --job <json|@file> [-o <file>]
+                        For the provisioner that starts a runner for one job:
+                        sign the job's system, repo, run, attempt, job,
+                        commit and runner name, and print the envelope.
+  ci runner-start verify [--base <rev>] [--commit <sha>] [--json]
+                        In the job: check the statement in CHANT_RUNNER_START,
+                        or the file CHANT_RUNNER_START_FILE names (default
+                        /run/chant/runner-start.json), against the forge's
+                        variables and .chant/trust.json at --base (default
+                        origin/HEAD). Exits 1 unless it verifies.
+  ci run --at <sha>     Ask for every required phase at a commit of the
+                        green branch with a ci/build/<sha> tag, and start the
+                        workflows holding them there on GitHub when a token
+                        is set; otherwise the next tick, or ci serve
+                        --build-command, does.
+  ci runs [--report-url <url>] [--json]
+                        List the runs in the index at the report URL (default
+                        the workspace's ci.reportUrl), newest first.
   ci serve --forge forgejo|github --repo <owner/repo> --env <env>
               [--interval <s>] [--max-jobs <n>] [--state <dir>]
               [--author <login>]... [--once] [--rerun-failed] [--unsigned]
-              [ci run's job flags]
+              [--apply-on-merge] [--build-command <line>] [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
-                        request head and ci run apply for each new commit on
-                        the branch. Dedupes on job and commit in a state file
+                        request head and ci run record for each new commit on
+                        the branch, then ci tick from the runs when the
+                        workspace declares ci.green. A merge deploys nothing;
+                        --apply-on-merge runs ci run apply in place of the
+                        record, and --wave-gate needs it. Dedupes on job and commit in a state file
                         under --state, takes a lease per apply group, keeps
                         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. Refuses to start when its
-                        runner key is not listed in .chant/trust.json at the
-                        target's head, unless --unsigned
+                        failed apply or plan again. Signs runs with a runner
+                        key when .chant/trust.json at the target's head lists
+                        it, and serves unsigned otherwise; with
+                        ci.green.signedSince it refuses to start without one.
+                        --build-command runs <line> once per ci/build/<sha>
+                        tag, in a fresh worktree of the commit, with
+                        CHANT_BUILD_COMMIT and CHANT_BUILD_PHASES set
   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
@@ -310,10 +353,14 @@ CI:
                         or a GitHub App's id and key, pushes the tags with a
                         token that may tag commits changing workflow files.
                         --runner-key-secret hands the tick the runner key it
-                        signs its tags with.
+                        signs its tags with. For each phase that sets build,
+                        it also writes the triggers and concurrency of the
+                        workflows holding it: newest builds on pushes and by
+                        hand, one run at a time, and every gives each commit
+                        a run of its own.
 
 Releases:
-  release cut [<label>] [--yes] [--build <command>] [--param <k=v>]
+  release cut [<label>] [--at <sha>] [--yes] [--build <command>] [--param <k=v>]
               [--params-file <file>] [--src <dir>] [-o <file>] [--lexicon <name>]
               [--actor <name>] [--sign [<key file>]] [--json]
                         A dry run of a cut of this member from HEAD, which
@@ -332,19 +379,29 @@ Releases:
                         requires it. A project with no components releases
                         what chant build --env <env> writes: --src <dir> is
                         the build root, -o <file> the output (dist/build.yaml),
-                        --lexicon narrows it.
+                        --lexicon narrows it. --at <sha> cuts that commit of
+                        trunk from a temporary worktree instead of HEAD, so
+                        the checkout need not be clean. The label reaches
+                        every compile and build as CHANT_RELEASE_LABEL.
+  release candidates [--env <env>] [--json]
+                        The green commits of trunk a release can be cut from,
+                        newest first, each with the commits, work items, pull
+                        requests and flags it would ship, and what each
+                        environment runs.
   release publish <label|digest> [--yes] [--allow-unsigned]
                   [--require-provenance] [--json]
                         Publish a cut release to the targets release.publish
                         in chant.config.ts declares (npm, OCI registries,
-                        forge release assets), each with an SBOM and the
-                        release's provenance. A dry run without --yes.
-                        Refuses a revoked release, one whose signature does
-                        not verify against .chant/allowed_signers unless
-                        --allow-unsigned, and with a target a checkout that
-                        is not the release's commit. Warns first when the run
-                        has no OIDC token, so what it publishes carries no
-                        OIDC provenance; --require-provenance refuses instead.
+                        forge release assets), each with the release's
+                        provenance and an SBOM when it has a source. A dry
+                        run without --yes. Refuses a revoked release, and
+                        with a target a checkout that is not the release's
+                        commit. Under security verified-releases it refuses
+                        one whose signature does not verify against
+                        .chant/allowed_signers unless --allow-unsigned; under
+                        supply-chain it warns when the run has no OIDC token
+                        and refuses a target with no SBOM source.
+                        --require-provenance refuses a run with no OIDC.
   release verify <label|digest> [--json]
                         Check, offline, that the release was signed by a key
                         .chant/allowed_signers lists at the release's commit.
@@ -875,6 +932,10 @@ Lifecycle (alias: lc):
                             estate size rather than stack count (#2405)
   lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
+  lifecycle health <env>    Whether each declared service is up, separate from
+                            drift: ECS running vs desired, Route 53 health
+                            checks, Container Apps revisions, Cloud Run Ready.
+                            A failed read is "not read", never unhealthy (--json)
   lifecycle whoami <env>    Who chant would act as in each configured lexicon,
                             and what that principal is scoped to — read-only,
                             before anything acts (--json, --strict)
@@ -919,7 +980,12 @@ Component release ledger + status:
                             report and note (--base <ref> --pr <n>
                             [--forge github|gitlab|forgejo] posts them);
                             applies nothing
-  components pr-apply      On merge: plan the same members again and apply
+  components pr-record     On merge (#4168): plan the same members again,
+                            store the change set and write the merge record
+                            _merges/<commit>.json; applies and refuses
+                            nothing, and a plan that differs from the
+                            approved one sets a failing chant/record status
+  components pr-apply      With --apply-on-merge: plan the same members again and apply
                             them only if an approval stands for that digest
                             (chant approve pr-<n> pr-apply --plan <digest>);
                             a moved plan refuses with exit 3
@@ -929,6 +995,10 @@ Component release ledger + status:
                             member's loop, gate op pr-<n>-<member>;
                             --resume <file> finishes an apply that failed
                             partway under the same approval;
+                            --wave-gate <name>: apply a wave at a time, each
+                            planned after the one before applied, a moved
+                            wave waiting at <name>-wave-<k>, with --wave <k>
+                            for one wave per CI job;
                             --events-json, both commands: the run-event
                             stream on stdout; --report-url <s3 or file URL>,
                             both commands: copy the report, the change set
@@ -998,7 +1068,8 @@ Servers:
   serve mcp             Start the MCP server (stdio)
 
 Project:
-  update                Sync lexicon types into .chant/types/
+  update (alias: sync)  Sync lexicon types into .chant/types/ (does not install
+                        packages: run npm install first)
   doctor                Check project health and configuration
 
 Options:
@@ -1217,6 +1288,9 @@ async function loadPluginsOrExit(path: string, lexicon?: string): Promise<import
     plugins = await loadPlugins(lexiconNames);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
+    // #4116: a lexicon package the project has not installed is named as such first.
+    const { reportUninstalledDependencies } = await import("./dependencies");
+    reportUninstalledDependencies([errorMessage], resolve(path));
     console.error(formatError({ message: errorMessage }));
     process.exit(1);
   }
@@ -1366,6 +1440,8 @@ export const commandRegistry: CommandDef[] = [
   // #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.
+  // #4147: a provisioner's signed word that it started a runner for one job, signed and checked.
+  { name: "ci runner-start", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-runner-start")).runCiRunnerStart(ctx) },
   { 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.
@@ -1374,6 +1450,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "release publish", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleasePublish(ctx) },
   // #4049: check a release's signature offline.
   { name: "release verify", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseVerify(ctx) },
+  { name: "release candidates", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCandidates(ctx) },
   { name: "release list", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseList(ctx) },
   { name: "release export", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseExport(ctx) },
   { name: "release compile", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCompile(ctx) },
@@ -1484,6 +1561,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
   { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
   { name: "lifecycle whoami", requiresPlugins: true, handler: runLifecycleWhoami },
+  // #4177 — runtime health, separate from drift. Imported on first use.
+  { name: "lifecycle health", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/lifecycle-health")).runLifecycleHealth(ctx) },
   { name: "lifecycle teardown", requiresPlugins: true, handler: runLifecycleTeardown },
   { name: "lifecycle log", handler: runLifecycleLog },
   // #4036 — retention's garbage collection. Imported on first use.
@@ -1499,6 +1578,7 @@ export const commandRegistry: CommandDef[] = [
   // #3183 — the pull-request loop the generated CI runs. Imported on first use.
   { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPlan(ctx) },
   { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrApply(ctx) },
+  { name: "components pr-record", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrRecord(ctx) },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },
@@ -1725,6 +1805,13 @@ const isMain = isEntryPoint(process.argv[1], import.meta.url);
 if (isMain) {
   main().catch(async (err) => {
     const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+    // #4116: a failure to import a package the project has not installed is named as such first.
+    try {
+      const { reportUninstalledDependencies } = await import("./dependencies");
+      reportUninstalledDependencies([err instanceof Error ? err.message : String(err)], process.cwd());
+    } catch {
+      // The original error below is what matters.
+    }
     if (verbose && err instanceof Error && err.stack) {
       console.error(err.stack);
     } else {