@intentius/chant 0.124.26 → 0.124.28

package/src/cli/handlers/run.ts

@@ -10,7 +10,7 @@ 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";
@@ -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,85 @@ 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 : "", 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 +861,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 +875,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 +925,7 @@ export async function recordAutoReleasesForRun(
   env: string,
   runId: string,
   disabled: boolean,
+  runOrigin: RunOrigin = { forge: "local" },
 ): Promise<ReleaseRecord[]> {
   const recorded: ReleaseRecord[] = [];
   for (const componentResult of results) {
@@ -842,8 +937,11 @@ 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) } : {}),
       },
       { disabled },
     );
@@ -1011,6 +1109,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 +1122,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 +1207,7 @@ 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);
     // `--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 +1295,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 +1339,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 +1488,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;
+  }
+}

package/src/cli/main.test.ts

@@ -16,6 +16,13 @@ describe("parseArgs", () => {
     expect(() => parseArgs(["graph", "--traffic"])).toThrow(/--traffic needs a level/);
   });
 
+  test("--before-script is repeatable and keeps its order; --image takes a reference (#4002)", () => {
+    const args = parseArgs(["build", "--components", "--generate", "forgejo", "--image", "node:22-bookworm", "--before-script", "npm ci", "--before-script", "-x"]);
+    expect(args.image).toBe("node:22-bookworm");
+    expect(args.beforeScript).toEqual(["npm ci", "-x"]);
+    expect(() => parseArgs(["build", "--before-script"])).toThrow(/--before-script needs a shell line/);
+  });
+
   test("--skip-undeclarable reaches live import (#3911)", () => {
     expect(parseArgs(["import", "--from", "prod"]).skipUndeclarable).toBeUndefined();
     expect(parseArgs(["import", "--from", "prod", "--skip-undeclarable"]).skipUndeclarable).toBe(true);

package/src/cli/main.ts

@@ -114,6 +114,7 @@ const runOpApprove = lazyHandler(runHandlers, (m) => m.runOpApprove);
 const runOpSignalRenamed = lazyHandler(runHandlers, (m) => m.runOpSignalRenamed);
 const runOpCancel = lazyHandler(runHandlers, (m) => m.runOpCancel);
 const runOpLog = lazyHandler(runHandlers, (m) => m.runOpLog);
+const runOpEvents = lazyHandler(runHandlers, (m) => m.runOpEvents);
 const runWaveHandlers = () => import("./handlers/run-wave");
 const runOpWaveCommand = lazyHandler(runWaveHandlers, (m) => m.runOpWaveCommand);
 const operatorHandlers = () => import("./handlers/operator");
@@ -227,22 +228,61 @@ Commands:
                                           applied) and path. Read-only.
 
 CI:
-  ci last-green [--json]  The newest first-parent commit of ci.green's branch
-                        with a ci/green tag and no ci/revoked tag. Reads local
-                        tags only; fetch them first.
-  ci tick [--dry-run] [--forge github]  Tag each commit within ci.green's
-                        window whose required phases all passed ci/green/<sha>,
-                        and revoke a green one that now fails ci/revoked/<sha>.
-                        Reads check runs from the forge, pushes the tags.
+  ci last-green [--json] [--from <rev>]  The newest first-parent commit of
+                        ci.green's branch, or of --from, with a ci/green tag
+                        and no ci/revoked tag. Reads local tags only; fetch
+                        them first. With ci.green.signedSince, a tag without a
+                        valid runner statement is ignored and reported.
+  ci list [--json] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs]
+                        The first-parent commits of ci.green's branch within
+                        its window, newest first, each green, revoked or
+                        undecided with its required phases' results. Reads
+                        local tags; --forge reads check runs for undecided
+                        commits, and source runs reads the signed Op runs on
+                        the local chant/lifecycle. --since replaces the window.
+  ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>]
+                        Tag each commit within ci.green's window whose
+                        required phases all passed ci/green/<sha>, and revoke
+                        a green one that now fails ci/revoked/<sha>. Reads
+                        check runs from the forge, or with source runs
+                        (ci.green.source or --source) the Op runs on
+                        chant/lifecycle that a runner key signed. Pushes the
+                        tags. --key, or the PEM in CHANT_RUNNER_KEY, signs
+                        each tag with a runner key.
   ci workflow [--workflow <name>]... [--output <file>]  Write
               [--chant <command>] [--install <command>]
               [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>]
+              [--runner-key-secret <NAME>]
                         .github/workflows/chant-ci-green.yml, which runs the
                         tick when a required workflow completes and every 15m.
                         --chant replaces the npx @intentius/chant pin the tick
                         runs; --install adds a step before it. --token-secret,
                         or a GitHub App's id and key, pushes the tags with a
                         token that may tag commits changing workflow files.
+                        --runner-key-secret hands the tick the runner key it
+                        signs its tags with.
+
+Releases:
+  release cut [<label>] [--build <command>] [--param <k=v>] [--params-file <file>]
+              [--src <dir>] [-o <file>] [--lexicon <name>] [--sign [<key file>]]
+                        Cut a release of this member from HEAD, which must
+                        carry a ci/green tag: compile every environment in
+                        the config's environments, build the artifacts once,
+                        and store it on chant/lifecycle under its digest.
+                        --build runs before each environment's templates are
+                        read, with CHANT_ENV set; {env} in --params-file is
+                        replaced by the environment. --sign signs the cut with
+                        the actor's ssh key; an identity.gates release entry
+                        requires it. A project with no components releases
+                        what chant build --env <env> writes: --src <dir> is
+                        the build root, -o <file> the output (dist/build.yaml),
+                        --lexicon narrows it.
+  release list [--json]  Every release of this member with its targets, its
+                        cuts and the environments that run it.
+  release export <label|digest> --env <env> [-o <dir>] [--json]
+                        Write the files the release recorded for <env>, each
+                        checked against its digest, at their recorded paths
+                        under <dir> (default: here), for a deploy to read.
 
 Change sets:
   change-set summary <file>  The grouped plan summary of a change-set
@@ -251,6 +291,10 @@ Change sets:
                                           replacement, failure and hole named.
                                           markdown fits an MR/PR note of --limit
                                           characters (default 65536). Read-only.
+  change-set show <digest>  The change set a pull-request or release gate
+                        [--member <name>] [--json]  bound, stored on
+                                          chant/lifecycle under its digest, each
+                                          entry with its graph node. Read-only.
 
 Ops:
   run <name>            Run an Op on the resolved runtime (--on; local by default)
@@ -260,11 +304,18 @@ Ops:
                         its Drift outcome is true (WatchOp failOn: "drift")
                         --no-record: a test run that records nothing on
                         chant/lifecycle and pushes nothing (local runtime)
+                        --key <runner key.pem>, or the PEM in
+                        CHANT_RUNNER_KEY: sign the run's record with a runner
+                        key, so ci tick from runs counts it (#4044)
   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
   run cancel <name>     Cancel the active run (requires --force)
   run log <name>        Show run history for an Op
+  run events <run>      Replay a run's events kept on this host (a run id, or
+                        an Op or component name for its newest run). --json
+                        prints the run-event lines; --follow streams a run in
+                        progress until run-settle (#4042)
   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;
@@ -299,6 +350,11 @@ Ops:
                         consumer to render live wave/component/phase/step
                         progress instead of tailing raw logs (additive; run
                         semantics/exit code unchanged)
+                        --events-json: stream the run's events instead, one
+                        run-event.schema.json line each, with the run id,
+                        commit and runtime on every line (#4041). Also on
+                        run <op>, components promote|rollback|redeploy,
+                        fan-out, pr-plan and pr-apply
   operator               Run scheduled ticks for discovered ConvergeOps
                         locally (#1485): acquire/renew a per-op
                         lease (git ref CAS), tick on --interval, record every
@@ -664,7 +720,13 @@ Workspace (level 1, #2524):
                         the severity (warn by default) and ignore globs. When
                         the declaration at base has writeScope or agents, each
                         commit that writes outside its writer's scope fails
-                        the check (write-scope-member, write-scope-kind)
+                        the check (write-scope-member, write-scope-kind). Each
+                        first-parent commit of the range should name its work
+                        item in a Chant-Record: <work kind>:<id> or a
+                        Chant-Lease trailer. commit-unlinked is a commit that
+                        names none, commit-wrongly-linked one whose trailers
+                        name no work item that exists; both follow the
+                        severity
   workspace patch <base>..<head>|<base>...<head>|<commit> [--path <p>...] [--max-bytes <n>] [--json]
   workspace patch [<commit>] --worktree [--path <p>...] [--max-bytes <n>] [--json]
                         The hunks of a diff, file by file: a range, a work
@@ -787,9 +849,12 @@ Component release ledger + status:
                             byte-for-byte plus a self-describing manifest.json
   components promote        Deploy the digests one environment's release
                             ledger records to another, without a build
-                            (--from <env> --to <env> [--component <name>
-                             [--digest <sha256:...>]]; --dry-run prints the
-                             plan; the target's gates still apply)
+                            (--to <env> [--from <env>] [--allow-skip]
+                             [--release <label|digest>]
+                             [--component <name> [--digest <sha256:...>]];
+                             --from defaults to the environment before --to
+                             in the config's environments; --dry-run prints
+                             the plan; the target's gates still apply)
   components rollback <env> Redeploy an earlier release of an environment
                             from its recorded digest (--component <name>
                             [--digest <sha256:...>]; defaults to the release
@@ -934,7 +999,7 @@ Options:
                         chant.config.ts's build.sandbox: true; #1045)
   --param <name=value>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy) Bind a
+                        components redeploy, release cut) Bind a
                         declared build-time parameter (chant.config.ts's buildParams)
                         to a value, for source to read as params.<name>
                         (#1064) instead of process.env — repeatable.
@@ -946,7 +1011,7 @@ Options:
                         chant.template.json declares instead (#2627).
   --params-file <path>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy) JSON file
+                        components redeploy, release cut) JSON file
                         of { "name": value } build-time parameter values
                         (#1064). Second precedence, after --param.
                         init --from refuses it: pass --param instead.
@@ -1195,10 +1260,18 @@ export const commandRegistry: CommandDef[] = [
   { name: "carve status", handler: runCarveStatus },
   // #3573 — which commits passed CI, kept as ci/green and ci/revoked tags (ws-103). Imported on first use.
   { name: "ci last-green", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiLastGreen(ctx) },
+  { name: "ci list", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiList(ctx) },
   { name: "ci tick", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiTick(ctx) },
   { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiWorkflow(ctx) },
+  // #4026: the release cut from a green commit (ws-104). Imported on first use.
+  { name: "release cut", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCut(ctx) },
+  { name: "release list", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseList(ctx) },
+  { name: "release export", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseExport(ctx) },
+  { name: "release compile", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseCompile(ctx) },
   // #3188 — the grouped plan summary of a change-set document. Reads one file; imported on first use.
   { name: "change-set summary", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set")).runChangeSetSummary(ctx) },
+  // #4022: the change set a gate bound, read from chant/lifecycle by its digest.
+  { name: "change-set show", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/change-set")).runChangeSetShow(ctx) },
   { name: "init", handler: runInit, runsNoConfig: true },
   { name: "init lexicon", handler: runInitLexicon },
 { name: "update", handler: runUpdate },
@@ -1220,6 +1293,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "run signal", handler: runOpSignalRenamed },
   { name: "run cancel", handler: runOpCancel },
   { name: "run log", handler: runOpLog },
+  { name: "run events", handler: runOpEvents },
   { name: "run wave", handler: runOpWaveCommand },
   // #3683 — start the CI jobs that wait at gates whose approval arrived. Imported on first use.
   { name: "run resume", handler: async (ctx) => (await import("./handlers/gate-resume")).runResumeCommand(ctx) },
@@ -1335,6 +1409,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "dev", handler: runDevUnknown },
   { name: "serve", handler: runServeUnknown },
   { name: "components", handler: runComponentsUnknown },
+  { name: "release", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release")).runReleaseUnknown(ctx) },
   { name: "workspace", handler: async (ctx) => (await import("../workspace/records-cli")).runWorkspaceUnknown(ctx) },
 ];
 

package/src/cli/mcp/never-over-mcp.test.ts

@@ -217,6 +217,8 @@ describe("neverOverMcp (chant#3447)", () => {
   const gateOnlyOps: Array<{ op: string; gate: string }> = [
     { op: "workspace-upgrade", gate: "." },
     { op: "pr-12", gate: "pr-apply" },
+    // #4045: a release gate approves a change to an environment, as a pull request's does.
+    { op: "release", gate: "prod-release" },
   ];
 
   for (const { op, gate } of gateOnlyOps) {

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

@@ -126,7 +126,7 @@ export const workspaceReadTools: ToolDefinition[] = [
   {
     name: "workspace-changes",
     description:
-      "The forward coverage check over a diff: chant workspace check --changes <range> --json (changes.schema.json, #2773). Each changed path with the current records whose constrains cover it, and a change-uncovered or change-out-of-scope finding for each gap, at the severity the declaration's changes block sets. Returns the document unchanged.",
+      "The forward coverage check over a diff: chant workspace check --changes <range> --json (changes.schema.json, #2773). Each changed path with the current records whose constrains cover it, and a change-uncovered or change-out-of-scope finding for each gap, at the severity the declaration's changes block sets. links says whether each trunk commit of the range names its work item, with commit-unlinked and commit-wrongly-linked findings at the same severity. Returns the document unchanged.",
     inputSchema: {
       type: "object",
       properties: {

package/src/cli/parse-args.ts

@@ -48,6 +48,8 @@ const BOOLEAN_FLAGS = new Set([
   "--local",
   "--json",
   "--progress-json",
+  "--events-json",
+  "--follow",
   "--update-snapshot",
   "--update-baseline",
   "--run-examples",
@@ -71,11 +73,13 @@ const BOOLEAN_FLAGS = new Set([
   "--current",
   "--uncommitted",
   "--allow-code",
+  "--allow-skip",
   "--root-only",
   "--generated",
   "--decide",
   "--record-plans",
   "--loopback",
+  "--artifacts",
 ]);
 
 /**
@@ -191,8 +195,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.overlayAnchor = v;
     } else if (arg === "--from") {
       // Shared by `migrate --from <lexicon>`, `import --from <env>`,
-      // `components promote --from <env>` and `init --from <repo>@<ref>`;
-      // the commands never run together, so one field carries all four.
+      // `components promote --from <env>`, `init --from <repo>@<ref>` and
+      // `ci last-green --from <rev>` (#4031); the commands never run
+      // together, so one field carries all five.
       result.migrateFrom = args[++i];
     } else if (arg === "--kustomize") {
       // `chant import --kustomize <dir>` (#1548): render the overlay, import
@@ -372,6 +377,10 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.requireReview = true;
     } else if (arg === "--pr-loop") {
       result.prLoop = true;
+    } else if (arg === "--before-script") {
+      const line = args[++i];
+      if (line === undefined || line === "") throw new Error("--before-script needs a shell line: --before-script '<line>'");
+      (result.beforeScript ??= []).push(line);
     } else if (arg === "--resume") {
       // `chant approve <op> <gate> --resume` (#3683) takes no value; the
       // fan-out and pull-request apply take the attempt file they resume.
@@ -384,6 +393,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.json = true;
     } else if (arg === "--progress-json") {
       result.progressJson = true;
+    } else if (arg === "--events-json") {
+      result.eventsJson = true;
+    } else if (arg === "--follow") {
+      // `chant run events <run> --follow` (#4042): tail a run in progress on this host.
+      result.follow = true;
     } else if (arg === "--gated-exit") {
       // `chant run <op> --gated-exit <code>` (#2243) — remap only the gated
       // outcome's exit code. Parsed as a number here and range-checked in the
@@ -502,6 +516,10 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--app-key-secret") {
       result.ciAppKeySecret = args[++i];
       if (!result.ciAppKeySecret || result.ciAppKeySecret.startsWith("-")) throw new Error("--app-key-secret needs the secret holding the App's private key: --app-key-secret <NAME>");
+    } else if (arg === "--runner-key-secret") {
+      // `chant ci workflow --runner-key-secret <NAME>` (#4031): the secret holding the runner key the tick signs its tags with.
+      result.ciRunnerKeySecret = args[++i];
+      if (!result.ciRunnerKeySecret || result.ciRunnerKeySecret.startsWith("-")) throw new Error("--runner-key-secret needs the repository secret holding the runner key, such as CHANT_RUNNER_KEY: --runner-key-secret <NAME>");
     } else if (arg === "--verdict") {
       // `chant workspace records review <id> --verdict agree|dissent|abstain` (#2670)
       result.verdict = args[++i];
@@ -588,6 +606,17 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (result.digest !== undefined) (result.digests ??= []).push(result.digest);
     } else if (arg === "--release-plan") {
       result.releasePlanFile = args[++i];
+    } else if (arg === "--release") {
+      // `chant components promote --release <label|digest>` (#4026)
+      result.release = args[++i];
+      if (!result.release || result.release.startsWith("-")) throw new Error("--release needs a release's label or digest: --release <label|digest>");
+    } else if (arg === "--build") {
+      // `chant release cut --build <command>` (#4026)
+      result.buildCommand = args[++i];
+      if (!result.buildCommand) throw new Error("--build needs a shell command: --build '<command>'");
+    } else if (arg === "--artifacts") {
+      // `chant release compile --artifacts` (#4026, internal)
+      result.artifacts = true;
     } else if (arg === "--git-sha") {
       result.gitSha = args[++i];
     } else if (arg === "--run-id") {
@@ -712,10 +741,15 @@ export function parseArgs(args: string[]): ParsedArgs {
       // #2550 — `chant workspace upgrade` runs a template's code migrations
       // only when asked to.
       result.allowCode = true;
+    } else if (arg === "--allow-skip") {
+      // #4030 — `chant components promote` skips a step of the member's
+      // declared promotion order only when asked to.
+      result.allowSkip = true;
     } else if (arg === "--source") {
       // #2551 — `chant workspace upgrade --source <repo>[#<member>]`.
       result.source = args[++i];
-      if (!result.source || result.source.startsWith("-")) throw new Error("--source needs a template: --source <repo>[#<member>]");
+      // #4044: also `chant ci tick|list --source checks|runs`.
+      if (!result.source || result.source.startsWith("-")) throw new Error("--source needs a template: --source <repo>[#<member>] for workspace upgrade, or a source for ci tick and ci list: --source checks|runs");
     } else if (arg === "--tags") {
       // #2551 — `chant workspace adopt-lineage --tags <glob>`, also hash-index and versions.
       result.tags = args[++i];