@intentius/chant 0.124.26 → 0.124.28

package/dist/cli/handlers/run.d.ts

@@ -1,8 +1,9 @@
 import { type OpConfig } from "../../op/types.js";
 import { type StepRecord } from "../../op/local-executor.js";
 import type { CommandContext } from "../registry.js";
+import type { RunEvent } from "../../run-event.js";
 import type { DriverComponentResult } from "../../components/driver.js";
-import type { ReleaseRecord } from "../../lifecycle/release-ledger.js";
+import { type ReleaseRecord, type RunOrigin } from "../../lifecycle/release-ledger.js";
 /**
  * The exit code a run that stopped at an unapproved gate uses (#2119).
  * Deliberately not 1: a gate is a standing fact waiting on a human, and a CI
@@ -26,6 +27,21 @@ export declare function completedRunExitCode(opName: string, config: Pick<OpConf
 export declare function runOpList(ctx: CommandContext): Promise<number>;
 export declare function runOpStatus(ctx: CommandContext): Promise<number>;
 export declare function runOpLog(ctx: CommandContext): Promise<number>;
+/** One event as a line for a person: its time, its type, where it is and how it ended. */
+export declare function humanRunEventLine(e: RunEvent): string;
+/**
+ * `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 declare function runOpEvents(ctx: CommandContext): Promise<number>;
 /**
  * `chant run approve <op> <gate> [--approver] [--url] [--note]` (#2121) — the
  * rename of `chant run signal`, and a different act.
@@ -48,6 +64,16 @@ export declare function runOpSignalRenamed(ctx: CommandContext): Promise<number>
 /** `chant run cancel <name>` — asks the resolved runtime (#2121) to stop the Op's active run. */
 export declare function runOpCancel(ctx: CommandContext): Promise<number>;
 export declare function runOp(ctx: CommandContext): Promise<number>;
+/**
+ * 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 declare function autoReleaseRun(localId: string): {
+    runId: string;
+    runOrigin: RunOrigin;
+};
 /**
  * After a successful `chant run --components` (local executor), auto-emit
  * one release record per successfully deployed component that published a
@@ -83,7 +109,7 @@ export declare function runOp(ctx: CommandContext): Promise<number>;
  *
  * Returns the records it wrote, for `--digest-file` (#2602).
  */
-export declare function recordAutoReleasesForRun(results: DriverComponentResult[], env: string, runId: string, disabled: boolean): Promise<ReleaseRecord[]>;
+export declare function recordAutoReleasesForRun(results: DriverComponentResult[], env: string, runId: string, disabled: boolean, runOrigin?: RunOrigin): Promise<ReleaseRecord[]>;
 /**
  * `chant run --components <name|all|a,b,c> [--env <env>]` (#585) — the
  * interpret driver's CLI entrypoint, and since #2116 the only component run

package/dist/cli/handlers/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/run.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EAAkD,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAU1G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAYlD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAGpE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AA+BjC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GAAG,OAAO,CAMjF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAChC,eAAe,EAAE,OAAO,GAAG,SAAS,EACpC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GACzC,MAAM,CAQR;AAuLD,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE;AAuED,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAetE;AA8BD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAenE;AA2CD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6CvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAQvE;AAID,iGAAiG;AACjG,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBtE;AAsMD,wBAAsB,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BhE;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,qBAAqB,EAAE,EAChC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,aAAa,EAAE,CAAC,CA0C1B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE;AAmMD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AA4OD,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAMjE"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/run.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,EAAkD,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAU1G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAWlD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAIhD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAIlG;;;;;GAKG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AA+BjC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GAAG,OAAO,CAMjF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAChC,eAAe,EAAE,OAAO,GAAG,SAAS,EACpC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GACzC,MAAM,CAQR;AAuLD,wBAAsB,SAAS,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE;AAuED,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAetE;AA8BD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAenE;AA2CD,0FAA0F;AAC1F,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAKrD;AAOD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA+CtE;AAOD;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA6CvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAQvE;AAID,iGAAiG;AACjG,wBAAsB,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBtE;AAsMD,wBAAsB,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BhE;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAEvF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,qBAAqB,EAAE,EAChC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,EACjB,SAAS,GAAE,SAA8B,GACxC,OAAO,CAAC,aAAa,EAAE,CAAC,CA6C1B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE;AAkND;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnE;AAyPD,wBAAgB,YAAY,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAMjE"}

package/dist/cli/handlers/run.js

@@ -23,9 +23,13 @@ import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/loca
 import { ledgerRecordingOff, noRecordEndNote, noRecordStartNote, resetNoRecordLedger, NO_RECORD_ENV } from "../../lifecycle/no-record.js";
 import { renderDriverHuman, renderDriverJson } from "../../components/driver-output.js";
 import { ndjsonProgressSink } from "../../components/run-progress.js";
+import { findStoredRun, readRunEvents } from "../../run-event-store.js";
+import { openCliRunEvents, refusesBothStreams, stdoutLine } from "../run-events.js";
 import { maybeRecordAutoRelease } from "../../components/auto-release.js";
 import { maybePersistBuildManifest } from "../../components/manifest-persistence.js";
 import { isComponentList } from "../../components/cli-support.js";
+import { resolveCiRun } from "../../lifecycle/release-ledger.js";
+import { gateAdmission, gateApprover } from "../../components/promote.js";
 import { runOpGenerate } from "./run-generate.js";
 /**
  * The exit code a run that stopped at an unapproved gate uses (#2119).
@@ -396,6 +400,78 @@ async function runOpLogOnRuntime(ctx, name) {
     }
     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) {
+    const x = e;
+    const where = [x.component, x.phase, x.step].filter((v) => 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) {
+    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) {
+    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.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> ────────────────────────────────────────────
 /**
  * `chant run approve <op> <gate> [--approver] [--url] [--note]` (#2121) — the
@@ -688,6 +764,8 @@ export async function runOp(ctx) {
         }));
         return 1;
     }
+    if (refusesBothStreams(ctx.args))
+        return 1;
     if (ctx.args.components)
         return runOpComponents(ctx);
     if (ctx.args.report) {
@@ -700,6 +778,15 @@ export async function runOp(ctx) {
     return runOpOnRuntime(ctx);
 }
 // ── 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) {
+    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
@@ -735,7 +822,7 @@ export async function runOp(ctx) {
  *
  * Returns the records it wrote, for `--digest-file` (#2602).
  */
-export async function recordAutoReleasesForRun(results, env, runId, disabled) {
+export async function recordAutoReleasesForRun(results, env, runId, disabled, runOrigin = { forge: "local" }) {
     const recorded = [];
     for (const componentResult of results) {
         if (!componentResult.ok)
@@ -746,8 +833,11 @@ export async function recordAutoReleasesForRun(results, env, runId, disabled) {
             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 });
         if (!outcome.recorded && outcome.reason === "error") {
             console.error(formatWarning({
@@ -909,6 +999,10 @@ async function runComponentSelection(ctx) {
     // `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.
@@ -919,14 +1013,29 @@ async function runComponentSelection(ctx) {
                 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;
+    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.
     if (ctx.args.dumpOutputs && result.run) {
@@ -990,7 +1099,7 @@ async function runComponentSelection(ctx) {
     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
@@ -1069,6 +1178,14 @@ async function runOpOnResolvedRuntime(ctx) {
         await stewardGate?.release?.();
         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() : undefined;
@@ -1103,6 +1220,10 @@ async function runOpOnResolvedRuntime(ctx) {
             ...(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 } : {}),
         });
@@ -1249,7 +1370,43 @@ async function resolveRunWork(ctx, config, provider) {
 export function runOpUnknown(ctx) {
     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) {
+    const fromFlag = ctx.args.key !== undefined;
+    let pem;
+    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.js");
+        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/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAkB,KAAK,UAAU,EAAmB,MAAM,YAAY,CAAC;AAa9E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAgB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;AAwkCzC;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBzE;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EA6KvC,CAAC"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":";AAKA,OAAO,EAAkB,KAAK,UAAU,EAAmB,MAAM,YAAY,CAAC;AAa9E,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAgB,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;AAyoCzC;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBzE;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,EAuLvC,CAAC"}

package/dist/cli/main.js

@@ -104,6 +104,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.js");
 const runOpWaveCommand = lazyHandler(runWaveHandlers, (m) => m.runOpWaveCommand);
 const operatorHandlers = () => import("./handlers/operator.js");
@@ -214,22 +215,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
@@ -238,6 +278,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)
@@ -247,11 +291,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;
@@ -286,6 +337,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
@@ -651,7 +707,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
@@ -774,9 +836,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
@@ -921,7 +986,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.
@@ -933,7 +998,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.
@@ -1178,10 +1243,18 @@ export const commandRegistry = [
     { 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.js")).runCiLastGreen(ctx) },
+    { name: "ci list", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).runCiList(ctx) },
     { name: "ci tick", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).runCiTick(ctx) },
     { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli.js")).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.js")).runReleaseCut(ctx) },
+    { name: "release list", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleaseList(ctx) },
+    { name: "release export", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleaseExport(ctx) },
+    { name: "release compile", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).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.js")).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.js")).runChangeSetShow(ctx) },
     { name: "init", handler: runInit, runsNoConfig: true },
     { name: "init lexicon", handler: runInitLexicon },
     { name: "update", handler: runUpdate },
@@ -1201,6 +1274,7 @@ export const commandRegistry = [
     { 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.js")).runResumeCommand(ctx) },
@@ -1307,6 +1381,7 @@ export const commandRegistry = [
     { name: "dev", handler: runDevUnknown },
     { name: "serve", handler: runServeUnknown },
     { name: "components", handler: runComponentsUnknown },
+    { name: "release", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/release.js")).runReleaseUnknown(ctx) },
     { name: "workspace", handler: async (ctx) => (await import("../workspace/records-cli.js")).runWorkspaceUnknown(ctx) },
 ];
 /**

package/dist/cli/mcp/workspace-tools.js

@@ -100,7 +100,7 @@ export const workspaceReadTools = [
     },
     {
         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.",
+        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. 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/dist/cli/parse-args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../src/cli/parse-args.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA0E7C;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAitBpD"}
+{"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../src/cli/parse-args.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA8E7C;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA+uBpD"}