@intentius/chant 0.124.30 → 0.124.32

package/src/cli/handlers/promote.test.ts

@@ -24,6 +24,8 @@ const writtenTemplates: unknown[] = [];
 let configEnvironments: unknown[] | undefined;
 let publishedDigest = "sha256:api";
 let failApplyFor: string | undefined;
+/** What `failApplyFor`'s apply throws; a plain error when unset. */
+let applyError: Error | undefined;
 
 vi.mock("../../lifecycle/git", () => ({
   getHeadCommit: async () => "abc123",
@@ -58,7 +60,7 @@ vi.mock("../../components/fan-out-support", () => ({
     step("docker-build", () => ({ digest: "sha256:rebuilt" }));
     step("publish-image", () => ({ digest: publishedDigest, uri: `reg/api@${publishedDigest}` }));
     step("apply", (ctx) => {
-      if (ctx.component === failApplyFor) throw new Error("apply failed");
+      if (ctx.component === failApplyFor) throw applyError ?? new Error("apply failed");
       return {};
     });
     // #4045: a planner whose member is provisional.
@@ -221,6 +223,7 @@ beforeEach(() => {
   configEnvironments = undefined;
   publishedDigest = "sha256:api";
   failApplyFor = undefined;
+  applyError = undefined;
   errors = [];
   logs = [];
   vi.spyOn(console, "error").mockImplementation((...m: unknown[]) => { errors.push(m.join(" ")); });
@@ -358,6 +361,21 @@ describe("chant components promote", () => {
     expect(appendReleaseRecordMock.mock.calls[0][0]).toMatchObject({ component: "api", env: "prod" });
   });
 
+  test.each([
+    ["marked planMoved", 3, { planMoved: true }],
+    ["with exitCode 3", 3, { exitCode: 3 }],
+    ["with exitCode 7", 1, { exitCode: 7 }],
+  ])("an apply that refuses its plan %s exits %i, and what deployed is still recorded (#3997)", async (_label, code, mark) => {
+    const web: DriverComponent = { ...api, name: "web" };
+    resolveTargetsMock.mockResolvedValue({ success: true, targets: [api, web] });
+    readReleaseLedgerMock.mockResolvedValue({ records: [staging, { ...staging, component: "web" }], malformed: 0 });
+    failApplyFor = "web";
+    applyError = Object.assign(new Error("web: refusing to apply, the plan moved"), mark);
+    expect(await runComponentsPromote(ctx({}))).toBe(code);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    expect(errors.join("\n")).toMatch(/promote failed at "web"/);
+  });
+
   test("--digest <component>=<digest> promotes the pinned release, not the latest one (#2602)", async () => {
     const web: DriverComponent = { ...api, name: "web" };
     resolveTargetsMock.mockResolvedValue({ success: true, targets: [api, web] });
@@ -795,6 +813,13 @@ describe("chant components redeploy", () => {
     ]);
     expect(errors.join("\n")).toMatch(/redeploy failed at "api"/);
   });
+
+  test("a redeploy whose apply refuses a moved plan exits 3 (#3997)", async () => {
+    failApplyFor = "api";
+    applyError = Object.assign(new Error("api: refusing to apply, the plan moved"), { planMoved: true });
+    expect(await runComponentsRedeploy(rd({}))).toBe(3);
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
 });
 
 describe("--events-json on promote, rollback and redeploy (#4041)", () => {

package/src/cli/handlers/promote.ts

@@ -58,7 +58,7 @@ import {
   type PromotionItem,
   type PromotionPlan,
 } from "../../components/promote";
-import type { DriverComponent } from "../../components/driver";
+import { failedRunExitCode, type DriverComponent } from "../../components/driver";
 import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
 import { approveCommand, describeGateMismatch, gateIsSealed, gitGateLedgerPort, type GateLedgerPort } from "../../op/gate";
 import type { ReleaseGateBinding } from "../../components/driver";
@@ -522,7 +522,8 @@ async function deployPlan(
 
   if (run.status !== "ok") {
     console.error(formatError({ message: `${verb} failed at "${run.failedComponent ?? "unknown"}"` }));
-    return 1;
+    // A step that refused a plan that moved since it was approved exits 3 (#3997).
+    return failedRunExitCode(run.results);
   }
   return 0;
 }

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");
@@ -836,6 +848,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace runs",
       "workspace signers",
       "workspace status",
+      "workspace trust",
       "workspace upgrade",
       "workspace verify",
       "workspace versions",
@@ -1020,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,34 +238,60 @@ 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.
   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>]... [--key <runner key.pem>] [-o <dir>]
+              [--pass-env <NAME>]... [--secrets <file>] [--key <runner key.pem>]
+              [-o <dir>] [--wave <k>] [--no-require-review]
+              [--no-status] [--status-url <url template>]
+              [--in-place | --local] [--no-push] [--verbose]
                         Run the pull-request pipeline's plan or apply job as
                         a pipeline Op in a fresh worktree of --commit (default
                         HEAD) with a clean environment. --base and --pr stand
                         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).
+                        pr-plan 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.
+                        --secrets (or CHANT_CI_SECRETS) names a dotenv or
+                        JSON file only its owner can read whose values the
+                        job gets, and which are shown as *** in the events,
+                        the record, the report and the output.
+                        With --report-url it also adds the run to
+                        <url>/runs/index.json, newest first, cut to the
+                        newest --run-index-limit entries (default 200).
+                        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.
+  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]
+              [--author <login>]... [--once] [--rerun-failed] [--unsigned]
               [ci run's job flags]
                         Poll the forge for open pull requests and the target
                         branch's head, and run ci run plan for each new pull
@@ -275,7 +301,16 @@ CI:
                         each apply's resume record there, and runs at most
                         --max-jobs (default 1) jobs at once. --once runs one
                         poll and waits for its jobs. --rerun-failed runs a
-                        failed apply or plan again.
+                        failed apply or plan again. 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
+  ci serve|run --setup-key [--trust [--principal <name>]] [--state <dir>] [--branch <name>]
+                        Make the host's runner key (Ed25519, mode 0600) in the
+                        state directory when there is none and print its public
+                        key. --trust commits its runner entry on a branch of its
+                        own and pushes it for review; the target branch is never
+                        written
   ci workflow [--workflow <name>]... [--output <file>]  Write
               [--chant <command>] [--install <command>]
               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
@@ -701,6 +736,13 @@ Workspace (level 1, #2524):
                         threshold of the old one. A commit an agent run made
                         is attested by the run's signed statement; with
                         attested-runs, only those commits must be
+  workspace trust runner add <principal> --key <ssh-ed25519 line or file> [--class runner|service] [--by <principal>] [--expect <digest>] [--dry-run]
+  workspace trust runner remove <principal> [--by <principal>] [--expect <digest>] [--dry-run]
+                        List a runner's key under runners in .chant/trust.json,
+                        granting a runner the runner role, or take both away,
+                        editing the file in place. --expect refuses the write
+                        when the file's digest has changed. Prints the
+                        trust-write document and the new digest; never commits
   workspace signers [--json] [rotate [--threshold <n>] | sign --key <file>]
                         Show the signer history at base, or propose the next
                         signer set and sign it with a current signer's key
@@ -899,6 +941,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
@@ -968,7 +1014,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:
@@ -1187,6 +1234,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);
   }
@@ -1335,6 +1385,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiWorkflow(ctx) },
   // #4094: one pull-request job as a pipeline Op in a fresh checkout, the chant runner's first slice.
   { name: "ci run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run")).runCiRun(ctx) },
+  // #4098: the run index at the report URL.
+  { name: "ci runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-run-index")).runCiRuns(ctx) },
   { name: "ci serve", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-serve")).runCiServe(ctx) },
   // #4026: the release cut from a green commit (ws-104). Imported on first use.
   { name: "release cut", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCut(ctx) },
@@ -1439,6 +1491,8 @@ export const commandRegistry: CommandDef[] = [
   // #2548 — an agent session's member, write scope and spec, for a session that resumes.
   { name: "workspace agent", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/agent-cli")).runWorkspaceAgent(ctx) },
   { name: "workspace verify", handler: async (ctx) => (await import("../workspace/trust/verify-cli")).runWorkspaceVerify(ctx) },
+  // #3510 — a runner entry of .chant/trust.json, written through chant so a box repo never edits it by hand (ws-074).
+  { name: "workspace trust", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/trust/trust-write")).runWorkspaceTrust(ctx) },
   { name: "workspace signers", handler: async (ctx) => (await import("../workspace/trust/signers-cli")).runWorkspaceSigners(ctx) },
   { name: "workspace evidence", handler: async (ctx) => (await import("../workspace/trust/evidence-cli")).runWorkspaceEvidence(ctx) },
 
@@ -1691,6 +1745,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 {