@intentius/chant 0.124.27 → 0.124.29

package/src/cli/handlers/run-auto-release.test.ts

@@ -0,0 +1,80 @@
+/**
+ * What `recordAutoReleasesForRun` hands the release record (#4020): the run
+ * and its origin, and for a component that passed a gate, who approved it and
+ * which resolution admitted it.
+ */
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+
+const maybeRecordAutoReleaseMock = vi.fn();
+vi.mock("../../components/auto-release", async () => {
+  const actual = await vi.importActual<typeof import("../../components/auto-release")>("../../components/auto-release");
+  return { ...actual, maybeRecordAutoRelease: (...args: unknown[]) => maybeRecordAutoReleaseMock(...args) };
+});
+vi.mock("../../components/manifest-persistence", async () => {
+  const actual = await vi.importActual<typeof import("../../components/manifest-persistence")>("../../components/manifest-persistence");
+  return { ...actual, maybePersistBuildManifest: async () => ({ persisted: false, reason: "no-manifest" }) };
+});
+
+import { autoReleaseRun, recordAutoReleasesForRun } from "./run";
+import type { DriverComponentResult } from "../../components/driver";
+
+const gatedResult = {
+  component: "api",
+  ok: true,
+  status: "ok",
+  records: [
+    { component: "api", phase: "Deploy", kind: "gate:approve-prod", status: "ok", durationMs: 1, approval: { gate: "approve-prod", resolvedBy: "alice", timestamp: "2026-10-16T10:05:00.000Z" } },
+    { component: "api", phase: "Deploy", kind: "apply", status: "ok", durationMs: 1 },
+  ],
+} as unknown as DriverComponentResult;
+const plainResult = { component: "worker", ok: true, status: "ok", records: [] } as unknown as DriverComponentResult;
+
+beforeEach(() => {
+  maybeRecordAutoReleaseMock.mockReset().mockResolvedValue({ recorded: false, reason: "no-digest" });
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe("recordAutoReleasesForRun", () => {
+  test("a component that passed a gate records its approver and admission, one that did not records neither", async () => {
+    await recordAutoReleasesForRun([gatedResult, plainResult], "prod", "9001", false, { forge: "github", repo: "acme/app" });
+    const [gated, plain] = maybeRecordAutoReleaseMock.mock.calls.map((c) => c[0]);
+    expect(gated).toMatchObject({
+      component: "api", runId: "9001", runOrigin: { forge: "github", repo: "acme/app" },
+      approver: "alice", admission: { op: "api", gate: "approve-prod", resolvedAt: "2026-10-16T10:05:00.000Z" },
+    });
+    expect(plain).not.toHaveProperty("approver");
+    expect(plain).not.toHaveProperty("admission");
+  });
+
+  test("a run under --release records the release digest on each component, one without it records none (#4043)", async () => {
+    const release = `jcs1-sha256:${"c".repeat(64)}`;
+    await recordAutoReleasesForRun([plainResult], "dev", "9001", false, { forge: "local" }, release);
+    expect(maybeRecordAutoReleaseMock.mock.calls[0][0]).toMatchObject({ releaseDigest: release });
+    maybeRecordAutoReleaseMock.mockClear();
+    await recordAutoReleasesForRun([plainResult], "dev", "9001", false, { forge: "local" });
+    expect(maybeRecordAutoReleaseMock.mock.calls[0][0]).not.toHaveProperty("releaseDigest");
+  });
+
+  test("the origin defaults to local", async () => {
+    await recordAutoReleasesForRun([plainResult], "prod", "local-1", false);
+    expect(maybeRecordAutoReleaseMock.mock.calls[0][0]).toMatchObject({ runId: "local-1", runOrigin: { forge: "local" } });
+  });
+});
+
+describe("autoReleaseRun", () => {
+  test("in CI it names the CI run, so the release and the gate it passed name one run", () => {
+    vi.stubEnv("GITHUB_RUN_ID", "9001");
+    vi.stubEnv("GITHUB_REPOSITORY", "acme/app");
+    vi.stubEnv("GITHUB_SERVER_URL", "https://github.example");
+    expect(autoReleaseRun("local-1")).toEqual({
+      runId: "9001",
+      runOrigin: { forge: "github", repo: "acme/app", url: "https://github.example/acme/app/actions/runs/9001" },
+    });
+  });
+
+  test("outside CI it keeps the local id", () => {
+    vi.stubEnv("GITHUB_RUN_ID", "");
+    vi.stubEnv("CI_PIPELINE_ID", "");
+    expect(autoReleaseRun("local-1")).toEqual({ runId: "local-1", runOrigin: { forge: "local" } });
+  });
+});

package/src/cli/handlers/run-events-cmd.test.ts

@@ -0,0 +1,92 @@
+/** #4042: `chant run events <run> [--json] [--follow]`. */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { runOpEvents } from "./run";
+import { openRunEventStore } from "../../run-event-store";
+import { openRunEventStream, runEventRunOf } from "../../run-event-stream";
+
+function args(o: Partial<ParsedArgs>): ParsedArgs {
+  return { command: "run", path: ".", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...o };
+}
+
+let dir: string;
+let cwd: string;
+let out: string[];
+beforeEach(() => {
+  cwd = process.cwd();
+  vi.stubEnv("CHANT_RUN_EVENTS_DIR", "");
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "run-events-cmd-")));
+  execFileSync("git", ["init", "-q", "-b", "main"], { cwd: dir });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "--allow-empty", "-m", "init"], { cwd: dir });
+  process.chdir(dir);
+  out = [];
+  vi.spyOn(process.stdout, "write").mockImplementation((s: string | Uint8Array) => (out.push(String(s)), true));
+  vi.spyOn(console, "log").mockImplementation((s: string) => void out.push(`${s}\n`));
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllEnvs();
+  process.chdir(cwd);
+  rmSync(dir, { recursive: true, force: true });
+});
+
+async function stream(runId: string, name = "deploy-api") {
+  const store = (await openRunEventStore(dir, runId))!;
+  return openRunEventStream(runEventRunOf({ kind: "op", name, runId }), store.write);
+}
+
+describe("chant run events", () => {
+  test("--json replays a settled run's lines and exits with its verdict", async () => {
+    const s = await stream("r-done");
+    s.emit({ type: "run-start", waves: null });
+    s.settle("failed", "boom");
+    const exit = await runOpEvents({ args: args({ extraPositional: "r-done", json: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    const events = out.join("").trim().split("\n").map((l) => JSON.parse(l));
+    expect(events.map((e) => e.type)).toEqual(["run-start", "run-settle"]);
+    expect(events[1]).toMatchObject({ status: "failed", error: "boom" });
+  });
+
+  test("--json replays a run in progress up to now and exits 0", async () => {
+    const s = await stream("r-live");
+    s.emit({ type: "run-start", waves: null });
+    s.emit({ type: "phase-start", component: null, phase: "Build" });
+    const exit = await runOpEvents({ args: args({ extraPositional: "deploy-api", json: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(out.join("").trim().split("\n").map((l) => JSON.parse(l).type)).toEqual(["run-start", "phase-start"]);
+  });
+
+  test("--follow prints each event of a run in progress, then the verdict", async () => {
+    const s = await stream("r-follow");
+    s.emit({ type: "run-start", waves: null });
+    const done = runOpEvents({ args: args({ extraPositional: "r-follow", json: true, follow: true }), plugins: [], serializers: [] });
+    await new Promise((r) => setTimeout(r, 150));
+    expect(out.join("").trim().split("\n")).toHaveLength(1);
+    s.emit({ type: "phase-start", component: null, phase: "Build" });
+    s.emit({ type: "phase-settle", component: null, phase: "Build", status: "gated" });
+    s.settle("gated");
+    expect(await done).toBe(3);
+    expect(out.join("").trim().split("\n").map((l) => JSON.parse(l).type)).toEqual(["run-start", "phase-start", "phase-settle", "run-settle"]);
+  });
+
+  test("without --json each event is one line for a person", async () => {
+    const s = await stream("r-human");
+    s.emit({ type: "run-start", waves: null });
+    s.settle("ok");
+    expect(await runOpEvents({ args: args({ extraPositional: "r-human" }), plugins: [], serializers: [] })).toBe(0);
+    expect(out.join("")).toMatch(/run-start/);
+    expect(out.join("")).toMatch(/run-settle\s+ok/);
+  });
+
+  test("a run with no kept events is refused by name; no run is refused", async () => {
+    expect(await runOpEvents({ args: args({ extraPositional: "nope" }), plugins: [], serializers: [] })).toBe(1);
+    expect(await runOpEvents({ args: args({}), plugins: [], serializers: [] })).toBe(1);
+    expect(await runOpEvents({ args: args({ extraPositional: "x", on: "fountain" }), plugins: [], serializers: [] })).toBe(1);
+  });
+});

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

@@ -0,0 +1,55 @@
+/**
+ * `chant run --components --release <label|digest>` (#4043): the run builds
+ * from the checked-out commit, so the release must be cut from it and have a
+ * target for the environment. Checked before anything deploys.
+ */
+import { describe, test, expect, vi } from "vitest";
+import { makeRelease } from "../../lifecycle/release-store";
+
+const COMMIT = "a1b2c3d4".repeat(5);
+const release = makeRelease({
+  member: null,
+  commit: COMMIT,
+  artifactDigests: [],
+  targets: [{ env: "dev", templates: [], params: [] }],
+});
+let head = COMMIT;
+
+vi.mock("../../lifecycle/git", () => ({
+  getHeadCommit: async () => head,
+  fetchLifecycle: async () => true,
+  pushLifecycle: async () => false,
+}));
+vi.mock("../../lifecycle/release-store", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/release-store")>("../../lifecycle/release-store");
+  return {
+    ...actual,
+    resolveRelease: async (ref: string) => (ref === "v1" || ref === release.releaseDigest ? { release, label: "v1" } : null),
+  };
+});
+
+const { resolveRunRelease } = await import("./run");
+
+describe("resolveRunRelease", () => {
+  test("a release cut from HEAD with a target for the environment is the run's release, by label or digest", async () => {
+    head = COMMIT;
+    expect(await resolveRunRelease("v1", "dev", ".")).toMatchObject({ releaseDigest: release.releaseDigest, label: "v1" });
+    expect(await resolveRunRelease(release.releaseDigest, "dev", ".")).toMatchObject({ releaseDigest: release.releaseDigest });
+  });
+
+  test("a release it can't find is refused", async () => {
+    expect(await resolveRunRelease("v9", "dev", ".")).toMatch(/no release is labelled or digested "v9"/);
+  });
+
+  test("a release cut from another commit is refused, and the message says why", async () => {
+    head = "f".repeat(40);
+    const why = await resolveRunRelease("v1", "dev", ".");
+    expect(why).toMatch(/was cut from a1b2c3d4a1b2 and this checkout is at ffffffffffff/);
+    expect(why).toMatch(/promote --release/);
+  });
+
+  test("a release with no target for the environment is refused", async () => {
+    head = COMMIT;
+    expect(await resolveRunRelease("v1", "prod", ".")).toMatch(/has no target for "prod"/);
+  });
+});

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

@@ -98,6 +98,7 @@ vi.mock("../../lifecycle/run-ledger", async (importOriginal) => {
 
 const { runOpList, runOpStatus, runOpLog, runOpSignalRenamed, runOpApprove, runOpCancel, runOp, runOpComponents } =
   await import("./run");
+const { checkRunEventLines } = await import("../../workspace/__fixtures__/run-event-check");
 
 function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
   return {
@@ -1554,6 +1555,35 @@ describe("runOpComponents", () => {
     vi.restoreAllMocks();
   });
 
+  test("--events-json streams the run-event stream as runComponents emits it, and ends one that never reached a component (#4041)", async () => {
+    runComponentsMock.mockImplementation(
+      async (_path: string, _selector: string, options: { onRunEvent?: (b: unknown) => void }) => {
+        options.onRunEvent?.({ type: "run-start", waves: [["svc"]] });
+        options.onRunEvent?.({ type: "run-settle", status: "ok", durationMs: null });
+        return {
+          success: true,
+          selected: ["svc"],
+          run: { order: ["svc"], waves: [["svc"]], results: [{ component: "svc", ok: true, status: "ok", records: [] }], ok: true, status: "ok" },
+        };
+      },
+    );
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    expect(await runOpComponents({ args: makeArgs({ path: "svc", eventsJson: true }), plugins: [], serializers: [] })).toBe(0);
+    const events = checkRunEventLines(stdoutWrite.mock.calls.map((c) => String(c[0])));
+    expect(events[0]).toMatchObject({ type: "run-start", kind: "component", name: "svc", waves: [["svc"]] });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+
+    stdoutWrite.mockClear();
+    runComponentsMock.mockReset().mockResolvedValue({ success: false, selected: [], error: "no component named svc" });
+    expect(await runOpComponents({ args: makeArgs({ path: "svc", eventsJson: true }), plugins: [], serializers: [] })).toBe(1);
+    const failed = checkRunEventLines(stdoutWrite.mock.calls.map((c) => String(c[0])));
+    expect(failed.map((e) => e.type)).toEqual(["run-start", "run-settle"]);
+    expect(failed.at(-1)).toMatchObject({ status: "failed", error: "no component named svc" });
+    vi.restoreAllMocks();
+  });
+
   test("without --progress-json, runComponents receives onProgress: undefined and nothing streams", async () => {
     runComponentsMock.mockResolvedValue({
       success: true,

package/src/cli/handlers/run.ts

@@ -10,12 +10,12 @@ import { runOpLocally, findPolicyGateStep, OpRunFailure, type StepRecord } from
 import { approveCommand, describeGateMismatch, gateIsSealed } from "../../op/gate";
 import { summaryLedgerPrefix, writeGatedRunSummary, type GatedRunSummary } from "../../op/gate-summary";
 import { createLocalOpRuntime } from "../../op/runtimes/local";
-import type { OpRuntimeProvider, OpRunStatus } from "../../op/runtime";
+import type { OpRuntimeProvider, OpRunRecord, OpRunStatus } from "../../op/runtime";
 import { pointAnswerCommand, renderHuman, renderJson } from "../../op/local-output";
 import { loadPlugins } from "../plugins";
 import { recordGateApproval } from "./operator";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
-import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
+import { parseParamFlags } from "../build-params-cli";
 import type { CommandContext } from "../registry";
 import { stewardBesideFor, stewardFormFor, stewardTurnLeaseName, DEFAULT_STEWARD_ENV, type StewardDeclaration } from "../../op/steward";
 import { holdBesideLease } from "../../op/steward-beside";
@@ -26,11 +26,15 @@ import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/loca
 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 { findStoredRun, readRunEvents } from "../../run-event-store";
+import type { RunEvent } from "../../run-event";
+import { openCliRunEvents, refusesBothStreams, stdoutLine } from "../run-events";
 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 { isComponentList, type ComponentRunPlan, type RunComponentsResult } from "../../components/cli-support";
+import { resolveCiRun, type ReleaseRecord, type RunOrigin } from "../../lifecycle/release-ledger";
+import { gateAdmission, gateApprover } from "../../components/promote";
 import { runOpGenerate } from "./run-generate";
 
 /**
@@ -460,6 +464,91 @@ async function runOpLogOnRuntime(ctx: CommandContext, name: string): Promise<num
   return 0;
 }
 
+// ── chant run events <run> ───────────────────────────────────────────────────
+
+/** One event as a line for a person: its time, its type, where it is and how it ended. */
+export function humanRunEventLine(e: RunEvent): string {
+  const x = e as unknown as Record<string, unknown>;
+  const where = [x.component, x.phase, x.step].filter((v): v is string => typeof v === "string").join("/");
+  const detail = [
+    where,
+    typeof x.status === "string" ? x.status : "",
+    // A blocked component (#4007) names what held it back.
+    typeof x.blockedBy === "string" ? `by ${x.blockedBy}` : "",
+    typeof x.error === "string" ? x.error : "",
+  ].filter(Boolean).join(" ");
+  return `${String(x.at ?? "")}  ${String(x.type).padEnd(16)}${detail}`.trimEnd();
+}
+
+/** The exit code a run's verdict maps to: `chant run`'s own (0 ok, 1 failed, 3 waiting on a person). */
+function exitOfSettle(status: unknown): number {
+  return status === "ok" ? 0 : status === "gated" || status === "waiting" ? 3 : 1;
+}
+
+/**
+ * `chant run events <run> [--json] [--follow]` (#4042): the events a run on
+ * this host kept, replayed. `<run>` is a run id, or the name of an Op or a
+ * component selection, for which the newest stored run stands. A settled run
+ * and a run in progress both replay what is in the file; `--follow` goes on
+ * from there until the run settles. `--json` prints the stored lines as they
+ * were written; without it each event is one line for a person.
+ *
+ * The exit code is the replayed run's verdict (0, 1, or 3 for a run waiting
+ * on a person). A replay of a run still going, and a follow cut short by
+ * Ctrl-C, exit 0.
+ */
+export async function runOpEvents(ctx: CommandContext): Promise<number> {
+  const ref = ctx.args.extraPositional;
+  if (!ref) {
+    console.error(formatError({ message: "A run id or an Op name is required: chant run events <run>" }));
+    return 1;
+  }
+  if (ctx.args.on !== undefined && ctx.args.on !== "local") {
+    console.error(formatError({
+      message: `run events reads the events kept on this host, so --on ${ctx.args.on} has none to read`,
+      hint: "A run hosted off this host is read once its in-flight state is off-host (#3990).",
+    }));
+    return 1;
+  }
+  const cwd = resolve(".");
+  let stored = await findStoredRun(cwd, ref);
+  if (!stored && ctx.args.follow) {
+    // The run may be starting: give it a moment to open its file.
+    const deadline = Date.now() + RUN_EVENTS_WAIT_MS;
+    while (!stored && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 100));
+      stored = await findStoredRun(cwd, ref);
+    }
+  }
+  if (!stored) {
+    console.error(formatError({
+      message: `No events are kept for "${ref}" on this host`,
+      hint: "A run keeps its events when it records to the ledger (not under --no-record), and a command other than `chant run <op>` keeps them under --events-json. Chant 0.124.28 and newer write them.",
+    }));
+    return 1;
+  }
+
+  const controller = new AbortController();
+  const onSigint = () => controller.abort();
+  process.on("SIGINT", onSigint);
+  try {
+    const settle = await readRunEvents(
+      stored.file,
+      (event, line) => {
+        if (ctx.args.json) process.stdout.write(line);
+        else console.log(humanRunEventLine(event));
+      },
+      { follow: ctx.args.follow === true, signal: controller.signal },
+    );
+    return settle ? exitOfSettle((settle as unknown as { status?: unknown }).status) : 0;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}
+
+/** How long `--follow` waits for a run's file to appear. */
+const RUN_EVENTS_WAIT_MS = 5000;
+
 // ── chant run approve <op> <gate> ────────────────────────────────────────────
 
 /**
@@ -778,6 +867,7 @@ export async function runOp(ctx: CommandContext): Promise<number> {
     }));
     return 1;
   }
+  if (refusesBothStreams(ctx.args)) return 1;
   if (ctx.args.components) return runOpComponents(ctx);
   if (ctx.args.report) {
     console.error(formatError({
@@ -791,6 +881,16 @@ export async function runOp(ctx: CommandContext): Promise<number> {
 
 // ── Auto-release recording post-run (#597) ──────────────────────────────────
 
+/**
+ * The run id and origin an auto-recorded release names (#4020): the CI run
+ * when the process is in CI, so the release and the gate it passed (which
+ * records the CI run id) name the same run, else `localId` with the `local`
+ * origin.
+ */
+export function autoReleaseRun(localId: string): { runId: string; runOrigin: RunOrigin } {
+  return resolveCiRun() ?? { runId: localId, runOrigin: { forge: "local" } };
+}
+
 /**
  * After a successful `chant run --components` (local executor), auto-emit
  * one release record per successfully deployed component that published a
@@ -831,6 +931,8 @@ export async function recordAutoReleasesForRun(
   env: string,
   runId: string,
   disabled: boolean,
+  runOrigin: RunOrigin = { forge: "local" },
+  releaseDigest?: string,
 ): Promise<ReleaseRecord[]> {
   const recorded: ReleaseRecord[] = [];
   for (const componentResult of results) {
@@ -842,8 +944,13 @@ export async function recordAutoReleasesForRun(
         success: true,
         records: componentResult.records,
         runId,
-        // A local-executor id resolves nowhere — say so in a field (#2045).
-        runOrigin: { forge: "local" },
+        // A local-executor id resolves nowhere, and says so in a field (#2045). A run in CI names the CI run.
+        runOrigin,
+        // #1035, #4020: who approved at the gate and which resolution admitted the deploy.
+        ...(gateApprover(componentResult) ? { approver: gateApprover(componentResult) } : {}),
+        ...(gateAdmission(componentResult) ? { admission: gateAdmission(componentResult) } : {}),
+        // #4043: the release the deploy was made under, when `--release` named one.
+        ...(releaseDigest !== undefined ? { releaseDigest } : {}),
       },
       { disabled },
     );
@@ -953,6 +1060,44 @@ function refusesNoRecordOn(runtime: Pick<OpRuntimeProvider, "name">): boolean {
   return true;
 }
 
+/**
+ * Resolve the release `chant run --components --release` names (#4043), or the
+ * reason it can't be used. The run builds from the checked-out commit, so the
+ * release's commit must be HEAD, and the release needs a target for `env`.
+ */
+export async function resolveRunRelease(ref: string, env: string, cwd: string) {
+  const { fetchLifecycle, getHeadCommit } = await import("../../lifecycle/git");
+  const { resolveRelease } = await import("../../lifecycle/release-store");
+  const { targetFor } = await import("../../components/release-promote");
+  await fetchLifecycle({ cwd }).catch(() => false);
+  const found = await resolveRelease(ref, { cwd });
+  if (!found) return `no release is labelled or digested "${ref}" in this member`;
+  const name = found.label ?? found.release.releaseDigest;
+  const head = await getHeadCommit({ cwd });
+  if (found.release.commit !== head) {
+    return `release ${name} was cut from ${found.release.commit.slice(0, 12)} and this checkout is at ${head.slice(0, 12)}; run builds from the checkout, so check out the release's commit, or deploy it with \`chant components promote --release\``;
+  }
+  const target = targetFor(found.release, env);
+  if ("error" in target) return target.error;
+  return { releaseDigest: found.release.releaseDigest, label: found.label, release: found.release };
+}
+
+/** A rebuilt image need not digest as the release's own did; say so, as promote does. Never fails the run. */
+async function warnOnArtifactMismatch(release: import("../../lifecycle/release-store").Release, recorded: readonly ReleaseRecord[]): Promise<void> {
+  try {
+    const { releaseArtifactMismatches } = await import("../../components/release-promote");
+    const { readBuildManifest } = await import("../../lifecycle/build-ledger-store");
+    const mismatches = await releaseArtifactMismatches(
+      release,
+      recorded.map((r) => ({ component: r.component, source: r })),
+      (digest) => readBuildManifest(digest).catch(() => null),
+    );
+    for (const message of mismatches) console.error(formatWarning({ message }));
+  } catch {
+    // The record is written; a manifest that can't be read is not worth failing the run for.
+  }
+}
+
 async function runComponentSelection(ctx: CommandContext): Promise<number> {
   const selector = ctx.args.path;
   if (!selector || selector === ".") {
@@ -968,11 +1113,13 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
 
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
-  const paramsResolution = resolveCliBuildParams(config.buildParams, {
+  // #4024: with --env, a workspace member's flag records back their parameters.
+  const { resolveFlaggedBuildParams } = await import("../../flag-params");
+  const paramsResolution = await resolveFlaggedBuildParams(projectPath, config.buildParams, {
     cli: parseParamFlags(ctx.args.param),
     paramsFile: ctx.args.paramsFile,
     verbose: ctx.args.verbose,
-  });
+  }, ctx.args.env);
   if (!paramsResolution.success) {
     for (const message of paramsResolution.errors) console.error(message);
     return 1;
@@ -990,6 +1137,20 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
   }
 
   const env = ctx.args.env ?? "local";
+
+  // #4043: `--release <label|digest>` says this run deploys that release. The
+  // run builds from the checked-out commit, so the release must have been cut
+  // from it, and must have a target for the environment. Both are checked
+  // before anything deploys; nothing is inferred when the flag is absent.
+  let underRelease: { releaseDigest: string; label: string | null; release: import("../../lifecycle/release-store").Release } | undefined;
+  if (ctx.args.release) {
+    const refused = await resolveRunRelease(ctx.args.release, env, projectPath);
+    if (typeof refused === "string") {
+      console.error(formatError({ message: refused, hint: "List the releases with: chant release list" }));
+      return 1;
+    }
+    underRelease = refused;
+  }
   // Seed cross-component/cross-stack outputs from upstream jobs' dumped files
   // (`--seed-outputs`), so a single-component run resolves references to a
   // component that ran in an earlier CI job.
@@ -1011,6 +1172,10 @@ async function runComponentSelection(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;
+  // `--events-json` (#4041): the run-event stream instead. The run is named by
+  // the id its release records carry, so the two join.
+  const release = autoReleaseRun(`local-${Date.now()}`);
+  const events = await openCliRunEvents(ctx.args, { kind: "component", name: selector, runId: release.runId, cwd: projectPath });
   // 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.
@@ -1020,14 +1185,25 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
         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 } : {}),
-  });
+  let result: RunComponentsResult;
+  try {
+    result = await runtime.runComponents(projectPath, selector, {
+      env: ctx.args.env,
+      componentOutputs: seededOutputs,
+      onProgress,
+      ...(events ? { onRunEvent: events.emit } : {}),
+      sandbox: ctx.args.sandbox,
+      buildParams: paramsResolution.provenance,
+      ...(onPlan ? { onPlan } : {}),
+    });
+  } catch (err) {
+    events?.settle("failed", err instanceof Error ? err.message : String(err));
+    throw err;
+  }
+  // A run that never reached its components (a bad selector, a cycle) still ends its stream.
+  if (result.success) events?.settle("ok");
+  else if (result.gated) events?.settle("gated");
+  else events?.settle("failed", result.error);
 
   // Dump the accumulated outputs for a downstream job to seed from. Written
   // even on failure (partial outputs) so a resumed run still has what completed.
@@ -1094,7 +1270,8 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
   if (result.success && result.run) {
     // #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);
+    const recorded = await recordAutoReleasesForRun(result.run.results, env, release.runId, disabled, release.runOrigin, underRelease?.releaseDigest);
+    if (underRelease) await warnOnArtifactMismatch(underRelease.release, recorded);
     // `--digest-file` (#2602): the releases this run recorded, one
     // `<component>=<digest>` line each, the form `chant components promote
     // --digest` takes. A generated promote job reads it to promote exactly
@@ -1182,6 +1359,15 @@ async function runOpOnResolvedRuntime(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // #4044: a runner key signs the run's record as it settles, so `ci tick`
+  // can count the run. `--key` must be a runner key; the PEM in
+  // CHANT_RUNNER_KEY that is not one leaves the run unsigned, with a warning.
+  const signRecord = await runSignerFor(ctx);
+  if (signRecord === null) {
+    await stewardGate?.release?.();
+    return 1;
+  }
+
   // `--progress-json` streams one NDJSON StepRecord per settled step, fed by
   // whatever the runtime reports through `progress`.
   const progress = ctx.args.progressJson ? ndjsonProgressSink<StepRecord>() : undefined;
@@ -1217,6 +1403,10 @@ async function runOpOnResolvedRuntime(ctx: CommandContext): Promise<number> {
       ...(params ? { params } : {}),
       ...(ctx.args.profile !== undefined ? { profile: ctx.args.profile } : {}),
       progress,
+      // `--events-json` (#4041): the runtime writes the run's events itself,
+      // since it is the one that knows the run's id and where it ran.
+      ...(ctx.args.eventsJson ? { runEvents: stdoutLine } : {}),
+      ...(signRecord ? { signRecord } : {}),
       signal: controller.signal,
       ...(work ? { work } : {}),
     });
@@ -1362,7 +1552,42 @@ async function resolveRunWork(
 export function runOpUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown run subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
-    hint: "Available: chant run <name>, run list, run status, run approve, run cancel, run log",
+    hint: "Available: chant run <name>, run list, run status, run approve, run cancel, run log, run events",
   }));
   return Promise.resolve(1);
 }
+
+/** The variable a runner key is read from, as PEM, as `chant ci tick` reads it (`RUNNER_KEY_ENV` in ../../workspace/ci-green.ts). */
+const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
+
+/**
+ * What signs the run's record (#4044): the runner key `--key` names, or the
+ * PEM in `CHANT_RUNNER_KEY`, checked against `.chant/trust.json` at `HEAD`.
+ * Undefined when neither is given. Null, after printing why, when `--key`
+ * is not a runner key; an unusable `CHANT_RUNNER_KEY` only warns, since the
+ * variable may be set for `ci tick` in a job that also runs Ops.
+ */
+async function runSignerFor(ctx: CommandContext): Promise<((record: OpRunRecord) => NonNullable<OpRunRecord["statement"]>) | undefined | null> {
+  const fromFlag = ctx.args.key !== undefined;
+  let pem: string | undefined;
+  try {
+    pem = fromFlag ? readFileSync(resolve(ctx.args.key!), "utf-8") : process.env[RUNNER_KEY_ENV] || undefined;
+  } catch (err) {
+    console.error(formatError({ message: `--key ${ctx.args.key}: ${err instanceof Error ? err.message : String(err)}` }));
+    return null;
+  }
+  if (pem === undefined) return undefined;
+  try {
+    // Loaded only when a key is given, so a run without one loads no workspace code (level 0, #2525).
+    const { opRunSigner } = await import("../../workspace/ci-green");
+    return opRunSigner(process.cwd(), pem);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (fromFlag) {
+      console.error(formatError({ message: `the run would not be signed: ${message}` }));
+      return null;
+    }
+    console.error(formatWarning({ message: `${RUNNER_KEY_ENV} is set, and the run will not be signed: ${message}` }));
+    return undefined;
+  }
+}