@intentius/chant 0.124.31 → 0.124.33

package/src/op/work-lease-run.test.ts

@@ -342,9 +342,10 @@ describe("an Op that changes the checkout", () => {
       expect(result.workLease).toMatchObject({ item: "W-7", branch: "chant/work/W-7", released: true, outcome: "done" });
       expect(result.workLease?.holder).toBe(stewardWorkHolder("box", "dispatch", "h1"));
 
-      // The worktree sat under the git directory and is gone; the branch keeps the build.
-      expect(worktree.startsWith(join(dir, ".git"))).toBe(true);
+      // The worktree sat at .chant/work/<item> in the checkout and is gone, with the directories it left empty; the branch keeps the build.
+      expect(worktree).toBe(join(dir, ".chant", "work", "W-7"));
       expect(existsSync(worktree)).toBe(false);
+      expect(existsSync(join(dir, ".chant"))).toBe(false);
       expect(git(["show", "chant/work/W-7:app/feature.ts"], dir).stdout).toBe("export const feature = true;\n");
 
       // The coding agent's checkout: its edit, its lock, HEAD and the index, as they were.
@@ -403,3 +404,88 @@ describe("an Op that changes the checkout", () => {
     });
   });
 });
+
+describe("where the worktree is (#2893)", () => {
+  const record = (seen: { worktree?: string; status?: string }) =>
+    new Map<string, ActivityFn>([
+      [
+        "build",
+        async (args) => {
+          seen.worktree = String(args.worktree);
+          writeFileSync(join(seen.worktree, "app", "feature.ts"), "export const feature = true;\n");
+          seen.status = git(["status", "--porcelain", "--untracked-files=all"], dir()).stdout;
+          return {};
+        },
+      ],
+    ]);
+  let current = "";
+  const dir = () => current;
+  const op = (item: string) => dispatchOp({ workLease: { item }, changesCheckout: true }, [step("build", { worktree: workLeaseOutput("worktree") })]);
+
+  test("it is .chant/work/<item> in the checkout, info/exclude gets /.chant/work/ once, and git status stays clean while it is there", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      const seen: { worktree?: string; status?: string } = {};
+      const first = await run(op("W-20"), record(seen), d);
+      expect(first.workLease).toMatchObject({ released: true, outcome: "done" });
+      expect(seen.worktree).toBe(join(d, ".chant", "work", "W-20"));
+      expect(seen.status).toBe("");
+      const exclude = () => readFileSync(join(d, ".git", "info", "exclude"), "utf-8").split("\n").filter((l) => l === "/.chant/work/");
+      expect(exclude()).toHaveLength(1);
+      await run(op("W-21"), record(seen), d);
+      expect(exclude()).toHaveLength(1);
+      expect(git(["status", "--porcelain", "--untracked-files=all"], d).stdout).toBe("");
+      expect(git(["worktree", "list", "--porcelain"], d).stdout).not.toContain(".chant/work");
+    });
+  });
+
+  test("info/exclude is left alone when the project already ignores .chant/work", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      writeFileSync(join(d, ".gitignore"), ".chant/\n");
+      git(["add", ".gitignore"], d);
+      git(["commit", "-q", "-m", "ignore"], d);
+      const before = existsSync(join(d, ".git", "info", "exclude")) ? readFileSync(join(d, ".git", "info", "exclude"), "utf-8") : "";
+      const seen: { worktree?: string; status?: string } = {};
+      await run(op("W-22"), record(seen), d);
+      expect(seen.status).toBe("");
+      const after = existsSync(join(d, ".git", "info", "exclude")) ? readFileSync(join(d, ".git", "info", "exclude"), "utf-8") : "";
+      expect(after).toBe(before);
+    });
+  });
+
+  test("a worktree a crashed run left under .git/chant-work with the branch checked out is removed, and the run goes on from the branch", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      const old = join(d, ".git", "chant-work", "W-23");
+      expect(git(["worktree", "add", "-q", "-b", "chant/work/W-23", old, "HEAD"], d).status).toBe(0);
+      writeFileSync(join(old, "app", "earlier.ts"), "export const earlier = 1;\n");
+      git(["add", "-A"], old);
+      git(["commit", "-q", "-m", "an earlier run"], old);
+      const seen: { worktree?: string; status?: string } = {};
+      const result = await run(op("W-23"), record(seen), d);
+      expect(result.workLease).toMatchObject({ released: true, outcome: "done" });
+      expect(seen.worktree).toBe(join(d, ".chant", "work", "W-23"));
+      expect(existsSync(old)).toBe(false);
+      expect(git(["worktree", "list", "--porcelain"], d).stdout).not.toContain("chant-work");
+      expect(git(["show", "chant/work/W-23:app/earlier.ts"], d).stdout).toBe("export const earlier = 1;\n");
+    });
+  });
+
+  test("a worktree a crashed run left at .chant/work with the branch checked out is replaced", async () => {
+    await withTestDir(async (d) => {
+      current = d;
+      await initRepo(d);
+      const left = join(d, ".chant", "work", "W-24");
+      expect(git(["worktree", "add", "-q", "-b", "chant/work/W-24", left, "HEAD"], d).status).toBe(0);
+      writeFileSync(join(left, "app", "stray.ts"), "stray\n");
+      const seen: { worktree?: string; status?: string } = {};
+      const result = await run(op("W-24"), record(seen), d);
+      expect(result.workLease).toMatchObject({ released: true, outcome: "done" });
+      expect(existsSync(left)).toBe(false);
+    });
+  });
+});

package/src/op/work-lease-run.ts

@@ -39,10 +39,11 @@
  *
  * An Op with `changesCheckout` (applying a build, `chant workspace upgrade`)
  * must declare `workLease`, and its leased steps get a git worktree of their
- * own: `chant/work/<item>` checked out under the repository's git directory,
- * from the checkout's HEAD, or from the branch as an earlier run left it. The
- * worktree is removed when the run ends and the branch keeps whatever the
- * steps committed, for the runner to deliver. The checkout a coding agent is
+ * own: `chant/work/<item>` checked out at `.chant/work/<item>` in the
+ * checkout (#2893), which `<git-common-dir>/info/exclude` keeps out of
+ * `git status`, from the checkout's HEAD or from the branch as an earlier run
+ * left it. The worktree is removed when the run ends and the branch keeps
+ * whatever the steps committed, for the runner to deliver. The checkout a coding agent is
  * editing, its index and its uncommitted files, are never touched.
  *
  * A run that ends `not_done` keeps its attempt aside (#3147): whatever the
@@ -54,7 +55,7 @@
  */
 
 import { existsSync, rmSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, resolve, sep } from "node:path";
 import { getRuntime } from "../runtime-adapter";
 import {
   claimWorkLease,
@@ -69,6 +70,7 @@ import {
   type WorkLease,
 } from "../lifecycle/work-lease";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { excludeWorkDir, legacyWorkWorktreePath, LEGACY_WORK_DIR, removeEmptyWorkDirs, WORK_DIR, workWorktreePath } from "../lifecycle/work-dir";
 import { currentHolderId } from "../lifecycle/lease";
 import { parseDuration } from "./duration";
 import { isStepOutputRef, stepOutput, type StepOutputRef } from "./step-output-ref";
@@ -271,21 +273,36 @@ export class RunWorkLease {
   }
 
   /**
-   * A worktree for `id` on `chant/work/[<member>/]<id>`, under the git
-   * directory so the checkout's own `git status` never lists it. Starts from
-   * the branch when an earlier run left it, from HEAD otherwise.
+   * A worktree for `id` on `chant/work/[<member>/]<id>`, at
+   * `<checkout>/.chant/work/[<member>/]<id>` (#2893): inside the checkout, so
+   * a coding agent may write there and `node_modules` resolves, and in
+   * `<git-common-dir>/info/exclude`, so the checkout's own `git status` never
+   * lists it. Starts from the branch when an earlier run left it, from HEAD
+   * otherwise. A worktree an earlier run left on the branch, here or where
+   * older versions made it under the git directory, is removed first.
    */
   private async makeWorktree(id: string, members: readonly string[]): Promise<{ worktree: string; branch: string }> {
     const cwd = this.opts.cwd;
     const common = await git(["rev-parse", "--git-common-dir"], cwd);
     if (!common.ok) throw new Error(`Op "${this.config.name}" changes the checkout, but ${cwd} is not a git checkout: ${common.stderr}`);
     const commonDir = isAbsolute(common.stdout) ? common.stdout : resolve(cwd, common.stdout);
+    // The top as the caller spells it (git's --show-toplevel resolves symbolic links).
+    const cdup = await git(["rev-parse", "--show-cdup"], cwd);
+    if (!cdup.ok) throw new Error(`Op "${this.config.name}" changes the checkout, but ${cwd} has no working tree: ${cdup.stderr}`);
+    const top = resolve(cwd, cdup.stdout);
     const scope = members.join("/");
     const branch = `${WORK_BRANCH_PREFIX}${scope ? `${scope}/` : ""}${id}`;
-    const worktree = join(commonDir, "chant-work", ...members, id);
-    if (existsSync(worktree)) {
-      await git(["worktree", "remove", "--force", worktree], cwd);
-      rmSync(worktree, { recursive: true, force: true });
+    const worktree = workWorktreePath(top, members, id);
+    const ignored = (await git(["check-ignore", "-q", `${WORK_DIR}/${id}`], top)).ok;
+    excludeWorkDir(commonDir, ignored);
+    for (const stale of await this.staleWorktrees(branch, commonDir, members, id)) {
+      await git(["worktree", "remove", "--force", stale], cwd);
+      rmSync(stale, { recursive: true, force: true });
+    }
+    for (const dir of [worktree, legacyWorkWorktreePath(commonDir, members, id)]) {
+      if (!existsSync(dir)) continue;
+      await git(["worktree", "remove", "--force", dir], cwd);
+      rmSync(dir, { recursive: true, force: true });
     }
     await git(["worktree", "prune"], cwd);
     const exists = (await git(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd)).ok;
@@ -298,6 +315,28 @@ export class RunWorkLease {
     return { worktree, branch };
   }
 
+  /**
+   * The registered worktrees that have `branch` checked out at a path chant
+   * makes work worktrees at: `.chant/work/[<member>/]<id>` in any checkout,
+   * or `<git-common-dir>/chant-work/[<member>/]<id>` where versions before
+   * #2893 made them. A run that crashed leaves one behind, and `git worktree
+   * add` then refuses the branch as already checked out.
+   */
+  private async staleWorktrees(branch: string, commonDir: string, members: readonly string[], id: string): Promise<string[]> {
+    const list = await git(["worktree", "list", "--porcelain"], this.opts.cwd);
+    if (!list.ok) return [];
+    const tail = [...members, id].join("/");
+    const legacy = legacyWorkWorktreePath(commonDir, members, id).split(sep).join("/");
+    const out: string[] = [];
+    for (const block of list.stdout.split(/\n\s*\n/)) {
+      const path = /^worktree (.+)$/m.exec(block)?.[1];
+      if (!path || !block.split("\n").includes(`branch refs/heads/${branch}`)) continue;
+      const posixPath = path.split(sep).join("/");
+      if (posixPath.endsWith(`/${WORK_DIR}/${tail}`) || posixPath === legacy || posixPath.endsWith(`/${LEGACY_WORK_DIR}/${tail}`)) out.push(path);
+    }
+    return out;
+  }
+
   private lose(why: string): void {
     if (this.lost !== undefined) return;
     this.lost = why;
@@ -408,6 +447,7 @@ export class RunWorkLease {
     if (lease.worktree) {
       await git(["worktree", "remove", "--force", lease.worktree], this.opts.cwd).catch(() => undefined);
       rmSync(lease.worktree, { recursive: true, force: true });
+      removeEmptyWorkDirs(lease.worktree);
       await git(["worktree", "prune"], this.opts.cwd).catch(() => undefined);
     }
     if (this.lost !== undefined) return base;

package/src/pr-forge-bundle.test.ts

@@ -34,7 +34,7 @@ describe("the pr-forge bundle", () => {
       expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
     }
     expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual(["packages/core/src/pr-forge.ts"]);
-    // About 27 KB today.
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(32 * 1024);
+    // About 33 KB today, after the pull request authors (#4000).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(36 * 1024);
   });
 });

package/src/pr-forge.test.ts

@@ -85,6 +85,21 @@ describe("github", () => {
     expect(calls[0].body).toEqual({ state: "success", context: "chant/plan", description: "2 members", target_url: "https://ci/run/1" });
   });
 
+  test("the authors of a pull request are its opener and every commit's author and committer, every page read (#4000)", async () => {
+    const page1 = Array.from({ length: 100 }, () => ({ author: { login: "carol" }, committer: { login: "carol" } }));
+    const { fetch, calls } = fakeFetch({
+      "GET /repos/acme/infra/pulls/12": { number: 12, user: { login: "carol" } },
+      "GET /repos/acme/infra/pulls/12/commits?page=1": page1,
+      "GET /repos/acme/infra/pulls/12/commits?page=2": [{ author: null, committer: { login: "dave" } }, { author: { login: "erin" }, committer: { login: "web-flow" } }],
+    });
+    expect(await githubForge({ ...opts, fetch }).authors(12)).toEqual(["carol", "dave", "erin", "web-flow"]);
+    expect(calls.map((c) => c.url)).toEqual([
+      "https://api.github.com/repos/acme/infra/pulls/12",
+      "https://api.github.com/repos/acme/infra/pulls/12/commits?per_page=100&page=1",
+      "https://api.github.com/repos/acme/infra/pulls/12/commits?per_page=100&page=2",
+    ]);
+  });
+
   test("an approver is someone whose newest deciding review approves", async () => {
     const { fetch } = fakeFetch({
       "GET /repos/acme/infra/pulls/12/reviews": [
@@ -195,6 +210,15 @@ describe("forgejo", () => {
     expect(calls[0].headers.Authorization).toBe("token t0k");
   });
 
+  test("the authors of a pull request come from the same endpoints, paged by limit (#4000)", async () => {
+    const { fetch, calls } = fakeFetch({
+      "GET /api/v1/repos/acme/infra/pulls/4": { number: 4, user: { login: "ana" } },
+      "GET /api/v1/repos/acme/infra/pulls/4/commits": [{ author: { login: "ana" }, committer: { login: "ben" } }],
+    });
+    expect(await forgejoForge({ ...opts, fetch }).authors(4)).toEqual(["ana", "ben"]);
+    expect(calls.map((c) => c.url)).toContain("https://codeberg.org/api/v1/repos/acme/infra/pulls/4/commits?limit=50&page=1");
+  });
+
   test("a dismissed approval no longer counts, and a comment review decides nothing", async () => {
     const { fetch } = fakeFetch({
       "GET /api/v1/repos/acme/infra/pulls/4/reviews": [
@@ -240,6 +264,24 @@ describe("gitlab", () => {
     expect(calls[0].body).toEqual({ state: "failed", name: "chant/apply", description: "refused" });
   });
 
+  test("the authors of a merge request: its author, and each commit email's account by the users search (#4000)", async () => {
+    const { fetch, calls } = fakeFetch({
+      "GET /api/v4/projects/42/merge_requests/5": { iid: 5, author: { username: "ana" } },
+      "GET /api/v4/projects/42/merge_requests/5/commits": [
+        { author_email: "ana@example.com", committer_email: "Ben@Example.com" },
+        { author_email: "ghost@example.com", committer_email: "ana@example.com" },
+      ],
+      "GET /api/v4/users": (c: Call) =>
+        ({ "ana@example.com": [{ username: "ana" }], "ben@example.com": [{ username: "ben" }] })[new URL(c.url).searchParams.get("search")!] ?? [],
+    });
+    expect(await gitlabForge({ ...opts, fetch }).authors(5)).toEqual(["ana", "ben"]);
+    expect(calls.filter((c) => new URL(c.url).pathname === "/api/v4/users").map((c) => new URL(c.url).searchParams.get("search"))).toEqual([
+      "ana@example.com",
+      "ben@example.com",
+      "ghost@example.com",
+    ]);
+  });
+
   test("approvers come from the approvals endpoint, merged requests from the commit", async () => {
     const { fetch } = fakeFetch({
       "GET /api/v4/projects/42/merge_requests/5/approvals": { approved_by: [{ user: { username: "ana" } }, { user: { username: "ben" } }] },

package/src/pr-forge.ts

@@ -349,6 +349,16 @@ export interface PrForge {
   upsertIssue(marker: string, title: string, body: string): Promise<string | undefined>;
   /** Logins whose standing review approves `pr`. */
   approvers(pr: number): Promise<string[]>;
+  /**
+   * Logins of the people who wrote `pr` (#4000): its author, and the author
+   * and committer of each of its commits. GitHub and Forgejo name a commit's
+   * people by the account its email belongs to; a commit whose email is on no
+   * account adds nobody. GitLab names them by email only, so each email is
+   * looked up among the users (`GET /users?search=`), which matches an
+   * account's public email; an email no account shows publicly adds nobody.
+   * Sorted, without repeats.
+   */
+  authors(pr: number): Promise<string[]>;
   /** The merged pull request that produced `sha`, or null. */
   pullRequestFor(sha: string): Promise<number | null>;
   /**
@@ -667,6 +677,20 @@ function githubShaped(kind: "github" | "forgejo", opts: GithubForgeOptions): Git
       }
       return [...standing].filter(([, state]) => state === "APPROVED").map(([login]) => login).sort();
     },
+    async authors(pr) {
+      const logins = new Set<string>();
+      const add = (v: unknown) => {
+        if (isObject(v) && typeof v.login === "string" && v.login !== "") logins.add(v.login);
+      };
+      const opened = await api.call("GET", `${repo}/pulls/${pr}`);
+      if (isObject(opened)) add(opened.user);
+      for (const c of await api.list(`${repo}/pulls/${pr}/commits`, pageParams, pageSize)) {
+        if (!isObject(c)) continue;
+        add(c.author);
+        add(c.committer);
+      }
+      return [...logins].sort();
+    },
     async pullRequestFor(sha) {
       if (kind === "forgejo") {
         try {
@@ -922,6 +946,22 @@ export function gitlabForge(opts: GitlabForgeOptions): PrForge {
         .filter((l): l is string => l !== undefined);
       return [...new Set(logins)].sort();
     },
+    async authors(mr) {
+      const logins = new Set<string>();
+      const merge = await api.call("GET", `${notes}/${mr}`);
+      const author = isObject(merge) ? authorOf(merge) : undefined;
+      if (author) logins.add(author);
+      const emails = new Set<string>();
+      for (const c of await api.list(`${notes}/${mr}/commits`, pageParams, 100)) {
+        if (!isObject(c)) continue;
+        for (const email of [str(c.author_email), str(c.committer_email)]) if (email) emails.add(email.toLowerCase());
+      }
+      for (const email of [...emails].sort()) {
+        const users = await api.call("GET", `/users?search=${encodeURIComponent(email)}`);
+        for (const u of Array.isArray(users) ? users : []) if (isObject(u) && typeof u.username === "string") logins.add(u.username);
+      }
+      return [...logins].sort();
+    },
     async pullRequestFor(sha) {
       const mrs = await api.call("GET", `${project}/repository/commits/${sha}/merge_requests`);
       if (!Array.isArray(mrs)) return null;

package/src/pr-loop-bundle.test.ts

@@ -41,6 +41,7 @@ describe("the pull-request loop bundle", () => {
       "packages/core/src/pr-forge.ts",
       "packages/core/src/pr-loop.ts",
     ]);
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(64 * 1024);
+    // About 65 KB today, after the pull request authors (#4000).
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(72 * 1024);
   });
 });

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` |");
@@ -177,10 +229,40 @@ describe("the note", () => {
   });
 });
 
+describe("the record stage (#4168)", () => {
+  const recorded: PrReport = { ...planReport, stage: "record", status: "recorded", approval: { status: "approved", approvedBy: ["github:rev"] } };
+  const moved: PrReport = { ...recorded, approval: { status: "changed", approved: changedDigest } };
+  const unapproved: PrReport = { ...recorded, approval: { status: "pending" } };
+
+  test("its reports validate", () => {
+    for (const report of [recorded, moved, unapproved]) expectValid(report);
+  });
+
+  test("a plan that differs from the approved one fails the chant/record status; an approved or unapproved one passes", () => {
+    expect(prStatusContext("record")).toBe("chant/record");
+    expect(prStatusContext("record", "net")).toBe("chant/record/net");
+    expect(prStatusState(recorded)).toBe("success");
+    expect(prStatusState(unapproved)).toBe("success");
+    expect(prStatusState(moved)).toBe("failure");
+    expect(prStatusDescription(recorded)).toMatch(/^recorded 2 members: the approved plan; plan [0-9a-f]{12}$/);
+    expect(prStatusDescription(moved)).toMatch(/^recorded 2 members: the plan differs from the approved one/);
+    expect(prStatusDescription(unapproved)).toMatch(/^recorded 2 members: no approval for this plan/);
+  });
+
+  test("the note says nothing applied and a release deploys it", () => {
+    const note = renderPrNote(unapproved);
+    expect(note).toContain("### chant record for `prod`");
+    expect(note).toContain("Recorded the plan of 2 members on merge. Nothing applied: a release that carries this commit deploys it.");
+    expect(note).toContain("No approval stands for this plan. The release gate decides before it deploys.");
+    expect(renderPrNote(moved)).toContain("the plan changed since it was approved");
+  });
+});
+
 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 +303,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");
+  });
+});