@intentius/chant 0.101.0 → 0.104.0

package/src/cli/handlers/pr.ts

@@ -0,0 +1,373 @@
+/**
+ * `chant components pr-plan` and `chant components pr-apply` (#3183): the
+ * pull-request loop the generated CI runs.
+ *
+ * ```
+ * chant components pr-plan  --base <ref> --pr <n> --env <env> [--forge github|gitlab|forgejo]
+ * chant approve pr-<n> pr-apply --plan <digest> --approver github:<login> --sign
+ * chant components pr-apply --base <ref> --env <env> [--pr <n>] [--forge <kind>] [--require-review]
+ * ```
+ *
+ * Both measure the change from the merge base of `--base` and `HEAD`, select
+ * the components it reaches and the ones that depend on them (the fan-out's
+ * derivation, #2417), and plan every member before anything applies
+ * (`../../components/pr-run.ts`). pr-plan writes the report and the note and
+ * applies nothing; it reads the gate ledger and writes nothing to it, since
+ * it runs the pull request's own code. pr-apply plans the same members on
+ * the merged commit, decides the gate against the digest it gets, and
+ * applies only when an approval stands for that digest. A moved plan stops
+ * it with both digests named and nothing applied (exit 3).
+ *
+ * Every run writes `pr-plan.json` or `pr-apply.json` (`pr-report.schema.json`),
+ * `change-set.json` and `pr-note.md` under `--output` (default `.chant/pr`).
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
+import { resolveCommit, resolveMergeBase } from "../../components/changed-files";
+import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
+import {
+  applyPrSet,
+  approvalOf,
+  approversWithoutReview,
+  decidePrGate,
+  planPrSet,
+  prReport,
+  readOnlyLedger,
+  type PrPlanSet,
+} from "../../components/pr-run";
+import { gitGateLedgerPort } from "../../op/gate";
+import {
+  describePlanChanged,
+  PR_APPLY_GATE,
+  PR_STATUS_CONTEXTS,
+  prApproveCommand,
+  prNoteMarker,
+  prOp,
+  prStatusDescription,
+  prStatusState,
+  renderPrNote,
+  type PrApproval,
+  type PrReport,
+} from "../../pr-loop";
+import { FORGE_KINDS, forgeFromEnv, forgePrincipalOf, type ForgeKind, type PrForge } from "../../pr-forge";
+import { GITHUB_COMMENT_LIMIT, GITLAB_NOTE_LIMIT } from "../../plan-summary";
+import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
+import { resolveChangedUnits } from "./fan-out";
+import { GATED_EXIT_CODE, recordAutoReleasesForRun } from "./run";
+import type { CommandContext } from "../registry";
+import type { ComponentChangeSignal, FanOutPlan } from "../../components/fan-out";
+import type { DriverComponent } from "../../components/driver";
+import type { CapabilityRegistry } from "../../components/capability";
+
+
+/** Where the reports land unless `--output` says. */
+export const PR_REPORT_DIR = ".chant/pr";
+
+interface Prepared {
+  config: ChantConfig;
+  env: string;
+  base: string;
+  head: string;
+  gate: string;
+  forge?: PrForge;
+  components: DriverComponent[];
+  plan: FanOutPlan;
+  signal: ComponentChangeSignal;
+  registry: CapabilityRegistry;
+  set: PrPlanSet;
+}
+
+const fail = (message: string, hint?: string): number => {
+  console.error(formatError({ message, ...(hint ? { hint } : {}) }));
+  return 1;
+};
+
+/** Everything both stages share: the change, the derivation and the plan of every member. */
+async function prepare(ctx: CommandContext, stage: "plan" | "apply"): Promise<Prepared | number> {
+  const { args } = ctx;
+  const projectPath = resolve(".");
+  const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
+  const paramsResolution = resolveCliBuildParams(config.buildParams, {
+    cli: parseParamFlags(args.param),
+    paramsFile: args.paramsFile,
+    verbose: args.verbose,
+  });
+  if (!paramsResolution.success) {
+    for (const message of paramsResolution.errors) console.error(message);
+    return 1;
+  }
+  if (!args.base) {
+    return fail(
+      `pr-${stage} needs the commit the change is measured from: --base <ref>`,
+      stage === "plan" ? "On a pull request, the target branch's commit." : "On a push, the commit before it.",
+    );
+  }
+  if (args.fromAffected) return fail(`pr-${stage} derives the change itself; drop --from-affected`);
+  if (args.forge !== undefined && !(FORGE_KINDS as readonly string[]).includes(args.forge)) {
+    return fail(`--forge ${args.forge} is not one of ${FORGE_KINDS.join(", ")}`);
+  }
+
+  let forge: PrForge | undefined;
+  if (args.forge) {
+    try {
+      forge = forgeFromEnv(args.forge as ForgeKind);
+    } catch (err) {
+      return fail(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  let base: string;
+  let head: string;
+  try {
+    head = await resolveCommit(projectPath, args.head ?? "HEAD");
+    base = await resolveMergeBase(projectPath, args.base, head);
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+
+  const signal = await resolveChangedUnits(ctx, config, { base, stacksOnly: true });
+  if ("error" in signal) return fail(signal.error, signal.hint);
+
+  let derived;
+  try {
+    derived = await deriveFanOut({
+      path: projectPath,
+      units: signal.units,
+      sandbox: args.sandbox,
+      buildParams: paramsResolution.provenance,
+      config,
+    });
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  if (!derived.success) return fail(derived.error ?? "Could not discover components");
+
+  const seededOutputs: Record<string, Record<string, unknown>> = {};
+  for (const file of args.seedOutputs ?? []) {
+    try {
+      Object.assign(seededOutputs, JSON.parse(readFileSync(resolve(file), "utf8")));
+    } catch (err) {
+      return fail(`--seed-outputs: could not read "${file}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  const env = args.env ?? "local";
+  const registry = await fanOutRegistry(projectPath, config);
+  const set = await planPrSet({ components: derived.components, plan: derived.plan, registry, env, seededOutputs });
+  return {
+    config,
+    env,
+    base,
+    head,
+    gate: args.gate ?? PR_APPLY_GATE,
+    ...(forge ? { forge } : {}),
+    components: derived.components,
+    plan: derived.plan,
+    signal: derived.signal,
+    registry,
+    set,
+  };
+}
+
+/** Write the report, the change set and the note; print the note's path. */
+function writeOutputs(ctx: CommandContext, report: PrReport, note: string): void {
+  const dir = resolve(ctx.args.output ?? PR_REPORT_DIR);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, `pr-${report.stage}.json`), JSON.stringify(report, null, 2) + "\n");
+  writeFileSync(join(dir, "change-set.json"), JSON.stringify(report.changeSet, null, 2) + "\n");
+  writeFileSync(join(dir, "pr-note.md"), note);
+}
+
+/** Post the note and the stage's status. A forge that refuses is a warning: the stage's outcome stands. */
+async function publish(forge: PrForge | undefined, report: PrReport, note: string): Promise<void> {
+  if (!forge) return;
+  const status = {
+    context: PR_STATUS_CONTEXTS[report.stage],
+    state: prStatusState(report),
+    description: prStatusDescription(report),
+    ...(forge.runUrl ? { url: forge.runUrl } : {}),
+  };
+  try {
+    await forge.setStatus(report.head, status);
+  } catch (err) {
+    console.error(formatWarning({ message: `could not set the ${status.context} status: ${err instanceof Error ? err.message : String(err)}` }));
+  }
+  if (report.pr === null) return;
+  try {
+    await forge.upsertNote(report.pr, prNoteMarker(report.env), note);
+  } catch (err) {
+    console.error(formatWarning({ message: `could not post the note on #${report.pr}: ${err instanceof Error ? err.message : String(err)}` }));
+  }
+}
+
+function noteFor(report: PrReport, forge: PrForge | undefined): string {
+  return renderPrNote(report, {
+    limit: forge?.kind === "gitlab" ? GITLAB_NOTE_LIMIT : GITHUB_COMMENT_LIMIT,
+    approver: forge ? forgePrincipalOf(forge.kind, forge.host, "<your-login>") : "<you>",
+  });
+}
+
+function printMembers(report: PrReport): void {
+  for (const m of report.members) {
+    const c = m.counts;
+    console.error(`  ${m.member.padEnd(20)} ${m.status.padEnd(12)} create ${c.create} update ${c.update} replace ${c.replace} delete ${c.delete}${m.error ? `  ${m.error}` : ""}`);
+  }
+}
+
+async function finish(ctx: CommandContext, p: Prepared, report: PrReport): Promise<void> {
+  const note = noteFor(report, p.forge);
+  writeOutputs(ctx, report, note);
+  await publish(p.forge, report, note);
+  if (ctx.args.json) console.log(JSON.stringify(report, null, 2));
+}
+
+/** chant components pr-plan --base <ref> --pr <n> [--env <env>] [--gate <name>] [--forge <kind>] [--output <dir>] [--json] */
+export async function runComponentsPrPlan(ctx: CommandContext): Promise<number> {
+  if (ctx.args.pr === undefined) {
+    return fail("pr-plan needs the pull or merge request: --pr <n>", "Its approval is recorded under op pr-<n>, so one pull request's approval never answers another's.");
+  }
+  const p = await prepare(ctx, "plan");
+  if (typeof p === "number") return p;
+  const op = prOp(ctx.args.pr);
+
+  let approval: PrApproval = { status: "pending" };
+  if (p.plan.order.length > 0) {
+    try {
+      approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort()), { op, gate: p.gate, digest: p.set.doc.digest }));
+    } catch (err) {
+      console.error(formatWarning({ message: `could not read the gate ledger, so the approval reads as pending: ${err instanceof Error ? err.message : String(err)}` }));
+    }
+  }
+  const status = p.plan.order.length === 0 ? "nothing" : p.set.failed ? "plan-failed" : "planned";
+  const report = prReport({
+    stage: "plan",
+    pr: ctx.args.pr,
+    env: p.env,
+    base: p.base,
+    head: p.head,
+    op,
+    gate: p.gate,
+    plan: p.plan,
+    signal: p.signal,
+    set: p.set,
+    approval,
+    status,
+  });
+  await finish(ctx, p, report);
+
+  console.error(formatInfo(`pr-plan: ${report.members.length} member(s), ${status}`));
+  printMembers(report);
+  if (status === "planned") {
+    console.error(formatInfo(`plan    : ${report.digest}`));
+    console.error(formatInfo(approval.status === "approved" ? `approved by ${(approval.approvedBy ?? []).join(", ")}` : `approve : ${prApproveCommand(report)}`));
+  }
+  return status === "plan-failed" ? 1 : 0;
+}
+
+/** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] */
+export async function runComponentsPrApply(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.requireReview && !args.forge) return fail("--require-review reads the pull request's reviews, so it needs --forge <kind>");
+  const p = await prepare(ctx, "apply");
+  if (typeof p === "number") return p;
+
+  let pr: number | null = args.pr ?? null;
+  if (pr === null && p.forge && p.plan.order.length > 0) {
+    try {
+      pr = await p.forge.pullRequestFor(p.head);
+    } catch (err) {
+      return fail(`could not ask ${p.forge.kind} which pull request merged ${p.head}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  const op = pr === null ? "pr-unknown" : prOp(pr);
+  const base = { stage: "apply" as const, pr, env: p.env, base: p.base, head: p.head, op, gate: p.gate, plan: p.plan, signal: p.signal, set: p.set };
+
+  const stop = async (report: PrReport, code: number): Promise<number> => {
+    await finish(ctx, p, report);
+    console.error((code === 0 ? formatInfo : (m: string) => formatWarning({ message: m }))(`pr-apply: ${report.status}${report.refusal ? ` (${report.refusal})` : ""}`));
+    if (report.message) console.error(report.message);
+    printMembers(report);
+    return code;
+  };
+
+  if (p.plan.order.length === 0) {
+    return stop(prReport({ ...base, approval: { status: "pending" }, status: "nothing" }), 0);
+  }
+  if (pr === null) {
+    return stop(
+      prReport({
+        ...base,
+        approval: { status: "pending" },
+        status: "refused",
+        refusal: "no-pull-request",
+        message: `No pull request merged ${p.head}, so no approval answers for this change. Nothing was applied. Pass --pr <n>, or land the change through a pull request.`,
+      }),
+      GATED_EXIT_CODE,
+    );
+  }
+  if (p.set.failed) {
+    return stop(
+      prReport({
+        ...base,
+        approval: { status: "pending" },
+        status: "plan-failed",
+        message: "A member failed to plan, so there is no plan to compare with the approved one. Nothing was applied.",
+      }),
+      1,
+    );
+  }
+
+  const check = await decidePrGate(gitGateLedgerPort(), {
+    op,
+    gate: p.gate,
+    digest: p.set.doc.digest,
+    description: `pull request #${pr}: ${p.plan.order.join(", ")}`,
+  });
+  const approval = approvalOf(check);
+  if (!check.satisfied) {
+    const partial = { ...base, approval, status: "refused" as const };
+    const report = approval.status === "changed"
+      ? prReport({ ...partial, refusal: "plan-changed", message: describePlanChanged({ op, gate: p.gate, digest: p.set.doc.digest, approval }) })
+      : prReport({
+          ...partial,
+          refusal: "not-approved",
+          message: `No approval stands for this plan, so nothing was applied. Approve it: ${prApproveCommand({ op, gate: p.gate, digest: p.set.doc.digest })}; then run the apply again.`,
+        });
+    return stop(report, GATED_EXIT_CODE);
+  }
+
+  if (args.requireReview && p.forge) {
+    let reviewers: string[];
+    try {
+      reviewers = (await p.forge.approvers(pr)).map((login) => p.forge!.principalOf(login));
+    } catch (err) {
+      return fail(`could not read the reviews of #${pr}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const strangers = approversWithoutReview(approval.approvedBy ?? [], reviewers);
+    if (strangers.length > 0) {
+      return stop(
+        prReport({
+          ...base,
+          approval,
+          status: "refused",
+          refusal: "not-a-reviewer",
+          message:
+            `The plan is approved by ${strangers.join(", ")}, who ${strangers.length === 1 ? "has" : "have"} no approving review on #${pr}` +
+            ` (approving reviews: ${reviewers.join(", ") || "none"}). Nothing was applied. ` +
+            `An approval counts when it names the reviewer the way the forge does: ${p.forge.principalOf("<login>")}.`,
+        }),
+        GATED_EXIT_CODE,
+      );
+    }
+  }
+
+  const applied = await applyPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: p.env, set: p.set });
+  await recordAutoReleasesForRun(applied.run.results, p.env, `${op}-${Date.now()}`, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord));
+  const report = prReport({ ...base, approval, status: applied.status, members: applied.members });
+  const code = await stop(report, applied.status === "applied" ? 0 : 1);
+  if (applied.status === "applied") console.error(formatSuccess(`applied the plan ${report.digest} approved by ${(approval.approvedBy ?? []).join(", ")}`));
+  return code;
+}

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

@@ -424,6 +424,30 @@ describe("runOp: a steward's turn (#2750)", () => {
     expect(acquireStewardTurnMock).not.toHaveBeenCalled();
   });
 
+  test("fountain form with run.on: fountain and no flag: runs on fountain like --on fountain (#2523)", async () => {
+    const runtime = {
+      name: "fountain",
+      start: vi.fn(async (op: { name: string }) => ({
+        op: op.name,
+        runId: "f-1",
+        result: async () => ({ op: op.name, runId: "f-1", state: "completed" as const, startedAt: "t", endedAt: "t" }),
+      })),
+      status: vi.fn(), log: vi.fn(), list: vi.fn(), cancel: vi.fn(),
+    };
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("release", [])]), errors: [] });
+    discoverStewardsMock.mockResolvedValueOnce(stewardOwning("release", "box-steward", "fountain"));
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["fountain"], run: { on: "fountain" } } });
+    makeStdoutSpy();
+    const exit = await runOp({
+      args: makeArgs({ path: "release" }),
+      plugins: [{ name: "fountain", opRuntime: runtime } as never], serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    expect(runtime.start).toHaveBeenCalledTimes(1);
+    expect(acquireStewardTurnMock).not.toHaveBeenCalled();
+  });
+
   test("local form, the turn lease's own acquire throws (a stale .lock): refused as a lease error, not an uncaught exception, and nothing runs", async () => {
     discoverOpsMock.mockResolvedValue({
       ops: new Map([localOp("release", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
@@ -899,6 +923,93 @@ describe("run subcommands on the resolved runtime", () => {
     expect(stderr.join("\n")).toContain('lexicon "plain" does not host Op runs');
   });
 
+  test("run.on in chant.config.ts is the default runtime when --on is not given (#2523)", async () => {
+    const runtime = makeStubRuntime();
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["stub"], run: { on: "stub" } } });
+    makeStdoutSpy();
+    makeStderrSpy();
+    const ctx = (over: Partial<ParsedArgs>) => ({ args: makeArgs(over), plugins: [stubPlugin(runtime)], serializers: [] });
+
+    expect(await runOp(ctx({ path: "hello" }))).toBe(0);
+    expect(await runOpStatus(ctx({ extraPositional: "hello" }))).toBe(0);
+    expect(await runOpLog(ctx({ extraPositional: "hello" }))).toBe(0);
+    expect(await runOpList(ctx({}))).toBe(0);
+    expect(runtime.start).toHaveBeenCalledTimes(1);
+    expect(runtime.status).toHaveBeenCalledWith("hello");
+    expect(runtime.log).toHaveBeenCalledTimes(1);
+    expect(runtime.list).toHaveBeenCalledTimes(1);
+  });
+
+  test("--on local overrides run.on and runs on the built-in runtime (#2523)", async () => {
+    const runtime = makeStubRuntime();
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["stub"], run: { on: "stub" } } });
+    makeStdoutSpy();
+    makeStderrSpy();
+    await runOpList({ args: makeArgs({ on: "local" }), plugins: [stubPlugin(runtime)], serializers: [] });
+    expect(runtime.list).not.toHaveBeenCalled();
+  });
+
+  test("run.on naming an unconfigured lexicon gets --on's refusal, naming run.on (#2523)", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["aws"], run: { on: "nope" } } });
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "hello" }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain('run.on "nope" in chant.config.ts: "nope" is not a configured lexicon');
+    expect(stderr.join("\n")).toContain("Configured lexicons: aws");
+    expect(stderr.join("\n")).toContain("--on local");
+  });
+
+  test("an explicit --on wins over run.on (#2523)", async () => {
+    const chosen = makeStubRuntime();
+    const other = makeStubRuntime();
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["stub", "other"], run: { on: "other" } } });
+    makeStdoutSpy();
+    makeStderrSpy();
+    const plugins = [stubPlugin(chosen), { name: "other", opRuntime: other } as never];
+    expect(await runOpList({ args: makeArgs({ on: "stub" }), plugins, serializers: [] })).toBe(0);
+    expect(chosen.list).toHaveBeenCalledTimes(1);
+    expect(other.list).not.toHaveBeenCalled();
+  });
+
+  test("run.on: local selects the built-in runtime (#2523)", async () => {
+    const runtime = makeStubRuntime();
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["stub"], run: { on: "local" } } });
+    makeStdoutSpy();
+    makeStderrSpy();
+    await runOpList({ args: makeArgs({}), plugins: [stubPlugin(runtime)], serializers: [] });
+    expect(runtime.list).not.toHaveBeenCalled();
+  });
+
+  test("an invalid run block is refused, not run locally (#2523)", async () => {
+    const { InvalidChantConfigError } = await vi.importActual<typeof import("../../config")>("../../config");
+    const runtime = makeStubRuntime();
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockRejectedValue(
+      new InvalidChantConfigError("Invalid chant config in /p/chant.config.ts: run.on: Expected string, received number", "run"),
+    );
+    const stderr = makeStderrSpy();
+    makeStdoutSpy();
+    expect(await runOpList({ args: makeArgs({}), plugins: [stubPlugin(runtime)], serializers: [] })).toBe(1);
+    expect(stderr.join("\n")).toContain("Invalid chant config in /p/chant.config.ts: run.on");
+    expect(runtime.list).not.toHaveBeenCalled();
+    // --on local still runs: the flag needs nothing from the config.
+    expect(await runOpList({ args: makeArgs({ on: "local" }), plugins: [stubPlugin(runtime)], serializers: [] })).toBe(0);
+  });
+
+  test("run.on naming a lexicon with no opRuntime gets --on's refusal, naming run.on (#2523)", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["plain"], run: { on: "plain" } } });
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "hello" }), plugins: [{ name: "plain" } as never], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain('run.on "plain" in chant.config.ts: lexicon "plain" does not host Op runs');
+  });
+
   test("--components on a runtime that cannot host them → one line, exit 1", async () => {
     const runtime = makeStubRuntime();
     const stderr = makeStderrSpy();

package/src/cli/handlers/run.ts

@@ -1,7 +1,7 @@
 import { lexiconNames } from "../../lexicon-module";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, basename } from "node:path";
 import { writeFileSync, mkdirSync, readFileSync } from "node:fs";
-import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
+import { loadChantConfig, resolveAutoReleaseDisabled, InvalidChantConfigError, type ChantConfig } from "../../config";
 import { discoverOps, discoverStewards } from "../../op/discover";
 import { stewardWorkHolder } from "../../op/work-lease-run";
 import type { OpConfig } from "../../op/types";
@@ -108,10 +108,12 @@ function refuseDurableComponentSubcommand(what: string, hint: string): number {
 /**
  * Resolve the one runtime this invocation talks to.
  *
- * `--on <name>` picks the named lexicon's `opRuntime` (`../../lexicon.ts`);
- * without it, core's built-in `local` provider runs the Op in this process.
- * Every `chant run` subcommand goes through whichever comes back, so there is
- * one dispatch path rather than a branch per runtime.
+ * `--on <name>` picks the named lexicon's `opRuntime` (`../../lexicon.ts`).
+ * Without it, `run.on` in `chant.config.ts` does (#2523), and without either,
+ * core's built-in `local` provider runs the Op in this process. `local`, from
+ * either place, names the built-in provider. Every `chant run` subcommand goes
+ * through whichever comes back, so there is one dispatch path rather than a
+ * branch per runtime.
  *
  * A lexicon already loaded into the command context wins the lookup — that is
  * how a test hands in a stub, and how a command that loaded plugins for its
@@ -121,22 +123,20 @@ function refuseDurableComponentSubcommand(what: string, hint: string): number {
  *
  * Returns `undefined` after printing an actionable error — an unconfigured
  * name is answered with the configured list, a configured lexicon that hosts
- * nothing is named outright.
+ * nothing is named outright. A `run.on` default gets the same messages as
+ * `--on`, labelled `run.on` and the config file instead of `--on`.
  */
 async function resolveOpRuntime(ctx: CommandContext): Promise<OpRuntimeProvider | undefined> {
-  const on = ctx.args.on;
+  const choice = await chooseOpRuntime(ctx);
+  if (!choice) return undefined;
+  const { on, source, configured } = choice;
   if (!on || on === "local") return createLocalOpRuntime({ projectPath: resolve(".") });
 
-  // Read the configured list straight from `chant.config.ts` rather than
-  // through `resolveProjectLexicons`: `--on` names a *configured* lexicon, and
-  // that helper's fallback is a source scan of the whole project, which is a
-  // long wait to be told a name is wrong.
-  let configured: string[] = [];
-  try {
-    configured = lexiconNames((await loadChantConfig(resolve("."))).config.lexicons ?? []);
-  } catch {
-    // No/unreadable chant.config.ts — the error below says so by listing nothing.
-  }
+  // How the error names the choice, and how to get the built-in runtime back.
+  const label = source === "flag" ? `--on ${on}` : `run.on "${on}" in ${choice.configFile}`;
+  const fallback = source === "flag"
+    ? "Omit --on to run on the built-in local runtime."
+    : `Fix \`run.on\` in ${choice.configFile}, or pass --on local to run on the built-in local runtime.`;
 
   let plugin = ctx.plugins.find((p) => p.name === on);
   if (!plugin && configured.includes(on)) {
@@ -146,18 +146,18 @@ async function resolveOpRuntime(ctx: CommandContext): Promise<OpRuntimeProvider
   if (!plugin) {
     const known = [...new Set([...ctx.plugins.map((p) => p.name), ...configured])];
     console.error(formatError({
-      message: `--on ${on}: "${on}" is not a configured lexicon`,
+      message: `${label}: "${on}" is not a configured lexicon`,
       hint: known.length > 0
-        ? `Configured lexicons: ${known.join(", ")}. Omit --on to run on the built-in local runtime.`
-        : "chant.config.ts configures no lexicons. Omit --on to run on the built-in local runtime.",
+        ? `Configured lexicons: ${known.join(", ")}. ${fallback}`
+        : `chant.config.ts configures no lexicons. ${fallback}`,
     }));
     return undefined;
   }
 
   if (!plugin.opRuntime) {
     console.error(formatError({
-      message: `--on ${on}: lexicon "${on}" does not host Op runs`,
-      hint: "It declares no opRuntime. Omit --on to run on the built-in local runtime.",
+      message: `${label}: lexicon "${on}" does not host Op runs`,
+      hint: `It declares no opRuntime. ${fallback}`,
     }));
     return undefined;
   }
@@ -165,6 +165,64 @@ async function resolveOpRuntime(ctx: CommandContext): Promise<OpRuntimeProvider
   return plugin.opRuntime;
 }
 
+/** Which runtime name an invocation asked for, and where the name came from. */
+interface OpRuntimeChoice {
+  /** The runtime name; `undefined` or `"local"` is the built-in runtime. */
+  on: string | undefined;
+  /** `flag` for `--on`, `config` for `run.on`, `default` when neither named one. */
+  source: "flag" | "config" | "default";
+  /** The lexicons `chant.config.ts` configures. */
+  configured: string[];
+  /** The config file's name, for messages about `run.on`. */
+  configFile: string;
+}
+
+/**
+ * The runtime name `--on`, then `run.on` in `chant.config.ts` (#2523), then
+ * the built-in default pick, without loading any lexicon.
+ *
+ * Reads the configured list straight from `chant.config.ts` rather than
+ * through `resolveProjectLexicons`: `--on` names a *configured* lexicon, and
+ * that helper's fallback is a source scan of the whole project, which is a
+ * long wait to be told a name is wrong.
+ *
+ * A config that fails to load leaves the flag's choice alone, as before. With
+ * no flag, a config whose `run` block is invalid is refused (printed, then
+ * `undefined`): running the Op locally would hide that the project asked for
+ * another runtime. Any other load failure falls back to the built-in runtime,
+ * which is what a project with no `run.on` got before. `quiet` skips printing
+ * that refusal, for a caller that only peeks at the choice and leaves the
+ * reporting to {@link resolveOpRuntime}.
+ */
+async function chooseOpRuntime(ctx: CommandContext, quiet = false): Promise<OpRuntimeChoice | undefined> {
+  const flag = ctx.args.on;
+  if (flag === "local") return { on: "local", source: "flag", configured: [], configFile: "chant.config.ts" };
+
+  let configured: string[] = [];
+  let configuredOn: string | undefined;
+  let configFile = "chant.config.ts";
+  try {
+    const { config, configPath } = await loadChantConfig(resolve("."));
+    configured = lexiconNames(config.lexicons ?? []);
+    configuredOn = config.run?.on;
+    if (configPath) configFile = basename(configPath);
+  } catch (err) {
+    if (!flag && err instanceof InvalidChantConfigError && err.key === "run") {
+      if (quiet) return undefined;
+      console.error(formatError({
+        message: err.message,
+        hint: "`run.on` names the runtime that hosts this project's Op runs: a configured lexicon with an opRuntime, or \"local\". Fix it, or pass --on to pick the runtime for this run.",
+      }));
+      return undefined;
+    }
+    // No/unreadable chant.config.ts: an `--on` error says so by listing nothing.
+  }
+
+  if (flag) return { on: flag, source: "flag", configured, configFile };
+  if (configuredOn) return { on: configuredOn, source: "config", configured, configFile };
+  return { on: undefined, source: "default", configured, configFile };
+}
+
 /** An ISO-8601 instant trimmed to what a table cell has room for. */
 function shortInstant(iso: string | undefined): string {
   return iso ? iso.slice(0, 19).replace("T", " ") : "—";
@@ -395,6 +453,8 @@ export async function runOpApprove(ctx: CommandContext): Promise<number> {
     note: ctx.args.note,
     url: ctx.args.url,
     plan: ctx.args.plan,
+    ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
+    ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
   });
   if (!outcome.ok) return 1;
 
@@ -582,7 +642,9 @@ async function stewardTurnGate(opName: string, ctx: CommandContext): Promise<Ste
   const form = stewardFormFor(owner, env);
 
   if (form === "fountain") {
-    if (ctx.args.on === "fountain") return { ok: true };
+    // `run.on: "fountain"` asks for the steward's thread 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}"`,