@intentius/chant 0.116.0 → 0.118.0

package/src/op/gate-review.ts

@@ -0,0 +1,339 @@
+/**
+ * Approval modes for a gate (#3684): which approvals of a wave's digest
+ * count.
+ *
+ * - `ledger` (the default): any resolution on `chant/lifecycle` that names
+ *   the digest, as `chant approve` writes it. Anyone who can push to the
+ *   branch can approve, in anyone's name.
+ * - `sealed`: a resolution counts only when its seal (`chant approve --sign`)
+ *   verifies against the signers file read at the base commit, for the
+ *   approver it names. A key that the change being applied adds to the
+ *   signers file is not at base, so it cannot approve that change.
+ * - `pr-review`: a resolution counts as under `ledger`, and so does the
+ *   forge review of the pull request that merged the applied commit: an
+ *   approving review of the pull request's head, by a writer other than its
+ *   author. It approves the digest that head planned, which the pull
+ *   request's pipeline records on `chant/lifecycle` with `chant run wave
+ *   --record-plans` ({@link HeadPlans}). A plan that moved after the review
+ *   waits for a `chant approve` of the new digest.
+ *
+ * What counts as an approving review, per forge:
+ *
+ * | Forge | Counts | Writer |
+ * |---|---|---|
+ * | GitHub | the reviewer's newest deciding review is `APPROVED` and names the head (`commit_id`) | `GET /repos/{repo}/collaborators/{login}/permission` is `admin`, `maintain` or `write` |
+ * | Forgejo | the same, not dismissed and not stale | the review is `official`, which Forgejo sets for a reviewer with write access |
+ * | GitLab | the merge request's approvals, when the project removes approvals on a new push (`reset_approvals_on_push`), since a GitLab approval names no commit | the approver's access level is Developer (30) or higher |
+ *
+ * A standing review that requests changes, from a writer, holds the review
+ * back. The author's own review never counts.
+ */
+
+import { readFileSync } from "node:fs";
+import { checkGateSeal } from "../workspace/trust/seal";
+import { readTrustPolicy, type TrustPolicy } from "../workspace/trust/policy";
+import { gitRevisionSource } from "../workspace/record-source";
+import { forgePrincipalOf, ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import type { GateApprovalRule } from "./gate";
+
+export { GATE_APPROVAL_SOURCES, type GateApprovalSource } from "./op-waves";
+
+// ── sealed ────────────────────────────────────────────────────────────────
+
+/** The signers policy at `base`, read from the repository at `cwd`. */
+export function trustPolicyAt(cwd: string, base: string): TrustPolicy {
+  return readTrustPolicy(gitRevisionSource(cwd, base), base);
+}
+
+/**
+ * The rule a `sealed` gate judges approvals by: a seal that verifies for the
+ * approver against `policy`, the signers at base. With no signers file at
+ * base nothing verifies, so nothing passes the gate.
+ */
+export function sealedApprovalRule(gate: string, policy: TrustPolicy): GateApprovalRule {
+  return {
+    requirement: { gate, class: null },
+    refuses(approval: GateResolutionRecord): string | null {
+      if (!policy.active) {
+        return `the gate is sealed, and there is no signers file (${policy.signersPath}) at base ${policy.base?.slice(0, 12) ?? ""}`.trim();
+      }
+      const check = checkGateSeal(policy, approval);
+      return check.attested === true ? null : check.message;
+    },
+  };
+}
+
+/** Both rules at once: an approval counts only when neither refuses it. */
+export function bothRules(a: GateApprovalRule | null, b: GateApprovalRule | null): GateApprovalRule | null {
+  if (!a) return b;
+  if (!b) return a;
+  return { requirement: a.requirement, refuses: (r) => a.refuses(r) ?? b.refuses(r) };
+}
+
+// ── pr-review ─────────────────────────────────────────────────────────────
+
+/** The digests each wave planned at one commit, recorded for a review of it to approve. */
+export interface HeadPlans {
+  version: 1;
+  /** The Op waves spec's name. */
+  name: string;
+  /** The commit the waves were planned at: a pull request's head. */
+  head: string;
+  timestamp: string;
+  waves: Array<{ wave: number; name: string; digest: string }>;
+}
+
+/** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
+export const HEAD_PLANS_DIR = "_wave-plans";
+
+export function headPlansPath(name: string, head: string): { dir: string; file: string } {
+  return { dir: `${HEAD_PLANS_DIR}/${name}`, file: `${head}.json` };
+}
+
+/** The merged pull request's review, as a `pr-review` gate reads it. */
+export interface MergedReview {
+  pr: number;
+  url?: string;
+  /** The author, as a principal (`github:<login>`). */
+  author: string;
+  /** The pull request's head commit. */
+  head: string;
+  /** Writers other than the author whose approval of the head stands, as principals. */
+  approvers: string[];
+  /** Why a review did not count, one line each. */
+  refused: string[];
+}
+
+/** What a `pr-review` gate asks of the forge. */
+export interface ReviewSource {
+  kind: ForgeKind;
+  /** The merged pull request whose merge produced `sha`, with its review, or null when none did. */
+  mergedReview(sha: string): Promise<MergedReview | null>;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+const trimSlash = (s: string): string => s.replace(/\/+$/, "");
+
+function client(base: string, headers: Record<string, string>, fetchImpl: ForgeFetch) {
+  return async (path: string): Promise<unknown> => {
+    const url = `${trimSlash(base)}${path}`;
+    const res = await fetchImpl(url, { method: "GET", headers });
+    const text = await res.text();
+    if (!res.ok) throw new ForgeApiError("GET", url, res.status, text);
+    return text ? JSON.parse(text) : null;
+  };
+}
+
+const hostOf = (url: string | undefined, fallback: string): string => {
+  try {
+    return url ? new URL(url).host.toLowerCase() : fallback;
+  } catch {
+    return fallback;
+  }
+};
+
+export interface ReviewSourceOptions {
+  apiBase: string;
+  /** `owner/name` on GitHub and Forgejo, the project id on GitLab. */
+  repo: string;
+  token: string;
+  /** The forge's host, for naming people. */
+  host: string;
+  fetch?: ForgeFetch;
+}
+
+/** GitHub or Forgejo, which share the pull request and review shapes. */
+function githubShapedReviews(kind: "github" | "forgejo", opts: ReviewSourceOptions): ReviewSource {
+  const get = client(
+    opts.apiBase,
+    kind === "github"
+      ? { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }
+      : { Authorization: `token ${opts.token}`, Accept: "application/json" },
+    opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch),
+  );
+  const repo = `/repos/${opts.repo}`;
+  const who = (login: string) => forgePrincipalOf(kind, opts.host, login);
+  const page = kind === "github" ? "per_page=100" : "limit=50";
+  async function prFor(sha: string): Promise<number | null> {
+    if (kind === "forgejo") {
+      try {
+        const pr = await get(`${repo}/commits/${sha}/pull`);
+        return isObject(pr) && typeof pr.number === "number" ? pr.number : null;
+      } catch (err) {
+        if (err instanceof ForgeApiError && err.status === 404) return null;
+        throw err;
+      }
+    }
+    const prs = await get(`${repo}/commits/${sha}/pulls`);
+    if (!Array.isArray(prs)) return null;
+    const merged = prs.filter((p) => isObject(p) && p.merged_at);
+    const pick = (merged.find((p) => isObject(p) && p.merge_commit_sha === sha) ?? merged[0]) as Record<string, unknown> | undefined;
+    return pick && typeof pick.number === "number" ? pick.number : null;
+  }
+  async function writer(login: string): Promise<boolean> {
+    const p = await get(`${repo}/collaborators/${encodeURIComponent(login)}/permission`);
+    return isObject(p) && ["admin", "maintain", "write", "owner"].includes(String(p.role_name ?? p.permission));
+  }
+  return {
+    kind,
+    async mergedReview(sha) {
+      const number = await prFor(sha);
+      if (number === null) return null;
+      const pr = await get(`${repo}/pulls/${number}`);
+      if (!isObject(pr) || !isObject(pr.user) || !isObject(pr.head)) throw new Error(`pull request #${number} came back without its author or head`);
+      const authorLogin = String(pr.user.login);
+      const head = String(pr.head.sha);
+      const reviews = await get(`${repo}/pulls/${number}/reviews?${page}`);
+      // A reviewer's newest deciding review is their standing one.
+      const standing = new Map<string, Record<string, unknown>>();
+      for (const r of Array.isArray(reviews) ? reviews : []) {
+        if (!isObject(r) || !isObject(r.user) || typeof r.state !== "string") continue;
+        const state = r.state.toUpperCase();
+        if (state === "COMMENTED" || state === "COMMENT" || state === "PENDING") continue;
+        standing.set(String(r.user.login), r);
+      }
+      const approvers: string[] = [];
+      const refused: string[] = [];
+      let changesRequested = false;
+      for (const [login, r] of standing) {
+        const state = r.dismissed === true ? "DISMISSED" : String(r.state).toUpperCase();
+        if (login.toLowerCase() === authorLogin.toLowerCase()) {
+          if (state === "APPROVED") refused.push(`${who(login)} is the author, whose own review never counts`);
+          continue;
+        }
+        const isWriter = kind === "forgejo" ? r.official === true : await writer(login);
+        if (state === "REQUEST_CHANGES" || state === "CHANGES_REQUESTED") {
+          if (isWriter) changesRequested = true;
+          refused.push(`${who(login)} requests changes`);
+          continue;
+        }
+        if (state !== "APPROVED") continue;
+        if (!isWriter) refused.push(`${who(login)} approved without write access${kind === "forgejo" ? " (the review is not official)" : ""}`);
+        else if (r.commit_id !== head || r.stale === true) refused.push(`${who(login)} approved ${String(r.commit_id ?? "another commit").slice(0, 12)}, not the head ${head.slice(0, 12)}`);
+        else approvers.push(who(login));
+      }
+      return {
+        pr: number,
+        ...(typeof pr.html_url === "string" ? { url: pr.html_url } : {}),
+        author: who(authorLogin),
+        head,
+        approvers: changesRequested ? [] : approvers.sort(),
+        refused,
+      };
+    },
+  };
+}
+
+/** A GitHub reader of pull request reviews. The token needs `pull-requests: read`. */
+export function githubReviews(opts: ReviewSourceOptions): ReviewSource {
+  return githubShapedReviews("github", opts);
+}
+
+/** A Forgejo (or Gitea) reader of pull request reviews. */
+export function forgejoReviews(opts: ReviewSourceOptions): ReviewSource {
+  return githubShapedReviews("forgejo", opts);
+}
+
+/** A GitLab reader of merge request approvals. The token needs `read_api`. */
+export function gitlabReviews(opts: ReviewSourceOptions): ReviewSource {
+  const get = client(opts.apiBase, { "PRIVATE-TOKEN": opts.token }, opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch));
+  const project = `/projects/${encodeURIComponent(decodeURIComponent(opts.repo))}`;
+  const who = (login: string) => forgePrincipalOf("gitlab", opts.host, login);
+  return {
+    kind: "gitlab",
+    async mergedReview(sha) {
+      const mrs = await get(`${project}/repository/commits/${sha}/merge_requests`);
+      const merged = Array.isArray(mrs)
+        ? mrs.find((m) => isObject(m) && m.state === "merged" && (m.merge_commit_sha === sha || m.squash_commit_sha === sha)) ??
+          mrs.find((m) => isObject(m) && m.state === "merged")
+        : undefined;
+      if (!isObject(merged) || typeof merged.iid !== "number") return null;
+      const iid = merged.iid;
+      const author = isObject(merged.author) ? String(merged.author.username) : "";
+      const head = String(merged.sha);
+      const settings = await get(`${project}/approvals`);
+      const resets = isObject(settings) && settings.reset_approvals_on_push === true;
+      const approvals = await get(`${project}/merge_requests/${iid}/approvals`);
+      const by = isObject(approvals) && Array.isArray(approvals.approved_by) ? approvals.approved_by : [];
+      const approvers: string[] = [];
+      const refused: string[] = [];
+      for (const a of by) {
+        const user = isObject(a) && isObject(a.user) ? a.user : undefined;
+        if (!user || typeof user.username !== "string") continue;
+        const login = user.username;
+        if (login.toLowerCase() === author.toLowerCase()) {
+          refused.push(`${who(login)} is the author, whose own approval never counts`);
+          continue;
+        }
+        if (!resets) {
+          refused.push(`${who(login)}'s approval names no commit, and the project keeps approvals after a new push (turn on "Remove all approvals when commits are added")`);
+          continue;
+        }
+        const member = await get(`${project}/members/all/${String(user.id)}`).catch((err) => {
+          if (err instanceof ForgeApiError && err.status === 404) return null;
+          throw err;
+        });
+        if (!isObject(member) || typeof member.access_level !== "number" || member.access_level < 30) {
+          refused.push(`${who(login)} approved without the Developer role`);
+          continue;
+        }
+        approvers.push(who(login));
+      }
+      return {
+        pr: iid,
+        ...(typeof merged.web_url === "string" ? { url: merged.web_url } : {}),
+        author: who(author),
+        head,
+        approvers: approvers.sort(),
+        refused,
+      };
+    },
+  };
+}
+
+/**
+ * The review source for the CI job this runs in: GitLab CI, Forgejo Actions
+ * or GitHub Actions, told apart as `./gate-resume.ts` does. The token is
+ * `CHANT_FORGE_TOKEN`, else `GITHUB_TOKEN`/`GH_TOKEN` or `GITLAB_TOKEN`.
+ * Throws naming what is missing.
+ */
+export function reviewSourceFromEnv(env: Record<string, string | undefined> = process.env, fetchImpl?: ForgeFetch): ReviewSource {
+  const f = fetchImpl ? { fetch: fetchImpl } : {};
+  if (env.GITLAB_CI === "true") {
+    const token = env.CHANT_FORGE_TOKEN ?? env.GITLAB_TOKEN;
+    if (!env.CI_API_V4_URL || !env.CI_PROJECT_ID || !token) {
+      throw new Error("a pr-review gate on GitLab needs CI_API_V4_URL, CI_PROJECT_ID and CHANT_FORGE_TOKEN (a token with read_api)");
+    }
+    return gitlabReviews({ apiBase: env.CI_API_V4_URL, repo: env.CI_PROJECT_ID, token, host: env.CI_SERVER_HOST ?? hostOf(env.CI_SERVER_URL, "gitlab.com"), ...f });
+  }
+  const token = env.CHANT_FORGE_TOKEN ?? env.GITHUB_TOKEN ?? env.GH_TOKEN;
+  if (!env.GITHUB_REPOSITORY || !token) {
+    throw new Error("a pr-review gate needs GITHUB_REPOSITORY and a token (GITHUB_TOKEN with pull-requests: read, or CHANT_FORGE_TOKEN)");
+  }
+  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true";
+  const host = hostOf(env.GITHUB_SERVER_URL, "github.com");
+  const opts = { apiBase: env.GITHUB_API_URL ?? (forgejo ? `${trimSlash(env.GITHUB_SERVER_URL ?? "")}/api/v1` : "https://api.github.com"), repo: env.GITHUB_REPOSITORY, token, host, ...f };
+  return forgejo ? forgejoReviews(opts) : githubReviews(opts);
+}
+
+/**
+ * The head of the pull request a CI job runs for, from its environment: the
+ * event payload's `pull_request.head.sha` on GitHub and Forgejo (whose
+ * checkout is a merge preview, not the head), and on GitLab the merge
+ * request's source commit. Undefined outside a pull request's pipeline.
+ */
+export function pullRequestHeadFromEnv(env: Record<string, string | undefined> = process.env): string | undefined {
+  if (env.GITLAB_CI === "true") {
+    if (!env.CI_MERGE_REQUEST_IID) return undefined;
+    return env.CI_MERGE_REQUEST_SOURCE_BRANCH_SHA || env.CI_COMMIT_SHA || undefined;
+  }
+  if (!env.GITHUB_EVENT_PATH) return undefined;
+  try {
+    const event = JSON.parse(readFileSync(env.GITHUB_EVENT_PATH, "utf-8")) as { pull_request?: { head?: { sha?: unknown } } };
+    const sha = event.pull_request?.head?.sha;
+    return typeof sha === "string" && sha !== "" ? sha : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/op/gate.ts

@@ -52,6 +52,7 @@ import { sortedJsonReplacer } from "../utils";
 import type { GateApprover, ResolvedGateApproval } from "./gate-approval";
 import { pushLifecycle, requireLifecycleLedger } from "../lifecycle/git";
 import { parseDuration } from "./duration";
+import { resolveGateRunLocator } from "./gate-resume";
 
 /**
  * What appending a pending fact learned about reaching the remote.
@@ -505,6 +506,8 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   }
 
   const url = resolveApprovalUrl();
+  // #3683: in CI, where this job runs, so an approval can start it again.
+  const resume = resolveGateRunLocator();
   const { record, pushed, pushWarning } = await port.appendPending({
     op: input.op,
     gate: input.gate,
@@ -515,6 +518,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(input.description ? { description: input.description } : {}),
     ...(input.runId ? { runId: input.runId } : {}),
     ...(url ? { url } : {}),
+    ...(resume ? { resume } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
     ...(env !== undefined ? { environment: env } : {}),
     ...(input.approval ? { approval: input.approval } : {}),

package/src/op/op-waves-run.ts

@@ -11,6 +11,11 @@
  *   needs an approval waits on `<gate>-wave-<k>` bound to
  *   {@link waveSetDigest} over its members, and exits 3 when nobody approved
  *   that digest.
+ * - Which approvals count is the wave's `approval`, read at base like its
+ *   policy (#3684): `ledger`, `sealed` or `pr-review` (`./gate-review.ts`).
+ *   Under `pr-review` the pull request's pipeline runs `--record-plans`
+ *   ({@link recordOpWaveHeadPlans}), which plans every wave at the head and
+ *   records the digests a review of that head approves.
  * - Apply: each run's `apply` command. A share job (`--share i`) re-plans its
  *   slice first and refuses, without applying it, a run whose plan digest is
  *   not the one the deciding job recorded (exit 4).
@@ -21,12 +26,16 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, posix } from "node:path";
 import { waveGateName, waveSetDigest, type WaveMember } from "../gated-waves";
 import { approveCommand, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
+import type { TrustPolicy } from "../workspace/trust/policy";
 import {
   OP_WAVE_DEFAULT_APPLY,
   OP_WAVE_GATE_POLICIES,
+  GATE_APPROVAL_SOURCES,
   assertOpWavesSpec,
   opWaveRecordPath,
   opWaveShare,
+  type GateApprovalSource,
   type OpWaveGatePolicy,
   type OpWaveRun,
   type OpWavesSpec,
@@ -59,6 +68,8 @@ export interface OpWaveDecision {
   op: string;
   gate: string;
   policy: OpWaveGatePolicy;
+  /** Which approvals count, read at base with the policy (#3684). */
+  approval: GateApprovalSource;
   policySource: OpWavePolicySource;
   /** The base commit the policy was read at. */
   base: string;
@@ -67,6 +78,10 @@ export interface OpWaveDecision {
   /** `approved`: an approval of this digest stands. `not-required`: the policy lets it through. `waiting`: neither. */
   status: "approved" | "not-required" | "waiting";
   approvedBy?: string;
+  /** How the approval arrived: a resolution on the ledger, or the merged pull request's review (#3684). */
+  via?: "ledger" | "pr-review";
+  /** The review that approved the wave, or why the review did not, under `pr-review`. */
+  review?: { pr?: number; head?: string; approvers?: string[]; url?: string; reason?: string };
   /** The command that approves this digest, when waiting. */
   approve?: string;
 }
@@ -128,19 +143,22 @@ export function readOpWavePolicy(
   base: string,
   cwd: string,
   show: OpWaveShowAtBase = gitShowAtBase,
-): { policy: OpWaveGatePolicy; source: OpWavePolicySource; base: string } {
+): { policy: OpWaveGatePolicy; approval: GateApprovalSource; source: OpWavePolicySource; base: string } {
   const { sha, text } = show(base, specFile.replace(/^\.\//, "").split("\\").join(posix.sep), cwd);
-  if (text === null) return { policy: "always", source: "absent-at-base", base: sha };
+  const absent = { policy: "always" as const, approval: "ledger" as const, source: "absent-at-base" as const, base: sha };
+  if (text === null) return absent;
   let spec: OpWavesSpec;
   try {
     spec = parseOpWavesSpec(text, `${specFile} at ${base}`);
   } catch {
-    return { policy: "always", source: "absent-at-base", base: sha };
+    return absent;
   }
   const wave = spec.waves.find((w) => w.name === name);
-  if (!wave) return { policy: "always", source: "absent-at-base", base: sha };
+  if (!wave) return absent;
   const policy = wave.gate ?? "always";
-  return { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", source: "base", base: sha };
+  // An approval mode this chant does not know reads as sealed: the strictest, so an unknown rule never loosens a gate.
+  const approval = wave.approval === undefined ? "ledger" : GATE_APPROVAL_SOURCES.includes(wave.approval) ? wave.approval : "sealed";
+  return { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha };
 }
 
 /** Fill one argv template for one run. */
@@ -172,6 +190,14 @@ export interface RunOpWaveOptions {
   show?: OpWaveShowAtBase;
   now?: string;
   log?: (line: string) => void;
+  /** The applied commit, which a `pr-review` gate finds the merged pull request by. Default `git rev-parse HEAD`. */
+  head?: string;
+  /** The forge's reviews, for a `pr-review` gate. Default: the CI job's forge (`reviewSourceFromEnv`). */
+  reviews?: ReviewSource;
+  /** The plans recorded for a pull request's head. Default: read from `chant/lifecycle`. */
+  headPlans?: (name: string, head: string) => Promise<HeadPlans | null>;
+  /** The signers policy at base, for a `sealed` gate. Default: read from the base commit. */
+  trust?: (base: string) => TrustPolicy;
 }
 
 export interface RunOpWaveResult {
@@ -268,23 +294,50 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
 
   const members = wave.runs.map((run) => planRun(ctx, wave.name, run));
   const digest = waveSetDigest(members);
-  const { policy, source, base } = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
+  const { policy, approval, source, base } = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
   const gate = waveGateName(spec.gate ?? spec.name, k);
-  const decision: OpWaveDecision = { wave: k, name: wave.name, op: spec.name, gate, policy, policySource: source, base, digest, members, status: "not-required" };
+  const decision: OpWaveDecision = { wave: k, name: wave.name, op: spec.name, gate, policy, approval, policySource: source, base, digest, members, status: "not-required" };
   if (opWaveNeedsApproval(policy, members)) {
-    const check = await evaluateGate(options.gates ?? gitGateLedgerPort({ cwd }), {
+    const ledger = options.gates ?? gitGateLedgerPort({ cwd });
+    let port = ledger;
+    if (approval === "sealed") {
+      // #3684: only an approval sealed by a signer listed at base counts.
+      const review = await import("./gate-review");
+      const sealed = review.sealedApprovalRule(gate, (options.trust ?? ((b) => review.trustPolicyAt(cwd, b)))(base));
+      port = {
+        ...ledger,
+        async approvalRule(g) {
+          const own = (await ledger.approvalRule?.(g)) ?? null;
+          return g === gate ? review.bothRules(own, sealed) : own;
+        },
+      };
+    }
+    const now = options.now ?? new Date().toISOString();
+    const check = await evaluateGate(port, {
       op: spec.name,
       gate,
       planDigest: digest,
-      description: `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}`,
-      ...(options.now ? { now: options.now } : {}),
+      description: `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}`,
+      now,
     });
     if (check.satisfied) {
       decision.status = "approved";
+      decision.via = "ledger";
       decision.approvedBy = check.resolution.resolvedBy;
+    } else if (approval === "pr-review") {
+      const byReview = await approveByReview(options, { op: spec.name, gate, k, digest, cwd, now, port: ledger });
+      decision.review = byReview.review;
+      if (byReview.approved) {
+        decision.status = "approved";
+        decision.via = "pr-review";
+        decision.approvedBy = byReview.review.approvers!.join(", ");
+      } else {
+        decision.status = "waiting";
+        decision.approve = approveCommand(spec.name, gate, undefined, digest);
+      }
     } else {
       decision.status = "waiting";
-      decision.approve = approveCommand(spec.name, gate, undefined, digest);
+      decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed");
     }
   }
   mkdirSync(dirname(recordPath), { recursive: true });
@@ -292,10 +345,14 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
   result.decision = decision;
   log(
     `wave ${k} (${wave.name}): gate ${policy} (read at ${base.slice(0, 12)}${source === "absent-at-base" ? ", where the wave is absent" : ""}), ` +
-      `digest ${digest}: ${decision.status}${decision.approvedBy ? ` by ${decision.approvedBy}` : ""}`,
+      `digest ${digest}: ${decision.status}${decision.approvedBy ? ` by ${decision.approvedBy}` : ""}` +
+      (decision.via === "pr-review" ? ` (review of #${decision.review?.pr})` : ""),
   );
+  if (approval === "pr-review" && decision.status === "waiting" && decision.review?.reason) {
+    log(`The pull request's review does not approve wave ${k}: ${decision.review.reason}`);
+  }
   if (decision.status === "waiting") {
-    log(`Nothing in wave ${k} or after it ran. Read the plans, then approve: ${decision.approve}`);
+    log(`Nothing in wave ${k} or after it ran. Read the plans, then approve: ${decision.approve} (with --resume, the approval also starts this job again)`);
     return { ...result, exitCode: 3 };
   }
   if (options.decide) return result;
@@ -323,3 +380,124 @@ function applyRun(
     result.failed.push(run.target);
   }
 }
+
+/** What {@link approveByReview} found. */
+interface ReviewOutcome {
+  approved: boolean;
+  review: NonNullable<OpWaveDecision["review"]>;
+}
+
+/**
+ * Under `pr-review` (#3684): the merged pull request's review approves the
+ * wave when a writer other than the author approved its head, and the head
+ * planned this wave's digest. The approval is then written to the ledger as a
+ * resolution that names the review, so the record says how the wave passed.
+ */
+async function approveByReview(
+  options: RunOpWaveOptions,
+  at: { op: string; gate: string; k: number; digest: string; cwd: string; now: string; port: GateLedgerPort },
+): Promise<ReviewOutcome> {
+  const review = await import("./gate-review");
+  const head = options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd: at.cwd, encoding: "utf-8" }).trim();
+  let merged: MergedReview | null;
+  try {
+    merged = await (options.reviews ?? review.reviewSourceFromEnv()).mergedReview(head);
+  } catch (err) {
+    return { approved: false, review: { reason: `the forge's review could not be read: ${err instanceof Error ? err.message : String(err)}` } };
+  }
+  if (!merged) return { approved: false, review: { reason: `no merged pull request produced ${head.slice(0, 12)}` } };
+  const seen = { pr: merged.pr, head: merged.head, ...(merged.url ? { url: merged.url } : {}) };
+  if (merged.approvers.length === 0) {
+    const why = merged.refused.length > 0 ? merged.refused.join("; ") : "nobody approved it";
+    return { approved: false, review: { ...seen, reason: `no writer other than its author approved the head of #${merged.pr}: ${why}` } };
+  }
+  const plans = await (options.headPlans ?? ((name, h) => readHeadPlans(name, h, at.cwd)))(options.spec.name, merged.head);
+  const planned = plans?.waves.find((w) => w.wave === at.k);
+  if (!planned) {
+    return {
+      approved: false,
+      review: { ...seen, approvers: merged.approvers, reason: `no plans are recorded for the head ${merged.head.slice(0, 12)} of #${merged.pr} (its pipeline runs \`chant run wave --record-plans\`)` },
+    };
+  }
+  if (planned.digest !== at.digest) {
+    return {
+      approved: false,
+      review: { ...seen, approvers: merged.approvers, reason: `the plan moved after the review: the head planned ${planned.digest}, and the merge plans ${at.digest}` },
+    };
+  }
+  const note = `approved by the review of #${merged.pr} at ${merged.head.slice(0, 12)}: ${merged.approvers.join(", ")}`;
+  await at.port.appendResolution?.({
+    op: at.op,
+    gate: at.gate,
+    resolvedBy: merged.approvers[0]!,
+    timestamp: at.now,
+    planDigest: at.digest,
+    approver: { kind: "human" },
+    note,
+    ...(merged.url ? { url: merged.url } : {}),
+    review: { pr: merged.pr, head: merged.head, approvers: merged.approvers },
+  });
+  return { approved: true, review: { ...seen, approvers: merged.approvers } };
+}
+
+async function readHeadPlans(name: string, head: string, cwd: string): Promise<HeadPlans | null> {
+  const { readBlobFromPath, requireLifecycleLedger } = await import("../lifecycle/git");
+  const { headPlansPath } = await import("./gate-review");
+  await requireLifecycleLedger({ cwd });
+  const { dir, file } = headPlansPath(name, head);
+  const text = await readBlobFromPath(dir, file, { cwd });
+  if (!text) return null;
+  try {
+    return JSON.parse(text) as HeadPlans;
+  } catch {
+    return null;
+  }
+}
+
+export interface RecordHeadPlansOptions {
+  spec: OpWavesSpec;
+  cwd?: string;
+  exec?: OpWaveExec;
+  /** The commit the plans are for. Default: the pull request's head from the CI job's environment, else `git rev-parse HEAD`. */
+  head?: string;
+  now?: string;
+  /** Write the record. Default: append to `chant/lifecycle` and push. */
+  write?: (plans: HeadPlans) => Promise<void>;
+}
+
+/**
+ * `chant run wave --spec <file> --record-plans` (#3684): plan every wave at a
+ * pull request's head and record each wave's digest on `chant/lifecycle`,
+ * `_wave-plans/<name>/<head>.json`. A `pr-review` wave reads it after the
+ * merge: the review of that head approves the digests it planned, and only
+ * those.
+ */
+export async function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Promise<HeadPlans> {
+  const { spec } = options;
+  assertOpWavesSpec(spec);
+  const cwd = options.cwd ?? process.cwd();
+  const exec = options.exec ?? spawnExec;
+  const review = await import("./gate-review");
+  const head = options.head ?? review.pullRequestHeadFromEnv() ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim();
+  const plans: HeadPlans = {
+    version: 1,
+    name: spec.name,
+    head,
+    timestamp: options.now ?? new Date().toISOString(),
+    waves: spec.waves.map((wave, i) => {
+      const members = wave.runs.map((run) => planRun({ spec, wave: i + 1, cwd, exec }, wave.name, run));
+      return { wave: i + 1, name: wave.name, digest: waveSetDigest(members) };
+    }),
+  };
+  await (options.write ?? ((p) => writeHeadPlans(p, cwd)))(plans);
+  return plans;
+}
+
+async function writeHeadPlans(plans: HeadPlans, cwd: string): Promise<void> {
+  const { pushLifecycle, requireLifecycleLedger, writeBlobToPath } = await import("../lifecycle/git");
+  const { headPlansPath } = await import("./gate-review");
+  await requireLifecycleLedger({ cwd });
+  const { dir, file } = headPlansPath(plans.name, plans.head);
+  await writeBlobToPath(dir, file, JSON.stringify(plans, null, 2) + "\n", `Op waves plans of ${plans.name} at ${plans.head.slice(0, 12)}`, { cwd });
+  if (!(await pushLifecycle({ cwd }))) throw new Error("the plans were recorded locally only: chant/lifecycle has no remote to push to");
+}