@intentius/chant 0.116.0 → 0.118.0

package/src/op/gate-resume.ts

@@ -0,0 +1,267 @@
+/**
+ * Resume the job that waits at a gate (#3683).
+ *
+ * A CI job that reaches a gate nobody approved records a pending fact on
+ * `chant/lifecycle` and exits 3. Nothing re-runs it when the approval lands,
+ * because a push to the ledger branch starts no pipeline. This module closes
+ * that loop through the forge's API.
+ *
+ * When the job runs in CI, the pending fact it records carries a
+ * {@link GateRunLocator}, read from the job's environment by
+ * {@link resolveGateRunLocator}: which forge, the API base, the repository,
+ * the run, and what the forge needs to start it again. After an approval,
+ * {@link resumeGateRun} starts it again:
+ *
+ * | Forge | Call | Token |
+ * |---|---|---|
+ * | GitHub | `POST /repos/{repo}/actions/runs/{run}/rerun-failed-jobs` | `actions: write` (the job's `GITHUB_TOKEN` with that permission, or a fine-grained token with Actions read and write) |
+ * | GitLab | `POST /projects/{id}/jobs/{job}/retry` | a project or personal access token with the `api` scope and the Developer role; `CI_JOB_TOKEN` cannot retry jobs |
+ * | Forgejo | `POST /repos/{repo}/actions/workflows/{file}/dispatches` on the run's branch | a token with the `write:repository` scope; Forgejo has no API to re-run a run, so it starts a new run of the workflow |
+ *
+ * GitHub re-runs the failed job and the jobs that need it, at the same
+ * commit. GitLab retries the job, and the jobs it skipped run after it. A
+ * Forgejo dispatch runs the whole workflow again at the branch's head, so the
+ * jobs before the gate run again too; they must be safe to repeat (a wave
+ * whose runs already applied plans nothing and applies nothing new).
+ *
+ * Resuming approves nothing. The resumed job decides the gate again from the
+ * ledger, so resuming a run whose approval does not count only makes it wait
+ * again. {@link resumeGateRun} skips a run that is still going, that ended
+ * well, or that was already resumed (a later GitHub attempt, a newer GitLab
+ * job of the same name, a newer Forgejo run of the workflow), so a scheduled
+ * resume job can call it every few minutes without starting a run twice.
+ */
+
+import { ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+import { latestResolutionForPlan } from "../lifecycle/gate-ledger";
+import { tallyGateApprovals } from "./gate";
+
+/** Where the job that recorded a pending fact runs, and what its forge needs to start it again. */
+export interface GateRunLocator {
+  forge: ForgeKind;
+  /** The forge's API base: `$GITHUB_API_URL` (GitHub and Forgejo) or `$CI_API_V4_URL` (GitLab). */
+  api: string;
+  /** `owner/name` on GitHub and Forgejo, the project id on GitLab. */
+  repo: string;
+  /** The run: GitHub's and Forgejo's run id, GitLab's pipeline id. */
+  run: string;
+  /** GitHub: the run attempt that waited. A later attempt means it was already re-run. */
+  attempt?: number;
+  /** GitLab: the job that waited. */
+  job?: string;
+  /** GitLab: that job's name, to find a retry of it. */
+  jobName?: string;
+  /** Forgejo: the workflow file the run came from, which a dispatch names. */
+  workflow?: string;
+  /** Forgejo: the branch a dispatch runs on. */
+  ref?: string;
+  /** The run's page, for a person. */
+  url?: string;
+}
+
+const trimSlash = (s: string): string => s.replace(/\/+$/, "");
+
+/**
+ * The locator of the CI job this process runs in, or undefined outside CI or
+ * when the environment lacks a part a resume needs. Forgejo Actions sets the
+ * `GITHUB_*` variables too, and is told apart by `FORGEJO_ACTIONS` or
+ * `GITEA_ACTIONS`.
+ */
+export function resolveGateRunLocator(env: Record<string, string | undefined> = process.env): GateRunLocator | undefined {
+  if (env.GITLAB_CI === "true") {
+    if (!env.CI_API_V4_URL || !env.CI_PROJECT_ID || !env.CI_PIPELINE_ID || !env.CI_JOB_ID) return undefined;
+    return {
+      forge: "gitlab",
+      api: trimSlash(env.CI_API_V4_URL),
+      repo: env.CI_PROJECT_ID,
+      run: env.CI_PIPELINE_ID,
+      job: env.CI_JOB_ID,
+      ...(env.CI_JOB_NAME ? { jobName: env.CI_JOB_NAME } : {}),
+      ...(env.CI_JOB_URL ? { url: env.CI_JOB_URL } : {}),
+    };
+  }
+  if (env.GITHUB_ACTIONS !== "true" || !env.GITHUB_REPOSITORY || !env.GITHUB_RUN_ID) return undefined;
+  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true";
+  const server = env.GITHUB_SERVER_URL ? trimSlash(env.GITHUB_SERVER_URL) : undefined;
+  const url = server ? `${server}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : undefined;
+  if (forgejo) {
+    const workflow = forgejoWorkflowFile(env);
+    const api = env.GITHUB_API_URL ?? (server ? `${server}/api/v1` : undefined);
+    if (!api || !workflow || !env.GITHUB_REF_NAME) return undefined;
+    return {
+      forge: "forgejo",
+      api: trimSlash(api),
+      repo: env.GITHUB_REPOSITORY,
+      run: env.GITHUB_RUN_ID,
+      workflow,
+      ref: env.GITHUB_REF_NAME,
+      ...(url ? { url } : {}),
+    };
+  }
+  const attempt = Number(env.GITHUB_RUN_ATTEMPT);
+  return {
+    forge: "github",
+    api: trimSlash(env.GITHUB_API_URL ?? "https://api.github.com"),
+    repo: env.GITHUB_REPOSITORY,
+    run: env.GITHUB_RUN_ID,
+    ...(Number.isInteger(attempt) && attempt > 0 ? { attempt } : {}),
+    ...(url ? { url } : {}),
+  };
+}
+
+/**
+ * The workflow file a Forgejo run came from, by its base name. Forgejo names
+ * a workflow by its file (`GITHUB_WORKFLOW`, `deploy.yml`); `GITHUB_WORKFLOW_REF`
+ * (`owner/repo/.forgejo/workflows/deploy.yml@refs/heads/main`) says it too.
+ */
+function forgejoWorkflowFile(env: Record<string, string | undefined>): string | undefined {
+  const fromRef = env.GITHUB_WORKFLOW_REF?.split("@")[0]?.split("/").pop();
+  if (fromRef && /\.ya?ml$/.test(fromRef)) return fromRef;
+  const name = env.GITHUB_WORKFLOW;
+  return name && /\.ya?ml$/.test(name) ? name.split("/").pop() : undefined;
+}
+
+/** Whether `value` is a {@link GateRunLocator} a resume can use. */
+export function isGateRunLocator(value: unknown): value is GateRunLocator {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.api !== "string" || typeof v.repo !== "string" || typeof v.run !== "string") return false;
+  if (v.forge === "github") return true;
+  if (v.forge === "gitlab") return typeof v.job === "string";
+  if (v.forge === "forgejo") return typeof v.workflow === "string" && typeof v.ref === "string";
+  return false;
+}
+
+/** What {@link resumeGateRun} did. */
+export type GateResumeOutcome =
+  | { status: "resumed"; forge: ForgeKind; how: string; url?: string }
+  | { status: "skipped"; forge: ForgeKind; reason: string; url?: string };
+
+export interface ResumeGateRunOptions {
+  token: string;
+  /** The approval's time. A Forgejo run of the workflow created after it means the run was already resumed. */
+  since?: string;
+  fetch?: ForgeFetch;
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+function client(base: string, headers: Record<string, string>, fetchImpl: ForgeFetch) {
+  return async (method: string, path: string, body?: unknown): Promise<unknown> => {
+    const url = `${trimSlash(base)}${path}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: { ...headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await res.text();
+    if (!res.ok) throw new ForgeApiError(method, url, res.status, text);
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  };
+}
+
+/**
+ * Start the job a pending fact's locator names again, or say why not. Throws
+ * {@link ForgeApiError} when the forge refuses a call, such as a token
+ * without the access the table in the module doc lists.
+ */
+export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOptions): Promise<GateResumeOutcome> {
+  const fetchImpl = opts.fetch ?? (globalThis.fetch as unknown as ForgeFetch);
+  const url = loc.url ? { url: loc.url } : {};
+  const skip = (reason: string): GateResumeOutcome => ({ status: "skipped", forge: loc.forge, reason, ...url });
+
+  if (loc.forge === "github") {
+    const call = client(loc.api, { Authorization: `Bearer ${opts.token}`, Accept: "application/vnd.github+json" }, fetchImpl);
+    const path = `/repos/${loc.repo}/actions/runs/${loc.run}`;
+    const run = await call("GET", path);
+    if (!isObject(run)) throw new Error(`GET ${path} returned no run`);
+    if (run.status !== "completed") return skip(`run ${loc.run} is ${String(run.status)}, not finished`);
+    const attempt = typeof run.run_attempt === "number" ? run.run_attempt : undefined;
+    if (loc.attempt !== undefined && attempt !== undefined && attempt > loc.attempt) {
+      return skip(`run ${loc.run} was already re-run (attempt ${attempt}; attempt ${loc.attempt} waited)`);
+    }
+    if (run.conclusion === "success") return skip(`run ${loc.run} succeeded`);
+    await call("POST", `${path}/rerun-failed-jobs`, {});
+    return { status: "resumed", forge: "github", how: `re-ran the failed jobs of run ${loc.run}`, ...url };
+  }
+
+  if (loc.forge === "gitlab") {
+    const call = client(loc.api, { "PRIVATE-TOKEN": opts.token }, fetchImpl);
+    const project = `/projects/${encodeURIComponent(decodeURIComponent(loc.repo))}`;
+    const job = await call("GET", `${project}/jobs/${loc.job}`);
+    if (!isObject(job)) throw new Error(`GET ${project}/jobs/${loc.job} returned no job`);
+    const status = String(job.status);
+    if (status === "success") return skip(`job ${loc.job} succeeded`);
+    if (!["failed", "canceled", "skipped"].includes(status)) return skip(`job ${loc.job} is ${status}, not finished`);
+    const name = loc.jobName ?? (typeof job.name === "string" ? job.name : undefined);
+    if (name) {
+      // The pipeline's jobs list leaves retried jobs out, so the job of this name is its newest try.
+      const jobs = await call("GET", `${project}/pipelines/${loc.run}/jobs?per_page=100`);
+      const newest = Array.isArray(jobs) ? jobs.find((j) => isObject(j) && j.name === name) : undefined;
+      if (isObject(newest) && String(newest.id) !== String(loc.job)) {
+        return skip(`job ${loc.job} (${name}) was already retried as job ${String(newest.id)}`);
+      }
+    }
+    const retried = await call("POST", `${project}/jobs/${loc.job}/retry`);
+    const id = isObject(retried) && retried.id !== undefined ? ` as job ${String(retried.id)}` : "";
+    return { status: "resumed", forge: "gitlab", how: `retried job ${loc.job}${id}`, ...url };
+  }
+
+  const call = client(loc.api, { Authorization: `token ${opts.token}`, Accept: "application/json" }, fetchImpl);
+  const repo = `/repos/${loc.repo}`;
+  const run = await call("GET", `${repo}/actions/runs/${loc.run}`);
+  if (!isObject(run)) throw new Error(`GET ${repo}/actions/runs/${loc.run} returned no run`);
+  const status = String(run.status);
+  if (status === "success") return skip(`run ${loc.run} succeeded`);
+  if (["waiting", "running", "blocked", "unknown"].includes(status)) return skip(`run ${loc.run} is ${status}, not finished`);
+  const listed = await call("GET", `${repo}/actions/runs?workflow_id=${encodeURIComponent(loc.workflow!)}&limit=50`);
+  const runs = isObject(listed) && Array.isArray(listed.workflow_runs) ? listed.workflow_runs : Array.isArray(listed) ? listed : [];
+  // Forgejo reports `created` in whole seconds.
+  const since = opts.since ? Math.floor(new Date(opts.since).getTime() / 1000) * 1000 : undefined;
+  const later = runs.find(
+    (r) =>
+      isObject(r) && Number(r.id) > Number(loc.run) &&
+      (r.prettyref === undefined || r.prettyref === loc.ref) &&
+      (since === undefined || (typeof r.created === "string" && new Date(r.created).getTime() >= since)),
+  );
+  if (isObject(later)) return skip(`run ${String(later.id)} of ${loc.workflow} started after the approval`);
+  await call("POST", `${repo}/actions/workflows/${encodeURIComponent(loc.workflow!)}/dispatches`, { ref: loc.ref });
+  return { status: "resumed", forge: "forgejo", how: `dispatched ${loc.workflow} on ${loc.ref}`, ...url };
+}
+
+/**
+ * The resolution that answers `standing`, read the way a run decides the gate
+ * (the plan, the environment, the quorum), or undefined. A workspace's
+ * `identity.gates` rule is not applied here: the resumed job applies it, and
+ * waits again when the approval does not count.
+ */
+export function resolutionAnswering(
+  resolutions: readonly GateResolutionRecord[],
+  standing: PendingGateRecord,
+): GateResolutionRecord | undefined {
+  const env = standing.environment;
+  const mine = resolutions.filter((r) => env === undefined || r.environment === env);
+  if (standing.approval) {
+    const tally = tallyGateApprovals(mine, standing.gate, standing.timestamp, standing.planDigest, standing.approval);
+    if (tally.permit) return tally.permit;
+    return tally.counted.length >= tally.need ? tally.counted[tally.counted.length - 1] : undefined;
+  }
+  return latestResolutionForPlan(mine, standing.gate, standing.timestamp, standing.planDigest).resolution;
+}
+
+/**
+ * The token a resume uses: `CHANT_FORGE_TOKEN`, else the forge's own
+ * (`GITHUB_TOKEN` or `GH_TOKEN` on GitHub and Forgejo, `GITLAB_TOKEN` on
+ * GitLab), the same order the pull-request loop reads (`../pr-forge.ts`).
+ */
+export function resumeTokenFromEnv(forge: ForgeKind, env: Record<string, string | undefined> = process.env): string | undefined {
+  if (env.CHANT_FORGE_TOKEN) return env.CHANT_FORGE_TOKEN;
+  return forge === "gitlab" ? env.GITLAB_TOKEN : env.GITHUB_TOKEN ?? env.GH_TOKEN;
+}
+

package/src/op/gate-review.test.ts

@@ -0,0 +1,225 @@
+import { afterAll, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { ForgeFetch } from "../pr-forge";
+import { waveSetDigest } from "../gated-waves";
+import { sealGateApproval } from "../workspace/trust/seal";
+import { TestRepo, hasSshKeygen } from "../workspace/trust/test-repo";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import { memoryGateLedgerPort } from "./gate";
+import { githubReviews, forgejoReviews, gitlabReviews, type MergedReview, type ReviewSource } from "./gate-review";
+import type { OpWavesSpec } from "./op-waves";
+import { recordOpWaveHeadPlans, runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+
+const HEAD = "h".repeat(40);
+const MERGE = "m".repeat(40);
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+/** A fake forge answering GETs by path. */
+function forge(routes: Record<string, unknown>): ForgeFetch {
+  return async (url) => {
+    const { pathname } = new URL(url);
+    if (!(pathname in routes)) return { ok: false, status: 404, text: async () => "not found" };
+    return { ok: true, status: 200, text: async () => JSON.stringify(routes[pathname]) };
+  };
+}
+
+const opts = (fetch: ForgeFetch, apiBase = "https://api.github.com") => ({ apiBase, repo: "acme/db", token: "t", host: "github.com", fetch });
+
+describe("the merged pull request's review", () => {
+  const pr = { number: 7, user: { login: "carol" }, head: { sha: HEAD }, html_url: "https://github.com/acme/db/pull/7" };
+  const base = {
+    "/repos/acme/db/commits/mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm/pulls": [{ number: 7, merged_at: "x", merge_commit_sha: MERGE }],
+    "/repos/acme/db/pulls/7": pr,
+    "/repos/acme/db/collaborators/alice/permission": { permission: "write", role_name: "write" },
+    "/repos/acme/db/collaborators/dave/permission": { permission: "read", role_name: "read" },
+  };
+
+  test("GitHub: the author's own approval never counts", async () => {
+    const review = await githubReviews(opts(forge({ ...base, "/repos/acme/db/pulls/7/reviews": [{ user: { login: "carol" }, state: "APPROVED", commit_id: HEAD }] }))).mergedReview(MERGE);
+    expect(review).toMatchObject({ pr: 7, author: "github:carol", head: HEAD, approvers: [] });
+    expect(review!.refused[0]).toMatch(/github:carol is the author/);
+  });
+
+  test("GitHub: a writer's approval of the head counts; a reader's, or one of an older commit, does not", async () => {
+    const review = await githubReviews(
+      opts(
+        forge({
+          ...base,
+          "/repos/acme/db/pulls/7/reviews": [
+            { user: { login: "alice" }, state: "APPROVED", commit_id: "old" },
+            { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD },
+            { user: { login: "dave" }, state: "APPROVED", commit_id: HEAD },
+          ],
+        }),
+      ),
+    ).mergedReview(MERGE);
+    expect(review!.approvers).toEqual(["github:alice"]);
+    expect(review!.refused).toEqual(["github:dave approved without write access"]);
+  });
+
+  test("GitHub: a writer who requests changes holds the review back", async () => {
+    const review = await githubReviews(
+      opts(
+        forge({
+          ...base,
+          "/repos/acme/db/collaborators/bob/permission": { permission: "write", role_name: "maintain" },
+          "/repos/acme/db/pulls/7/reviews": [
+            { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD },
+            { user: { login: "bob" }, state: "CHANGES_REQUESTED", commit_id: HEAD },
+          ],
+        }),
+      ),
+    ).mergedReview(MERGE);
+    expect(review!.approvers).toEqual([]);
+  });
+
+  test("Forgejo: only an official review that is neither stale nor dismissed counts", async () => {
+    const review = await forgejoReviews(
+      opts(
+        forge({
+          "/api/v1/repos/acme/db/commits/mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm/pull": { number: 7 },
+          "/api/v1/repos/acme/db/pulls/7": pr,
+          "/api/v1/repos/acme/db/pulls/7/reviews": [
+            { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD, official: true },
+            { user: { login: "dave" }, state: "APPROVED", commit_id: HEAD, official: false },
+            { user: { login: "erin" }, state: "APPROVED", commit_id: HEAD, official: true, stale: true },
+          ],
+        }),
+        "https://code.example.org/api/v1",
+      ),
+    ).mergedReview(MERGE);
+    expect(review!.approvers).toEqual(["forgejo@github.com:alice"]);
+    expect(review!.refused).toHaveLength(2);
+  });
+
+  test("GitLab: an approval counts only where a push removes approvals, and never the author's", async () => {
+    const routes = {
+      "/api/v4/projects/7/repository/commits/mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm/merge_requests": [{ iid: 3, state: "merged", merge_commit_sha: MERGE, sha: HEAD, author: { username: "carol" } }],
+      "/api/v4/projects/7/merge_requests/3/approvals": { approved_by: [{ user: { id: 1, username: "carol" } }, { user: { id: 2, username: "alice" } }] },
+      "/api/v4/projects/7/members/all/2": { access_level: 30 },
+    };
+    const keeps = await gitlabReviews({ ...opts(forge({ ...routes, "/api/v4/projects/7/approvals": { reset_approvals_on_push: false } }), "https://gl/api/v4"), repo: "7", host: "gitlab.com" }).mergedReview(MERGE);
+    expect(keeps!.approvers).toEqual([]);
+    const resets = await gitlabReviews({ ...opts(forge({ ...routes, "/api/v4/projects/7/approvals": { reset_approvals_on_push: true } }), "https://gl/api/v4"), repo: "7", host: "gitlab.com" }).mergedReview(MERGE);
+    expect(resets).toMatchObject({ pr: 3, head: HEAD, approvers: ["gitlab:alice"] });
+    expect(resets!.refused[0]).toMatch(/gitlab:carol is the author/);
+  });
+});
+
+const spec = (approval: "pr-review" | "sealed"): OpWavesSpec => ({
+  name: "migrations",
+  op: "migrate",
+  plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+  apply: ["tool", "apply", "{target}"],
+  waves: [{ name: "prod", runs: [{ target: "prod" }], approval }],
+});
+
+function harness(plan: string, dir?: string) {
+  const cwd = dir ?? mkdtempSync(join(tmpdir(), "gate-review-"));
+  const applied: string[] = [];
+  const exec: OpWaveExec = (argv, at) => {
+    if (argv[1] === "plan") {
+      mkdirSync(join(at, argv[4]!, ".."), { recursive: true });
+      writeFileSync(join(at, argv[4]!), JSON.stringify({ planDigest: plan }));
+    }
+    if (argv[1] === "apply") applied.push(argv[2]!);
+    return 0;
+  };
+  return { cwd, exec, applied };
+}
+
+describe("a pr-review wave (#3684)", () => {
+  const set = (plan: string) => waveSetDigest([{ member: "prod", planDigest: plan }]);
+  const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec("pr-review")) });
+  const reviewed = (approvers: string[], refused: string[] = []): ReviewSource => ({
+    kind: "github",
+    async mergedReview(): Promise<MergedReview> {
+      return { pr: 7, author: "github:carol", head: HEAD, approvers, refused, url: "https://github.com/acme/db/pull/7" };
+    },
+  });
+  const plans = (d: string) => async () => ({ version: 1 as const, name: "migrations", head: HEAD, timestamp: "t", waves: [{ wave: 1, name: "prod", digest: d }] });
+
+  test("the author's own review applies nothing", async () => {
+    const h = harness(digest("a"));
+    const result = await runOpWave({
+      spec: spec("pr-review"), specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show, head: MERGE,
+      gates: memoryGateLedgerPort(), reviews: reviewed([], ["github:carol is the author, whose own review never counts"]), headPlans: plans(set(digest("a"))),
+    });
+    expect(result).toMatchObject({ exitCode: 3, applied: [], decision: { approval: "pr-review", status: "waiting" } });
+    expect(result.decision!.review!.reason).toMatch(/is the author/);
+    expect(h.applied).toEqual([]);
+  });
+
+  test("a writer's review of the head approves the digest the head planned, and the ledger records it", async () => {
+    const h = harness(digest("a"));
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({
+      spec: spec("pr-review"), specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show, head: MERGE,
+      gates, reviews: reviewed(["github:alice"]), headPlans: plans(set(digest("a"))),
+    });
+    expect(result).toMatchObject({ exitCode: 0, applied: ["prod"], decision: { status: "approved", via: "pr-review", approvedBy: "github:alice" } });
+    expect(gates.resolved[0]).toMatchObject({ resolvedBy: "github:alice", planDigest: set(digest("a")), review: { pr: 7, head: HEAD, approvers: ["github:alice"] } });
+  });
+
+  test("a plan that moved after the review waits for a new approval", async () => {
+    const h = harness(digest("b"));
+    const result = await runOpWave({
+      spec: spec("pr-review"), specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show, head: MERGE,
+      gates: memoryGateLedgerPort(), reviews: reviewed(["github:alice"]), headPlans: plans(set(digest("a"))),
+    });
+    expect(result.exitCode).toBe(3);
+    expect(result.decision!.review!.reason).toMatch(/plan moved after the review/);
+  });
+
+  test("--record-plans records each wave's digest at the head", async () => {
+    const h = harness(digest("a"));
+    let written: unknown;
+    const recorded = await recordOpWaveHeadPlans({ spec: spec("pr-review"), cwd: h.cwd, exec: h.exec, head: HEAD, now: "t", write: async (p) => void (written = p) });
+    expect(recorded.waves).toEqual([{ wave: 1, name: "prod", digest: set(digest("a")) }]);
+    expect(written).toEqual(recorded);
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("a sealed wave (#3684)", () => {
+  const repo = new TestRepo("3684-sealed");
+  const alice = repo.key("alice");
+  const mallory = repo.key("mallory");
+  afterAll(() => rmSync(join(repo.dir, ".."), { recursive: true, force: true }));
+
+  // Base: the spec and a signers file listing alice. The applied change adds mallory's key.
+  writeFileSync(join(repo.dir, "waves.json"), JSON.stringify(spec("sealed")));
+  mkdirSync(join(repo.dir, ".chant"), { recursive: true });
+  writeFileSync(join(repo.dir, ".chant/allowed_signers"), `alice ${alice.pub}\n`);
+  repo.git(["add", "-A"]);
+  repo.git(["commit", "-q", "-m", "base"]);
+  writeFileSync(join(repo.dir, ".chant/allowed_signers"), `alice ${alice.pub}\nmallory ${mallory.pub}\n`);
+  repo.git(["add", "-A"]);
+  repo.git(["commit", "-q", "-m", "the change adds a signer"]);
+
+  const plan = digest("a");
+  const set = waveSetDigest([{ member: "prod", planDigest: plan }]);
+  const approval = (by: string, keyFile?: string): GateResolutionRecord => {
+    const a = { op: "migrations", gate: "migrations-wave-1", resolvedBy: by, timestamp: "2026-10-10T00:00:00Z", planDigest: set };
+    return { version: 1, ...a, ...(keyFile ? { seal: sealGateApproval(keyFile, a) } : {}) };
+  };
+  const run = (resolutions: GateResolutionRecord[]) => {
+    const h = harness(plan, repo.dir);
+    return runOpWave({ spec: spec("sealed"), specFile: "waves.json", wave: 1, cwd: repo.dir, exec: h.exec, gates: memoryGateLedgerPort({ resolutions }), now: "2026-10-10T01:00:00Z" });
+  };
+
+  test("an unsigned approval applies nothing, and the hint asks for --sign", async () => {
+    const result = await run([approval("alice")]);
+    expect(result).toMatchObject({ exitCode: 3, decision: { approval: "sealed", status: "waiting" } });
+    expect(result.decision!.approve).toMatch(/--sign$/);
+  });
+
+  test("a seal by a key the change itself added applies nothing", async () => {
+    expect((await run([approval("mallory", mallory.file)])).exitCode).toBe(3);
+  });
+
+  test("a seal by a signer listed at base applies the wave", async () => {
+    expect(await run([approval("alice", alice.file)])).toMatchObject({ exitCode: 0, applied: ["prod"], decision: { status: "approved", approvedBy: "alice" } });
+  });
+});