@intentius/chant 0.101.0 → 0.104.0

package/src/components/capability.ts

@@ -12,6 +12,9 @@
  * Cloud implementations are a later phase (see epic #551, issue #554).
  */
 
+import type { ReleaseIdentity } from "../telemetry-attribution";
+import type { ChangeSetPart } from "../change-set";
+
 /**
  * Ambient information a capability's `run`/`rollback` receives, independent of
  * its typed `input`. Deliberately minimal for this phase: the orchestrator
@@ -27,6 +30,42 @@ export interface DeployContext {
   component: string;
   /** Arbitrary environment config resolved by the orchestrator (registry URLs, cluster names, ...). */
   vars?: Record<string, unknown>;
+  /**
+   * The release this run deploys (#3061, ws-081): the commit, set by the
+   * caller, and the digest of the artifact a publish step has promoted so
+   * far in this component's run, set by the driver. A deploy step passes it
+   * to the workload with `releaseEnvironment()`. Absent outside
+   * `chant run --components`.
+   */
+  release?: ReleaseIdentity;
+  /**
+   * What this component's steps planned before its wave's gate was decided
+   * (#3049), keyed by {@link CapabilityPlan.member}. Set by a gated-wave
+   * fan-out and by a pull request's apply (#3183). A capability whose `run`
+   * finds its own member here applies that plan, the one the approver
+   * approved, instead of planning again.
+   */
+  plans?: Record<string, unknown>;
+}
+
+/**
+ * What a capability's `plan` produced (#3049): the member it planned, that
+ * plan's digest, and whatever `run` needs to apply exactly that plan.
+ */
+export interface CapabilityPlan {
+  /** The member's name in a wave's set digest. For a terraform-family step, the root. */
+  member: string;
+  /** The digest a gate on this member alone would bind (#2300). */
+  planDigest: string;
+  /** Handed back to `run` as `DeployContext.plans[member]`. Opaque to the runner. */
+  artifact?: unknown;
+  /**
+   * The member's part of a change-set document (#3181): every change the
+   * plan proposes. A pull request's plan (#3183) composes the parts into the
+   * document whose grouped summary the PR note shows. Without it the member
+   * still counts toward the digest, with no entries.
+   */
+  changeSet?: ChangeSetPart;
 }
 
 /**
@@ -61,6 +100,22 @@ export interface Capability<In = unknown, Out = unknown> {
    * never needs it (most of them) simply ignores the third parameter.
    */
   rollback?(ctx: DeployContext, input: In, output?: Out): Promise<void>;
+  /**
+   * Optional: say what `run` would change, without changing it (#3049). A
+   * gated-wave fan-out calls this for every step of every component in a
+   * wave, once the waves before it have applied, and binds the wave's gate
+   * to the set digest of the results. `run` then receives the result's
+   * `artifact` through `DeployContext.plans`. A capability without `plan`
+   * is covered by its component's composition digest instead.
+   */
+  plan?(ctx: DeployContext, input: In): Promise<CapabilityPlan>;
+  /**
+   * Optional: the outputs `run` exposed when it last ran, read without
+   * changing anything (#3183). A pull request's plan reads them for each
+   * component a planned one depends on, so a `stackOutput()` wiring resolves
+   * to the value standing now. The shape is `run`'s `outputs` field.
+   */
+  outputs?(ctx: DeployContext, input: In): Promise<Record<string, unknown>>;
   /**
    * How this verb relates to rollback, for the COMP003 composition check.
    * Usually derivable and left unset: a capability with a `rollback` method is

package/src/components/changed-files.ts

@@ -0,0 +1,66 @@
+/**
+ * The files a change touched, and the units lexicons own that those files
+ * belong to (#3183).
+ *
+ * `lifecycle affected` judges chant source by diffing what it builds. A unit
+ * that is not chant source, such as a hand-written Terraform root, never
+ * shows in that diff, so a lexicon that owns such units answers from the
+ * changed paths instead (`LexiconPlugin.changedUnits`).
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { LexiconPlugin } from "../lexicon";
+
+const execFileAsync = promisify(execFile);
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+  return stdout;
+}
+
+/**
+ * The commit a change is measured from: the merge base of `base` and `head`.
+ * A pull request's head that branched before `base` moved is measured from
+ * where it branched, so the other changes on `base` are not counted as its
+ * own; a merge commit's first parent is its own merge base.
+ */
+export async function resolveMergeBase(cwd: string, base: string, head = "HEAD"): Promise<string> {
+  try {
+    return (await git(cwd, ["merge-base", base, head])).trim();
+  } catch (err) {
+    const detail = (err as { stderr?: string }).stderr?.trim();
+    throw new Error(
+      `cannot find where ${head} and ${base} meet${detail ? `: ${detail}` : ""}. ` +
+        "Is the base fetched? A CI checkout needs the history (fetch-depth: 0, GIT_DEPTH: 0).",
+    );
+  }
+}
+
+/** The full commit `ref` names. */
+export async function resolveCommit(cwd: string, ref: string): Promise<string> {
+  return (await git(cwd, ["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+}
+
+/**
+ * Files changed between `base` and `head`, relative to `cwd` and limited to
+ * it, with `/` separators. A rename counts as its old and its new path.
+ */
+export async function changedFilesBetween(cwd: string, base: string, head = "HEAD"): Promise<string[]> {
+  const out = await git(cwd, ["diff", "--name-only", "-z", "--no-renames", "--relative", base, head]);
+  return out.split("\0").filter(Boolean).sort();
+}
+
+/** The union of every plugin's `changedUnits` answer, sorted. */
+export async function lexiconChangedUnits(
+  plugins: readonly Pick<LexiconPlugin, "changedUnits">[],
+  ctx: { projectRoot: string; config: Record<string, unknown>; changedFiles: string[] },
+): Promise<string[]> {
+  if (ctx.changedFiles.length === 0) return [];
+  const units = new Set<string>();
+  for (const plugin of plugins) {
+    if (!plugin.changedUnits) continue;
+    for (const unit of await plugin.changedUnits(ctx)) units.add(unit);
+  }
+  return [...units].sort();
+}

package/src/components/cli-support.ts

@@ -22,11 +22,13 @@
  *    executor, the CLI entrypoint the driver (#556) never had.
  */
 
+import { UnknownCanaryError } from "../gated-waves";
 import { lexiconModulePath, lexiconNames, importLexiconPackage } from "../lexicon-module";
 import { discoverComponents } from "./discover";
 import type { BuildParamProvenance } from "../provenance";
-import { inferArchetype, projectToJson, type Archetype } from "./component";
+import { inferArchetype, projectToJson, type Archetype, type ComponentEnvironmentDeclaration } from "./component";
 import {
+  deployContext,
   resolveComponentGraph,
   runInterpretDriver,
   runComponentDeploy,
@@ -43,7 +45,9 @@ import type { GateDigestMismatch, GateLedgerPort } from "../op/gate";
 import { gateName } from "../op/gate-name";
 import { isLexiconPlugin, type LexiconPlugin, type ComponentPipelineOptions } from "../lexicon";
 import type { RunProgressEvent } from "./run-progress";
-import { relative } from "node:path";
+import { dirname, relative } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { getHeadCommit } from "../lifecycle/git";
 import { buildCapabilityRegistry } from "./capability-plugin-loader";
 import type { CapabilityRegistry } from "./capability";
 import { applyConfigDefaults } from "./config-defaults";
@@ -156,6 +160,8 @@ export interface ComponentGraphResult {
    * (`inferArchetype`), so a reader can label a component without its source
    * (#2662). */
   archetypes?: Record<string, Archetype>;
+  /** Component name → the environments it declares (#3153), present only for components that declared them. */
+  environments?: Record<string, ComponentEnvironmentDeclaration[]>;
   error?: string;
 }
 
@@ -192,7 +198,10 @@ export async function computeComponentGraph(
   // that declared them — no identity fallback (see ComponentGraphResult doc).
   const composites: Record<string, string[]> = {};
   const archetypes: Record<string, Archetype> = {};
+  const environments: Record<string, ComponentEnvironmentDeclaration[]> = {};
   for (const [name, discovered] of result.components) {
+    const declaredEnvironments = discovered.component.environments;
+    if (declaredEnvironments && declaredEnvironments.length > 0) environments[name] = declaredEnvironments.map((e) => ({ ...e }));
     archetypes[name] = discovered.component.archetype ?? inferArchetype(discovered.component);
     files[name] = relative(path, discovered.filePath);
     const declared = discovered.component.liveNames;
@@ -207,7 +216,7 @@ export async function computeComponentGraph(
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges, files, liveNames, composites, archetypes };
+    return { success: true, order, waves, edges, files, liveNames, composites, archetypes, environments };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };
@@ -302,7 +311,7 @@ export async function generateComponentsPipeline(
     const { yaml, stages, jobs, env } = plugin.generateComponentPipeline(driverComponents, options);
     return { success: true, yaml, stages, jobs, ...(env ? { env } : {}), buildParams };
   } catch (err) {
-    if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
+    if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError || err instanceof UnknownCanaryError) {
       return { success: false, error: err.message };
     }
     throw err;
@@ -421,6 +430,12 @@ export interface RunComponentsOptions {
   buildParams?: BuildParamProvenance[];
   /** Where a `gate` step's facts are read and written (#2119). Defaults to the `chant/lifecycle` orphan branch; a test passes `memoryGateLedgerPort()` from `../op/gate.ts`. */
   gates?: GateLedgerPort;
+  /**
+   * The commit the run deploys, for the workloads' `vcs.ref.head.revision`
+   * (#3061). Default: `git rev-parse HEAD` in the project, or nothing outside
+   * a checkout. `null` passes none.
+   */
+  revision?: string | null;
 }
 
 /** Result of `chant run --components <name|all>`. */
@@ -571,11 +586,19 @@ export async function runComponents(
   const { onProgress } = options;
 
   const gates = options.gates;
+  // #3061: the commit this run deploys, for the workloads' vcs.ref.head.revision. The digest comes
+  // from the run's own publish step. Best effort: outside a git checkout nothing is passed.
+  const revision =
+    options.revision !== undefined
+      ? options.revision ?? undefined
+      : await getHeadCommit({ cwd: existsSync(path) && statSync(path).isDirectory() ? path : dirname(path) }).catch(() => undefined);
+  const releaseIdentity = () => (revision ? { revision } : {});
 
   try {
     if (selector === "all") {
       const run = await runInterpretDriver(resolvedTargets, registry, {
         env,
+        releaseIdentity,
         componentOutputs: seedOutputs,
         onProgress,
         ...(gates ? { gates } : {}),
@@ -618,7 +641,7 @@ export async function runComponents(
     onProgress?.({ type: "component-start", wave: 1, component: componentName });
     const componentResult = await runComponentDeploy(
       resolvedTargets[0],
-      { env, component: componentName },
+      deployContext({ env, releaseIdentity }, componentName),
       registry,
       componentOutputs,
       onProgress,

package/src/components/component.schema.json

@@ -60,6 +60,23 @@
       "description": "Optional: the composite kind name(s) this component's deployed resources come from, when a consumer cannot infer it from `name` (#1492). Without this, a consumer joining a composite graph to the component DAG guesses by kebab-casing each composite's kind and matching it against this component's `name`, which only holds when a component maps 1:1 to a composite named for it. Omitted entirely (the default), the naming convention stays in effect with no behavior change. A component built from several composites may list them all.",
       "items": { "type": "string", "minLength": 1 },
       "minItems": 1
+    },
+    "environments": {
+      "type": "array",
+      "description": "Optional: where a release of this component goes, by environment (#3153). Each names an environment --env takes and, for it, the runtime that hosts the release, the URL it answers on, a custom domain attached to it, and the git remote its lifecycle records are pushed to. chant workspace graph --composites lists them first among the component's environments, with source component. Omitted, the component's environments are its member's.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$", "description": "The environment's name, as --env takes it." },
+          "runtime": { "type": "string", "minLength": 1, "description": "The runtime that hosts a release here, such as local or fly." },
+          "url": { "type": "string", "pattern": "^https?://", "description": "Where the released component answers." },
+          "domain": { "type": "string", "minLength": 1, "description": "A custom domain the release attaches to it." },
+          "lifecycle": { "type": "string", "minLength": 1, "description": "The git remote this environment's approvals, effect receipts and ledger records are pushed to." }
+        }
+      }
     }
   },
   "$defs": {

package/src/components/component.ts

@@ -183,6 +183,31 @@ export interface Component {
    * default and nothing changes.
    */
   composites?: string[];
+  /**
+   * Optional: where a release of this component goes, by environment
+   * (#3153, ws-095). Each names an environment `--env` takes and, for that
+   * environment, the runtime that hosts the release, the URL its health
+   * answers on, a custom domain attached to it, and the git remote its
+   * approvals, effect receipts and ledger records are pushed to. `chant
+   * workspace graph --composites` lists them first among the component's
+   * environments, with source `component`. Omitted, the component's
+   * environments are its member's, as before.
+   */
+  environments?: ComponentEnvironmentDeclaration[];
+}
+
+/** One environment a component declares it deploys to (#3153). */
+export interface ComponentEnvironmentDeclaration {
+  /** The environment's name, as `--env` takes it. */
+  name: string;
+  /** The runtime that hosts a release here, such as `local` or a lexicon's runtime (`fly`). */
+  runtime?: string;
+  /** Where the released component answers, such as its health endpoint's origin. */
+  url?: string;
+  /** A custom domain the release attaches to it. */
+  domain?: string;
+  /** The git remote this environment's approvals, effect receipts and ledger records are pushed to. */
+  lifecycle?: string;
 }
 
 /** Author a named phase. `steps` may mix capability `Step`s, `Gate`s, and nested `Phase`s (fan-out). */

package/src/components/deploy-units.ts

@@ -56,6 +56,9 @@ export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
   { kind: "argo-app", field: "stack", lexicon: "k8s" },
   { kind: "flux-reconcile", field: "stack", lexicon: "k8s" },
   { kind: "helm-upgrade", field: "release", lexicon: "helm" },
+  // A Terraform-family root (#3049). Its unit is the root's name in
+  // `terraform.roots`, which is also the member a gated wave's digest names.
+  { kind: "terraform-apply", field: "root", lexicon: "terraform" },
 ];
 
 /** One resolved unit a component's deploy composition targets. */

package/src/components/driver.test.ts

@@ -1069,3 +1069,55 @@ describe("capabilities are consumed exactly as the registry provides them", () =
     expect(failed?.error).toMatch(/capability "some-future-verb" is not implemented/);
   });
 });
+
+describe("the release a deploy step sees (#3061, ws-081)", () => {
+  function setup() {
+    const registry = new CapabilityRegistry();
+    registry.register(fakeCapability("publish-image", { run: () => ({ uri: "ghcr.io/acme/api@sha256:abc", digest: "sha256:abc" }) }).capability);
+    registry.register(fakeCapability("generate-sbom", { run: () => ({ digest: "sha256:sbom" }) }).capability);
+    const deploy = fakeCapability("deploy");
+    registry.register(deploy.capability);
+    return { registry, deploy };
+  }
+
+  it("carries the caller's revision and the digest a publish step promoted, not an SBOM's", async () => {
+    const { registry, deploy } = setup();
+    const api: DriverComponent = {
+      name: "api",
+      dependsOn: [],
+      deploy: [
+        { phase: "Publish", steps: [{ kind: "publish-image" }, { kind: "generate-sbom" }] },
+        { phase: "Deploy", steps: [{ kind: "deploy" }] },
+      ],
+    };
+    const result = await runInterpretDriver([api], registry, { env: "prod", releaseIdentity: () => ({ revision: "0123abc" }) });
+    expect(result.ok).toBe(true);
+    expect(deploy.calls[0]!.ctx.release).toEqual({ revision: "0123abc", version: "sha256:abc" });
+  });
+
+  it("keeps each component's release its own, and passes none without releaseIdentity", async () => {
+    const { registry, deploy } = setup();
+    const api: DriverComponent = { name: "api", dependsOn: [], deploy: [{ phase: "P", steps: [{ kind: "publish-image" }, { kind: "deploy" }] }] };
+    const worker: DriverComponent = { name: "worker", dependsOn: ["api"], deploy: [{ phase: "D", steps: [{ kind: "deploy" }] }] };
+    await runInterpretDriver([api, worker], registry, { env: "prod", releaseIdentity: () => ({ revision: "r1" }) });
+    expect(deploy.calls.map((c) => [c.ctx.component, c.ctx.release])).toEqual([
+      ["api", { revision: "r1", version: "sha256:abc" }],
+      ["worker", { revision: "r1" }],
+    ]);
+    const plain = setup();
+    await runInterpretDriver([{ ...worker, dependsOn: [] }], plain.registry, { env: "prod" });
+    expect(plain.deploy.calls[0]!.ctx.release).toBeUndefined();
+  });
+
+  it("a promote's recorded digest is the version when no step publishes one", async () => {
+    const { registry, deploy } = setup();
+    const api: DriverComponent = { name: "api", dependsOn: [], deploy: [{ phase: "D", steps: [{ kind: "deploy" }] }] };
+    await runInterpretDriver([api], registry, {
+      env: "prod",
+      gates: memoryGateLedgerPort(),
+      releases: new Map([["api", "sha256:recorded"]]),
+      releaseIdentity: () => ({ revision: "r0" }),
+    });
+    expect(deploy.calls[0]!.ctx.release).toEqual({ revision: "r0", version: "sha256:recorded" });
+  });
+});

package/src/components/driver.ts

@@ -47,11 +47,14 @@
  */
 
 import { topoSort } from "../codegen/topo-sort";
+import { kahnLayers } from "./layers";
 import { evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedgerPort } from "../op/gate";
 import { gateName } from "../op/gate-name";
 import { componentPlanDigest } from "./gate-plan";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import type { CapabilityRegistry, DeployContext } from "./capability";
+import { isPromotedArtifact } from "./auto-release";
+import type { ReleaseIdentity } from "../telemetry-attribution";
 import type { RunProgressEvent, RunProgressStatus } from "./run-progress";
 
 export type { RunProgressEvent } from "./run-progress";
@@ -237,18 +240,9 @@ export function resolveComponentGraph(components: DriverComponent[]): ComponentG
   const deps = new Map<string, Set<string>>();
   for (const c of components) deps.set(c.name, new Set(c.dependsOn ?? []));
 
-  const remaining = new Set(deps.keys());
-  const waves: string[][] = [];
-  while (remaining.size > 0) {
-    const wave = [...remaining]
-      .filter((n) => [...deps.get(n)!].every((d) => !remaining.has(d)))
-      .sort();
-    if (wave.length === 0) {
-      throw new DependencyCycleError([...remaining].sort());
-    }
-    for (const n of wave) remaining.delete(n);
-    waves.push(wave);
-  }
+  const layered = kahnLayers(deps);
+  if (layered.cycle) throw new DependencyCycleError(layered.cycle);
+  const waves = layered.waves;
 
   const order = topoSort(
     components,
@@ -566,6 +560,11 @@ async function runPhase(
     });
     if (record.status === "ok") {
       phaseOutputs[phaseDef.phase] = { ...(phaseOutputs[phaseDef.phase] ?? {}), ...(output as object) };
+      // The release's service.version is the digest a later deploy step stamps (#3061): the
+      // last artifact this component promoted, the same one auto-release records.
+      if (ctx.release && isPromotedArtifact(output) && typeof output.digest === "string" && output.digest !== "") {
+        ctx.release.version = output.digest;
+      }
     }
     return {
       records: [record],
@@ -715,11 +714,15 @@ export async function runComponentDeploy(
   onProgress?: (event: RunProgressEvent) => void,
   gateContext: GateContext = { port: gitGateLedgerPort() },
 ): Promise<DriverComponentResult> {
+  // Each component tracks its own release: a digest one component promoted never stamps another's deploy.
+  if (ctx.release) ctx = { ...ctx, release: { ...ctx.release } };
   const phaseOutputs: Record<string, Record<string, unknown>> = {};
   // #2574: every gate this component reaches binds its approval to this
   // environment and this composition, so an approval for staging or for last
   // week's deploy cannot pass it.
   const release = gateContext.releases?.get(component.name);
+  // A promote or rollback deploys a recorded digest without publishing one (#2574); that digest is the release's version.
+  if (ctx.release && release !== undefined && ctx.release.version === undefined) ctx.release.version = release;
   const gates: GateContext = {
     ...gateContext,
     planDigest: componentPlanDigest({
@@ -909,6 +912,12 @@ export interface InterpretRunOptions {
   now?: string;
   /** The recorded digest a promote or rollback deploys, per component (#2574). Part of the plan a gate approval is bound to. */
   releases?: ReadonlyMap<string, string>;
+  /**
+   * The release each component deploys (#3061, ws-081), threaded into its
+   * `DeployContext.release`. The driver fills in `version` when a publish
+   * step promotes an artifact. Absent: no deploy step sees a release.
+   */
+  releaseIdentity?: (component: string) => ReleaseIdentity | undefined;
 }
 
 /**
@@ -930,6 +939,15 @@ export interface InterpretRunOptions {
  * purely on the generic `Component`/`Phase`/`Step` shapes and the registry —
  * no branch anywhere names a specific component or capability.
  */
+/** A component's `DeployContext` for a run: its env, vars and, when the caller knows it, its release. */
+export function deployContext(
+  options: { env: string; vars?: Record<string, unknown>; releaseIdentity?: (component: string) => ReleaseIdentity | undefined },
+  component: string,
+): DeployContext {
+  const release = options.releaseIdentity?.(component);
+  return { env: options.env, component, ...(options.vars ? { vars: options.vars } : {}), ...(release ? { release: { ...release } } : {}) };
+}
+
 export async function runInterpretDriver(
   components: DriverComponent[],
   registry: CapabilityRegistry,
@@ -960,7 +978,7 @@ export async function runInterpretDriver(
         onProgress?.({ type: "component-start", wave: waveNum, component: component.name });
         const result = await runComponentDeploy(
           component,
-          { env: options.env, component: component.name, vars: options.vars },
+          deployContext(options, component.name),
           registry,
           componentOutputs,
           onProgress,

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

@@ -31,6 +31,7 @@
 
 import type { FanOutPlan, FanOutSkip } from "./fan-out";
 import type { FanOutRunResult } from "./fan-out-run";
+import { waveGateName, type WaveRecord } from "../gated-waves";
 
 type Writer = (line: string) => void;
 
@@ -47,6 +48,12 @@ export interface FanOutRenderOptions {
   write?: Writer;
   /** Present when a gate covers the set, so the render can print the exact approve line. */
   gate?: FanOutGateRef;
+  /**
+   * Present when each wave has its own gate (#3049). A wave's digest is known
+   * only once it is planned, so a plan-only render names each wave's gate and
+   * no digest.
+   */
+  waveGate?: FanOutGateRef;
 }
 
 /** `unaffected` → `unaffected`; `blocked` also names the failure it was reached from. */
@@ -85,7 +92,8 @@ export function renderFanOutPlan(plan: FanOutPlan, options: FanOutRenderOptions
     write("  nothing to run");
   } else {
     for (const [index, wave] of plan.waves.entries()) {
-      write(`  wave ${index + 1}: ${wave.join(", ")}`);
+      const gated = options.waveGate ? `  (gate ${waveGateName(options.waveGate.gate, index + 1)})` : "";
+      write(`  wave ${index + 1}: ${wave.join(", ")}${gated}`);
     }
   }
 
@@ -117,6 +125,28 @@ export function renderFanOutPlan(plan: FanOutPlan, options: FanOutRenderOptions
   if (options.gate) {
     write(`  approve: chant approve ${options.gate.op} ${options.gate.gate} --plan ${plan.digest}`);
   }
+  if (options.waveGate) {
+    write(`  each wave is planned when it is reached, and its gate binds that wave's set digest`);
+  }
+}
+
+/** One line per wave a gated-wave run reached (#3049): its digest, members and where it got to. */
+function renderWaves(waves: readonly WaveRecord[], write: Writer): void {
+  for (const wave of waves) {
+    const state =
+      wave.status === "applied"
+        ? `applied, approved by ${wave.approvedBy ?? "unknown"}`
+        : wave.status === "gated"
+          ? wave.approved
+            ? "stopped: the set changed after it was approved"
+            : "waiting for approval"
+          : "failed";
+    write(`wave ${wave.wave} (${wave.gate}): ${state}`);
+    if (wave.digest) write(`  set digest: ${wave.digest}`);
+    for (const member of wave.members) write(`    ${member.member}  ${member.planDigest}`);
+    if (wave.approved) write(`  approved digest: ${wave.approved}`);
+    for (const f of wave.failed ?? []) write(`  ${f.component} failed${f.error ? `: ${f.error}` : ""}`);
+  }
 }
 
 /**
@@ -130,6 +160,17 @@ export function renderFanOutPlan(plan: FanOutPlan, options: FanOutRenderOptions
 export function renderFanOutHuman(result: FanOutRunResult, options: FanOutRenderOptions = {}): void {
   const write = options.write ?? stderr;
   renderFanOutPlan(result.plan, { ...options, write });
+  if (result.waves) renderWaves(result.waves, write);
+
+  if (result.status === "gated" && result.waves) {
+    const at = result.waves[result.waves.length - 1];
+    write(
+      `gated at wave ${at?.wave ?? "?"}: ${result.completed.length} applied before it, ` +
+        `nothing in it or after it ran.`,
+    );
+    if (result.gate?.expiresAt) write(`  expires: ${result.gate.expiresAt}`);
+    return;
+  }
 
   if (result.status === "gated") {
     const gate = result.gate;

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

@@ -0,0 +1,69 @@
+/**
+ * The fan-out attempt record (`--resume`, #2420, #2417, #3049): what an
+ * attempt left behind and what the next one reads.
+ *
+ * It lives here rather than in the CLI handler so a caller that runs a wave
+ * per CI job (#3183) reads and writes the same file without importing the
+ * command.
+ *
+ * The digest is stored alongside the progress because progress is only
+ * meaningful for the plan it was made against. A fan-out derived from different
+ * source is a different fan-out, and carrying "cluster-a already applied" into
+ * it would be a claim about work nobody did.
+ *
+ * `outputs` holds what each completed component exposed. A component left to
+ * run may read one of them through `stackOutput()`, and without the record the
+ * re-run would resolve that reference to nothing unless somebody supplied the
+ * value by hand with `--seed-outputs`.
+ *
+ * `waves`, for a gated-wave fan-out, holds one entry per wave reached: its set
+ * digest, its members, its gate and where it got to. A resumed attempt plans
+ * a wave afresh rather than trusting this, since the point of the gate is the
+ * plan now. The entries are for whoever reads the record, the plan report
+ * (#3349) among them.
+ */
+
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readWaveRecords, type WaveRecord } from "../gated-waves";
+
+export interface FanOutAttempt {
+  digest: string;
+  completed: string[];
+  failed: string[];
+  outputs: Record<string, Record<string, unknown>>;
+  /** Gated-wave fan-outs only (#3049). */
+  waves?: WaveRecord[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Read an attempt record, or `undefined` when there is none yet. Throws on a file that is not JSON. */
+export function readFanOutAttempt(path: string): FanOutAttempt | undefined {
+  if (!existsSync(path)) return undefined;
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<FanOutAttempt>;
+  const outputs: Record<string, Record<string, unknown>> = {};
+  if (isRecord(parsed.outputs)) {
+    for (const [name, value] of Object.entries(parsed.outputs)) if (isRecord(value)) outputs[name] = value;
+  }
+  const waves = readWaveRecords(parsed.waves);
+  return {
+    digest: typeof parsed.digest === "string" ? parsed.digest : "",
+    completed: Array.isArray(parsed.completed) ? parsed.completed.filter((n): n is string => typeof n === "string") : [],
+    failed: Array.isArray(parsed.failed) ? parsed.failed.filter((n): n is string => typeof n === "string") : [],
+    outputs,
+    ...(waves.length > 0 ? { waves } : {}),
+  };
+}
+
+/**
+ * Written through a temporary file and a rename, so a process killed during the
+ * write leaves the previous record whole rather than half a JSON document.
+ */
+export function writeFanOutAttempt(path: string, attempt: FanOutAttempt): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporary, JSON.stringify(attempt, null, 2) + "\n");
+  renameSync(temporary, path);
+}

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

@@ -116,6 +116,23 @@ describe("resuming", () => {
     expect(ran.sort()).toEqual(["app-one", "app-two", "cluster-a"]);
     expect(second.plan.skipped).toContainEqual({ component: "net", reason: "already-applied" });
   });
+
+  test("each component is reported as it settles, so progress survives a run that never returns", async () => {
+    const plan = planFanOut({ components: ESTATE, changed: ["net"] });
+    const settled: string[] = [];
+    const { registry, ran } = registryWith(["cluster-a"]);
+    const result = await runFanOut(plan, ESTATE, registry, {
+      ...opts(),
+      onComponentSettled: (r) => {
+        settled.push(`${r.component}:${r.status}`);
+        // Every report lands before any later wave starts.
+        if (r.component === "net") expect(ran).toEqual(["net"]);
+      },
+    });
+
+    expect(result.status).toBe("fail");
+    expect(settled.sort()).toEqual(["app-three:ok", "cluster-a:fail", "cluster-b:ok", "net:ok"]);
+  });
 });
 
 describe("one approval over the whole set", () => {