@intentius/chant 0.124.27 → 0.124.29

package/src/components/fan-out-inputs.ts

@@ -0,0 +1,192 @@
+/**
+ * What each component of a fan-out would apply, as one digest per component
+ * (#4081), and which of an earlier attempt's progress still holds against it.
+ *
+ * A fan-out's plan digest identifies the derivation: who runs, in what order,
+ * off which edges. Two different changes that touch the same components in
+ * the same shape derive the same plan, so the plan digest alone cannot say
+ * whether "cluster-a already applied" is about the change in front of us.
+ * The attempt record therefore keeps, for each component it applied, the
+ * input digest computed here, and a resumed attempt carries a component as
+ * `already-applied` only when that digest is the one the component has now.
+ *
+ * ## What a component's input digest covers
+ *
+ * - The environment. Progress against `local` says nothing about `prod`.
+ * - The composition: every phase and step as authored, `rollback` included.
+ *   A `stackOutput` reference is hashed as the reference, not its value.
+ * - The bytes of every file a step input names. A string input that resolves,
+ *   relative to the project root, to a file or directory inside the root is
+ *   read and hashed, so `template: "dist/cluster-a.template.json"` covers the
+ *   built template and a rebuild that changes it changes the digest. A
+ *   directory is hashed by its files, skipping `.git`, `node_modules` and
+ *   `.chant`, the last because the attempt record itself lives there.
+ * - The input digests of the components it depends on. A parameter filled
+ *   from an upstream output gets its value from that upstream's apply, so a
+ *   change upstream changes the digest of everything downstream of it, the
+ *   same reach the fan-out's own walk has.
+ *
+ * Nothing decided during the run goes in: no run id, no time, no output an
+ * apply produced.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import { sha256Hex } from "../content-digest";
+import type { DriverComponent, DriverPhase } from "./driver";
+
+export interface ComponentInputOptions {
+  /** The root step inputs' file paths are read relative to, the project the fan-out runs in. */
+  projectRoot: string;
+  /** The environment the fan-out applies to. */
+  env: string;
+  /** Environment config resolved ahead of the run, when the caller has any. */
+  vars?: Record<string, unknown>;
+}
+
+const SKIPPED_DIRS = new Set([".git", "node_modules", ".chant"]);
+
+/** Inside `root`, and not `root` itself: a bare "." names the whole project, which is no one step's input. */
+function insideRoot(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/** Hash a file, or a directory by the relative path and bytes of each file under it. */
+function hashPath(path: string): string | undefined {
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    return undefined;
+  }
+  if (stat.isFile()) return `sha256:${sha256Hex(readFileSync(path))}`;
+  if (!stat.isDirectory()) return undefined;
+  const files: Record<string, string> = {};
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) files[relative(path, full).split(sep).join("/")] = sha256Hex(readFileSync(full));
+    }
+  };
+  walk(path);
+  return computePlanDigest("component-input-dir", files);
+}
+
+/** Every file or directory a component's steps name, keyed by the string the step wrote. */
+function referencedFiles(component: DriverComponent, root: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const visit = (value: unknown): void => {
+    if (typeof value === "string") {
+      if (value === "" || value.includes("\n") || value in out) return;
+      const path = resolve(root, value);
+      if (!insideRoot(root, path) || !existsSync(path)) return;
+      const digest = hashPath(path);
+      if (digest !== undefined) out[value] = digest;
+      return;
+    }
+    if (Array.isArray(value)) value.forEach(visit);
+    else if (value && typeof value === "object") Object.values(value).forEach(visit);
+  };
+  // Only a step's inputs name files. A phase name or a step's `kind` that
+  // happens to match a directory in the project is not one.
+  const visitPhases = (phases: DriverPhase[] | undefined): void => {
+    for (const phase of phases ?? []) {
+      for (const step of phase.steps) {
+        if (isPhase(step)) {
+          visitPhases([step]);
+          continue;
+        }
+        if (step.kind === "gate") continue;
+        const { kind: _kind, ...inputs } = step;
+        visit(inputs);
+      }
+      visitPhases(phase.onFailure);
+    }
+  };
+  visitPhases(component.deploy);
+  visitPhases(component.rollback);
+  return out;
+}
+
+function isPhase(step: DriverPhase["steps"][number]): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+/**
+ * One input digest per component in `components`, keyed by name. Each folds
+ * in the digests of the components it depends on, so `components` should be
+ * the whole project: a dependency it does not contain is hashed by name only.
+ */
+export function componentInputDigests(
+  components: DriverComponent[],
+  options: ComponentInputOptions,
+): Record<string, string> {
+  const root = resolve(options.projectRoot);
+  const byName = new Map(components.map((c) => [c.name, c]));
+  const digests = new Map<string, string>();
+  const visiting = new Set<string>();
+
+  const digestOf = (name: string): string | null => {
+    const known = digests.get(name);
+    if (known !== undefined) return known;
+    const component = byName.get(name);
+    // An unknown dependency or a cycle is refused by the fan-out's derivation
+    // before this runs; here it only has to not loop.
+    if (!component || visiting.has(name)) return null;
+    visiting.add(name);
+    const upstream = [...(component.dependsOn ?? [])].sort().map((dep) => ({ component: dep, digest: digestOf(dep) }));
+    visiting.delete(name);
+    const digest = computePlanDigest("component-input", {
+      environment: options.env,
+      component: name,
+      deploy: component.deploy,
+      rollback: component.rollback ?? null,
+      vars: options.vars ?? null,
+      files: referencedFiles(component, root),
+      upstream,
+    });
+    digests.set(name, digest);
+    return digest;
+  };
+
+  for (const c of components) digestOf(c.name);
+  return Object.fromEntries([...digests.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/** What of an earlier attempt's progress holds against the inputs the components have now. */
+export interface CarriedProgress {
+  /** Components the attempt applied whose input is the same now. These stay `already-applied`. */
+  carried: string[];
+  /** Components the attempt applied whose input moved since. These run again. */
+  changed: string[];
+  /**
+   * True when the record has no input digests at all, as one written before
+   * #4081 has. Nothing carries from such a record, since nothing in it says
+   * what was applied.
+   */
+  unrecorded: boolean;
+}
+
+/**
+ * Split an attempt's `completed` by whether each component's input is the
+ * same as now. A component the record holds no digest for counts as changed:
+ * a claim that it applied is only worth keeping for the input it applied.
+ */
+export function progressThatCarries(
+  attempt: { completed: string[]; inputs?: Record<string, string> },
+  now: Record<string, string>,
+): CarriedProgress {
+  const recorded = attempt.inputs;
+  const carried: string[] = [];
+  const changed: string[] = [];
+  for (const name of [...attempt.completed].sort()) {
+    const then = recorded?.[name];
+    if (then !== undefined && now[name] !== undefined && then === now[name]) carried.push(name);
+    else changed.push(name);
+  }
+  return { carried, changed, unrecorded: recorded === undefined };
+}

package/src/components/fan-out-record.test.ts

@@ -70,3 +70,13 @@ describe("prApply (#3464)", () => {
     for (const name of ["a.json", "b.json", "c.json"]) expect(readFanOutAttempt(join(dir, name))?.prApply).toBeUndefined();
   });
 });
+
+describe("inputs (#4081)", () => {
+  test("round-trips, and a record without them reads as none", () => {
+    const dir = mkdtempSync(join(tmpdir(), "fan-out-record-"));
+    writeFanOutAttempt(join(dir, "a.json"), { digest: "d", completed: ["net"], failed: [], outputs: {}, inputs: { net: "jcs1-sha256:x" } });
+    expect(readFanOutAttempt(join(dir, "a.json"))?.inputs).toEqual({ net: "jcs1-sha256:x" });
+    writeFileSync(join(dir, "b.json"), JSON.stringify({ digest: "d", completed: ["net"], failed: [], outputs: {} }));
+    expect(readFanOutAttempt(join(dir, "b.json"))?.inputs).toBeUndefined();
+  });
+});

package/src/components/fan-out-record.ts

@@ -25,6 +25,14 @@
  * `carried` holds what a step asked to keep for its member (#3459). It rides
  * in the record rather than beside it because the record is the one file a
  * per-wave CI job hands to the next.
+ *
+ * `inputs` holds, for each component in `completed`, the input digest it
+ * applied (#4081, ./fan-out-inputs.ts). The plan digest only identifies the
+ * derivation, and two different changes with the same shape derive the same
+ * one, so the digest alone would carry "cluster-a already applied" into a
+ * change that never applied it. A resumed attempt carries a component only
+ * when its input digest is the same now. A record written before #4081 has
+ * no `inputs`, and none of its progress carries.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -68,6 +76,11 @@ export interface FanOutAttempt {
   carried?: Record<string, unknown>;
   /** A pull request's apply only (#3464). */
   prApply?: PrApplyRecord;
+  /**
+   * The input digest each completed component applied (#4081), keyed by
+   * name. Absent on a record written before it, which then carries nothing.
+   */
+  inputs?: Record<string, string>;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -109,6 +122,11 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
   }
   const waves = readWaveRecords(parsed.waves);
   const prApply = readPrApplyRecord(parsed.prApply);
+  let inputs: Record<string, string> | undefined;
+  if (isRecord(parsed.inputs)) {
+    inputs = {};
+    for (const [name, value] of Object.entries(parsed.inputs)) if (typeof value === "string") inputs[name] = value;
+  }
   return {
     digest: typeof parsed.digest === "string" ? parsed.digest : "",
     completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n): n is string => typeof n === "string") : [],
@@ -117,6 +135,7 @@ export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
     ...(waves.length > 0 ? { waves } : {}),
     ...(isRecord(parsed.carried) && Object.keys(parsed.carried).length > 0 ? { carried: parsed.carried } : {}),
     ...(prApply ? { prApply } : {}),
+    ...(inputs ? { inputs } : {}),
   };
 }
 

package/src/components/fan-out-run.ts

@@ -49,12 +49,58 @@ import type { ReleaseIdentity } from "../telemetry-attribution";
 import { downstreamWithin, remainingFanOut, type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out";
 import { evaluateGate, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "../op/gate";
 import type { RunProgressEvent } from "./run-progress";
+import { emitGateStep, joinRunEventSinks, progressSinkOf, type RunEventSink } from "../run-event-stream";
 import type { CapabilityRegistry } from "./capability";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { DeployContext } from "./capability";
 import { planWaveComponent, type WaveComponentPlan } from "./wave-plan";
 import { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest, type WaveMember, type WaveRecord } from "../wave-engine";
 
+/** The sink a fan-out emits to: run events, and the older stream through them. */
+function fanOutSink(options: FanOutRunOptions): RunEventSink | undefined {
+  return joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
+}
+
+/** The 1-based wave of each component in `waves`. */
+function waveNumbers(waves: string[][]): Map<string, number> {
+  const out = new Map<string, number>();
+  waves.forEach((wave, i) => wave.forEach((name) => out.set(name, i + 1)));
+  return out;
+}
+
+/**
+ * The settles of components a fan-out does not start (#4007): `blocked`
+ * when a dependency failed or stopped at a gate, `already-applied` when an
+ * earlier attempt applied it. Each is said once, with no `component-start`
+ * before it, so a reader of the stream sees every component of the plan.
+ */
+function skipSettles(emit: RunEventSink | undefined, waveOf: Map<string, number>) {
+  const said = new Set<string>();
+  const say = (component: string, wave: number | undefined, body: { status: "blocked"; blockedBy: string } | { status: "already-applied" }): void => {
+    if (!emit || wave === undefined || said.has(component)) return;
+    said.add(component);
+    emit({ type: "component-settle", wave, component, ...body });
+  };
+  return {
+    /** Each component in `blockedBy` not yet said, in wave order then by name. */
+    blocked(blockedBy: Map<string, string>): void {
+      const order = [...blockedBy.keys()].sort((a, b) => (waveOf.get(a) ?? 0) - (waveOf.get(b) ?? 0) || a.localeCompare(b));
+      for (const component of order) say(component, waveOf.get(component), { status: "blocked", blockedBy: blockedBy.get(component)! });
+    },
+    /**
+     * What an earlier attempt left (`remainingFanOut`'s skips): the components
+     * it applied, and the ones its failures blocked. Their wave is the one
+     * they have in the derivation, `derived`, which a resumed run re-layers.
+     */
+    carried(skipped: FanOutSkip[], derived: Map<string, number>): void {
+      for (const skip of skipped) {
+        if (skip.reason === "already-applied") say(skip.component, derived.get(skip.component), { status: "already-applied" });
+        else if (skip.reason === "blocked" && skip.blockedBy) say(skip.component, derived.get(skip.component), { status: "blocked", blockedBy: skip.blockedBy });
+      }
+    },
+  };
+}
+
 /**
  * One gate per wave (#3049), each bound to its wave's set digest. The other
  * mode beside {@link FanOutGate}: that one approves the whole set once, this
@@ -115,6 +161,12 @@ export interface FanOutRunOptions {
   /** Outputs of components this run is not running: the ones the plan lists in `seeds`. */
   componentOutputs?: Record<string, Record<string, unknown>>;
   onProgress?: (event: RunProgressEvent) => void;
+  /**
+   * Where the run's events go (#4041, `--events-json`). A gate over the set
+   * or over a wave is a `gate:<name>` step of a `gate` phase with no
+   * component, settled before the components it lets through start.
+   */
+  onRunEvent?: RunEventSink;
   gates?: GateLedgerPort;
   now?: string;
   /** One approval over the ordered set, bound to `plan.digest`. */
@@ -206,18 +258,27 @@ export async function runFanOut(
     return runGatedWaves(plan, active, components, registry, options, options.waveGate, gates, componentOutputs);
   }
 
+  const emit = fanOutSink(options);
+  emit?.({ type: "run-start", waves: active.waves });
+  const skips = skipSettles(emit, waveNumbers(active.waves));
+  skips.carried(active.skipped, waveNumbers(plan.waves));
+
   if (options.gate) {
-    const check = await evaluateGate(gates.port, {
-      op: options.gate.op,
-      gate: options.gate.gate,
-      planDigest: active.digest,
-      ...(options.gate.description ? { description: options.gate.description } : {}),
-      ...(options.gate.timeout ? { timeout: options.gate.timeout } : {}),
-      ...(options.now ? { now: options.now } : {}),
-    });
+    const gate = options.gate;
+    const check = await emitGateStep(emit, gate, () =>
+      evaluateGate(gates.port, {
+        op: gate.op,
+        gate: gate.gate,
+        planDigest: active.digest,
+        ...(gate.description ? { description: gate.description } : {}),
+        ...(gate.timeout ? { timeout: gate.timeout } : {}),
+        ...(options.now ? { now: options.now } : {}),
+      }),
+    );
     if (!check.satisfied) {
       // Nothing ran, so nothing is half-applied and there is nothing to
       // compensate. A gate is a fact, not a failure.
+      emit?.({ type: "run-settle", status: "gated", durationMs: null });
       return {
         plan: active,
         status: "gated",
@@ -246,29 +307,28 @@ export async function runFanOut(
     }
   };
 
-  options.onProgress?.({ type: "run-start", waves: active.waves });
-
   for (const [waveIndex, wave] of active.waves.entries()) {
     const waveNum = waveIndex + 1;
     // A component whose upstream failed in an earlier wave is not dispatched.
     const runnable = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name));
     if (runnable.length === 0) continue;
 
-    options.onProgress?.({ type: "wave-start", wave: waveNum, components: runnable });
+    emit?.({ type: "wave-start", wave: waveNum, components: runnable });
     const waveResults = await Promise.all(
       runnable.map(async (name) => {
-        options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+        emit?.({ type: "component-start", wave: waveNum, component: name });
         const planned = options.plans?.[name];
         const result = await runComponentDeploy(
           byName.get(name)!,
           { ...fanOutContext(options, name), ...(planned && Object.keys(planned).length > 0 ? { plans: planned } : {}) },
           registry,
           componentOutputs,
-          options.onProgress,
+          undefined,
           gates,
+          emit,
         );
-        options.onProgress?.({
-          type: "component-done",
+        emit?.({
+          type: "component-settle",
           wave: waveNum,
           component: name,
           status: result.status === "fail" ? "failed" : result.status,
@@ -297,11 +357,13 @@ export async function runFanOut(
     }
 
     const waveFailed = waveResults.some((r) => r.status === "fail");
-    options.onProgress?.({
-      type: "wave-done",
+    emit?.({
+      type: "wave-settle",
       wave: waveNum,
       status: waveFailed ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
     });
+    // What this wave's failures and gates hold back settles now, before the next wave starts.
+    skips.blocked(blockedBy);
   }
 
   const blocked: FanOutSkip[] = [...blockedBy.entries()]
@@ -311,7 +373,7 @@ export async function runFanOut(
   // A failure outranks a gate: something is actually broken, and reporting the
   // run as "waiting on a human" would hide it. Same precedence the driver uses.
   const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
-  options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+  emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {
     plan: active,
@@ -391,7 +453,10 @@ async function runGatedWaves(
     }
   };
 
-  options.onProgress?.({ type: "run-start", waves: plan.waves });
+  const emit = fanOutSink(options);
+  emit?.({ type: "run-start", waves: plan.waves });
+  const skips = skipSettles(emit, waveNumbers(plan.waves));
+  skips.carried(active.skipped, waveNumbers(plan.waves));
 
   /** What planning one wave gave. */
   interface Planned {
@@ -459,6 +524,7 @@ async function runGatedWaves(
         results.push(planFailure(f.component, f.error ?? "plan failed"));
         markBlocked(f.component);
       }
+      skips.blocked(blockedBy);
 
       const toRun = runnable.filter((name) => plansFor.has(name));
       const record: WaveRecord = {
@@ -477,14 +543,16 @@ async function runGatedWaves(
         return { end: "next" };
       }
 
-      const check = await decideWaveGate(gates.port, {
-        op: waveGate.op,
-        gate: gateName,
-        digest,
-        description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
-        ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
-        ...(options.now ? { now: options.now } : {}),
-      });
+      const check = await emitGateStep(emit, { op: waveGate.op, gate: gateName }, () =>
+        decideWaveGate(gates.port, {
+          op: waveGate.op,
+          gate: gateName,
+          digest,
+          description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
+          ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
+          ...(options.now ? { now: options.now } : {}),
+        }),
+      );
       if (!check.satisfied) {
         // Nothing in this wave ran, and no later wave is planned: its plan
         // would read outputs this wave has not written.
@@ -502,15 +570,15 @@ async function runGatedWaves(
     },
 
     async apply({ k: waveNum }, { contexts, plansFor, waveFailures }, { check, record, toRun }) {
-      options.onProgress?.({ type: "wave-start", wave: waveNum, components: toRun });
+      emit?.({ type: "wave-start", wave: waveNum, components: toRun });
       const waveResults = await Promise.all(
         toRun.map(async (name) => {
-          options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+          emit?.({ type: "component-start", wave: waveNum, component: name });
           const plans = plansFor.get(name)!;
           const ctx = { ...contexts.get(name)!, ...(Object.keys(plans).length > 0 ? { plans } : {}) };
-          const result = await runComponentDeploy(byName.get(name)!, ctx, registry, componentOutputs, options.onProgress, gates);
-          options.onProgress?.({
-            type: "component-done",
+          const result = await runComponentDeploy(byName.get(name)!, ctx, registry, componentOutputs, undefined, gates, emit);
+          emit?.({
+            type: "component-settle",
             wave: waveNum,
             component: name,
             status: result.status === "fail" ? "failed" : result.status,
@@ -543,11 +611,12 @@ async function runGatedWaves(
       };
       waves.push(settled);
       options.onWaveSettled?.(settled);
-      options.onProgress?.({
-        type: "wave-done",
+      emit?.({
+        type: "wave-settle",
         wave: waveNum,
         status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
       });
+      skips.blocked(blockedBy);
       return "next";
     },
   });
@@ -557,7 +626,7 @@ async function runGatedWaves(
     .map(([component, by]) => ({ component, reason: "blocked" as const, blockedBy: by }));
 
   const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
-  options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+  emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {
     // The derivation's waves, not the narrowed re-layering: their numbers name the gates.

package/src/components/fan-out.ts

@@ -89,6 +89,10 @@ export interface FanOutRequest {
    * {@link FanOutPlan.digest} so an approval is bound to *what* would be
    * applied and not only to who would run. Absent, the digest still identifies
    * the derivation — the selection, the order and the edges it came from.
+   *
+   * `chant components fan-out` does not pass it: its approval stays bound to
+   * the derivation, and it binds a resumed attempt's progress to each
+   * component's input instead (./fan-out-inputs.ts, #4081).
    */
   inputDigests?: Record<string, string>;
   /**

package/src/components/pr-pipeline.ts

@@ -29,6 +29,13 @@
  * squash merges and rebase merges alike, and every job measures from the
  * merge base of that commit and its own head (`resolveMergeBase`).
  *
+ * With `events` (#4007) both commands pass `--events-json`, so the job log
+ * carries the run-event stream, and keep a copy of it under the report
+ * directory through `CHANT_RUN_EVENTS_DIR`, so the report artifact carries
+ * it too. With `reportUrl` both pass `--report-url`, which copies the report,
+ * the change set and the events where a reader outside CI can fetch them;
+ * the job's own environment brings the credentials an `s3://` URL needs.
+ *
  * In a workspace member (#3465) both commands run in the member's directory
  * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
  * note and statuses stay apart from every other member's on the same pull
@@ -68,6 +75,13 @@ export function prLoopSetup(image: string): string[] {
   return image === PR_LOOP_IMAGE ? PR_LOOP_SETUP : [];
 }
 
+/**
+ * Where the jobs keep their run-event files with `events` (#4007), as
+ * `CHANT_RUN_EVENTS_DIR`: inside the report directory, so the report
+ * artifact carries them.
+ */
+export const PR_LOOP_EVENTS_DIR = `${PR_LOOP_REPORT_DIR}/run-events`;
+
 /** The `prLoop` generator option (`ComponentPipelineOptions.prLoop`). */
 export interface PrLoopPipelineOptions {
   /** The gate the apply waits on. Default `pr-apply`. */
@@ -79,6 +93,18 @@ export interface PrLoopPipelineOptions {
   branch?: string;
   /** Count an approval only from someone who approved the pull request on the forge. Default true. */
   requireReview?: boolean;
+  /**
+   * Stream each job's run events (#4007): `--events-json` on both commands,
+   * and `CHANT_RUN_EVENTS_DIR` set to {@link PR_LOOP_EVENTS_DIR}. Default false.
+   */
+  events?: boolean;
+  /**
+   * Copy each job's report, change set and events to this `s3://` or
+   * `file://` URL (#4007, `--report-url`), under `<pr>/<commit>/`. It is
+   * passed in double quotes, so it may name a variable the job expands,
+   * such as `$CHANT_REPORT_URL`.
+   */
+  reportUrl?: string;
   /**
    * Which GitHub-shaped forge the workflow is for. Set by the forgejo
    * generator, which reuses the github one; a caller never needs to.
@@ -112,16 +138,21 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
   const common = [
     "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
     ...(member ? ["--member", member] : []),
+    ...(options.events ? ["--events-json"] : []),
+    ...(options.reportUrl ? ["--report-url", JSON.stringify(options.reportUrl)] : []),
   ];
   const github = forge !== "gitlab";
-  const token: Record<string, string> = github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {};
+  const jobEnv: Record<string, string> = {
+    ...(github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {}),
+    ...(options.events ? { CHANT_RUN_EVENTS_DIR: PR_LOOP_EVENTS_DIR } : {}),
+  };
   return [
     {
       jobName: "plan",
       command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common].join(" "),
       env: github
-        ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...token }
-        : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" },
+        ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...jobEnv }
+        : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", ...jobEnv },
     },
     {
       jobName: "apply",
@@ -130,7 +161,7 @@ export function prLoopJobs(forge: ForgeKind, env: string, options: PrLoopPipelin
         ...(options.requireReview === false ? [] : ["--require-review"]),
         "--resume", PR_APPLY_RECORD,
       ].join(" "),
-      env: github ? { BASE_SHA: "${{ github.event.before }}", ...token } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA" },
+      env: github ? { BASE_SHA: "${{ github.event.before }}", ...jobEnv } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA", ...jobEnv },
       ...(github ? {} : { setup: [gitlabBaseFallback(options.branch)] }),
     },
   ];