@intentius/chant 0.124.31 → 0.124.32

package/src/pr-loop.test.ts

@@ -14,7 +14,10 @@ import {
   describePlanChanged,
   memberCounts,
   PR_REPORT_DEPLOYED_OUTPUTS_FLOOR,
+  PR_REPORT_PLANNED_OUTPUTS_FLOOR,
+  prRoundGate,
   PR_REPORT_SCHEMA_ID,
+  PR_REPORT_WAVES_FLOOR,
   prApproveCommand,
   prNoteMarker,
   PR_GATE_OP,
@@ -113,6 +116,34 @@ const resumedReport: PrReport = {
 /** A plan whose members read `net` and `a` from the deployed estate (#4104). */
 const deployedReport: PrReport = { ...planReport, deployedOutputs: { a: ["id"], net: ["cidr"], dns: [] } };
 
+/** A plan where `app` reads `a.id`, which `a`'s plan knows only after apply, and `a.arn`, which it knows (#3999). */
+const unknownReport: PrReport = {
+  ...planReport,
+  deployedOutputs: { net: ["cidr"] },
+  plannedOutputs: { a: ["arn"] },
+  members: [planReport.members[0]!, { ...planReport.members[1]!, unknownInputs: ["a.id"], buildInputs: ["img.publish.digest"] }],
+};
+
+const roundDoc = composeChangeSet([part("app", 3, [{ address: "terraform_data.app", action: "update" }])]);
+/** The apply of {@link unknownReport}: `a` applied, and `app`, planned again, waits on round 2's gate (#3999). */
+const waitingReport: PrReport = {
+  ...unknownReport,
+  stage: "apply",
+  status: "waiting",
+  approval: { status: "approved", approvedBy: ["github:alice"] },
+  rounds: [{ round: 2, gate: prRoundGate("pr-apply", 2), digest: roundDoc.digest, components: ["app"], approval: { status: "pending" }, status: "waiting", changeSet: roundDoc }],
+  members: [
+    { ...planReport.members[0]!, status: "applied" },
+    {
+      ...unknownReport.members[1]!,
+      status: "waiting",
+      round: 2,
+      planDigest: `jcs1-sha256:${hex(3)}`,
+      held: "its plan read a.id before that output applied as another value",
+    },
+  ],
+};
+
 describe("the pr-report schema", () => {
   test("is a valid schema and names this module's id", () => {
     expect(validSchema(schema)).toBe(true);
@@ -120,7 +151,7 @@ describe("the pr-report schema", () => {
   });
 
   test("every stage's report validates, and its change set validates against the change-set schema", () => {
-    for (const report of [planReport, refusedReport, appliedReport, resumedReport, deployedReport]) {
+    for (const report of [planReport, refusedReport, appliedReport, resumedReport, deployedReport, unknownReport, waitingReport]) {
       expectValid(report);
       expectValidChangeSet(report.changeSet);
       expect(report.changeSet.digest).toBe(report.digest);
@@ -170,6 +201,27 @@ describe("the note", () => {
     expect(schema.required).not.toContain("deployedOutputs");
   });
 
+  test("a plan names the outputs read from upstream plans and the ones known only after apply (#3999)", () => {
+    const note = renderPrNote(unknownReport);
+    expect(note).toContain("Planned against the outputs this change's plans say its upstreams will have: `a` (`arn`).");
+    expect(note).toContain("Known only after apply: `app` reads `a.id`. This approval does not cover what those members do with them.");
+    expect(renderPrNote(planReport)).not.toContain("Known only after apply");
+    expect(note).toContain("From this pull request's build: `app` reads `img.publish.digest`. The image digest comes from this pull request's build");
+    expect(renderPrNote(planReport)).not.toContain("From this pull request's build");
+    expect(PR_REPORT_PLANNED_OUTPUTS_FLOOR).toBe("0.124.32");
+    expect(schema.required).not.toContain("plannedOutputs");
+  });
+
+  test("a waiting apply names the round's digest and the command that approves it (#3999)", () => {
+    const note = renderPrNote(waitingReport, { approver: "github:<your-login>" });
+    expect(note).toContain("Applied 1 of 2 members; 1 wait on an approval of the plan made after their upstream applied.");
+    expect(note).toContain(`chant approve pr-12 pr-apply-round-2 --plan ${roundDoc.digest} --approver github:<your-login> --sign`);
+    expect(note).toContain("| `app` | app | waiting on its new plan |");
+    expect(prStatusState(waitingReport)).toBe("pending");
+    expect(prStatusDescription(waitingReport)).toBe("waiting: app planned again after an upstream applied, not approved yet");
+    expect(prRoundGate("pr-apply", 1)).toBe("pr-apply");
+  });
+
   test("a small limit leaves the summary out rather than cutting the table", () => {
     const note = renderPrNote(planReport, { limit: 800 });
     expect(note).toContain("| `app` |");
@@ -181,6 +233,7 @@ describe("the status", () => {
   test("describes each stage in at most 140 characters", () => {
     expect(prStatusDescription(planReport)).toMatch(/^2 members: 1 to change, 0 to destroy or replace; plan [0-9a-f]{12}$/);
     expect(prStatusDescription(refusedReport)).toBe("refused: the plan changed after review");
+    expect(prStatusDescription({ ...refusedReport, refusal: "author-approved" })).toBe("refused: the approver wrote the change");
     expect(prStatusDescription(appliedReport)).toMatch(/^applied 2 members/);
     for (const r of [planReport, refusedReport, appliedReport]) expect(prStatusDescription(r).length).toBeLessThanOrEqual(140);
   });
@@ -221,3 +274,66 @@ describe("a workspace member's loop (#3465)", () => {
     expect(note).toContain("chant approve pr-12-network pr-apply");
   });
 });
+
+describe("a gate per wave on merge (#4003)", () => {
+  const waveDigest = `jcs1-sha256:${hex(7)}`;
+  const wave1 = { wave: 1, components: ["a"], status: "applied" as const, approval: "pull-request" as const, gate: "pr-apply", digest: doc.digest, approvedBy: ["github:alice"] };
+  const waveApplied: PrReport = {
+    ...appliedReport,
+    status: "wave-applied",
+    waveGate: "release",
+    waves: [wave1],
+    members: [{ ...planReport.members[0], status: "applied" }, planReport.members[1]],
+  };
+  const waiting: PrReport = {
+    ...waveApplied,
+    status: "refused",
+    refusal: "wave-not-approved",
+    message: "Wave 2 was planned after the waves before it applied, and the pull request's approved plan does not cover it.",
+    waves: [
+      wave1,
+      { wave: 2, components: ["app"], status: "waiting", approval: "wave", gate: "release-wave-2", digest: waveDigest, moved: ["app now writes app.main.cidr to a different value than the approved plan"] },
+    ],
+  };
+
+  test("the reports validate, waveGate and waves are optional, and both came with the same chant", () => {
+    for (const r of [waveApplied, waiting]) expectValid(r);
+    expect(schema.required).not.toContain("waves");
+    expect(schema.required).not.toContain("waveGate");
+    expect(PR_REPORT_WAVES_FLOOR).toBe("0.124.32");
+  });
+
+  test("the note has a row per wave saying whose approval it applied under", () => {
+    const note = renderPrNote(waveApplied);
+    expect(note).toContain("Applied wave 1 of 2. The next wave runs in its own job.");
+    expect(note).toContain("| 1 | `a` | applied | the pull request's `pr-apply` by `github:alice` |");
+  });
+
+  test("a wave that waits names why its plan moved and the approve command for its own gate", () => {
+    const note = renderPrNote(waiting, { approver: "github:<your-login>" });
+    expect(note).toContain("Wave 2 waits at its gate `release-wave-2`; nothing in it applied.");
+    expect(note).toContain("| 2 | `app` | waiting | its own `release-wave-2`, not approved yet |");
+    expect(note).toContain("- app now writes app.main.cidr to a different value than the approved plan");
+    expect(note).toContain(`chant approve pr-12 release-wave-2 --plan ${waveDigest} --approver github:<your-login> --sign`);
+    golden("pr-apply-wave-waiting.note.golden.md", note);
+  });
+
+  test("with --wave-gate the plan's note says later waves are planned again and may stop at their own gate; without it, nothing", () => {
+    const sentence = "On merge each wave after the first is planned again once the waves before it apply, and a wave whose plan moved stops at its own gate, `release-wave-<k>`, for approval.";
+    const planned = renderPrNote({ ...planReport, waveGate: "release" });
+    expect(planned).toContain(sentence);
+    expect(renderPrNote({ ...planReport, waveGate: "release", approval: { status: "approved", approvedBy: ["github:alice"] } })).toContain(sentence);
+    expect(renderPrNote(planReport)).not.toContain("planned again");
+    expect(renderPrNote(waveApplied)).not.toContain("planned again");
+    expectValid({ ...planReport, waveGate: "release" });
+  });
+
+  test("the status: a wave applied succeeds, a wave waiting on its approval is pending, a moved approval fails", () => {
+    expect(prStatusDescription(waveApplied)).toBe("applied wave 1 of 2 under the pull request's approval");
+    expect(prStatusState(waveApplied)).toBe("success");
+    expect(prStatusDescription(waiting)).toBe("wave 2 waits at release-wave-2: its plan moved, approve it");
+    expect(prStatusState(waiting)).toBe("pending");
+    expect(prStatusState({ ...waiting, refusal: "wave-plan-changed" })).toBe("failure");
+    expect(prStatusDescription({ ...waiting, waves: [wave1], refusal: "earlier-wave" })).toBe("refused: an earlier wave has not applied");
+  });
+});

package/src/pr-loop.ts

@@ -28,6 +28,16 @@
  * and decides the gate against the new digest. The same plan applies; a moved
  * plan stops with both digests named and nothing applied.
  *
+ * ## A gate per wave on merge
+ *
+ * With `--wave-gate <gate>` (#4003) the apply runs a wave at a time, and
+ * plans each wave after the one before it applied. Wave 1 applies under the
+ * pull request's approval. A later wave whose new plan the approved change
+ * set covers (`planCoveredBy`) applies under that approval too; one whose
+ * plan moved waits at `<gate>-wave-<k>`, under the same op, for an approval
+ * of its new plan. The report's `waves` says which wave applied under which
+ * approval.
+ *
  * ## Inside a workspace member
  *
  * Each workspace member that generates the pipeline (#3465) runs its own
@@ -49,6 +59,15 @@ export const PR_REPORT_CONTRACT = 1;
 /** The first chant whose report can carry `deployedOutputs` (#4104). */
 export const PR_REPORT_DEPLOYED_OUTPUTS_FLOOR = "0.124.30";
 
+/** The first chant whose report can carry `waveGate` and `waves` (#4003). */
+export const PR_REPORT_WAVES_FLOOR = "0.124.32";
+/**
+ * The first chant whose report can carry `plannedOutputs`, `rounds`, a
+ * member's `unknownInputs`, `buildInputs`, `round` and `held`, and the `waiting` statuses
+ * (#3999).
+ */
+export const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -60,6 +79,16 @@ export function prOp(pr: number, member?: string): string {
   return member ? `pr-${pr}-${member}` : `pr-${pr}`;
 }
 
+/**
+ * The gate a round of an apply waits on (#3999): the pull request's own
+ * gate for the first, and `<gate>-round-<n>` for each one planned after an
+ * upstream applied. A workspace's `identity.gates` entry for `gate` covers
+ * every round.
+ */
+export function prRoundGate(gate: string, round: number): string {
+  return round <= 1 ? gate : `${gate}-round-${round}`;
+}
+
 /** Whether `op` is a pull request's gate op, with or without a member. Member names follow the declaration's name pattern. */
 export const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
 
@@ -95,7 +124,13 @@ export type PrMemberStatus =
   /** The apply failed. */
   | "failed"
   /** Not applied because a member it depends on failed. */
-  | "blocked";
+  | "blocked"
+  /**
+   * Apply stage (#3999): held back because its plan read an upstream output
+   * that applied as another value, or was known only after apply. It waits
+   * on an approval of the plan the apply made for it afterwards (`rounds`).
+   */
+  | "waiting";
 
 export interface PrMember {
   /** The member's name in the change set: a root, for a terraform-family step. */
@@ -110,9 +145,48 @@ export interface PrMember {
   /**
    * Components this one depends on whose outputs changed when they applied
    * (apply stage). Its applied plan read the values from before, so the next
-   * run plans it again.
+   * run plans it again. Not written since #3999, which holds such a member
+   * back and plans it again in the same apply (`held`, `round`).
    */
   inputsMoved?: string[];
+  /**
+   * The upstream outputs its plan read that the change's plans could not
+   * say (#3999), as `<component>.<output>`, sorted: known only after that
+   * upstream applies. The approval does not cover what this member does
+   * with them; the apply plans it again once they are known.
+   */
+  unknownInputs?: string[];
+  /**
+   * The published artifact identities its plan read from a build in the
+   * same change (#3999), as `<component>.publish.<field>`, sorted: an image
+   * digest, say. Known only after the build runs, but never approved again:
+   * the build's provenance and attestation bind the digest, so the member
+   * applies without a later round.
+   */
+  buildInputs?: string[];
+  /** Apply stage (#3999): the round whose plan it applied or waits on, when not the first. */
+  round?: number;
+  /** Apply stage (#3999): why the first round's plan did not apply. */
+  held?: string;
+}
+
+/** A round of plans an apply made after an upstream applied (#3999), the report's `rounds`. */
+export interface PrRound {
+  /** 2 for the first plan made after an upstream applied, and on. */
+  round: number;
+  /** The gate it waits on: {@link prRoundGate}. */
+  gate: string;
+  /** The change-set digest of what the round planned. What its gate binds. */
+  digest: string;
+  /** The components planned again, in apply order. */
+  components: string[];
+  approval: PrApproval;
+  /** `waiting`: no approval stands for `digest`. `plan-failed`: a member failed to plan, so the round did not apply. */
+  status: "applied" | "failed" | "waiting" | "plan-failed";
+  /** With `waiting`: why an approval that stands does not count (`--require-review`). */
+  message?: string;
+  /** The change-set document the round planned. */
+  changeSet: ChangeSetDocument;
 }
 
 /** Where the approval stands for the planned digest. */
@@ -141,8 +215,19 @@ export type PrStatus =
   | "applied"
   /** Apply stage: a member failed to apply. Its dependents did not run. */
   | "failed"
+  /**
+   * Apply stage with `--wave-gate` and `--wave` (#4003): this wave applied,
+   * and a later wave of the change is still to run.
+   */
+  | "wave-applied"
   /** Apply stage: nothing applied, see `refusal`. */
-  | "refused";
+  | "refused"
+  /**
+   * Apply stage (#3999): the approved plans applied, except members held
+   * back after an upstream applied. They wait on the approval of the plan
+   * the last of `rounds` made.
+   */
+  | "waiting";
 
 /** Why an apply refused. */
 export type PrRefusal =
@@ -152,8 +237,45 @@ export type PrRefusal =
   | "plan-changed"
   /** The approval names someone who has not approved the pull request on the forge. */
   | "not-a-reviewer"
+  /** The approval names the pull request's author, or an author or committer of one of its commits (#4000). */
+  | "author-approved"
   /** No pull request merged this commit, so there is no approval to read. */
-  | "no-pull-request";
+  | "no-pull-request"
+  /** `--wave-gate` (#4003): the wave's new plan is not one the pull request approved, and no approval stands for it. */
+  | "wave-not-approved"
+  /** `--wave-gate`: an approval of the wave's gate stands for another digest, so its plan moved since. */
+  | "wave-plan-changed"
+  /** `--wave-gate` with `--wave <k>`: an earlier wave has work left, or no record says it applied. */
+  | "earlier-wave";
+
+/**
+ * One wave of an apply with `--wave-gate` (#4003): what it planned, where it
+ * got to, and which approval it applied or waits under.
+ */
+export interface PrWave {
+  /** 1-based, from the derivation (`selection.waves`). */
+  wave: number;
+  /** The components planned in it on the run that reached it. */
+  components: string[];
+  /** `applied`; `failed` or `plan-failed`; or `waiting` at its gate. */
+  status: "applied" | "failed" | "plan-failed" | "waiting";
+  /**
+   * `pull-request`: the approved change set covers the wave's plan, so it
+   * applies under the pull request's approval. `wave`: its plan moved, so it
+   * needs an approval of its own gate.
+   */
+  approval: "pull-request" | "wave";
+  /** The gate it applied or waits under: the pull request's, or `<wave gate>-wave-<k>`. */
+  gate: string;
+  /** The digest that gate binds: the pull request's change set, or the wave's new plan. */
+  digest: string;
+  /** Who approved that digest. */
+  approvedBy?: string[];
+  /** Waiting: an approval of the wave's gate stands for this other digest. */
+  approved?: string;
+  /** Why the approved change set does not cover the wave's plan, one line per member. */
+  moved?: string[];
+}
 
 /**
  * The document `pr-plan` and `pr-apply` write (`pr-report.schema.json`).
@@ -194,7 +316,28 @@ export interface PrReport {
    * {@link PR_REPORT_DEPLOYED_OUTPUTS_FLOOR}.
    */
   deployedOutputs?: Record<string, string[]>;
+  /**
+   * Per dependency in the change that a member was planned against (#3999),
+   * the names of the outputs its plan knows, sorted. An output it reads that
+   * is not here is known only after apply (a member's `unknownInputs`).
+   * Absent when no member read one. Added within contract 1 by chant
+   * {@link PR_REPORT_PLANNED_OUTPUTS_FLOOR}.
+   */
+  plannedOutputs?: Record<string, string[]>;
+  /**
+   * Apply stage (#3999): the rounds planned after an upstream applied, in
+   * order, each with its own gate and digest. Absent when nothing was held.
+   */
+  rounds?: PrRound[];
   approval: PrApproval;
+  /**
+   * The wave gate's base name with `--wave-gate` (#4003): wave k waits on
+   * `<waveGate>-wave-<k>` when its plan moved. Added within contract 1 by
+   * chant {@link PR_REPORT_WAVES_FLOOR}.
+   */
+  waveGate?: string;
+  /** With `waveGate`: each wave reached so far, in order. */
+  waves?: PrWave[];
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
     changed: string[];
@@ -252,6 +395,7 @@ const STATUS_WORDS: Record<PrMemberStatus, string> = {
   applied: "applied",
   failed: "apply failed",
   blocked: "blocked",
+  waiting: "waiting on its new plan",
 };
 
 function headline(report: PrReport): string {
@@ -268,11 +412,55 @@ function headline(report: PrReport): string {
       return `Applied ${members}.`;
     case "failed":
       return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${report.members.filter((m) => m.status === "applied").length} applied.`;
-    case "refused":
-      return "The apply refused.";
+    case "wave-applied": {
+      const applied = (report.waves ?? []).filter((w) => w.status === "applied").map((w) => w.wave);
+      const total = report.selection.waves.length;
+      return `Applied wave ${applied.at(-1) ?? "?"} of ${total}. The next wave runs in its own job.`;
+    }
+    case "refused": {
+      const waiting = report.waves?.find((w) => w.status === "waiting");
+      return waiting ? `Wave ${waiting.wave} waits at its gate ${code(waiting.gate)}; nothing in it applied.` : "The apply refused.";
+    }
+    case "waiting":
+      return `Applied ${report.members.filter((m) => m.status === "applied").length} of ${members}; ${report.members.filter((m) => m.status === "waiting").length} wait on an approval of the plan made after their upstream applied.`;
   }
 }
 
+/** Who a wave applied or waits under, as a table cell. */
+function waveApproval(w: PrWave): string {
+  const whose = w.approval === "pull-request" ? "the pull request's" : "its own";
+  const by = w.approvedBy?.length ? ` by ${w.approvedBy.map(code).join(", ")}` : w.status === "waiting" ? ", not approved yet" : "";
+  return `${whose} ${code(w.gate)}${by}`;
+}
+
+/**
+ * The waves of an apply with `--wave-gate` (#4003): a row per wave reached,
+ * saying which approval it applied under, then for a wave that waits the
+ * reason its plan moved and the approve command for its new plan.
+ */
+function waveLines(report: PrReport, approver: string): string[] {
+  const waves = report.waves ?? [];
+  if (waves.length === 0) return [];
+  const out = ["", "| Wave | Components | Status | Approval |", "|---:|---|---|---|"];
+  for (const w of waves) out.push(`| ${w.wave} | ${w.components.map(code).join(", ")} | ${w.status} | ${waveApproval(w)} |`);
+  for (const w of waves.filter((x) => x.status === "waiting")) {
+    out.push("", `Wave ${w.wave} was planned after the waves before it applied, and the approved plan does not cover it:`, "");
+    for (const why of w.moved ?? []) out.push(`- ${why}`);
+    if (w.approved) out.push("", `An approval of ${code(w.gate)} stands for ${code(w.approved)}, not for the plan now.`);
+    out.push(
+      "",
+      `Read wave ${w.wave}'s plan, ${code(w.digest)}, and approve it with:`,
+      "",
+      "```",
+      prApproveCommand({ op: report.op, gate: w.gate, digest: w.digest }, approver),
+      "```",
+      "",
+      "Then run the wave's apply job again.",
+    );
+  }
+  return out;
+}
+
 function approvalLines(report: PrReport, approver: string): string[] {
   const a = report.approval;
   if (report.status === "nothing") return [];
@@ -332,6 +520,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
       out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
     }
   }
+  out.push(...waveLines(report, options.approver ?? "<you>"));
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }
@@ -340,9 +529,43 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
     const each = deployed.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none yet"})`);
     out.push("", `Planned against outputs read from the deployed estate: ${each.join("; ")}.`);
   }
+  const planned = Object.entries(report.plannedOutputs ?? {});
+  if (planned.length > 0) {
+    const each = planned.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none known"})`);
+    out.push("", `Planned against the outputs this change's plans say its upstreams will have: ${each.join("; ")}.`);
+  }
+  const unknown = [...new Set(report.members.flatMap((m) => (m.unknownInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+  if (unknown.length > 0) {
+    out.push(
+      "",
+      `Known only after apply: ${unknown.join("; ")}. This approval does not cover what those members do with them. ` +
+        "The apply plans them again once their upstream applied and asks for an approval of that plan.",
+    );
+  }
+  const fromBuild = [...new Set(report.members.flatMap((m) => (m.buildInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+  if (fromBuild.length > 0) {
+    out.push(
+      "",
+      `From this pull request's build: ${fromBuild.join("; ")}. The image digest comes from this pull request's build, whose provenance binds it, ` +
+        "so those members apply with it once the build ran, without a second approval.",
+    );
+  }
+  for (const r of report.rounds ?? []) {
+    const what = `Round ${r.round} planned ${r.components.map(code).join(", ")} again after their upstream applied, digest ${code(r.digest)}`;
+    if (r.status === "waiting") {
+      if (r.message) out.push("", `> ${r.message}`);
+      out.push("", `${what}. Not approved yet. Approve it, then run the apply again with the same \`--resume\` record:`, "", "```", prApproveCommand({ op: report.op, gate: r.gate, digest: r.digest }, options.approver ?? "<you>"), "```");
+    } else {
+      out.push("", `${what}: ${r.status === "applied" ? `applied, approved by ${(r.approval.approvedBy ?? []).map(code).join(", ")}` : r.status === "plan-failed" ? "a member failed to plan" : "the apply failed"}.`);
+    }
+  }
   if (report.status !== "nothing") {
     out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
   }
+  // #4003: with a gate per wave, a later wave's plan on merge may differ from this one.
+  if (report.stage === "plan" && report.status === "planned" && report.waveGate) {
+    out.push("", `On merge each wave after the first is planned again once the waves before it apply, and a wave whose plan moved stops at its own gate, ${code(`${report.waveGate}-wave-<k>`)}, for approval.`);
+  }
   const head = out.join("\n") + "\n";
   if (report.status === "nothing" || report.changeSet.members.length === 0) return head;
   const room = limit - [...head].length - 1;
@@ -374,19 +597,38 @@ export function prStatusDescription(report: PrReport): string {
     case "applied":
       text = `applied ${n} member${n === 1 ? "" : "s"}${digest}`;
       break;
+    case "wave-applied": {
+      const last = (report.waves ?? []).filter((w) => w.status === "applied").at(-1);
+      text = `applied wave ${last?.wave ?? "?"} of ${report.selection.waves.length}${last ? ` under ${last.approval === "pull-request" ? "the pull request's approval" : `${last.gate}`}` : ""}`;
+      break;
+    }
     case "failed":
       text = `apply failed for ${report.members.filter((m) => m.status === "failed").map((m) => m.member).join(", ")}`;
       break;
-    case "refused":
-      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+    case "waiting":
+      text = `waiting: ${report.members.filter((m) => m.status === "waiting").map((m) => m.member).join(", ")} planned again after an upstream applied, not approved yet`;
       break;
+    case "refused": {
+      const waiting = report.waves?.find((w) => w.status === "waiting");
+      if (waiting && (report.refusal === "wave-not-approved" || report.refusal === "wave-plan-changed")) {
+        text = `wave ${waiting.wave} waits at ${waiting.gate}: ${report.refusal === "wave-plan-changed" ? "its plan changed after its approval" : "its plan moved, approve it"}`;
+        break;
+      }
+      if (report.refusal === "earlier-wave") {
+        text = "refused: an earlier wave has not applied";
+        break;
+      }
+      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "author-approved" ? "the approver wrote the change" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+      break;
+    }
   }
   return text.length > 140 ? text.slice(0, 137) + "..." : text;
 }
 
 /** The commit status state for a report: success, failure, or pending while it waits on approval. */
 export function prStatusState(report: PrReport): "success" | "failure" | "pending" {
-  if (report.status === "planned" || report.status === "applied" || report.status === "nothing") return "success";
-  if (report.status === "refused" && report.refusal === "not-approved") return "pending";
+  if (report.status === "planned" || report.status === "applied" || report.status === "wave-applied" || report.status === "nothing") return "success";
+  if (report.status === "refused" && (report.refusal === "not-approved" || report.refusal === "wave-not-approved")) return "pending";
+  if (report.status === "waiting") return "pending";
   return "failure";
 }

package/src/pr-report-url.ts

@@ -44,17 +44,17 @@ export type ReportTarget =
   | { scheme: "file"; url: string; dir: string }
   | { scheme: "s3"; url: string; bucket: string; prefix: string };
 
-/** `--report-url` read, or why it can't be. */
-export function parseReportUrl(raw: string): ReportTarget | { error: string } {
+/** `--report-url` read, or why it can't be. `name` is what the error calls the value: the flag, or `ci.reportUrl` (#4160). */
+export function parseReportUrl(raw: string, name = "--report-url"): ReportTarget | { error: string } {
   const url = raw.trim();
   if (url.startsWith("file://")) {
     let dir: string;
     try {
       dir = fileURLToPath(url);
     } catch (err) {
-      return { error: `--report-url ${url}: ${err instanceof Error ? err.message : String(err)}` };
+      return { error: `${name} ${url}: ${err instanceof Error ? err.message : String(err)}` };
     }
-    if (!isAbsolute(dir)) return { error: `--report-url ${url}: a file URL names an absolute directory` };
+    if (!isAbsolute(dir)) return { error: `${name} ${url}: a file URL names an absolute directory` };
     return { scheme: "file", url: url.replace(/\/+$/, ""), dir };
   }
   const s3 = /^s3:\/\/([^/]+)\/?(.*)$/.exec(url);
@@ -62,7 +62,7 @@ export function parseReportUrl(raw: string): ReportTarget | { error: string } {
     const prefix = s3[2]!.replace(/\/+$/, "");
     return { scheme: "s3", url: `s3://${s3[1]}${prefix ? `/${prefix}` : ""}`, bucket: s3[1]!, prefix };
   }
-  return { error: `--report-url ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
+  return { error: `${name} ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
 }
 
 /** The key a stage's files are kept under, below the URL: `<pr>/<commit>[/<member>]`. */

package/src/terraform/__fixtures__/advise.test.ts

@@ -1,5 +1,7 @@
 import { describe, test, expect } from "vitest";
 import { join } from "path";
+import { cpSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
 import {
   carveAdvise,
   carveJson,
@@ -50,10 +52,27 @@ describe("carve advise against the sample estate", () => {
     expect(byAddr["random_pet.suffix"].score).toBe(0);
     expect(byAddr["random_pet.suffix"].band).toBe("leave in Terraform");
 
-    // The report never proposes a mutation.
-    const text = formatCarveReport(r);
+    // The report never proposes a mutation. The estate path is the caller's,
+    // so it is masked before the check (#3169).
+    const text = formatCarveReport(r).split(r.from!).join("<estate>");
     expect(text).not.toMatch(/state rm|apply|destroy/i);
   });
+
+  test("the no-mutation check holds in a checkout whose path says apply or destroy (#3169)", async () => {
+    if (!parserAvailable) return;
+    const parent = mkdtempSync(join(tmpdir(), "carve-native-apply-destroy-"));
+    try {
+      const estate = join(parent, "sample-estate");
+      cpSync(ESTATE, estate, { recursive: true });
+      const r = await carveAdvise({ from: estate });
+      expect(r.ok).toBe(true);
+      const text = formatCarveReport(r);
+      expect(text).toContain(estate);
+      expect(text.split(r.from!).join("<estate>")).not.toMatch(/state rm|apply|destroy/i);
+    } finally {
+      rmSync(parent, { recursive: true, force: true });
+    }
+  });
 });
 
 /**