@intentius/chant 0.124.23 → 0.124.25

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", () => {
@@ -979,3 +1003,13 @@ describe("chant workspace check --generated (#2641)", () => {
     expect(() => parseArgs(["workspace", "check", "--generated=yes"])).toThrow();
   });
 });
+
+describe("chant --help", () => {
+  test("lists every top-level command in the registry", () => {
+    const source = readFileSync(join(import.meta.dirname, "main.ts"), "utf-8");
+    const help = source.slice(source.indexOf("function printHelp("), source.indexOf("Options:", source.indexOf("function printHelp(")));
+    const listed = new Set([...help.matchAll(/^ {2}([a-z][a-z-]*)\b/gm)].map((m) => m[1]));
+    const commands = new Set(commandRegistry.map((def) => def.name.split(" ")[0]));
+    expect([...commands].filter((name) => !listed.has(name))).toEqual([]);
+  });
+});

package/src/cli/main.ts

@@ -167,7 +167,12 @@ Commands:
                         okf emits an OKF v0.2 knowledge bundle — one markdown
                         concept per entity + index.md; -o <dir> writes the
                         bundle tree, otherwise JSON path→content on stdout)
-  generate              Generate typed code from sources chant.config declares
+  search "<query>"      Answer an estate question with a few matching rows
+                        instead of a graph dump (kind:, tag:, attr:, ->/<- edge
+                        terms; --live or --at <ref> with --env <name> reads the
+                        estate or a recorded snapshot; --show <attr>,
+                        --check-live, --check-snapshot, --fail-on-drift)
+  generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
                         output no longer matches its sources, as build does
@@ -253,6 +258,8 @@ Ops:
                         with a work lease runs under, and who holds it
                         --fail-on-drift: exit 2 when the run completes and
                         its Drift outcome is true (WatchOp failOn: "drift")
+                        --no-record: a test run that records nothing on
+                        chant/lifecycle and pushes nothing (local runtime)
   run list              List all Ops with the runtime's state for each
   run status <name>     Show the runtime's state for one Op's latest run
   run approve <op> <gate>  Record a gate's resolution and wake the runtime
@@ -261,7 +268,8 @@ Ops:
   run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
                         waves spec (#3679): the job a generated waves
                         pipeline runs. --decide plans and decides only;
-                        --share <i> applies one share of a decided wave.
+                        --share <i> applies one share of a decided wave;
+                        --group <name> applies one job group's runs.
                         --record-plans (no --wave), in a pull request's
                         pipeline: plan every wave at its head and record the
                         digests a pr-review approval mode compares
@@ -278,8 +286,11 @@ Ops:
                         declares a schedule or from --spec <file.json>.
                         Files go to the forge's own directory unless
                         --output <dir>; --format json prints them instead
-  run --components <name|all>  Run discovered Component(s) through the interpret
-                        driver on the local executor (--env <env>; #585).
+  run --components <name|all|a,b,c>  Run discovered Component(s) through the
+                        interpret driver on the local executor (--env <env>;
+                        #585). A comma list also runs what the named
+                        components depend on, in dependency order, in one
+                        run, and prints that order first (#3950).
                         On success, auto-emits a release-ledger record per
                         component that published a digest (default: on;
                         --no-release-record to opt out; #597)
@@ -396,9 +407,11 @@ Workspace (level 1, #2524):
                         state transitions, new verdicts, new supersessions
                         and changed pins. A session id compares the commits
                         the session opened and closed at
-  workspace records pin <path>
+  workspace records pin <path> [--kind <kind file>]
                         Print the path from the workspace root and the
-                        sha256 of a file, for a decision's evidence pin
+                        sha256 of a file, for a decision's evidence pin. The
+                        root is the kind file's workspace with --kind, else
+                        the workspace above the current directory
   workspace records new [<kind file>] --from <file|-> [--prefix <prefix>] [--sign [<key file>]] [--dry-run]
                         Write one new record in the kind's directory from
                         the JSON fields given, after validating them as
@@ -553,6 +566,11 @@ Workspace (level 1, #2524):
   workspace points retract <id> --by <name>... [--note <text>] [--kind <kind file>] [--dry-run]
                         Take an answer back: the question is open for people
                         again, and the answer stays in its retractions
+  workspace points withdraw <id> --by <name>... [--note <text>] [--kind <kind file>] [--dry-run]
+                        Close an open question that no longer applies, such as
+                        one about a work item its author changed: points --open
+                        leaves it out, nobody answers it, and asking it again
+                        opens it again (#2888)
   workspace pin <path> [--json]
                         Print the integrity value that pins the plugin at
                         <path>, to put in a path pin of chant.workspace.json.
@@ -807,7 +825,8 @@ Lexicon development:
 Local:
   emulator <up|down|status>  Boot/stop/inspect configured lexicons' local
                            emulators (Floci etc.); --lexicon <name>, --json,
-                           --port; \`chant emulator --help\` lists ports and logins
+                           --port, --image, --network, --setting, --loopback;
+                           \`chant emulator --help\` lists ports and logins
 
 Servers:
   serve lsp             Start the LSP server (stdio)
@@ -880,6 +899,12 @@ Options:
                         successful \`run --components\` deploy (default: on;
                         also settable via chant.config.ts's
                         release.autoRecord: false; #597)
+  --no-record           (run <op>, run --components) Run every step but record
+                        nothing on chant/lifecycle and push nothing: no
+                        release, run record, receipt or gate fact. A gate
+                        step fails. The run says so at its start and end.
+                        CHANT_NO_RECORD=1 does the same for a whole CI job
+                        (#3955)
   --fold                (build) Fold source modules statically instead of
                         running them; folds resource constructors and
                         composite factory calls (#1022/#1023), falling back
@@ -1213,16 +1238,18 @@ export const commandRegistry: CommandDef[] = [
 
   // Workspace reads (#2524). Imported on first use, so a level-0 command never
   // loads anything under workspace/ (#2525 rule 5, pinned by #2526's goldens).
-  { name: "workspace records", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceRecords(ctx) },
+  // #3276 — records, points, ls and status read the declaration and never the
+  // config of the member they run in, so they skip its load (and tsx with it).
+  { name: "workspace records", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceRecords(ctx) },
   // ws-058 (#2739) — decision points and the questions asked of them; never calls a model.
-  { name: "workspace points", handler: async (ctx) => (await import("../workspace/points-cli")).runWorkspacePoints(ctx) },
+  { name: "workspace points", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/points-cli")).runWorkspacePoints(ctx) },
   { name: "workspace init", handler: async (ctx) => (await import("../workspace/init")).runWorkspaceInit(ctx) },
-  { name: "workspace ls", handler: async (ctx) => (await import("../workspace/ls")).runWorkspaceLs(ctx) },
+  { name: "workspace ls", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ls")).runWorkspaceLs(ctx) },
   // #2732 — the work lease: claim, renew and release a work item.
   { name: "workspace work", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/work-cli")).runWorkspaceWork(ctx) },
   // #3033 — the agent run record: what each run cost and which commits it made. chant records runs and never starts one.
   { name: "workspace runs", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/runs-cli")).runWorkspaceRuns(ctx) },
-  { name: "workspace status", handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
+  { name: "workspace status", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
   { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli")).runWorkspaceLineage(ctx) },
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },
   // #2551 — adopt a lineage, the hash index it matches against, and the versions of a family of workspaces.

package/src/cli/mcp/workspace-tools.e2e.test.ts

@@ -85,7 +85,7 @@ describe("which servers have the workspace tools", () => {
       const { tools } = (await rpc(server(cwd), "tools/list")) as { tools: { name: string }[] };
       expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(names));
     }
-    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer", "points-retract"]);
+    expect(names).toEqual(["workspace-ls", "workspace-status", "workspace-graph", "workspace-changes", "workspace-records", "workspace-points", "workspace-agent", "workspace-work-history", "workspace-runs", "records-new", "records-amend", "records-review", "records-close", "points-answer", "points-retract", "points-withdraw"]);
   });
 
   test("a server outside any workspace, or given none, does not", async () => {