@intentius/chant 0.101.0 → 0.102.0

package/src/cli/commands/pinned-upgrade.ts

@@ -1,7 +1,7 @@
 /**
  * `chant dev pinned-upgrade <lexicon-dir>` command implementation.
  *
- * Detects whether a pinned-version lexicon (k8s, gcp, docker, gitlab) has a
+ * Detects whether a lexicon that declares `upstreamPin` has a
  * newer stable upstream release. When it does, it dry-run bumps the pinned
  * version constant, regenerates + surface-diffs (via #524's regenLexicon), then
  * reverts the bump — leaving the working tree unchanged.
@@ -10,20 +10,21 @@
  */
 
 import { existsSync } from "fs";
-import { basename, resolve } from "path";
+import { resolve } from "path";
 import {
-  checkPinnedUpgrade,
+  checkPinnedUpgrades,
+  lexiconNameOf,
   type LexiconId,
   type UpgradeCheckResult,
 } from "../../codegen/pinned-upgrade";
 
-const PINNED_LEXICONS: readonly LexiconId[] = ["k8s", "gcp", "docker", "gitlab"];
-
 export interface PinnedUpgradeOptions {
   /** Resolved path to the lexicon directory. */
   lexiconDir: string;
   /** Explicit lexicon id; inferred from the directory name when omitted. */
   lexicon?: LexiconId;
+  /** Label of one pin to check, for a lexicon that declares several. Omitted: all of them. */
+  pin?: string;
   /** Force re-fetch of the upstream spec during regen. */
   force?: boolean;
   /** Print subprocess output while running. */
@@ -31,12 +32,13 @@ export interface PinnedUpgradeOptions {
 }
 
 /**
- * Infer the lexicon id from a directory name. Returns null when the directory
- * basename is not one of the pinned lexicons.
+ * Infer the lexicon id from a directory: its package name
+ * (`@intentius/chant-lexicon-<name>`), else the directory name. Whether the
+ * lexicon is pinned is the plugin's `upstreamPin`, checked by
+ * `checkPinnedUpgrade`, not a list here.
  */
-export function inferLexicon(lexiconDir: string): LexiconId | null {
-  const name = basename(lexiconDir);
-  return (PINNED_LEXICONS as readonly string[]).includes(name) ? (name as LexiconId) : null;
+export function inferLexicon(lexiconDir: string): LexiconId {
+  return lexiconNameOf(lexiconDir);
 }
 
 /**
@@ -52,37 +54,38 @@ export function semverLabel(result: UpgradeCheckResult): "minor" | "major" | "no
 
 /**
  * Run the pinned-upgrade check and return the structured result.
- * Never throws — a missing dir or an unrecognised lexicon becomes a fetchError.
+ * Never throws — a missing dir or a lexicon with no `upstreamPin` becomes a fetchError.
  */
 export async function runPinnedUpgrade(opts: PinnedUpgradeOptions): Promise<UpgradeCheckResult> {
+  return (await runPinnedUpgrades(opts))[0]!;
+}
+
+/**
+ * Run the check for every pin the plugin declares (or the one in `opts.pin`),
+ * one result each. A lexicon with one pin gives one result.
+ */
+export async function runPinnedUpgrades(opts: PinnedUpgradeOptions): Promise<UpgradeCheckResult[]> {
   const dir = resolve(opts.lexiconDir);
 
   const lexicon = opts.lexicon ?? inferLexicon(dir);
-  if (!lexicon) {
-    return {
-      lexicon: "k8s",
-      hasUpgrade: false,
-      from: "(unknown)",
-      to: null,
-      validation: null,
-      fetchError: `Not a pinned lexicon directory: ${dir}. Expected one of: ${PINNED_LEXICONS.join(", ")}.`,
-    };
-  }
 
   if (!existsSync(dir)) {
-    return {
-      lexicon,
-      hasUpgrade: false,
-      from: "(unknown)",
-      to: null,
-      validation: null,
-      fetchError: `Lexicon directory not found: ${dir}`,
-    };
+    return [
+      {
+        lexicon,
+        hasUpgrade: false,
+        from: "(unknown)",
+        to: null,
+        validation: null,
+        fetchError: `Lexicon directory not found: ${dir}`,
+      },
+    ];
   }
 
-  return checkPinnedUpgrade({
+  return checkPinnedUpgrades({
     lexiconDir: dir,
     lexicon,
+    pin: opts.pin,
     force: opts.force,
     verbose: opts.verbose,
   });
@@ -112,12 +115,14 @@ function c(text: string, code: string): string {
  */
 export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boolean): void {
   const label = semverLabel(result);
+  const name = result.pin ? `${result.lexicon}/${result.pin}` : result.lexicon;
 
   if (json) {
     console.log(
       JSON.stringify(
         {
           lexicon: result.lexicon,
+          ...(result.pin ? { pin: result.pin } : {}),
           hasUpgrade: result.hasUpgrade,
           from: result.from,
           to: result.to,
@@ -128,6 +133,7 @@ export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boole
           validationOk: result.validation?.ok ?? null,
           failures: result.validation?.failures ?? [],
           fetchError: result.fetchError,
+          manualPin: result.manualPin ?? null,
         },
         null,
         2,
@@ -137,22 +143,31 @@ export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boole
   }
 
   if (result.fetchError) {
-    console.log(c(`[${result.lexicon}] error: ${result.fetchError}`, COLORS.red));
+    console.log(c(`[${name}] error: ${result.fetchError}`, COLORS.red));
     return;
   }
 
   if (!result.hasUpgrade) {
     console.log(
-      c(`[${result.lexicon}] up to date`, COLORS.green) +
+      c(`[${name}] up to date`, COLORS.green) +
         `  pinned=${result.from}` +
         (result.to ? ` latest=${result.to}` : ""),
     );
     return;
   }
 
+  if (result.manualPin) {
+    console.log(
+      c(`[${name}] upgrade available`, COLORS.bold) + `  ${result.from} -> ${result.to}`,
+    );
+    console.log(`  The pin in ${result.manualPin.file} cannot be rewritten generically, so nothing was edited or regenerated.`);
+    console.log(`  ${result.manualPin.instructions}`);
+    return;
+  }
+
   // Upgrade available
   console.log(
-    c(`[${result.lexicon}] upgrade available`, COLORS.bold) +
+    c(`[${name}] upgrade available`, COLORS.bold) +
       `  ${result.from} -> ${result.to}`,
   );
 
@@ -202,3 +217,28 @@ export function printPinnedUpgradeResult(result: UpgradeCheckResult, json: boole
     `Validation: ${validationLabel}  Semver: ${c(label, labelColor)}  ${result.from} -> ${result.to}`,
   );
 }
+
+/**
+ * Print one result per pin. One result prints exactly as `printPinnedUpgradeResult`;
+ * several print in turn, and `json` emits an array of the same objects.
+ */
+export function printPinnedUpgradeResults(results: UpgradeCheckResult[], json: boolean): void {
+  if (results.length === 1) {
+    printPinnedUpgradeResult(results[0]!, json);
+    return;
+  }
+  if (json) {
+    // Each result prints as its own JSON object; collect them into one array.
+    const lines: string[] = [];
+    const log = console.log;
+    console.log = (...a: unknown[]) => void lines.push(a.join(" "));
+    try {
+      for (const r of results) printPinnedUpgradeResult(r, true);
+    } finally {
+      console.log = log;
+    }
+    console.log(`[${lines.join(",\n")}]`);
+    return;
+  }
+  for (const r of results) printPinnedUpgradeResult(r, false);
+}

package/src/cli/handlers/__snapshots__/build-member.test.ts.snap

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     container: node:22-slim
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - run: chant run --components shared-alb --env staging --dump-outputs shared-alb.outputs.json
       - name: Upload shared-alb outputs
         uses: actions/upload-artifact@v4
@@ -27,7 +27,7 @@ jobs:
       - shared-alb
     container: node:22-slim
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Download shared-alb outputs
         uses: actions/download-artifact@v4
         with:

package/src/cli/handlers/components.ts

@@ -48,7 +48,7 @@ import type { ComponentBomSummary } from "../../lifecycle/build-ledger";
 import type { BuildArchiveManifest } from "../../components/verbs/build-archive";
 import { loadChantConfig } from "../../config";
 import { applyLiveEndpoint } from "../../live-endpoint";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { build } from "../../build";
 import { discoverComponents } from "../../components/discover";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
@@ -643,7 +643,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
           const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
           for (const [name, entity] of buildResult.entities) {
             // Resource declarables only (see lifecycle/observe.ts).
-            if (entity.lexicon === plugin.name && isResourceDeclarable(entity)) {
+            if (entity.lexicon === plugin.name && isObservableDeclarable(entity)) {
               declared.add(name);
               entities.set(name, {
                 entityType: entity.entityType,

package/src/cli/handlers/dev.ts

@@ -85,16 +85,18 @@ export async function runDevSurfaceDiff(ctx: CommandContext): Promise<number> {
 
 export async function runDevPinnedUpgrade(ctx: CommandContext): Promise<number> {
   const dir = ctx.args.extraPositional ?? ".";
-  const { runPinnedUpgrade, printPinnedUpgradeResult } = await import("../commands/pinned-upgrade");
-  const result = await runPinnedUpgrade({
+  const { runPinnedUpgrades, printPinnedUpgradeResults } = await import("../commands/pinned-upgrade");
+  // The optional second positional is a pin label, for a lexicon that declares several pins.
+  const results = await runPinnedUpgrades({
     lexiconDir: resolve(dir),
+    pin: ctx.args.extraPositional2,
     force: ctx.args.force,
     verbose: ctx.args.verbose,
   });
-  printPinnedUpgradeResult(result, ctx.args.format === "json");
-  // Exit non-zero when the upstream query failed or the regen validation broke.
-  if (result.fetchError) return 1;
-  if (result.validation && !result.validation.ok) return 1;
+  printPinnedUpgradeResults(results, ctx.args.format === "json");
+  // Exit non-zero when an upstream query failed or a regen validation broke.
+  if (results.some((r) => r.fetchError)) return 1;
+  if (results.some((r) => r.validation && !r.validation.ok)) return 1;
   return 0;
 }
 

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

@@ -97,6 +97,19 @@ function makeBuildResult(entitiesByLexicon: Record<string, string[]>): BuildResu
   } as unknown as BuildResult;
 }
 
+/**
+ * #3001 — a build holding one resource and one property-kind declarable that
+ * the resource inlines, the shape every grafana dashboard with exported panels
+ * has. Only the resource has a live counterpart of its own.
+ */
+function buildWithPropertyKind(lexicon: string): BuildResult {
+  const build = makeBuildResult({ [lexicon]: ["board"] });
+  const panel = { lexicon, entityType: `${lexicon}::Panel`, kind: "property", props: { title: "CPU" } };
+  build.entities.set("board", { lexicon, entityType: `${lexicon}::Board`, kind: "resource", props: { panels: [panel] } } as never);
+  build.entities.set("cpuPanel", panel as never);
+  return build;
+}
+
 const meta = (overrides: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
   type: "AWS::S3::Bucket",
   status: "CREATE_COMPLETE",
@@ -537,6 +550,37 @@ describe("runLifecycleDiff --live", () => {
   });
 
   // #1014 — property-level drift, gated purely on the deep capability.
+  test("hands only resource-kind entities to describeResources and observeResourcesDeep (#3001)", async () => {
+    buildMock.mockResolvedValue(buildWithPropertyKind("graf"));
+    fetchLifecycleMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+    const seen: { thin?: string[]; deep?: string[] } = {};
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "graf",
+        describeResources: async (opts) => {
+          seen.thin = [...opts.entities.keys()];
+          return { board: meta({ type: "graf::Board", physicalId: "uid-1" }) };
+        },
+        observeResourcesDeep: async (opts) => {
+          seen.deep = [...opts.entities.keys()];
+          return deepObservation({ board: { type: "graf::Board", properties: { panels: [{ title: "CPU" }] } } });
+        },
+      }),
+    ];
+    const exit = await runLifecycleDiff({
+      args: makeArgs({ path: "diff", extraPositional: "prod", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    expect(seen.thin).toEqual(["board"]);
+    expect(seen.deep).toEqual(["board"]);
+    const stdout = stdoutBuf.join("\n");
+    expect(stdout).not.toContain("cpuPanel");
+    expect(stdout).toContain("0 missing");
+  });
+
   describe("deep observation (#1014)", () => {
     const withDeep = (over: Parameters<typeof createMockPlugin>[0] = {}) =>
       createMockPlugin({
@@ -872,6 +916,29 @@ describe("runLifecyclePlan", () => {
     expect(stdoutBuf.join("\n")).toContain("bucket");
   });
 
+  test("proposes no create for a property-kind declarable its parent inlines (#3001)", async () => {
+    buildMock.mockResolvedValue(buildWithPropertyKind("graf"));
+    let names: string[] = [];
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "graf",
+        describeResources: async (opts) => {
+          names = opts.entityNames;
+          return { board: meta({ type: "graf::Board", physicalId: "uid-1" }) };
+        },
+      }),
+    ];
+    const exit = await runLifecyclePlan({
+      args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    expect(names).toEqual(["board"]);
+    const plan = JSON.parse(stdoutBuf.join("\n"));
+    expect(plan.entries.map((e: { name: string }) => e.name)).not.toContain("cpuPanel");
+  });
+
   // #1983 — `--report markdown` emits the reviewer-facing projection instead
   // of the human render, same as `--report gitlab-mr` swaps in the widget JSON.
   test("--report markdown emits the markdown projection instead of the human render", async () => {

package/src/cli/handlers/lifecycle.ts

@@ -42,7 +42,7 @@ import { unknownEnvError, isProdLikeEnvironment } from "../../env";
 import { planTeardown, executeTeardown, type TeardownPlan, type TeardownReport } from "../../lifecycle/teardown";
 import { collectBuildRootContributors } from "../plugins";
 import { applyLiveEndpoint } from "../../live-endpoint";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import type { LifecycleSnapshot } from "../../lifecycle/types";
@@ -812,13 +812,14 @@ async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<LiveDiffOutcome
     }
 
     // Build per-lexicon entity index. Resource declarables only — outputs,
-    // parameters and serializer directives have no live counterpart, and a
+    // parameters, serializer directives and property-kind declarables (read
+    // inside their parent, #3001) have no live counterpart of their own, and a
     // declared name the reader can never resolve reads as missing (see
     // lifecycle/observe.ts).
     const declared = new Set<string>();
     const entities: DeclaredEntities = new Map();
     for (const [name, entity] of args.buildResult.entities) {
-      if (entity.lexicon === lexiconName && isResourceDeclarable(entity)) {
+      if (entity.lexicon === lexiconName && isObservableDeclarable(entity)) {
         declared.add(name);
         // Path origins are carried across explicitly (#1443): this map is plain
         // objects, and the symbol-keyed provenance channel does not survive it.
@@ -1289,11 +1290,11 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         // A receipt has no `props` payload of its own but is declared, diffed,
         // and observed like any resource (#1832) — it joins the declared axis
         // so its lexicon's observation can confirm presence or absence.
-        if (entity.lexicon === lexiconName && (isResourceDeclarable(entity) || isEffectReceipt(entity))) {
+        if (entity.lexicon === lexiconName && (isObservableDeclarable(entity) || isEffectReceipt(entity))) {
           declared.add(name);
           entities.set(name, {
             entityType: entity.entityType,
-            props: (isResourceDeclarable(entity) && entity.props != null ? entity.props : {}) as Record<string, unknown>,
+            props: (isObservableDeclarable(entity) && entity.props != null ? entity.props : {}) as Record<string, unknown>,
           });
         }
       }

package/src/cli/handlers/misc.ts

@@ -324,6 +324,7 @@ export async function runImport(ctx: CommandContext): Promise<number> {
       lexicon: "k8s",
       output: args.output,
       force: args.force,
+      parserOptions: args.parserOption,
     });
     printImportResult(result);
     return result.success ? 0 : 1;
@@ -381,6 +382,7 @@ export async function runImport(ctx: CommandContext): Promise<number> {
     output: ctx.args.output,
     force: ctx.args.force,
     lexicon: ctx.args.lexicon,
+    parserOptions: ctx.args.parserOption,
   });
 
   printImportResult(result);

package/src/cli/handlers/operator.ts

@@ -9,7 +9,7 @@
 import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { build } from "../../build";
-import { isResourceDeclarable } from "../../declarable";
+import { isObservableDeclarable } from "../../declarable";
 import { collectBuildRootContributors, collectChangeSubscribers } from "../plugins";
 import { discoverOps, discoverStewards } from "../../op/discover";
 import { pickSteward, stewardBesideOf, stewardFormFor, stewardLeaseName, stewardTurnOps, DEFAULT_STEWARD_ENV } from "../../op/steward";
@@ -116,7 +116,7 @@ async function collectOperatorSubscribers(
     // subscription may watch.
     const entities = new Map<string, Map<string, { entityType: string; props: Record<string, unknown> }>>();
     for (const [name, entity] of buildResult.entities) {
-      if (!isResourceDeclarable(entity)) continue;
+      if (!isObservableDeclarable(entity)) continue;
       let perLexicon = entities.get(entity.lexicon);
       if (!perLexicon) entities.set(entity.lexicon, (perLexicon = new Map()));
       perLexicon.set(name, {
@@ -902,6 +902,7 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     allowSameOrigin: ctx.args.allowSameOrigin,
     ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
     ...(ctx.args.agent ? { agent: true } : {}),
+    ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
   });
   if (!outcome.ok) return 1;
 
@@ -959,6 +960,15 @@ export interface GateApprovalOptions {
    * model-authored channel it is one whether or not this is set.
    */
   agent?: boolean;
+  /**
+   * `--sign [<key file>]` (#3163, ws-080): seal the approval with an ssh key,
+   * a key file or true for git's `user.signingkey`. The seal attests the
+   * approver when the signers file at base lists the key for them, and a gate
+   * the declaration's `identity.gates` names counts only sealed approvals.
+   */
+  sign?: string | true;
+  /** Where the workspace and the key file are looked up from. Defaults to the process's directory. */
+  cwd?: string;
   /** Replaces the lexicon evaluator a gate policy is loaded from. For tests. */
   evaluator?: GatePolicyEvaluator;
 }
@@ -1107,6 +1117,78 @@ export async function recordGateApproval(
     ...(opts.roles && opts.roles.length > 0 ? { roles: [...new Set(opts.roles)] } : {}),
   };
 
+  // #3163, ws-080: the declaration at base may require a checkable approver
+  // (identity.attribution "identified") and a signed approval for this gate
+  // (identity.gates). Both are judged before anything is written.
+  const cwd = opts.cwd ?? process.cwd();
+  const identity = await import("../../workspace/identity");
+  const { scopeSource } = await import("../../workspace/write-scope");
+  const scope = scopeSource(cwd);
+  try {
+    identity.refuseUnidentified(scope, [resolvedBy], opts.actor !== undefined ? "--actor" : "the approver");
+  } catch (err) {
+    if (!(err instanceof identity.IdentityError)) throw err;
+    console.error(formatError({
+      message: `Gate "${gate}" on "${opName}" was not approved: ${err.message}`,
+      hint: "Pass --actor <forge identity or signer>, as the surface that signed the person in maps them, for example --actor github:<login>.",
+    }));
+    return { ok: false };
+  }
+  const rule = identity.gateAdmissionFrom(scope, gate);
+  if (rule && opts.sign === undefined) {
+    console.error(formatError({
+      message:
+        `Gate "${gate}" needs a signed approval: chant.workspace.json at base names it in identity.gates` +
+        (rule.requirement.class !== null ? `, from the class ${rule.requirement.class}` : "") +
+        `, and this approval is not signed`,
+      hint: `chant approve ${opName} ${gate} --actor <principal> --sign [<key file>], with a key ${scope.policy.signersPath} at base lists for that principal.`,
+    }));
+    return { ok: false };
+  }
+  const timestamp = new Date().toISOString();
+  let seal: GateResolutionRecord["seal"];
+  if (opts.sign !== undefined) {
+    const { resolveSigningKey, sealGateApproval, SealError } = await import("../../workspace/trust/seal");
+    try {
+      const key = resolveSigningKey(opts.sign, cwd);
+      try {
+        seal = sealGateApproval(key.file, {
+          op: opName,
+          gate,
+          ...(environment !== undefined ? { environment } : {}),
+          ...(planDigest !== undefined ? { planDigest } : {}),
+          resolvedBy,
+          timestamp,
+        });
+      } finally {
+        key.cleanup();
+      }
+    } catch (err) {
+      if (!(err instanceof SealError)) throw err;
+      console.error(formatError({ message: `Gate "${gate}" on "${opName}" was not approved: ${err.message}` }));
+      return { ok: false };
+    }
+  }
+  if (rule) {
+    const why = rule.refuses({
+      op: opName,
+      gate,
+      ...(environment !== undefined ? { environment } : {}),
+      ...(planDigest !== undefined ? { planDigest } : {}),
+      resolvedBy,
+      timestamp,
+      seal,
+    });
+    if (why !== null) {
+      console.error(formatError({
+        message: `Gate "${gate}" on "${opName}" was not approved: ${why}`,
+        hint: `identity.gates.${gate} in chant.workspace.json at base counts only an approval signed by a key ${scope.policy.signersPath} lists for the approver` +
+          (rule.requirement.class !== null ? `, who holds the role of the class ${rule.requirement.class}` : "") + ".",
+      }));
+      return { ok: false };
+    }
+  }
+
   // #2508: a gate with a policy has it evaluated for this approval now, while
   // the approver is known, against the context the gated run recorded. The
   // decision is written next to the approval, so a pass can be traced to the
@@ -1148,7 +1230,8 @@ export async function recordGateApproval(
     op: opName,
     gate,
     resolvedBy,
-    timestamp: new Date().toISOString(),
+    timestamp,
+    ...(seal ? { seal } : {}),
     approver,
     ...(policyDecision ? { policyDecision } : {}),
     ...(opts.note ? { note: opts.note } : {}),
@@ -1166,6 +1249,7 @@ export async function recordGateApproval(
   console.error(formatSuccess(
     `Gate "${gate}" on "${opName}" resolved by ${record.resolvedBy} at ${record.timestamp}` +
       (record.url ? ` (${record.url})` : "") +
+      (record.seal ? `, signed with ${record.seal.key}` : "") +
       (pushed ? "" : " (local only — the push did not land)"),
   ));
   if (record.planDigest) {

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();