@intentius/chant 0.124.26 → 0.124.28

package/src/cli/compiled-cli.e2e.test.ts

@@ -18,6 +18,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 
 const coreRoot = resolve(import.meta.dirname, "..", "..");
@@ -37,12 +38,13 @@ const TRACER = `
 import { registerHooks } from "node:module";
 import { appendFileSync } from "node:fs";
 const out = process.env.CHANT_TRACE_OUT;
-const seen = { chantSrc: 0, chantDist: 0, tsx: 0 };
+const seen = { chantSrc: 0, chantDist: 0, tsx: 0, typescript: 0, dist: [] };
 registerHooks({
   load(url, context, next) {
     if (url.includes("/@intentius/chant/src/")) seen.chantSrc++;
-    else if (url.includes("/@intentius/chant/dist/")) seen.chantDist++;
+    else if (url.includes("/@intentius/chant/dist/")) { seen.chantDist++; seen.dist.push(url.slice(url.indexOf("/@intentius/chant/dist/") + 23)); }
     else if (url.includes("/node_modules/tsx/")) seen.tsx++;
+    else if (url.includes("/node_modules/typescript/")) seen.typescript++;
     return next(url, context);
   },
 });
@@ -59,14 +61,15 @@ interface Run {
   status: number | null;
   stdout: string;
   stderr: string;
-  loaded: { chantSrc: number; chantDist: number; tsx: number };
+  /** Counts of what loaded, plus each compiled module's path under `dist/`. */
+  loaded: { chantSrc: number; chantDist: number; tsx: number; typescript: number; dist: string[] };
 }
 
-function run(cwd: string, args: string[]): Run {
+function run(cwd: string, args: string[], extraEnv: NodeJS.ProcessEnv = {}, command = chant): Run {
   const traceOut = join(scratch, `trace-${Math.random().toString(36).slice(2)}.jsonl`);
-  const env: NodeJS.ProcessEnv = { ...process.env, NODE_OPTIONS: `--import ${tracer}`, CHANT_TRACE_OUT: traceOut };
+  const env: NodeJS.ProcessEnv = { ...process.env, ...extraEnv, NODE_OPTIONS: `--import ${tracer}`, CHANT_TRACE_OUT: traceOut };
   delete env.CHANT_ENV;
-  const result = spawnSync(chant, args, { cwd, env, encoding: "utf-8" });
+  const result = spawnSync(command, args, { cwd, env, encoding: "utf-8" });
   const lines = readFileSync(traceOut, "utf-8").trim().split("\n");
   return { status: result.status, stdout: result.stdout, stderr: result.stderr, loaded: JSON.parse(lines[0]!) as Run["loaded"] };
 }
@@ -192,6 +195,28 @@ describe("the installed chant CLI (#3878)", () => {
     expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0 });
   });
 
+  test("workspace status on a steward-index miss loads no tsx for a member without Op files (#3976)", () => {
+    // A cache dir of its own, so there is no index to read and the member's stewards are discovered.
+    const r = run(join(workspace, "app"), ["workspace", "status", "local", "--json"], { CHANT_CACHE_DIR: mkdtempSync(join(scratch, "cache-")) });
+    expect(r.status, r.stderr).toBe(0);
+    const status = JSON.parse(r.stdout) as { members: Array<{ name: string; stewards: unknown[] }> };
+    expect(status.members.map((m) => [m.name, m.stewards])).toEqual([["app", []]]);
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0 });
+  });
+
+  test("importing the op entry loads the Op authoring surface, not lint, the LSP, codegen or typescript (#3982)", () => {
+    // Every *.op.ts imports @intentius/chant/op, so this is what a steward-index miss in `workspace status` pays per
+    // member with Op files. The base activities, which reach lint and typescript, load only when an Op runs.
+    const entry = join(project, "node_modules", "@intentius", "chant", "dist", "op", "index.js");
+    const script = `const op = await import(${JSON.stringify(pathToFileURL(entry).href)});\n` +
+      `if (typeof op.Op !== "function" || typeof op.factoryOp !== "function" || typeof op.declareSteward !== "function") process.exit(2);\n`;
+    const r = run(project, ["--input-type=module", "-e", script], {}, process.execPath);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0, typescript: 0 });
+    const heavy = r.loaded.dist.filter((path) => /^(lint|lsp|codegen|mcp|audit|fold|cli)\//.test(path) || path === "index.js" || path === "op/activities/index.js");
+    expect(heavy).toEqual([]);
+  });
+
   test("build loads the TypeScript lexicon and project through tsx, against the one compiled core", () => {
     const r = run(project, ["build", "src", "-o", "out/render.json"]);
     expect(r.status, r.stderr).toBe(0);

package/src/cli/handlers/approve-release.test.ts

@@ -0,0 +1,80 @@
+/**
+ * `chant approve` on a release gate (#4045): the approval copies the release
+ * the pending fact names, with its plan and environment, so it counts for
+ * that release only. Against a temp repo; nothing is pushed.
+ */
+
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendPendingGate, readGateLedger } from "../../lifecycle/gate-ledger";
+import { resetGateOrigin } from "../../lifecycle/gate-origin";
+
+vi.mock("../../op/discover", () => ({ discoverOps: async () => ({ errors: [], ops: new Map() }) }));
+
+const { recordGateApproval } = await import("./approve");
+
+function git(args: string[], cwd: string): void {
+  spawnSync("git", args, { cwd, encoding: "utf-8" });
+}
+
+const RELEASE = `jcs1-sha256:${"a".repeat(64)}`;
+const DOC = `jcs1-sha256:${"d".repeat(64)}`;
+
+async function repoWithReleaseGate(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "t@chant.dev"], dir);
+  git(["config", "user.name", "T"], dir);
+  writeFileSync(join(dir, "README.md"), "x\n");
+  git(["add", "."], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+  await appendPendingGate(
+    {
+      op: "release",
+      gate: "prod-release",
+      timestamp: "2026-10-16T00:00:00.000Z",
+      expiresAt: "2999-01-01T00:00:00.000Z",
+      planDigest: DOC,
+      environment: "prod",
+      releaseDigest: RELEASE,
+    },
+    { cwd: dir },
+  );
+}
+
+describe("chant approve on a release gate (#4045)", () => {
+  const cwd = process.cwd();
+  afterEach(() => {
+    process.chdir(cwd);
+    resetGateOrigin();
+    vi.restoreAllMocks();
+  });
+
+  test("the approval names the release, the environment and the change set the pending fact names", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await withTestDir(async (dir) => {
+      await repoWithReleaseGate(dir);
+      process.chdir(dir);
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod" });
+      expect(outcome.ok).toBe(true);
+      const { resolutions } = await readGateLedger("release", { cwd: dir });
+      expect(resolutions).toEqual([expect.objectContaining({ resolvedBy: "alice", planDigest: DOC, environment: "prod", releaseDigest: RELEASE })]);
+    });
+  });
+
+  test("an approval of another plan names no release, so no release gate counts it", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    await withTestDir(async (dir) => {
+      await repoWithReleaseGate(dir);
+      process.chdir(dir);
+      const other = `jcs1-sha256:${"e".repeat(64)}`;
+      const outcome = await recordGateApproval("release", "prod-release", { origin: "cli", actor: "alice", cwd: dir, environment: "prod", plan: other });
+      expect(outcome.ok).toBe(true);
+      const { resolutions } = await readGateLedger("release", { cwd: dir });
+      expect(resolutions[0].planDigest).toBe(other);
+      expect(resolutions[0].releaseDigest).toBeUndefined();
+    });
+  });
+});

package/src/cli/handlers/approve.ts

@@ -21,7 +21,7 @@ import {
   type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
 } from "../../op/gate-approval";
 import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate";
-import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
+import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, RELEASE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
 import { PR_GATE_OP } from "../../pr-loop";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
 import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
@@ -112,6 +112,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
       timestamp: now,
       expiresAt: now,
       ...(standing.description ? { description: standing.description } : {}),
+      ...(standing.runId ? { runId: standing.runId } : {}),
+      ...(standing.gitSha ? { gitSha: standing.gitSha } : {}),
     });
     const push = await reportedPush(
       `The expiry is recorded locally on ${LIFECYCLE_BRANCH}. Until it reaches the remote, ` +
@@ -127,6 +129,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
           ? `The next \`chant components pr-apply\` decides this gate from scratch and records a fresh pending fact.`
           : opName === WORKSPACE_UPGRADE_GATE_OP
           ? `The next \`chant workspace upgrade ${gate}\` decides this gate from scratch and records a fresh pending fact.`
+          : opName === RELEASE_GATE_OP
+          ? `The next \`chant components promote --release\` decides this gate from scratch and records a fresh pending fact.`
           : `The next \`chant run ${opName}\` decides this gate from scratch and records a fresh pending fact.`,
     ));
     return 0;
@@ -177,6 +181,8 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
           ? `The pull request's apply (\`chant components pr-apply\`) walks through gate "${gate}" when it plans this same digest.`
           : opName === WORKSPACE_UPGRADE_GATE_OP
           ? `Repeat \`chant workspace upgrade ${gate}\` with the same target, and it applies the patch this approval names.`
+          : opName === RELEASE_GATE_OP
+          ? `Repeat the same \`chant components promote --release\`, and it walks through gate "${gate}" when it plans this same change set for this release.`
           : `Run \`chant run ${opName}\` and it walks through gate "${gate}".`),
   ));
   return 0;
@@ -283,7 +289,7 @@ export async function recordGateApproval(
   // so there is no `*.op.ts` to find and nothing is wrong when none is there.
   // #3949: a gate that lists this one as an alias, after an Op was restructured.
   const successor = aliasingGate([...ops.values()].map((o) => o.config), opName, gate);
-  if (!successor && !ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP) {
+  if (!successor && !ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP && opName !== RELEASE_GATE_OP) {
     console.error(formatWarning({
       message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
     }));
@@ -389,6 +395,11 @@ export async function recordGateApproval(
     standing?.checkpointDigest !== undefined && samePlanDigest(planDigest, standing.planDigest)
       ? standing.checkpointDigest
       : undefined;
+  // #4045: a release gate's fact names the release its change set was
+  // planned for. An approval of that fact's plan is for that release too; an
+  // approval of another plan names none, and no release gate counts it.
+  const releaseDigest =
+    standing?.releaseDigest !== undefined && samePlanDigest(planDigest, standing.planDigest) ? standing.releaseDigest : undefined;
 
   // chant#2384 — the gate's whole value is that its two halves have different
   // authors. At a shell they do: a person runs, reads the plan, and approves.
@@ -587,6 +598,10 @@ export async function recordGateApproval(
     ...(planDigest !== undefined ? { planDigest } : {}),
     ...(checkpointDigest !== undefined ? { checkpointDigest } : {}),
     ...(environment !== undefined ? { environment } : {}),
+    ...(releaseDigest !== undefined ? { releaseDigest } : {}),
+    // #4020: the commit and run the gate waited on, off the fact this approves.
+    ...(standing?.gitSha ? { gitSha: standing.gitSha } : {}),
+    ...(standing?.runId ? { runId: standing.runId } : {}),
     origin,
     ...(refusal && opts.allowSameOrigin ? { sameOriginOverride: true } : {}),
   });
@@ -607,6 +622,7 @@ export async function recordGateApproval(
     console.error(formatInfo(
       `This approves the plan ${record.planDigest}` +
         (record.environment !== undefined ? ` in environment "${record.environment}"` : "") +
+        (record.releaseDigest !== undefined ? ` for release ${record.releaseDigest}` : "") +
         ", and only that plan. A run whose fresh plan differs refuses rather than applying it.",
     ));
   }

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

@@ -70,6 +70,37 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--promote-to that skips a step of the declared promotion order is refused, and generates nothing (#4030)", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({ config: { environments: ["dev", "staging", "prod"] } });
+    const stderr = makeStderrSpy();
+    const exit = await runBuild({ args: makeArgs({ env: "dev", promoteTo: "prod" }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(generateComponentsPipelineMock).not.toHaveBeenCalled();
+    const out = stderr.join("\n");
+    expect(out).toMatch(/\[promote-skips-environment\]/);
+    expect(out).toMatch(/--allow-skip/);
+  });
+
+  test("--promote-to the next step of the order generates as before (#4030)", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({ config: { environments: ["dev", "staging", "prod"] } });
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "x", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    const exit = await runBuild({ args: makeArgs({ env: "staging", promoteTo: "prod" }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock.mock.calls[0][2]).toEqual({ env: "staging", promoteTo: "prod" });
+  });
+
+  test("--allow-skip lets the skip through and the promote job passes it on (#4030)", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({ config: { environments: ["dev", "staging", "prod"] } });
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "x", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    const exit = await runBuild({ args: makeArgs({ env: "dev", promoteTo: "prod", allowSkip: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock.mock.calls[0][2]).toMatchObject({
+      promoteCommand: ["chant", "components", "promote", "--from", "dev", "--to", "prod", "--allow-skip"],
+    });
+  });
+
   test("--promote-to is forwarded to the generator as promoteTo (#2575)", async () => {
     generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
     vi.spyOn(console, "log").mockImplementation(() => {});
@@ -81,6 +112,27 @@ describe("runBuild --components --generate (chant #1108 build-time parameters)",
     vi.restoreAllMocks();
   });
 
+  test("--image and each --before-script are forwarded to the generator, in order (#4002)", async () => {
+    generateComponentsPipelineMock.mockResolvedValue({ success: true, yaml: "stages: []", stages: [], jobs: [] });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    const exit = await runBuild({
+      args: makeArgs({ generate: "forgejo", prLoop: true, image: "node:22-bookworm", beforeScript: ["npm ci", "npm run setup"] }),
+      plugins: [],
+      serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    expect(generateComponentsPipelineMock).toHaveBeenCalledWith(
+      ".",
+      "forgejo",
+      { env: undefined, prLoop: {}, image: "node:22-bookworm", beforeScript: ["npm ci", "npm run setup"] },
+      undefined,
+      [],
+    );
+    vi.restoreAllMocks();
+  });
+
   test("chant.config.ts's declared buildParams resolve, log, and are forwarded to generateComponentsPipeline", async () => {
     loadChantConfigUpwardMock.mockResolvedValue({
       config: { buildParams: { tier: { type: "string", default: "light" } } },

package/src/cli/handlers/build.ts

@@ -7,6 +7,7 @@ import { generateComponentsPipeline } from "../../components/cli-support";
 import { loadChantConfigUpward, type ChantConfig } from "../../config";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { findWorkspaceRoot } from "../../project-root";
+import { resolvePromotionSource } from "../../components/promote-order";
 
 /**
  * `chant build --components --generate <lexicon>` — generate mode (#563,
@@ -45,6 +46,24 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // #4030: the generated promote job runs `promote --from <env> --to <promote-to>`,
+  // which the member's declared promotion order refuses when it skips a step.
+  // Refuse here, with the same code, rather than write a job that fails.
+  if (args.promoteTo) {
+    // Loaded here, not at the top: a build without --promote-to loads no workspace module (#2526).
+    const { promotionOrder } = await import("../../workspace/promotion-order");
+    const resolved = resolvePromotionSource({
+      order: promotionOrder(config.environments),
+      to: args.promoteTo,
+      from: args.env ?? "production",
+      ...(args.allowSkip ? { allowSkip: true } : {}),
+    });
+    if ("error" in resolved) {
+      console.error(formatError({ message: `${resolved.error.message} [${resolved.error.code}]`, hint: resolved.error.fix }));
+      return 1;
+    }
+  }
+
   // A project inside a workspace member gets that member's pipeline (#2542):
   // path-filtered, run in the member's directory, written to a file named
   // after the member and recorded as the member's generated file. The
@@ -62,11 +81,14 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
         lexicon,
         env: args.env,
         promoteTo: args.promoteTo,
+        ...(args.allowSkip ? { allowSkip: true } : {}),
         output: args.output,
         params: args.param,
         paramsFile: args.paramsFile,
         ...(args.waveGate ? { waveGate: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } } : {}),
         ...(args.prLoop ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } } : {}),
+        ...(args.image ? { image: args.image } : {}),
+        ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
       });
     } catch (err) {
       console.error(formatError({ message: memberPipeline.describeError(err) }));
@@ -84,6 +106,10 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
     {
       env: args.env,
       ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}),
+      // #4030: the job passes --allow-skip through, so it is not refused again at deploy time.
+      ...(args.promoteTo && args.allowSkip
+        ? { promoteCommand: ["chant", "components", "promote", "--from", args.env ?? "production", "--to", args.promoteTo, "--allow-skip"] }
+        : {}),
       ...(plan ? { member: plan.member } : {}),
       // #3049: one job per wave of a gated-wave fan-out instead of one per component.
       ...(args.waveGate
@@ -93,6 +119,9 @@ async function runGenerateComponents(ctx: CommandContext): Promise<number> {
       ...(args.prLoop
         ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } }
         : {}),
+      // #4002: the job image and the lines that install what it lacks, chant itself included.
+      ...(args.image ? { image: args.image } : {}),
+      ...(args.beforeScript?.length ? { beforeScript: args.beforeScript } : {}),
     },
     args.sandbox,
     paramsResolution.provenance,

package/src/cli/handlers/change-set.ts

@@ -1,10 +1,12 @@
 import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID, type ChangeSetDocument } from "../../change-set";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown, renderPlanSummaryText } from "../../plan-summary";
-import { formatError } from "../format";
+import { formatError, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
 const USAGE = "chant change-set summary <change-set.json> [--format text|json|markdown] [--limit <chars>]";
+const SHOW_USAGE = "chant change-set show <digest> [--member <name>] [--json]";
 
 /**
  * `chant change-set summary <file>` (#3188): the grouped plan summary of a
@@ -42,3 +44,49 @@ export async function runChangeSetSummary(ctx: CommandContext): Promise<number>
   else process.stdout.write(renderPlanSummaryText(summary));
   return 0;
 }
+
+/**
+ * `chant change-set show <digest>` (#4022): the change-set document a gate
+ * bound, stored on `chant/lifecycle` under its digest, with each entry's
+ * graph node. `--json` prints the read contract's `change-set-show`
+ * document (`../../workspace/change-set-show.ts`); without it, the grouped
+ * summary and each entry with its node. `--member` reads a workspace
+ * member's ledger from anywhere in the checkout. Exit 1 when nothing is
+ * stored under the digest.
+ */
+export async function runChangeSetShow(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const digest = args.extraPositional;
+  const { changeSetShowDocument, CHANGE_SET_DIGEST_PATTERN } = await import("../../workspace/change-set-show");
+  if (!digest || !CHANGE_SET_DIGEST_PATTERN.test(digest)) {
+    console.error(formatError({ message: digest ? `${digest} is not a change-set digest` : "change-set show needs the digest a gate binds", hint: SHOW_USAGE }));
+    return 1;
+  }
+  if ((args.members?.length ?? 0) > 1) {
+    console.error(formatError({ message: `change-set show reads one member, not ${args.members!.join(", ")}`, hint: SHOW_USAGE }));
+    return 1;
+  }
+  const member = args.members?.[0]?.split("/").filter(Boolean);
+  const doc = await changeSetShowDocument({ cwd: resolve("."), digest, ...(member ? { member } : {}) });
+  if (args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc || doc.changeSet === null ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: doc.error.message, hint: SHOW_USAGE }));
+    return 1;
+  }
+  if (doc.reason) console.error(formatWarning({ message: doc.reason.message }));
+  if (doc.changeSet === null) {
+    if (!doc.reason) console.error(formatError({ message: `no change set is stored under ${digest}${doc.member ? ` for member ${doc.member}` : ""}`, hint: "A pull-request or release gate stores the change set it binds; a component gate binds a lifecycle plan and stores none." }));
+    return 1;
+  }
+  process.stdout.write(renderPlanSummaryText(groupChangeSet(doc.changeSet)));
+  const graph = doc.changeSet.graph;
+  console.log(graph ? `\nNodes from the graph of ${graph.member ?? "this project"}${graph.at ? ` at ${graph.at.slice(0, 12)}` : ""}:` : "\nNo graph was read, so no entry has a node.");
+  for (const e of doc.changeSet.entries) {
+    if (e.action === "no-op" || e.action === "read") continue;
+    console.log(`  ${e.action.padEnd(8)} ${e.member}  ${e.address}${e.deposed ? ` (deposed ${e.deposed})` : ""}  ${e.node ?? "(no node)"}`);
+  }
+  return 0;
+}

package/src/cli/handlers/fan-out.test.ts

@@ -52,6 +52,7 @@ const sealedGates = new Set<string>();
 const { CapabilityRegistry } = await import("../../components/capability");
 const { memoryGateLedgerPort } = await import("../../op/gate");
 const { runComponentsFanOut } = await import("./fan-out");
+const { checkRunEventLines } = await import("../../workspace/__fixtures__/run-event-check");
 
 let gateLedger = memoryGateLedgerPort();
 
@@ -622,3 +623,50 @@ describe("gated waves (#3049): one gate per wave, bound to the wave's set digest
     expect(stderr()).toContain("--wave runs one wave");
   });
 });
+
+describe("--events-json (#4041)", () => {
+  const lines = () => stdoutLines.filter((l) => l.startsWith('{"$schema"'));
+
+  test("a fan-out over the set: the gate is a gate phase settled gated, and nothing after it starts", async () => {
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", eventsJson: true }))).toBe(3);
+    const events = checkRunEventLines(lines());
+    expect(events[0]).toMatchObject({ type: "run-start", kind: "component", waves: [["net"], ["cluster-a", "cluster-b"], ["app-one", "app-three", "app-two"]] });
+    expect(events.map((e) => e.type)).toEqual(["run-start", "phase-start", "step-start", "gate-waiting", "step-settle", "phase-settle", "run-settle"]);
+    expect(events.find((e) => e.type === "gate-waiting")).toMatchObject({ component: null, phase: "gate", step: "gate:release", op: "fan-out", gate: "release" });
+    expect(events.at(-1)).toMatchObject({ status: "gated" });
+  });
+
+  test("approved, the gate resolves and every wave and component follows, each step started before it settles", async () => {
+    await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release" }));
+    const pending = gateLedger.appended[0];
+    gateLedger = memoryGateLedgerPort({
+      pending: [pending],
+      resolutions: [{
+        version: 1, kind: "resolution", op: "fan-out", gate: "release", resolvedBy: "operator",
+        timestamp: new Date(Date.parse(pending.timestamp) + 1000).toISOString(), planDigest: pending.planDigest,
+      }],
+    });
+    stdoutLines = [];
+    failing = ["cluster-b"];
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", eventsJson: true }))).toBe(1);
+    const events = checkRunEventLines(lines());
+    expect(events.find((e) => e.type === "gate-resolved")).toMatchObject({ gate: "release", resolvedBy: "operator" });
+    expect(events.filter((e) => e.type === "wave-start").map((e) => (e as { wave: number }).wave)).toEqual([1, 2, 3]);
+    expect(events.find((e) => e.type === "component-settle" && e.component === "cluster-b")).toMatchObject({ status: "failed" });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed" });
+  });
+
+  test("--progress-json on a set the gate stops now prints run-start and run-done gated (a level-0 change)", async () => {
+    expect(await runComponentsFanOut(ctx({ base: "main", env: "test", gate: "release", progressJson: true }))).toBe(3);
+    const progress = stdoutLines.filter((l) => l.startsWith('{"type"')).map((l) => JSON.parse(l));
+    expect(progress).toEqual([
+      { type: "run-start", waves: [["net"], ["cluster-a", "cluster-b"], ["app-one", "app-three", "app-two"]] },
+      { type: "run-done", status: "gated" },
+    ]);
+  });
+
+  test("beside --progress-json it is refused", async () => {
+    expect(await runComponentsFanOut(ctx({ base: "main", eventsJson: true, progressJson: true }))).toBe(1);
+    expect(stderr()).toContain("--events-json and --progress-json both stream to stdout");
+  });
+});

package/src/cli/handlers/fan-out.ts

@@ -52,6 +52,7 @@ import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt } from "../..
 import { describeChangedWave, withWaveRecord, type WaveRecord } from "../../gated-waves";
 import { renderFanOutHuman, renderFanOutJson, renderFanOutPlan } from "../../components/fan-out-output";
 import { ndjsonProgressSink } from "../../components/run-progress";
+import { openCliRunEvents, refusesBothStreams } from "../run-events";
 import { summaryLedgerPrefix, writeGatedRunSummary } from "../../op/gate-summary";
 import { approveCommand, gateIsSealed } from "../../op/gate";
 import { getHeadCommit } from "../../lifecycle/git";
@@ -60,7 +61,7 @@ import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
 import { formatError, formatInfo, formatWarning } from "../format";
 import { FAN_OUT_GATE_OP } from "../../op/gate-name";
 import { resolveBuildRoot } from "./lifecycle";
-import { GATED_EXIT_CODE, recordAutoReleasesForRun } from "./run";
+import { GATED_EXIT_CODE, autoReleaseRun, recordAutoReleasesForRun } from "./run";
 import type { CommandContext } from "../registry";
 
 /**
@@ -172,10 +173,11 @@ export async function resolveChangedUnits(
  * chant components fan-out --base <ref> | --from-affected <file>
  *   [--head <ref>] [--include-dependents] [--env <env>] [--gate <name>]
  *   [--dry-run] [--json] [--resume <file>] [--seed-outputs <file>]
- *   [--dump-outputs <file>] [--progress-json]
+ *   [--dump-outputs <file>] [--progress-json | --events-json]
  */
 export async function runComponentsFanOut(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
+  if (refusesBothStreams(args)) return 1;
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
 
@@ -334,6 +336,11 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
     writeFanOutAttempt(resumePath, attempt);
   };
 
+  // The run id the release records carry, chosen before the run so that
+  // `--events-json` (#4041) names the run by it too.
+  const release = autoReleaseRun(`fan-out-${Date.now()}`);
+  const events = await openCliRunEvents(args, { kind: "component", name: `fan-out ${derived.plan.order.join(",")}`, runId: release.runId, cwd: projectPath });
+
   let result;
   try {
     result = await runFanOut(derived.plan, derived.components, registry, {
@@ -364,6 +371,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
           }
         : {}),
       ...(args.progressJson ? { onProgress: ndjsonProgressSink() } : {}),
+      ...(events ? { onRunEvent: events.emit } : {}),
       ...(resumePath
         ? {
             onComponentSettled: (settled, outputs) => {
@@ -379,6 +387,7 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
         : {}),
     });
   } catch (err) {
+    events?.settle("failed", err instanceof Error ? err.message : String(err));
     // `--wave <n>` reached before an earlier wave applied: nothing ran.
     if (err instanceof EarlierWaveNotAppliedError) {
       console.error(formatError({ message: err.message }));
@@ -386,6 +395,8 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
     }
     throw err;
   }
+  // The fan-out settles the stream; this only ends one it left open.
+  events?.settle(result.status === "fail" ? "failed" : result.status);
 
   if (args.dumpOutputs) {
     const dumpPath = resolve(args.dumpOutputs);
@@ -420,8 +431,9 @@ export async function runComponentsFanOut(ctx: CommandContext): Promise<number>
     await recordAutoReleasesForRun(
       result.results,
       args.env ?? "local",
-      `fan-out-${Date.now()}`,
+      release.runId,
       resolveAutoReleaseDisabled(config, args.noReleaseRecord),
+      release.runOrigin,
     );
   }
 

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

@@ -850,6 +850,43 @@ describe("runApprove — the resolution names the plan it approves (#2300)", ()
     errSpy.mockRestore();
   });
 
+  // #4020: the resolution names the commit and run the gate waited on, off the fact it answers.
+  test("it copies the standing fact's commit and run onto the resolution", async () => {
+    readGateLedgerMock.mockResolvedValue({
+      resolutions: [],
+      pending: [{
+        version: 1, kind: "pending", op: "fountain-apply", gate: "rollout-gate",
+        timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z",
+        planDigest: PLAN_A, gitSha: "f".repeat(40), runId: "9001",
+      }],
+      malformed: 0,
+    });
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+    expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({ gitSha: "f".repeat(40), runId: "9001" }));
+    errSpy.mockRestore();
+  });
+
+  test("a standing fact from before the commit was recorded gives a resolution without one", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+    const written = appendGateResolutionMock.mock.calls.at(-1)![0] as Record<string, unknown>;
+    expect(written).not.toHaveProperty("gitSha");
+    expect(written).not.toHaveProperty("runId");
+    errSpy.mockRestore();
+  });
+
   test("--plan names one explicitly, and wins over the standing fact's", async () => {
     const other = `sha256:${"b".repeat(64)}`;
     seedPending("fountain-apply", "rollout-gate", PLAN_A);