@intentius/chant 0.124.27 → 0.124.29

package/src/op/run-events.test.ts

@@ -0,0 +1,166 @@
+/**
+ * #4041: the local executor's run-event stream (`chant run <op>
+ * --events-json`). Every line passes the schema; each step's start comes
+ * before its settle under the same step id; and the cases an old
+ * `StepRecord` could not tell apart come out as `gated`, `skip: "receipt"`
+ * and `skip: "not-run"`.
+ */
+
+import { describe, expect, test, vi } from "vitest";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig } from "./types";
+import { OpRunFailure, runOpLocally, type RunOpOptions } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import { receiptActivities, type ReceiptStore } from "./receipt-store";
+import { EffectReceipt, receiptExpectation } from "../effect-receipt";
+import { effect } from "./builders";
+import type { RunEvent } from "../run-event";
+import { checkRunEventLines, stepKey, stepTrail } from "../workspace/__fixtures__/run-event-check";
+
+vi.mock("./gate", async () => {
+  const actual = await vi.importActual<typeof import("./gate")>("./gate");
+  return { ...actual, gateIsSealed: async () => false };
+});
+
+const PROFILES: Record<string, ActivityProfile> = { fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } } };
+const NOW = "2026-10-16T12:00:00.000Z";
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+
+const op = (partial: Partial<OpConfig>): OpConfig => ({ name: "deploy-api", overview: "", phases: [], ...partial });
+const ok: ActivityFn = async () => ({ done: true });
+
+/** Run an Op with its events captured, settling whether it resolves or rejects. */
+async function run(config: OpConfig, activities: Map<string, ActivityFn>, options: RunOpOptions = {}) {
+  const lines: string[] = [];
+  let status: string;
+  try {
+    status = (await runOpLocally(config, activities, PROFILES, undefined, {
+      gates: memoryGateLedgerPort(),
+      now: NOW,
+      runId: "local-1",
+      commit: SHA,
+      runEvents: { write: (l) => lines.push(l) },
+      ...options,
+    })).status;
+  } catch (err) {
+    if (!(err instanceof OpRunFailure)) throw err;
+    status = err.result.status;
+  }
+  return { status, events: checkRunEventLines(lines) };
+}
+
+describe("the local runtime's run events", () => {
+  test("a run that passes: run, phases and steps, each step started before it settles, named as the run record names it", async () => {
+    const { status, events } = await run(
+      op({ phases: [{ name: "Build", steps: [{ kind: "activity", fn: "make" }] }, { name: "Ship", steps: [{ kind: "activity", fn: "push" }] }] }),
+      new Map([["make", ok], ["push", ok]]),
+    );
+    expect(status).toBe("ok");
+    // In a CI job the run keeps its own id and names the CI run as its origin, as its run record does (#4020).
+    const ci = Boolean(process.env.GITHUB_RUN_ID || process.env.CI_PIPELINE_ID);
+    expect(events[0]).toMatchObject({ runId: "local-1", kind: "op", name: "deploy-api", gitSha: SHA, runtime: ci ? "ci" : "local" });
+    expect(events[0]!.runOrigin.forge).toBe(process.env.GITHUB_RUN_ID ? "github" : process.env.CI_PIPELINE_ID ? "gitlab" : "local");
+    expect(events.map((e) => e.type)).toEqual([
+      "run-start",
+      "phase-start", "step-start", "step-settle", "phase-settle",
+      "phase-start", "step-start", "step-settle", "phase-settle",
+      "run-settle",
+    ]);
+    expect(events.at(-1)).toMatchObject({ status: "ok" });
+  });
+
+  test("a step's start is emitted before its settle, with the same step id", async () => {
+    const { events } = await run(
+      op({ phases: [{ name: "Build", steps: [{ kind: "activity", fn: "make" }, { kind: "activity", fn: "make" }] }] }),
+      new Map([["make", ok]]),
+    );
+    const steps = events.filter((e): e is Extract<RunEvent, { type: "step-start" | "step-settle" }> => e.type === "step-start" || e.type === "step-settle");
+    // Two steps of one phase share a name; the index keeps them apart.
+    expect(steps.map((e) => [e.type, stepKey(e)])).toEqual([
+      ["step-start", JSON.stringify([null, "Build", "make", 0])],
+      ["step-settle", JSON.stringify([null, "Build", "make", 0])],
+      ["step-start", JSON.stringify([null, "Build", "make", 1])],
+      ["step-settle", JSON.stringify([null, "Build", "make", 1])],
+    ]);
+    expect(steps[0]!.seq).toBeLessThan(steps[1]!.seq);
+  });
+
+  test("a parallel phase starts each step before any settles, and tells two steps of one name apart by index", async () => {
+    const { events } = await run(
+      op({ phases: [{ name: "Fan", parallel: true, steps: [{ kind: "activity", fn: "probe", args: { at: 1 } }, { kind: "activity", fn: "probe", args: { at: 2 } }] }] }),
+      new Map([["probe", ok]]),
+    );
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "probe"], ["step-start", "probe"], ["step-settle", "probe", "ok"], ["step-settle", "probe", "ok"],
+    ]);
+    expect(events.filter((e) => e.type === "step-settle").map((e) => (e as { index?: number }).index)).toEqual([0, 1]);
+  });
+
+  test("an unapproved gate settles gated after gate-waiting; the steps after it settle skipped as not-run", async () => {
+    const { status, events } = await run(
+      op({ phases: [{ name: "Ship", steps: [{ kind: "activity", fn: "before" }, { kind: "gate", gate: "approve-prod" }, { kind: "activity", fn: "after" }] }] }),
+      new Map([["before", ok], ["after", ok]]),
+    );
+    expect(status).toBe("gated");
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "before"], ["step-settle", "before", "ok"],
+      ["step-start", "gate:approve-prod"], ["gate-waiting", "gate:approve-prod"], ["step-settle", "gate:approve-prod", "gated"],
+      ["step-settle", "after", "skipped:not-run"],
+    ]);
+    expect(events.find((e) => e.type === "gate-waiting")).toMatchObject({ op: "deploy-api", gate: "approve-prod", point: null, index: 1 });
+    expect(events.find((e) => e.type === "phase-settle")).toMatchObject({ status: "gated" });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "gated" });
+  });
+
+  test("an approved gate resolves, naming who approved it", async () => {
+    const gates = memoryGateLedgerPort({
+      resolutions: [{ version: 1, op: "deploy-api", gate: "approve-prod", resolvedBy: "alex", timestamp: "2026-10-16T11:00:00.000Z" }],
+    });
+    const { status, events } = await run(op({ phases: [{ name: "Ship", steps: [{ kind: "gate", gate: "approve-prod" }] }] }), new Map(), { gates });
+    expect(status).toBe("ok");
+    expect(events.find((e) => e.type === "gate-resolved")).toMatchObject({ gate: "approve-prod", resolvedBy: "alex", via: null, index: 0 });
+  });
+
+  test("a failed step fails its phase and the run, with its error, and the rest of its phase is not-run", async () => {
+    const boom: ActivityFn = async () => { throw new Error("disk full"); };
+    const { status, events } = await run(
+      op({ phases: [{ name: "Build", steps: [{ kind: "activity", fn: "make" }, { kind: "activity", fn: "pack" }] }] }),
+      new Map([["make", boom], ["pack", ok]]),
+    );
+    expect(status).toBe("fail");
+    expect(stepTrail(events)).toEqual([["step-start", "make"], ["step-settle", "make", "failed"], ["step-settle", "pack", "skipped:not-run"]]);
+    expect(events.find((e) => e.type === "phase-settle")).toMatchObject({ status: "failed" });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed", error: "disk full" });
+  });
+
+  test("an effect whose receipt matched settles its steps skipped with skip: receipt", async () => {
+    const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { version: 3 } });
+    const values = new Map<string, string>([["seeded", receiptExpectation(seeded)]]);
+    const store: ReceiptStore = {
+      read: async (r) => values.get(r.name),
+      write: async (r, e) => void values.set(r.name, e),
+    };
+    const { receiptRead, receiptWrite } = receiptActivities(store);
+    const { status, events } = await run(
+      op({ phases: [{ name: "Seed", steps: [effect(seeded, [{ kind: "activity", fn: "seed" }])] }] }),
+      new Map<string, ActivityFn>([["seed", ok], ["receiptRead", receiptRead as unknown as ActivityFn], ["receiptWrite", receiptWrite as unknown as ActivityFn]]),
+    );
+    expect(status).toBe("ok");
+    expect(stepTrail(events)).toEqual([
+      ["step-start", "receiptRead"], ["step-settle", "receiptRead", "ok"],
+      ["step-settle", "seed", "skipped:receipt"],
+    ]);
+  });
+
+  test("a run that throws before its first phase still ends its stream, failed with the reason", async () => {
+    const lines: string[] = [];
+    await expect(
+      runOpLocally(op({ phases: [{ name: "P", parallel: true, steps: [effect(EffectReceipt("r", { effect: "e", flavor: "existence", inputs: {} }), [])] }] }), new Map(), PROFILES, undefined, {
+        gates: memoryGateLedgerPort(), now: NOW, commit: SHA, runEvents: { write: (l) => lines.push(l) },
+      }),
+    ).rejects.toThrow(/cannot run in a parallel phase/);
+    const events = checkRunEventLines(lines);
+    expect(events.map((e) => e.type)).toEqual(["run-start", "run-settle"]);
+    expect(events.at(-1)).toMatchObject({ status: "failed", error: expect.stringMatching(/cannot run in a parallel phase/) });
+  });
+});

package/src/op/run-live.ts

@@ -86,7 +86,7 @@ function keyOf(prefix: string, env: string, op: string): string {
 }
 
 /** The checkout's shared git directory (the same for every worktree), or null outside a checkout. */
-async function gitCommonDir(cwd: string): Promise<string | null> {
+export async function gitCommonDir(cwd: string): Promise<string | null> {
   try {
     const { stdout } = await execFileAsync("git", ["rev-parse", "--git-common-dir"], { cwd });
     const dir = stdout.trim();

package/src/op/runtime.ts

@@ -20,6 +20,7 @@ import type { OpConfig } from "./types";
 import type { StepRecord, OpRunResult } from "./local-executor";
 import type { WaitingPoint } from "./steward-points";
 import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import type { RunOrigin } from "../lifecycle/release-ledger";
 import type { RunComponentsOptions, RunComponentsResult } from "../components/cli-support";
 
 /**
@@ -159,6 +160,29 @@ export interface OpRunRecord {
    * first phase.
    */
   resumed?: { gate: string; run: string; checkpoint: string };
+  /**
+   * The commit the run built from (#4020): the checkout's `HEAD`, else the
+   * commit the CI job started for. Gate facts the run writes carry the same
+   * commit, so a run and its gate join on it. Absent on a record written
+   * before 0.124.28 and when the run knew no commit.
+   */
+  gitSha?: string;
+  /**
+   * The CI run this Op ran in (#4020), as a deploy record's `runOrigin` names
+   * its run, so the two name a run the same way. `id` is still the Op's own
+   * run id. Absent outside CI and on a record written before 0.124.28.
+   */
+  runOrigin?: RunOrigin;
+  /**
+   * The run's statement (#4044): a DSSE envelope over an in-toto statement
+   * (`https://intentius.io/chant/op-run/v1`) a runner key signed at the end
+   * of the run, naming the run, its commit and the SHA-256 of this record
+   * without the statement (`../workspace/trust/op-run-statement.ts`).
+   * `chant ci tick` with `ci.green.source: "runs"` counts only a run that
+   * carries one. Absent on a run given no runner key, and on a record
+   * written before 0.124.28.
+   */
+  statement?: { payloadType: string; payload: string; signatures: { keyid: string; sig: string }[] };
 }
 
 /** An {@link OpRunRecord} before the ledger stamps its version and mints an id. */
@@ -187,6 +211,14 @@ export interface OpRunStartOptions {
   profile?: string;
   /** Called once per settled step, so `--progress-json` can stream. */
   progress?: (record: StepRecord) => void;
+  /**
+   * Where the run's event stream goes (#4041, `--events-json`): one
+   * `run-event.schema.json` line at a time, written through the one writer
+   * (`createRunEventWriter`). The local runtime writes `runtime: "local"`
+   * events (`ci` in a CI job); a hosted runtime writes its own, as fountain
+   * writes `runtime: "steward"` ones. A runtime that cannot stream omits it.
+   */
+  runEvents?: (line: string) => void;
   /** Aborts in-flight work (Ctrl-C). */
   signal?: AbortSignal;
   /**
@@ -205,6 +237,13 @@ export interface OpRunStartOptions {
    * and the run `chant run status --on fountain` reports carry the same id.
    */
   runId?: string;
+  /**
+   * Signs the run's record when it settles (#4044), for `chant run <op>
+   * --key` or `CHANT_RUNNER_KEY`: the local runtime stores what it returns
+   * on the record as `statement`. A runtime that writes no record here
+   * ignores it.
+   */
+  signRecord?: (record: OpRunRecord) => NonNullable<OpRunRecord["statement"]>;
 }
 
 /** What a caller hands {@link OpRuntimeProvider.resolveGate} besides the resolution. */

package/src/op/runtimes/local.test.ts

@@ -51,6 +51,7 @@ vi.mock("../../lifecycle/run-ledger", async () => {
 });
 
 const { createLocalOpRuntime } = await import("./local");
+const { checkRunEventLines, stepTrail } = await import("../../workspace/__fixtures__/run-event-check");
 
 function op(name: string, steps: unknown[]): OpConfig {
   return {
@@ -145,6 +146,21 @@ describe("the local op runtime", () => {
     expect(seen).toEqual(["ok", "ok"]);
   });
 
+  test("runEvents gets the run's event stream, named by the handle's run id (#4041)", async () => {
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
+    const runtime = createLocalOpRuntime();
+    const lines: string[] = [];
+
+    const handle = await runtime.start(op("hello", [{ kind: "activity", fn: "ok", args: {} }]), { runEvents: (l) => lines.push(l) });
+    await handle.result();
+
+    const events = checkRunEventLines(lines);
+    expect(events[0]).toMatchObject({ type: "run-start", runId: handle.runId, kind: "op", name: "hello" });
+    expect(events[0]!.runtime).toBe(process.env.GITHUB_RUN_ID || process.env.CI_PIPELINE_ID ? "ci" : "local");
+    expect(stepTrail(events)).toEqual([["step-start", "ok"], ["step-settle", "ok", "ok"]]);
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "ok" });
+  });
+
   test("a gated Op settles as gated, naming the gate, and runs nothing after it (#2119)", async () => {
     const after = vi.fn(async () => ({}));
     loadActivitiesMock.mockResolvedValue(new Map([["after", after]]));

package/src/op/runtimes/local.ts

@@ -176,6 +176,15 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
                     `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`,
                 ),
               ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+              ...(startOpts.runEvents ? { runEvents: { write: startOpts.runEvents } } : {}),
+              // #4044: a runner key signs the record as the run settles.
+              ...(startOpts.signRecord
+                ? {
+                    signRecord: startOpts.signRecord,
+                    onSignError: (err: unknown) =>
+                      process.stderr.write(`warning: run "${runId}" of "${op.name}" was not signed: ${err instanceof Error ? err.message : String(err)}\n`),
+                  }
+                : {}),
               // #3956: a running step's output, and a still-running line while
               // it is quiet, on stderr as they happen; stdout stays the
               // `--json` record's and `--progress-json`'s.

package/src/plan-summary.test.ts

@@ -261,3 +261,23 @@ describe("addresses", () => {
     expect(escapeMarkerAddress('aws_s3_bucket.logs["a*b"]')).toBe("aws_s3_bucket.logs:a+00002Ab");
   });
 });
+
+describe("a no-change group with holes (#4084)", () => {
+  const part = (member: string, holes: ChangeSetPart["member"]["holes"] = []): ChangeSetPart => ({
+    member: { member, lexicon: "aws", planner: "chant", status: "planned", planDigest: `jcs1-sha256:${member}`, holes },
+    entries: [],
+  });
+  const hole = { address: "cluster-a", type: "AWS::CloudFormation::Stack", reason: "inputs from network; re-checked on apply" };
+
+  test("does not say no changes for a member whose plan has holes, and keeps the group and its id", () => {
+    const withHole = groupChangeSet(composeChangeSet([part("app-01"), part("app-02"), part("cluster-a", [hole])]));
+    const without = groupChangeSet(composeChangeSet([part("app-01"), part("app-02"), part("cluster-a")]));
+    expect(withHole.groups.map((g) => [g.id, g.units, g.noChanges])).toEqual(without.groups.map((g) => [g.id, g.units, g.noChanges]));
+    const id = withHole.groups[0].id;
+    const text = renderPlanSummaryText(withHole);
+    expect(text).toContain(`Group ${id}: 3 members, no changes known: 1 with holes, listed above:`);
+    expect(text).toContain("cluster-a: cluster-a: inputs from network; re-checked on apply");
+    expect(renderPlanSummaryMarkdown(withHole)).toContain(`#### Group ${id}: 3 members, no changes known: 1 with holes, listed above`);
+    expect(renderPlanSummaryText(without)).toContain(`Group ${id}: 3 members, no changes:`);
+  });
+});

package/src/plan-summary.ts

@@ -689,7 +689,14 @@ function groupTitle(s: PlanSummary, g: PlanSummaryGroup): string {
   if (g.resource) t += ` of ${g.resource}`;
   if (g.outlier) t += " (outlier)";
   if (g.provisional) t += " (provisional)";
-  if (g.noChanges) t += ", no changes";
+  if (g.noChanges) {
+    // A member with holes planned no entries, but its plan says nothing about
+    // what the holes cover, so the group cannot say "no changes" for it
+    // (#4084). Only the heading says so: the group and its id are unchanged.
+    const holed = s.unit === "member" ? new Set(s.holes.map((h) => h.member)) : new Set<string>();
+    const unknown = g.units.filter((u) => holed.has(u)).length;
+    t += unknown > 0 ? `, no changes known: ${unknown} with holes, listed above` : ", no changes";
+  }
   else if (g.extends) t += `, group ${g.extends}'s change plus`;
   else if (g.units.length > 1) t += ", identical change";
   else t += ", change";

package/src/point-decision.ts

@@ -36,7 +36,7 @@ import { parseDuration } from "./op/duration";
 import type { GateLedgerPort } from "./op/gate";
 import { DEFAULT_GATE_POINT_PASS, defaultGatePointStore, gatePointInputs, gateSubject, type GatePoint, type GatePointFacts, type GatePointStore } from "./op/gate-point";
 import type { WaitingPoint } from "./op/steward-points";
-import { resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
+import { ciCommitFromEnv, ciRunIdFromEnv, resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
 import { refuseGateWithoutRecording } from "./lifecycle/no-record";
 
 export {
@@ -102,6 +102,13 @@ export interface GatePointAsker {
   ask(request: GatePointRequest): Promise<GatePointQuestion>;
 }
 
+/** The run and commit a gate record names (#4020): the input's own, else the CI job's. */
+function runStamp(input: { runId?: string; gitSha?: string }): { runId?: string; gitSha?: string } {
+  const runId = input.runId || ciRunIdFromEnv();
+  const gitSha = input.gitSha || ciCommitFromEnv();
+  return { ...(runId ? { runId } : {}), ...(gitSha ? { gitSha } : {}) };
+}
+
 /** What the run needs to decide a gate that asks a point. */
 export interface PointGateInput {
   op: string;
@@ -112,6 +119,8 @@ export interface PointGateInput {
   description?: string;
   timeout?: string;
   runId?: string;
+  /** The commit the run is at (#4020). Default: the commit the CI job started for, when it runs in CI. */
+  gitSha?: string;
   planDigest?: string;
   /** The environment the run was started for: the `gate.env` input. Op gate facts on the ledger record none. */
   env?: string;
@@ -202,6 +211,7 @@ export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePo
       resolvedBy: resolvedByOf(q),
       timestamp: now,
       note: `answered through decision point ${q.point} (${q.id})`,
+      ...runStamp(input),
       ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
       approver: { kind: q.decider === "quorum" || q.answeredBy.length > 0 ? "human" : "agent" },
       answer,
@@ -228,7 +238,7 @@ export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePo
     timestamp: now,
     expiresAt: new Date(new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY)).toISOString(),
     ...(input.description ? { description: input.description } : {}),
-    ...(input.runId ? { runId: input.runId } : {}),
+    ...runStamp(input),
     ...(url ? { url } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
     ...(resume ? { resume } : {}),

package/src/pr-loop.ts

@@ -204,6 +204,17 @@ export function memberCounts(doc: Pick<ChangeSetDocument, "summary">, member: st
   return { create: n("create"), update: n("update"), replace: n("replace"), delete: n("delete") };
 }
 
+/**
+ * Why a member's plan cannot say everything it will change: its holes'
+ * reasons, each once, in order (#4084). A `cfn-deploy` member whose inputs
+ * come from a stack the same run applies first says `inputs from <stack>;
+ * re-checked on apply`.
+ */
+export function memberHoleReasons(report: Pick<PrReport, "changeSet">, member: string): string[] {
+  const m = report.changeSet.members.find((x) => x.member === member);
+  return [...new Set((m?.holes ?? []).map((h) => h.reason))];
+}
+
 /** The approve command a reviewer runs for this report's digest. */
 export function prApproveCommand(report: Pick<PrReport, "op" | "gate" | "digest">, approver = "<you>"): string {
   return `chant approve ${report.op} ${report.gate} --plan ${report.digest} --approver ${approver} --sign`;
@@ -295,8 +306,16 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   if (report.members.length > 0) {
     out.push("", "| Member | Component | Status | Create | Update | Replace | Delete |", "|---|---|---|---:|---:|---:|---:|");
     for (const m of report.members) {
-      const status = STATUS_WORDS[m.status] + (m.inputsMoved?.length ? `, inputs from ${m.inputsMoved.join(", ")} moved` : "");
-      out.push(`| ${code(m.member)} | ${m.component} | ${status} | ${m.counts.create} | ${m.counts.update} | ${m.counts.replace} | ${m.counts.delete} |`);
+      const holes = memberHoleReasons(report, m.member);
+      const status =
+        STATUS_WORDS[m.status] +
+        (m.inputsMoved?.length ? `, inputs from ${m.inputsMoved.join(", ")} moved` : "") +
+        (holes.length > 0 ? `; ${holes.length > 2 ? `${holes[0]}; and ${holes.length - 1} more, listed under Holes` : holes.join("; ")}` : "");
+      // A member whose plan has holes and no entries says nothing about what
+      // it changes, so its counts are unknown, not zero (#4084).
+      const unknown = holes.length > 0 && !report.changeSet.entries.some((e) => e.member === m.member);
+      const n = (k: keyof PrMemberCounts): string => (unknown ? "?" : String(m.counts[k]));
+      out.push(`| ${code(m.member)} | ${m.component} | ${status} | ${n("create")} | ${n("update")} | ${n("replace")} | ${n("delete")} |`);
     }
     if (report.members.some((m) => m.inputsMoved?.length)) {
       out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
@@ -328,9 +347,11 @@ export function prStatusDescription(report: PrReport): string {
     case "nothing":
       text = "nothing to plan";
       break;
-    case "planned":
-      text = `${n} member${n === 1 ? "" : "s"}: ${sum.change} to change, ${sum.destroy} to destroy or replace${digest}`;
+    case "planned": {
+      const unknown = report.members.filter((m) => memberHoleReasons(report, m.member).length > 0).length;
+      text = `${n} member${n === 1 ? "" : "s"}: ${sum.change} to change, ${sum.destroy} to destroy or replace${unknown > 0 ? `, ${unknown} with holes` : ""}${digest}`;
       break;
+    }
     case "plan-failed":
       text = `a member failed to plan${digest}`;
       break;

package/src/pr-report-url.test.ts

@@ -0,0 +1,131 @@
+/**
+ * `--report-url` (#4007): the URL forms, the key, and the upload of a run's
+ * events as it goes: one upload in flight at a time, a failure that warns
+ * and never stops the run, and a last upload that carries everything. The
+ * s3 scheme runs a fake AWS CLI; nothing here reaches a network.
+ */
+
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { openPrReportUpload, parseReportUrl, reportKey, reportPut, type ReportPut } from "./pr-report-url";
+
+const line = (type: string, extra: Record<string, unknown> = {}): string => JSON.stringify({ type, ...extra }) + "\n";
+
+let dir: string;
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), "pr-report-url-"));
+});
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe("parseReportUrl", () => {
+  test("reads s3 and file URLs and refuses anything else", () => {
+    expect(parseReportUrl("s3://bucket/a/b/")).toEqual({ scheme: "s3", url: "s3://bucket/a/b", bucket: "bucket", prefix: "a/b" });
+    expect(parseReportUrl("s3://bucket")).toEqual({ scheme: "s3", url: "s3://bucket", bucket: "bucket", prefix: "" });
+    expect(parseReportUrl(pathToFileURL(dir).href)).toMatchObject({ scheme: "file", dir });
+    expect(parseReportUrl("https://example.invalid/x")).toHaveProperty("error");
+  });
+
+  test("keys by pull request and commit, and by member after them", () => {
+    expect(reportKey(12, "abc")).toBe("12/abc");
+    expect(reportKey(null, "abc")).toBe("unknown/abc");
+    expect(reportKey(12, "abc", "api")).toBe("12/abc/api");
+  });
+});
+
+describe("openPrReportUpload", () => {
+  /** A put whose uploads finish only when the test says, recording what each carried. */
+  function heldPut() {
+    const calls: Array<{ key: string; body: string; finish: (err?: Error) => void }> = [];
+    let inFlight = 0;
+    let most = 0;
+    const put: ReportPut = (key, body) =>
+      new Promise<void>((resolve, reject) => {
+        inFlight++;
+        most = Math.max(most, inFlight);
+        calls.push({ key, body, finish: (err) => { inFlight--; if (err) reject(err); else resolve(); } });
+      });
+    return { put, calls, most: () => most };
+  }
+
+  test("uploads the events on each settle, never two at once, and the settles that came meanwhile in one more", async () => {
+    const held = heldPut();
+    const upload = openPrReportUpload({ target: { scheme: "s3", url: "s3://b", bucket: "b", prefix: "" }, key: "12/abc", stage: "apply", warn: () => {}, put: held.put });
+    upload.line(line("run-start"));
+    expect(held.calls).toHaveLength(0);
+    upload.line(line("wave-start", { wave: 1 }));
+    upload.line(line("component-settle", { wave: 1 }));
+    expect(held.calls).toHaveLength(1);
+    upload.line(line("wave-settle", { wave: 1 }));
+    upload.line(line("wave-start", { wave: 2 }));
+    upload.line(line("component-settle", { wave: 2 }));
+    // Both settles wait behind the one in flight, and go up as one.
+    expect(held.calls).toHaveLength(1);
+    held.calls[0]!.finish();
+    await new Promise((r) => setImmediate(r));
+    expect(held.calls).toHaveLength(2);
+    expect(held.calls[1]!.body.split("\n").filter(Boolean)).toHaveLength(6);
+    expect(held.calls[1]!.key).toBe("12/abc/pr-apply.events.jsonl");
+
+    upload.file("pr-apply.json", "{}\n");
+    const closing = upload.close();
+    await new Promise((r) => setImmediate(r));
+    // The last upload waits for the one in flight.
+    expect(held.calls).toHaveLength(2);
+    held.calls[1]!.finish();
+    await new Promise((r) => setImmediate(r));
+    held.calls[2]!.finish();
+    await new Promise((r) => setImmediate(r));
+    held.calls[3]!.finish();
+    await closing;
+    expect(held.calls.map((c) => c.key)).toEqual(["12/abc/pr-apply.events.jsonl", "12/abc/pr-apply.events.jsonl", "12/abc/pr-apply.events.jsonl", "12/abc/pr-apply.json"]);
+    expect(held.most()).toBe(1);
+  });
+
+  test("a failed upload as the run goes warns once and the run goes on; the last one is tried again", async () => {
+    const warnings: string[] = [];
+    let fail = true;
+    const put: ReportPut = async (key) => {
+      if (fail) throw new Error(`no bucket for ${key}`);
+    };
+    const upload = openPrReportUpload({ target: { scheme: "s3", url: "s3://b", bucket: "b", prefix: "" }, key: "12/abc", stage: "apply", warn: (m) => warnings.push(m), put });
+    upload.line(line("component-settle"));
+    await new Promise((r) => setImmediate(r));
+    upload.line(line("wave-settle"));
+    await new Promise((r) => setImmediate(r));
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toMatch(/as the run went: no bucket .*The run goes on/);
+    fail = false;
+    await upload.close();
+    expect(warnings).toHaveLength(1);
+  });
+
+  test("file://: each settle replaces the events file whole, so it holds a wave's settle before the next wave starts", async () => {
+    const target = parseReportUrl(pathToFileURL(dir).href);
+    if ("error" in target) throw new Error(target.error);
+    const upload = openPrReportUpload({ target, key: "12/abc", stage: "apply", warn: () => {} });
+    upload.line(line("run-start"));
+    upload.line(line("wave-settle", { wave: 1 }));
+    await new Promise((r) => setImmediate(r));
+    const events = join(dir, "12", "abc", "pr-apply.events.jsonl");
+    expect(await readFile(events, "utf8")).toBe(line("run-start") + line("wave-settle", { wave: 1 }));
+    upload.line(line("run-settle"));
+    upload.file("change-set.json", "{}\n");
+    await upload.close();
+    expect((await readFile(events, "utf8")).split("\n").filter(Boolean)).toHaveLength(3);
+    expect(await readFile(join(dir, "12", "abc", "change-set.json"), "utf8")).toBe("{}\n");
+  });
+
+  test("s3://: the AWS CLI copies each object from its stdin, with the content type, and chant hands it no credential", async () => {
+    const runs: Array<{ args: string[]; stdin: string }> = [];
+    const put = reportPut({ scheme: "s3", url: "s3://b/p", bucket: "b", prefix: "p" }, async (args, stdin) => {
+      runs.push({ args, stdin });
+    });
+    await put("12/abc/pr-plan.json", "{}\n", "application/json");
+    expect(runs).toEqual([{ args: ["s3", "cp", "-", "s3://b/p/12/abc/pr-plan.json", "--content-type", "application/json", "--only-show-errors"], stdin: "{}\n" }]);
+  });
+});