@intentius/chant 0.124.23 → 0.124.24

package/src/cli/handlers/emulator.ts

@@ -1,9 +1,9 @@
 import { exec, execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { emulatorLifecycle, emulatorsOf, type EmulatorCapability } from "../../op";
+import { checkSettings, emulatorLifecycle, emulatorsOf, type EmulatorCapability, type EmulatorUpArgs } from "../../op";
 import type { LexiconPlugin } from "../../lexicon";
 import { formatError, formatWarning, formatSuccess } from "../format";
-import type { CommandContext } from "../registry";
+import type { CommandContext, ParsedArgs } from "../registry";
 
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -116,13 +116,60 @@ export function parsePortMappings(values: readonly string[], targets: readonly E
   return ports;
 }
 
+/** The `up` options other than the port (#3952), per selected emulator. */
+type UpOptions = Pick<EmulatorUpArgs, "image" | "network" | "settings" | "loopback">;
+
+/**
+ * `--image`, `--network`, `--setting` and `--loopback` as each selected
+ * emulator's `up` options (#3952). `--image` needs exactly one emulator
+ * selected, the way a bare `--port` does. A `--setting` goes to each emulator
+ * whose settings prefix its key starts with, and a key that no selected
+ * emulator takes is refused rather than passed to a container as plain env.
+ */
+export function parseUpOptions(
+  args: Pick<ParsedArgs, "image" | "network" | "setting" | "loopback">,
+  targets: readonly EmulatorCapability[],
+): Map<EmulatorCapability, UpOptions> {
+  if (args.image !== undefined && targets.length !== 1) {
+    throw new Error(`--image ${args.image} is ambiguous with ${targets.length} emulators selected; pick one with --lexicon <name>`);
+  }
+  const settings = new Map<EmulatorCapability, Record<string, string>>();
+  for (const value of args.setting ?? []) {
+    const match = /^([^=]+)=(.*)$/s.exec(value);
+    if (!match) throw new Error(`--setting ${value}: expected <KEY>=<VALUE>, e.g. --setting FLOCI_<NAME>=<value>`);
+    const [, key, val] = match as unknown as [string, string, string];
+    const takers = targets.filter((t) => t.spec.settingsPrefix && key.startsWith(t.spec.settingsPrefix));
+    if (takers.length === 0) {
+      const prefixes = targets.filter((t) => t.spec.settingsPrefix).map((t) => `${t.spec.settingsPrefix}* (${t.spec.name})`);
+      throw new Error(`--setting ${key}: no selected emulator takes it; ${prefixes.length ? `the selected ones take ${prefixes.join(", ")}` : "the selected ones take no settings"}`);
+    }
+    for (const t of takers) {
+      const own = { ...settings.get(t), [key]: val };
+      checkSettings(t.spec, own);
+      settings.set(t, own);
+    }
+  }
+  const out = new Map<EmulatorCapability, UpOptions>();
+  for (const t of targets) {
+    const opts: UpOptions = {};
+    if (args.image !== undefined) opts.image = args.image;
+    if (args.network !== undefined) opts.network = args.network;
+    if (args.loopback) opts.loopback = true;
+    const own = settings.get(t);
+    if (own) opts.settings = own;
+    out.set(t, opts);
+  }
+  return out;
+}
+
 /**
  * `chant emulator --help` (#3673): the subcommands and flags, and for each
  * configured lexicon's emulator the port, endpoint and sign-in a client uses.
  */
 export function formatEmulatorHelp(plugins: readonly LexiconPlugin[]): string {
   const lines = [
-    "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--json]",
+    "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--image <ref>]",
+    "       [--network <name>] [--setting <KEY>=<VALUE>] [--loopback] [--json]",
     "",
     "Boot, stop or inspect the local emulators of the project's configured lexicons.",
     "",
@@ -137,6 +184,11 @@ export function formatEmulatorHelp(plugins: readonly LexiconPlugin[]): string {
     "  --lexicon <name>     Act on one lexicon's emulators only.",
     "  --port <c>=<h>       up: publish container port <c> on host port <h>; repeatable.",
     "                       A bare <h> works when one emulator is selected.",
+    "  --image <ref>        up: start this image instead of the pinned default; one emulator only.",
+    "  --network <name>     up: join each started container to this Docker network.",
+    "  --setting <K>=<V>    up: pass an emulator setting as -e K=V; repeatable. The key must",
+    "                       start with the emulator's prefix (FLOCI_ for aws).",
+    "  --loopback           up: publish ports on 127.0.0.1 only, not on every interface.",
     "  --json               Print the machine-readable report on stdout.",
     "",
   ];
@@ -195,9 +247,18 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
   }
 
   let ports: Map<number, number>;
+  let upOptions: Map<EmulatorCapability, UpOptions>;
   try {
     if (args.port?.length && action !== "up") throw new Error("--port applies to `chant emulator up` only");
+    const upOnly = [
+      args.image !== undefined && "--image",
+      args.network !== undefined && "--network",
+      args.setting?.length && "--setting",
+      args.loopback && "--loopback",
+    ].filter(Boolean);
+    if (upOnly.length && action !== "up") throw new Error(`${upOnly.join(", ")} applies to \`chant emulator up\` only`);
     ports = parsePortMappings(args.port ?? [], targets.map((t) => t.cap));
+    upOptions = parseUpOptions(args, targets.map((t) => t.cap));
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
@@ -209,7 +270,7 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
     if (action === "up") {
       const port = ports.get(cap.spec.containerPort);
       try {
-        const { endpoint } = await lc.up(port === undefined ? {} : { port });
+        const { endpoint } = await lc.up({ ...upOptions.get(cap), ...(port === undefined ? {} : { port }) });
         reports.push({ lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
       } catch (err) {
         console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));

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

@@ -39,6 +39,7 @@ vi.mock("../../config", async () => {
 });
 
 vi.mock("../../components/cli-support", () => ({
+  isComponentList: (selector: string) => selector.includes(","),
   resolveComponentTargets: (...args: unknown[]) => resolveTargetsMock(...args),
 }));
 
@@ -286,6 +287,12 @@ describe("chant components rollback", () => {
     expect(appendReleaseRecordMock.mock.calls[0][0]).not.toHaveProperty("promotedFrom");
   });
 
+  test("a comma list is refused: rollback acts on one component (#3950)", async () => {
+    expect(await runComponentsRollback(rb({ component: "api,web" }))).toBe(1);
+    expect(errors.join("\n")).toMatch(/--component takes one component name, not a list/);
+    expect(ran).toEqual([]);
+  });
+
   test("a digest the environment never recorded fails clearly", async () => {
     expect(await runComponentsRollback(rb({ digest: "sha256:elsewhere" }))).toBe(1);
     expect(errors.join("\n")).toMatch(/sha256:elsewhere is not recorded for "api" in "prod"/);

package/src/cli/handlers/promote.ts

@@ -25,7 +25,7 @@ import {
   type ReleaseRecord,
   type ReleaseRecordInput,
 } from "../../lifecycle/release-ledger";
-import { resolveComponentTargets } from "../../components/cli-support";
+import { isComponentList, resolveComponentTargets } from "../../components/cli-support";
 import { applyConfigDefaults } from "../../components/config-defaults";
 import { fanOutRegistry } from "../../components/fan-out-support";
 import { renderDriverHuman } from "../../components/driver-output";
@@ -107,6 +107,12 @@ async function loadProject(ctx: CommandContext, selector: string) {
     for (const message of paramsResolution.errors) console.error(message);
     return 1;
   }
+  // A comma list is `chant run --components`' selector (#3950), which pulls in
+  // dependencies; promote, rollback and redeploy act on the one named component.
+  if (isComponentList(selector)) {
+    console.error(formatError({ message: `--component takes one component name, not a list ("${selector}")` }));
+    return 1;
+  }
   const targets = await resolveComponentTargets(projectPath, selector, args.sandbox, paramsResolution.provenance);
   if (!targets.success) {
     console.error(formatError({ message: targets.error ?? "Could not discover components" }));

package/src/cli/handlers/run-no-record.e2e.test.ts

@@ -0,0 +1,87 @@
+/**
+ * #3955 — `chant run <op> --no-record` through the real CLI: the run executes,
+ * says at its start and end that it recorded nothing, and leaves
+ * `chant/lifecycle` where it was, both in the checkout and on origin. A plain
+ * run beside it records, so the unchanged ref is the flag's doing.
+ */
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, git, repo, REPO } from "../../workspace/__fixtures__/contract-repo";
+import { pushLifecycleStatus, writeBlobToPath } from "../../lifecycle/git";
+
+const MAIN = join(REPO, "packages/core/src/cli/main.ts");
+const LOADER = pathToFileURL(join(REPO, "node_modules/tsx/dist/loader.mjs")).href;
+
+/** An Op entity as `Op()` exports it, written as a literal so the fixture needs no import to resolve. */
+function opModule(name: string, steps: unknown[]): string {
+  return `export const op = ${JSON.stringify({ entityType: "Chant::Op", props: { name, overview: name, phases: [{ name: "Main", steps }] } })};\n`;
+}
+
+const SHELL = { kind: "activity", fn: "shellCmd", profile: "atMostOnce", args: { cmd: "echo ran" } };
+
+let dir: string;
+let remote: string;
+
+beforeAll(async () => {
+  remote = repo({}, false);
+  git(remote, "config", "core.bare", "true");
+  dir = repo(
+    {
+      "chant.config.ts": "export default { lexicons: [] };\n",
+      "ops/hello.op.ts": opModule("hello", [SHELL]),
+      "ops/gated.op.ts": opModule("gated", [{ kind: "gate", gate: "approve-prod" }, SHELL]),
+    },
+    false,
+  );
+  git(dir, "config", "user.name", "Run Test");
+  git(dir, "config", "user.email", "run@example.com");
+  commitAll(dir, "c0");
+  git(dir, "remote", "add", "origin", join(remote, ".git"));
+  await writeBlobToPath("seed", "seed.json", "{}\n", "seed", { cwd: dir });
+  expect((await pushLifecycleStatus({ cwd: dir })).status).toBe("pushed");
+});
+afterAll(cleanScratch);
+
+function chant(args: string[], env: Record<string, string> = {}): { status: number | null; stderr: string } {
+  const r = spawnSync(process.execPath, ["--import", LOADER, MAIN, ...args], {
+    cwd: dir,
+    encoding: "utf8",
+    env: { ...process.env, NO_COLOR: "1", TSX_DISABLE_CACHE: "1", CHANT_NO_RECORD: "", ...env },
+  });
+  return { status: r.status, stderr: r.stderr };
+}
+
+function ledgerRefs(): { local: string; origin: string } {
+  return { local: git(dir, "rev-parse", "refs/heads/chant/lifecycle"), origin: git(dir, "ls-remote", "origin", "refs/heads/chant/lifecycle").split(/\s/)[0]! };
+}
+
+describe("chant run --no-record (#3955)", () => {
+  test("runs the Op, says so at the start and the end, and leaves the ledger ref unchanged here and on origin", () => {
+    const before = ledgerRefs();
+    const r = chant(["run", "hello", "--no-record"]);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.stderr).toContain("not recording (--no-record): nothing this run writes goes on chant/lifecycle");
+    expect(r.stderr).toMatch(/not recorded \(--no-record\): nothing went on chant\/lifecycle and nothing was pushed; 1 ledger write was dropped \(1 file\)/);
+    expect(ledgerRefs()).toEqual(before);
+  });
+
+  test("CHANT_NO_RECORD=1 fails a gate without writing a pending fact", () => {
+    const before = ledgerRefs();
+    const r = chant(["run", "gated"], { CHANT_NO_RECORD: "1" });
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('gate "approve-prod" of "gated" cannot be passed under --no-record');
+    expect(r.stderr).toContain("not recorded (CHANT_NO_RECORD=1)");
+    expect(ledgerRefs()).toEqual(before);
+  });
+
+  test("a plain run of the same Op records its run", () => {
+    const before = ledgerRefs();
+    const r = chant(["run", "hello"]);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.stderr).not.toContain("not recording");
+    // The run record moves the local branch; it is pushed by the next write that pushes.
+    expect(ledgerRefs().local).not.toBe(before.local);
+  });
+});

package/src/cli/handlers/run-wave.ts

@@ -29,16 +29,16 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
   if (!specFile || args.wave === undefined) {
     console.error(formatError({
       message: "`chant run wave` needs --spec <file> and --wave <k>",
-      hint: "Run it as a generated Op waves pipeline does: chant run wave --spec <file> --wave <k> [--decide | --share <i>]",
+      hint: "Run it as a generated Op waves pipeline does: chant run wave --spec <file> --wave <k> [--decide | --share <i> | --group <name> [--share <i>]]",
     }));
     return 1;
   }
-  if (args.decide && args.share !== undefined) {
-    console.error(formatError({ message: "--decide and --share are two different jobs; pass one" }));
+  if (args.decide && (args.share !== undefined || args.group !== undefined)) {
+    console.error(formatError({ message: `--decide and --${args.share !== undefined ? "share" : "group"} are two different jobs; pass one` }));
     return 1;
   }
   let spec: OpWavesSpec | undefined;
-  const job = args.share !== undefined ? { share: args.share } : {};
+  const job = { ...(args.share !== undefined ? { share: args.share } : {}), ...(args.group !== undefined ? { group: args.group } : {}) };
   try {
     const path = resolve(specFile);
     spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
@@ -48,6 +48,7 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
       wave: args.wave,
       ...(args.decide ? { decide: true } : {}),
       ...(args.share !== undefined ? { share: args.share } : {}),
+      ...(args.group !== undefined ? { group: args.group } : {}),
       ...(args.base ? { base: args.base } : {}),
     });
     if (args.json) console.log(JSON.stringify(result, null, 2));

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

@@ -61,6 +61,7 @@ vi.mock("node:fs", async () => {
   };
 });
 vi.mock("../../components/cli-support", () => ({
+  isComponentList: (selector: string) => selector.includes(","),
   runComponents: (...args: unknown[]) => runComponentsMock(...args),
   listComponents: (...args: unknown[]) => listComponentsMock(...args),
 }));
@@ -1277,6 +1278,25 @@ describe("runOp dispatcher: --components routes to runOpComponents", () => {
     vi.restoreAllMocks();
   });
 
+  test("a list selector prints the resolved order and the added dependencies before running (#3950)", async () => {
+    discoverOpsMock.mockReset();
+    const stderr = makeStderrSpy();
+    let printedBeforeRun = "";
+    runComponentsMock.mockImplementation(async (_path: string, _selector: string, options: { onPlan?: (plan: unknown) => void }) => {
+      options.onPlan?.({ order: ["db", "api", "web"], waves: [["db"], ["api", "web"]], added: ["db"] });
+      printedBeforeRun = stderr.join("\n");
+      return { success: true, selected: ["db", "api", "web"], run: { order: ["db", "api", "web"], waves: [["db"], ["api", "web"]], results: [], ok: true, status: "ok" } };
+    });
+
+    const exit = await runOp({ args: makeArgs({ path: "api,web", components: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(runComponentsMock).toHaveBeenCalledWith(expect.any(String), "api,web", expect.objectContaining({ onPlan: expect.any(Function) }));
+    expect(printedBeforeRun).toContain("run order: db, then api + web");
+    expect(printedBeforeRun).toContain("added as dependencies: db");
+    vi.restoreAllMocks();
+  });
+
   // chant #1116 — the component driver never checked --report, so it was
   // silently ignored and the command fell through to a real dispatch.
   // Hard-error instead, before runComponents is ever reached.
@@ -1929,3 +1949,109 @@ describe("runOp: --fail-on-drift (#3675)", () => {
     expect(await runOp({ args: makeArgs({ path: "watch" }), plugins: [], serializers: [] })).toBe(2);
   });
 });
+
+/**
+ * chant #3955 — `--no-record` runs every step and records nothing on
+ * `chant/lifecycle`. The run says so before it starts and after it ends, a
+ * gate fails rather than recording a pending fact nobody could approve, and
+ * a runtime that would record elsewhere is refused.
+ */
+describe("runOp --no-record (#3955)", () => {
+  const START = "not recording (--no-record)";
+  const END = "not recorded (--no-record): nothing went on chant/lifecycle and nothing was pushed";
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadChantConfigMock.mockReset().mockResolvedValue({ config: {} });
+    loadPluginsMock.mockReset().mockResolvedValue([]);
+    runComponentsMock.mockReset();
+    maybeRecordAutoReleaseMock.mockReset();
+    maybePersistBuildManifestMock.mockReset().mockResolvedValue({ persisted: false, reason: "no-manifest" });
+    gateLedger = memoryGateLedgerPort();
+    delete process.env.CHANT_NO_RECORD;
+  });
+
+  afterEach(() => {
+    delete process.env.CHANT_NO_RECORD;
+    vi.restoreAllMocks();
+  });
+
+  test("an Op runs, the run says at its start and end that nothing was recorded, and the flag does not outlive it", async () => {
+    let during: string | undefined;
+    discoverOpsMock.mockImplementation(async () => {
+      during = process.env.CHANT_NO_RECORD;
+      return { ops: new Map([localOp("hello", [{ kind: "activity", fn: "shellCmd", profile: "atMostOnce", args: { cmd: "true" } }])]), errors: [] };
+    });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "hello", noRecord: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(during).toBe("1");
+    expect(process.env.CHANT_NO_RECORD).toBeUndefined();
+    expect(stderr[0]).toContain(START);
+    expect(stderr.at(-1)).toContain(END);
+  });
+
+  test("a gate fails the run and leaves no pending fact, and the end line still prints", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("gated", [{ kind: "gate", gate: "approve-prod" }])]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gated", noRecord: true, gatedExit: 0 }), plugins: [], serializers: [] });
+
+    // A failure, not a gated stop: --gated-exit cannot turn it green.
+    expect(exit).toBe(1);
+    expect(gateLedger.appended).toHaveLength(0);
+    expect(stderr.at(-1)).toContain(END);
+  });
+
+  test("CHANT_NO_RECORD does the same without the flag, names itself, and stays set", async () => {
+    process.env.CHANT_NO_RECORD = "1";
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("hello", [])]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "hello" }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(stderr[0]).toContain("not recording (CHANT_NO_RECORD=1)");
+    expect(process.env.CHANT_NO_RECORD).toBe("1");
+  });
+
+  test("a runtime other than local is refused before the run starts", async () => {
+    const start = vi.fn();
+    loadChantConfigMock.mockResolvedValue({ config: { lexicons: ["stub"] } });
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({
+      args: makeArgs({ path: "hello", on: "stub", noRecord: true }),
+      plugins: [{ name: "stub", opRuntime: { name: "stub", start } } as never], serializers: [],
+    });
+
+    expect(exit).toBe(1);
+    expect(start).not.toHaveBeenCalled();
+    expect(stderr.join("\n")).toContain('--no-record runs on the local runtime; the "stub" runtime records the run where it executes it');
+  });
+
+  test("--components records no release and persists no manifest", async () => {
+    runComponentsMock.mockResolvedValue({
+      success: true,
+      selected: ["svc"],
+      run: { order: ["svc"], waves: [["svc"]], results: [{ component: "svc", ok: true, status: "ok", records: [] }], ok: true, status: "ok" },
+    });
+    maybeRecordAutoReleaseMock.mockResolvedValue({ recorded: false, reason: "opted-out" });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const stderr = makeStderrSpy();
+
+    const exit = await runOpComponents({ args: makeArgs({ path: "svc", noRecord: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(maybeRecordAutoReleaseMock.mock.calls[0][1]).toMatchObject({ disabled: true });
+    expect(maybePersistBuildManifestMock.mock.calls[0][1]).toMatchObject({ disabled: true });
+    expect(stderr[0]).toContain(START);
+    expect(stderr.at(-1)).toContain(END);
+  });
+});

package/src/cli/handlers/run.ts

@@ -23,11 +23,13 @@ import { acquireStewardTurn, STEWARD_TURN_WAIT_MS } from "../../op/operator";
 import { releaseLease, currentHolderId, type AcquireLeaseResult } from "../../lifecycle/lease";
 import { StaleLockError } from "../../lifecycle/git";
 import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
+import { ledgerRecordingOff, noRecordEndNote, noRecordStartNote, resetNoRecordLedger, NO_RECORD_ENV } from "../../lifecycle/no-record";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
 import { maybeRecordAutoRelease } from "../../components/auto-release";
 import { maybePersistBuildManifest } from "../../components/manifest-persistence";
 import type { DriverComponentResult } from "../../components/driver";
+import { isComponentList, type ComponentRunPlan } from "../../components/cli-support";
 import type { ReleaseRecord } from "../../lifecycle/release-ledger";
 import { runOpGenerate } from "./run-generate";
 
@@ -873,12 +875,13 @@ export async function recordAutoReleasesForRun(
   return recorded;
 }
 
-// ── chant run --components <name|all> ────────────────────────────────────────
+// ── chant run --components <name|all|a,b,c> ──────────────────────────────────
 
 /**
- * `chant run --components <name|all> [--env <env>]` (#585) — the interpret
- * driver's CLI entrypoint, and since #2116 the only component run path there
- * is. `args.path` is the component name (or `all`), matching `chant run
+ * `chant run --components <name|all|a,b,c> [--env <env>]` (#585) — the
+ * interpret driver's CLI entrypoint, and since #2116 the only component run
+ * path there is. `args.path` is the component name (or `all`, or a comma list
+ * that also runs what the named components depend on, #3950), matching `chant run
  * <name>`'s Op-dispatch convention exactly (`args.path` is the Op name there
  * too) rather than a project directory — components are always discovered from
  * the current working directory, the same way Op discovery (`discoverOps()`)
@@ -909,11 +912,52 @@ export async function recordAutoReleasesForRun(
  * auto-release check below used to apply itself) and reused for that check,
  * rather than loaded a second time.
  */
-export async function runOpComponents(ctx: CommandContext): Promise<number> {
+export function runOpComponents(ctx: CommandContext): Promise<number> {
+  return withRecordingChoice(ctx, () => runComponentSelection(ctx));
+}
+
+/**
+ * Run `run` with recording off when `--no-record` or `CHANT_NO_RECORD` asks
+ * for it (#3955), and say so before it starts and after it ends, whatever
+ * the outcome. The flag sets `CHANT_NO_RECORD` for the length of the run, so
+ * the ledger seam (`../../lifecycle/git.ts`) and every chant process a step
+ * starts see the same choice. A run with recording on is untouched.
+ */
+async function withRecordingChoice(ctx: CommandContext, run: () => Promise<number>): Promise<number> {
+  const flagged = ctx.args.noRecord === true;
+  if (!flagged && !ledgerRecordingOff()) return run();
+  const source = flagged ? "--no-record" : `${NO_RECORD_ENV}=${process.env[NO_RECORD_ENV]}`;
+  const prior = process.env[NO_RECORD_ENV];
+  if (flagged) process.env[NO_RECORD_ENV] = "1";
+  resetNoRecordLedger();
+  console.error(formatWarning({ message: noRecordStartNote(source) }));
+  try {
+    return await run();
+  } finally {
+    console.error(formatWarning({ message: noRecordEndNote(source) }));
+    resetNoRecordLedger();
+    if (flagged) {
+      if (prior === undefined) delete process.env[NO_RECORD_ENV];
+      else process.env[NO_RECORD_ENV] = prior;
+    }
+  }
+}
+
+/** A run that records nothing stays in this process (#3955): a runtime that runs it elsewhere would record there. */
+function refusesNoRecordOn(runtime: Pick<OpRuntimeProvider, "name">): boolean {
+  if (!ledgerRecordingOff() || runtime.name === "local") return false;
+  console.error(formatError({
+    message: `--no-record runs on the local runtime; the "${runtime.name}" runtime records the run where it executes it`,
+    hint: `Omit --on to run it here without recording, or drop --no-record (and ${NO_RECORD_ENV}).`,
+  }));
+  return true;
+}
+
+async function runComponentSelection(ctx: CommandContext): Promise<number> {
   const selector = ctx.args.path;
   if (!selector || selector === ".") {
     console.error(formatError({
-      message: "Component name is required: chant run --components <name|all>",
+      message: "Component name is required: chant run --components <name|all|a,b,c>",
       hint: "Run `chant list --components` to see available components.",
     }));
     return 1;
@@ -936,6 +980,7 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
 
   const runtime = await resolveOpRuntime(ctx);
   if (!runtime) return 1;
+  if (refusesNoRecordOn(runtime)) return 1;
   if (!runtime.runComponents) {
     console.error(formatError({
       message: `--components is not supported on the "${runtime.name}" runtime`,
@@ -966,12 +1011,22 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
   // `undefined` and every `onProgress?.(...)` call in the driver is a no-op —
   // behavior is byte-for-byte unchanged from before this flag existed.
   const onProgress = ctx.args.progressJson ? ndjsonProgressSink() : undefined;
+  // A list (#3950) pulls in what its components depend on; say which ones and
+  // in what order before the first one runs. stderr, so --json and
+  // --progress-json keep stdout to themselves.
+  const onPlan = isComponentList(selector)
+    ? (plan: ComponentRunPlan) => {
+        console.error(formatInfo(`run order: ${plan.waves.map((wave) => wave.join(" + ")).join(", then ")}`));
+        if (plan.added.length > 0) console.error(formatInfo(`added as dependencies: ${plan.added.join(", ")}`));
+      }
+    : undefined;
   const result = await runtime.runComponents(projectPath, selector, {
     env: ctx.args.env,
     componentOutputs: seededOutputs,
     onProgress,
     sandbox: ctx.args.sandbox,
     buildParams: paramsResolution.provenance,
+    ...(onPlan ? { onPlan } : {}),
   });
 
   // Dump the accumulated outputs for a downstream job to seed from. Written
@@ -1037,7 +1092,8 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
   }
 
   if (result.success && result.run) {
-    const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord);
+    // #3955: a run that records nothing has no release to report either.
+    const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord) || ledgerRecordingOff();
     const recorded = await recordAutoReleasesForRun(result.run.results, env, `local-${Date.now()}`, disabled);
     // `--digest-file` (#2602): the releases this run recorded, one
     // `<component>=<digest>` line each, the form `chant components promote
@@ -1065,7 +1121,11 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
  * what they were before the seam existed; a runtime that reports only a state
  * gets the terser render instead.
  */
-export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
+export function runOpOnRuntime(ctx: CommandContext): Promise<number> {
+  return withRecordingChoice(ctx, () => runOpOnResolvedRuntime(ctx));
+}
+
+async function runOpOnResolvedRuntime(ctx: CommandContext): Promise<number> {
   const opName = ctx.args.path;
   if (!opName || opName === ".") {
     console.error(formatError({
@@ -1108,7 +1168,7 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
   }
 
   const runtime = await resolveOpRuntime(ctx);
-  if (!runtime) {
+  if (!runtime || refusesNoRecordOn(runtime)) {
     await stewardGate?.release?.();
     return 1;
   }

package/src/cli/main.test.ts

@@ -361,6 +361,22 @@ describe("parseArgs", () => {
 
   // ── --no-release-record (#597) ───────────────────────────────────────────
 
+  test("emulator up --image/--network/--setting/--loopback parse, and a missing value is refused (#3952)", () => {
+    const a = parseArgs([
+      "emulator", "up", "--image", "floci/floci:1.6.0", "--network", "loom",
+      "--setting", "FLOCI_A=1", "--setting", "FLOCI_B=2", "--loopback",
+    ]);
+    expect(a.image).toBe("floci/floci:1.6.0");
+    expect(a.network).toBe("loom");
+    expect(a.setting).toEqual(["FLOCI_A=1", "FLOCI_B=2"]);
+    expect(a.loopback).toBe(true);
+    expect(parseArgs(["emulator", "up", "--setting=FLOCI_A=1"]).setting).toEqual(["FLOCI_A=1"]);
+    expect(() => parseArgs(["emulator", "up", "--image"])).toThrow(/--image needs an image reference/);
+    expect(() => parseArgs(["emulator", "up", "--network", "--json"])).toThrow(/--network needs a Docker network name/);
+    expect(() => parseArgs(["emulator", "up", "--setting"])).toThrow(/--setting needs a value/);
+    expect(() => parseArgs(["emulator", "up", "--loopback=yes"])).toThrow();
+  });
+
   test("--promote-to <env> sets promoteTo, and a missing value is refused (#2575)", () => {
     expect(parseArgs(["build", "--components", "--generate", "github", "--promote-to", "prod"]).promoteTo).toBe("prod");
     expect(() => parseArgs(["build", "--components", "--generate", "github", "--promote-to"])).toThrow(/--promote-to needs an environment/);
@@ -390,6 +406,14 @@ describe("parseArgs", () => {
     expect(result.noReleaseRecord).toBeUndefined();
   });
 
+  test("parses --no-record for run <op> and run --components, apart from --no-release-record (#3955)", () => {
+    expect(parseArgs(["run", "smoke", "--no-record"])).toMatchObject({ path: "smoke", noRecord: true });
+    const components = parseArgs(["run", "--components", "svc", "--no-record"]);
+    expect(components).toMatchObject({ components: true, noRecord: true });
+    expect(components.noReleaseRecord).toBeUndefined();
+    expect(parseArgs(["run", "smoke"]).noRecord).toBeUndefined();
+  });
+
   // ── --progress-json (M3, behold roadmap) ─────────────────────────────────
 
   test("parses --progress-json for run --components", () => {