@intentius/chant 0.124.40 → 0.124.42

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

@@ -68,11 +68,16 @@ import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger"
 import type { GatePointAsker } from "../point-decision";
 import type { WaitingPoint } from "./steward-points";
 import { isApprovalSpent, type AppliedGateRecord } from "../lifecycle/gate-applied";
+import { samePlanDigest } from "../lifecycle/plan-digest";
 import { isLifecycleLocalNote } from "../lifecycle/local-note";
 import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
 import type { TrustPolicy } from "../workspace/trust/policy";
-import type { GateSigners } from "../workspace/trust/gate-seal";
+import type { GateSigners } from "../lifecycle/gate-seal";
 import { ciRunIdFromEnv } from "./gate-run-locator";
+import {
+  quorumProblems, quorumRuleLine, quorumRulesFor, quorumWaiting, ruleNeedsProof, samePrincipal, trustQuorumJudge,
+  type GateQuorumRule, type GateQuorumRuleProgress,
+} from "./gate-quorum";
 import {
   OP_WAVE_DEFAULT_APPLY,
   OP_WAVE_GATE_POLICIES,
@@ -83,6 +88,7 @@ import {
   opWaveApplyHooksRunBy,
   opWaveGateName,
   opWaveHooksAt,
+  opWaveHookRuns,
   opWavePointAt,
   opWavePointProblems,
   opWaveRecordPath,
@@ -99,6 +105,26 @@ import {
   type OpWaveRun,
   type OpWavesSpec,
 } from "./op-waves";
+import {
+  OP_WAVE_PENDING_RESERVED,
+  opWaveArgv,
+  pendingFields,
+  readHoldRequest,
+  runHookList,
+  runStageHooks,
+  spawnExec,
+  type HookPlace,
+  type OpWaveExec,
+  type OpWaveHoldRequest,
+  type OpWaveHookOutcome,
+  type OpWaveHookRun,
+  type OtherGateHold,
+  type RunStageHooksOptions,
+  type StageHooksRun,
+} from "./stage-hooks";
+
+export { OP_WAVE_PENDING_RESERVED, opWaveArgv, runStageHooks };
+export type { OpWaveExec, OpWaveHoldRequest, OpWaveHookOutcome, OpWaveHookRun, RunStageHooksOptions, StageHooksRun };
 
 /** What a run's plan command writes to `{plan}`. */
 export interface OpWavePlanFile {
@@ -113,6 +139,13 @@ export interface OpWavePlanFile {
    * plan digest and these rules counts (`@intentius/chant/override-gate`).
    */
   denied?: { rules: string[]; reason?: string };
+  /**
+   * The product's policy holds this plan for a person (#4294): the ids of
+   * the hold rules that matched. The wave waits for an approval of its set
+   * digest whatever its gate policy says, as a hook with `onFailure:
+   * approve` holds it. `@intentius/chant/gate-policy` gives the rules.
+   */
+  held?: { rules: string[]; reason?: string };
 }
 
 /** What a wave-level plan command writes to `{plans}` (#3762): one plan per run, by target. The array alone is read too. */
@@ -141,12 +174,6 @@ export interface OpWavePlansFile {
   waves?: number;
 }
 
-/** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
-export const OP_WAVE_PENDING_RESERVED = [
-  "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
-  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer", "wave", "heldBy",
-] as const;
-
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
 export interface OpWaveRunsFile {
   /** The wave's name. */
@@ -170,6 +197,8 @@ export interface OpWaveMember extends WaveMember {
   denied?: { rules: string[]; reason?: string };
   /** The override that lets the denied plan through (#3821). */
   override?: { by: string; at: string; digest: string; reason: string };
+  /** The product's policy holds the plan for a person (#4294). */
+  held?: { rules: string[]; reason?: string };
 }
 
 /** Where a wave's policy came from. */
@@ -207,6 +236,10 @@ export interface OpWaveDecision {
   point?: OpWavePoint & { question?: WaitingPoint; answer?: GateAnswerRef };
   /** 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 approval rules at base the wave's targets take (#4290). Absent when it takes none. */
+  quorum?: GateQuorumRule[];
+  /** Where each of those rules stands (#4290), while the wave waits. */
+  quorumProgress?: GateQuorumRuleProgress[];
   /** The command that approves this digest, when waiting. */
   approve?: string;
   /** The hooks read at base (#3762), which a wide wave's share jobs run too. Absent when there are none. */
@@ -286,18 +319,6 @@ export interface OpWaveApplyOutcome {
 
 export const OP_WAVE_APPLY_OUTCOMES = ["stood-down", "held", "replan"] as const;
 
-/** What a hook asks for when it holds a wave on another gate (#3821): it writes this to `CHANT_HOLD` and exits non-zero. */
-export interface OpWaveHoldRequest {
-  /** The op the gate is recorded under. Default: the spec's name. */
-  op?: string;
-  gate: string;
-  /** The digest an approval binds. */
-  digest: string;
-  description?: string;
-  /** Fields for the pending fact, as a plans file's `pending`. */
-  pending?: Record<string, unknown>;
-}
-
 /** A hold on another gate, as the decision records it (#3821). */
 export interface OpWaveHeldOn {
   op: string;
@@ -328,26 +349,6 @@ export interface OpWaveHeldOnApproval {
   approvedAt: string;
 }
 
-/** One hook's run (#3762). */
-export interface OpWaveHookOutcome {
-  moment: OpWaveHookMoment;
-  name: string;
-  /** The run, for a `perRun` hook. */
-  target?: string;
-  exit: number;
-  outcome: "passed" | "failed" | "held" | "skipped";
-  /** Why the moment was skipped, for `skipped` (#3811). */
-  reason?: string;
-}
-
-/** One run as a hook sees it (#3804). */
-export interface OpWaveHookRun {
-  target: string;
-  op: string;
-  /** The run's plan file, once planned. */
-  plan?: string;
-}
-
 /**
  * What chant hands an apply command in `CHANT_HOOKS` (#3804), and what
  * {@link opWaveHooksAtBase} builds for an apply outside the waves. Paths are
@@ -423,15 +424,6 @@ export interface OpWaveApplyHooksRun {
   proceed: boolean;
 }
 
-/** Runs one argv; returns its exit code. `env` is added to the job's environment. Injected so tests run no processes. */
-export type OpWaveExec = (argv: string[], cwd: string, env?: Record<string, string>) => number;
-
-const spawnExec: OpWaveExec = (argv, cwd, env) => {
-  const result = spawnSync(argv[0]!, argv.slice(1), { cwd, stdio: "inherit", ...(env ? { env: { ...process.env, ...env } } : {}) });
-  if (result.error) throw result.error;
-  return result.status ?? 1;
-};
-
 /** Reads one file at one commit, or null when the commit has no such file. Injected for tests. */
 export type OpWaveShowAtBase = (base: string, path: string, cwd: string) => { sha: string; text: string | null };
 
@@ -489,6 +481,10 @@ export interface OpWaveBaseRules {
   point?: OpWavePoint;
   /** Set when the point at base cannot be asked: the wave fails rather than fall back to the ledger (#3836). */
   pointRefused?: string;
+  /** The approval rules at base (#4290), `approvals.quorum`. */
+  quorum?: GateQuorumRule[];
+  /** Set when the rules at base cannot be read: the wave fails rather than wait on fewer approvers than they ask. */
+  quorumRefused?: string;
 }
 
 const noHooks = (): Record<OpWaveHookMoment, OpWaveHook[]> =>
@@ -521,7 +517,7 @@ export function readOpWavePolicy(
   const spend = (spec as { approvals?: { spend?: unknown } }).approvals?.spend === true;
   const neverOverMcp = (spec as { neverOverMcp?: unknown }).neverOverMcp === true;
   // #3836: the gate's decision point, the spec's for a wave the base does not have yet.
-  const asks = pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`);
+  const asks = { ...pointAtBase(spec, name, `${specFile} at ${sha.slice(0, 12)}`), ...quorumAtBase(spec, `${specFile} at ${sha.slice(0, 12)}`) };
   const wave = spec.waves.find((w) => w.name === name);
   if (!wave) return { ...absent, spend, neverOverMcp, ...asks };
   const policy = wave.gate ?? "always";
@@ -540,6 +536,15 @@ export function readOpWavePolicy(
   return rules;
 }
 
+/** The approval rules at base (#4290), or why they cannot be read. A spec at base with none has none. */
+function quorumAtBase(spec: OpWavesSpec, where: string): Pick<OpWaveBaseRules, "quorum" | "quorumRefused"> {
+  const raw = (spec as { approvals?: { quorum?: unknown } }).approvals?.quorum;
+  if (raw === undefined) return {};
+  const problems = Array.isArray(raw) ? quorumProblems(raw, "approvals.quorum", { notAuthor: true }) : ["`approvals.quorum` must be a list of rules"];
+  if (problems.length > 0) return { quorumRefused: `the approval rules in ${where} cannot be read (${problems.join("; ")})` };
+  return (raw as GateQuorumRule[]).length > 0 ? { quorum: raw as GateQuorumRule[] } : {};
+}
+
 /** The point wave `name` asks at base (#3836), or why it cannot be asked. */
 function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWaveBaseRules, "point" | "pointRefused"> {
   const raw = spec.waves.find((w) => w.name === name)?.point ?? spec.point;
@@ -549,22 +554,6 @@ function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWav
   return { point: opWavePointAt(spec, name)! };
 }
 
-/** Fill one argv template. A placeholder whose value is not given is left as it is. */
-export function opWaveArgv(
-  template: readonly string[],
-  values: { op: string; wave: string; target?: string; plan?: string; runs?: string; plans?: string },
-): string[] {
-  const pairs: Array<[string, string | undefined]> = [
-    ["{op}", values.op],
-    ["{target}", values.target],
-    ["{wave}", values.wave],
-    ["{plans}", values.plans],
-    ["{plan}", values.plan],
-    ["{runs}", values.runs],
-  ];
-  return template.map((part) => pairs.reduce((out, [key, value]) => (value === undefined ? out : out.replaceAll(key, value)), part));
-}
-
 /** Where a run's plan file goes. */
 export function opWavePlanPath(spec: Pick<OpWavesSpec, "name">, wave: number, target: string): string {
   return `.chant/op-waves/${spec.name}/wave-${wave}/${target.replace(/[^A-Za-z0-9._-]/g, "_")}.plan.json`;
@@ -674,11 +663,12 @@ function planRun(opts: { spec: OpWavesSpec; wave: number; cwd: string; exec: OpW
 }
 
 function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember {
-  const denied = file.denied as unknown;
-  if (denied !== undefined) {
-    const d = denied as { rules?: unknown; reason?: unknown } | null;
+  for (const key of ["denied", "held"] as const) {
+    const value = file[key] as unknown;
+    if (value === undefined) continue;
+    const d = value as { rules?: unknown; reason?: unknown } | null;
     if (!d || typeof d !== "object" || !Array.isArray(d.rules) || d.rules.length === 0 || !d.rules.every((r) => typeof r === "string" && r.trim() !== "") || (d.reason !== undefined && typeof d.reason !== "string")) {
-      throw new Error(`the plan of ${target} has denied ${JSON.stringify(denied)}; a denial is { "rules": ["<rule id>", ...], "reason"?: "<text>" }`);
+      throw new Error(`the plan of ${target} has ${key} ${JSON.stringify(value)}; ${key === "denied" ? "a denial" : "a hold"} is { "rules": ["<rule id>", ...], "reason"?: "<text>" }`);
     }
   }
   return {
@@ -688,6 +678,7 @@ function member(target: string, op: string, file: OpWavePlanFile): OpWaveMember
     ...(file.destructive === true ? { destructive: true } : {}),
     ...(file.empty === true ? { empty: true } : {}),
     ...(file.denied ? { denied: { rules: file.denied.rules, ...(file.denied.reason ? { reason: file.denied.reason } : {}) } } : {}),
+    ...(file.held ? { held: { rules: [...new Set(file.held.rules)].sort(), ...(file.held.reason ? { reason: file.held.reason } : {}) } } : {}),
   };
 }
 
@@ -768,7 +759,7 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
   const members = runs.map((run) => {
     const m = member(run.target, run.op ?? spec.op, byTarget.get(run.target)!);
     const path = join(cwd, opWavePlanPath(spec, k, run.target));
-    writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}), ...(m.denied ? { denied: m.denied } : {}) }) + "\n");
+    writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}), ...(m.denied ? { denied: m.denied } : {}), ...(m.held ? { held: m.held } : {}) }) + "\n");
     return m;
   });
   const overriders = Array.isArray(parsed) ? undefined : (parsed as { overriders?: unknown }).overriders;
@@ -819,16 +810,6 @@ function extraMembers(value: unknown, targets: ReadonlySet<string>, where: strin
   return out.length > 0 ? out : undefined;
 }
 
-/** A plans file's `pending` (#3821): an object whose keys chant does not write itself, `description` aside. Undefined when absent or empty. */
-function pendingFields(value: unknown, where: string): Record<string, unknown> | undefined {
-  if (value === undefined) return undefined;
-  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${where}: \`pending\` must be an object of fields for the pending fact`);
-  const reserved = Object.keys(value).filter((key) => (OP_WAVE_PENDING_RESERVED as readonly string[]).includes(key));
-  if (reserved.length > 0) throw new Error(`${where}: \`pending\` sets ${reserved.join(", ")}, which chant writes itself`);
-  if ("description" in value && typeof (value as { description?: unknown }).description !== "string") throw new Error(`${where}: pending.description must be a string`);
-  return Object.keys(value).length > 0 ? (value as Record<string, unknown>) : undefined;
-}
-
 /**
  * A wave's set digest (#3821): {@link waveSetDigest} over its runs' plans,
  * or under `digest.over: "changing"` over the runs whose plan is not empty,
@@ -849,107 +830,6 @@ interface HooksOutcome {
   waitingOn?: OpWaveHeldOn;
 }
 
-/** A hook call that held the wave on another gate (#3821), kept so it can run again once that gate is approved. */
-interface OtherGateHold {
-  label: string;
-  name: string;
-  moment: OpWaveHookMoment;
-  target?: string;
-  argv: string[];
-  env: Record<string, string>;
-  request: OpWaveHoldRequest;
-}
-
-/** Read the hold file a hook wrote (#3821), or undefined when it wrote none or one that names no gate and digest. */
-function readHoldRequest(path: string, log: (line: string) => void, label: string): OpWaveHoldRequest | undefined {
-  if (!existsSync(path)) return undefined;
-  try {
-    const r = JSON.parse(readFileSync(path, "utf-8")) as Partial<OpWaveHoldRequest>;
-    if (typeof r.gate !== "string" || r.gate === "" || typeof r.digest !== "string" || r.digest === "") throw new Error("it names no gate and digest");
-    if (r.op !== undefined && (typeof r.op !== "string" || r.op === "")) throw new Error("its op is not a name");
-    return { gate: r.gate, digest: r.digest, ...(r.op ? { op: r.op } : {}), ...(typeof r.description === "string" ? { description: r.description } : {}), ...(r.pending ? { pending: pendingFields(r.pending, `the hold ${label} wrote`) ?? {} } : {}) };
-  } catch (err) {
-    log(`${label} wrote a hold file that cannot be read (${err instanceof Error ? err.message : String(err)}), so it holds the wave on its set digest`);
-    return undefined;
-  }
-}
-
-/** Where hooks run: the wave they belong to and the job's tools. */
-interface HookPlace {
-  /** The spec's name and `op`. */
-  name: string;
-  op: string;
-  waveName: string;
-  k: number;
-  cwd: string;
-  exec: OpWaveExec;
-  log: (line: string) => void;
-}
-
-/**
- * Run one moment's hooks, in order: each once for the wave, or once per run
- * for a `perRun` hook. A hook that fails stops the rest, unless its
- * `onFailure` is `approve`: then it holds the wave and the hooks after it run.
- */
-function runHookList(
-  at: HookPlace,
-  moment: OpWaveHookMoment,
-  hooks: readonly OpWaveHook[] | undefined,
-  runs: readonly OpWaveHookRun[],
-  runsPath: string,
-  extraEnv: Record<string, string> = {},
-): HooksOutcome & { outcomes: OpWaveHookOutcome[]; otherGates: OtherGateHold[] } {
-  const out: HooksOutcome & { outcomes: OpWaveHookOutcome[]; otherGates: OtherGateHold[] } = { holds: [], outcomes: [], otherGates: [] };
-  if (!hooks || hooks.length === 0) return out;
-  const { name: specName, op, waveName, k, cwd, exec, log } = at;
-  // #3821: a hook that holds the wave on another gate names it in this file.
-  const holdPath = `.chant/op-waves/${specName}/wave-${k}/hold.json`;
-  const env = { CHANT_OP_WAVES: specName, CHANT_WAVE: waveName, CHANT_WAVE_NUMBER: String(k), CHANT_HOOK: moment, CHANT_RUNS: runsPath, CHANT_HOLD: holdPath, ...extraEnv };
-  for (const hook of hooks) {
-    const name = hook.name ?? (hook.command.join(" ").length > 60 ? `${hook.command.join(" ").slice(0, 57)}...` : hook.command.join(" "));
-    const calls = hook.perRun
-      ? runs.map((run) => ({
-          target: run.target as string | undefined,
-          argv: opWaveArgv(hook.command, { op: run.op, wave: waveName, target: run.target, runs: runsPath, ...(run.plan ? { plan: run.plan } : {}) }),
-          env: { ...env, CHANT_TARGET: run.target, ...(run.plan ? { CHANT_PLAN: run.plan } : {}) } as Record<string, string>,
-        }))
-      : [{ target: undefined, argv: opWaveArgv(hook.command, { op, wave: waveName, runs: runsPath }), env: env as Record<string, string> }];
-    for (const call of calls) {
-      const label = `${moment} hook ${name}${call.target ? ` (${call.target})` : ""}`;
-      let code: number;
-      rmSync(join(cwd, holdPath), { force: true });
-      try {
-        code = exec(call.argv, cwd, call.env);
-      } catch (err) {
-        log(`${label} did not run: ${err instanceof Error ? err.message : String(err)}`);
-        code = 127;
-      }
-      const base = { moment, name, ...(call.target ? { target: call.target } : {}), exit: code };
-      if (code === 0) {
-        out.outcomes.push({ ...base, outcome: "passed" });
-        continue;
-      }
-      if (hook.onFailure === "approve") {
-        out.outcomes.push({ ...base, outcome: "held" });
-        const request = readHoldRequest(join(cwd, holdPath), log, label);
-        if (request) {
-          out.otherGates.push({ label, name, moment, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
-          log(`${label} exited ${code} and holds wave ${k} (${waveName}) on gate ${request.op ?? specName} / ${request.gate}, digest ${request.digest}`);
-          continue;
-        }
-        out.holds.push(label);
-        log(`${label} exited ${code}, so wave ${k} (${waveName}) waits for an approval of its set digest`);
-        continue;
-      }
-      out.outcomes.push({ ...base, outcome: "failed" });
-      out.failed = `${label} exited ${code}`;
-      log(out.failed);
-      return out;
-    }
-  }
-  return out;
-}
-
 const placeOf = (ctx: WaveContext): HookPlace => ({ name: ctx.spec.name, op: ctx.spec.op, waveName: ctx.wave.name, k: ctx.k, cwd: ctx.cwd, exec: ctx.exec, log: ctx.log });
 
 const hookRuns = (spec: OpWavesSpec, k: number, runs: readonly OpWaveRun[], members?: ReadonlyMap<string, OpWaveMember>): OpWaveHookRun[] =>
@@ -1034,6 +914,18 @@ async function runHooks(
   return back;
 }
 
+/**
+ * The hooks that run before a job plans (#4288): `before-observe`, then
+ * `before-plan`. A failure or a hold on another gate in the first ends it
+ * there; the holds of both add up.
+ */
+async function runBeforePlanHooks(ctx: WaveContext, hooks: Partial<Record<OpWaveHookMoment, OpWaveHook[]>> | undefined, runs: readonly OpWaveRun[]): Promise<HooksOutcome> {
+  const observe = await runHooks(ctx, "before-observe", hooks?.["before-observe"], runs);
+  if (observe.failed || observe.waitingOn) return observe;
+  const plan = await runHooks(ctx, "before-plan", hooks?.["before-plan"], runs);
+  return { ...plan, holds: [...observe.holds, ...plan.holds] };
+}
+
 /** How many gates one hook call holds a wave on in turn (#3847): the first hold and the holds its approved re-runs ask for. */
 export const OP_WAVE_MAX_CHAINED_HOLDS = 10;
 
@@ -1396,7 +1288,7 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
       log(`${part} of wave ${k} (${wave.name}) holds none of the wave's runs; nothing to apply`);
       return { end: result };
     }
-    const before = await runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
+    const before = await runBeforePlanHooks(ctx, decision.hooks, slice);
     if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in ${part} of wave ${k} was planned or applied`) };
     if (before.waitingOn) return { end: await waitOnOther(ctx, decision, before.waitingOn) };
     const { members } = planRuns(ctx, slice);
@@ -1415,6 +1307,12 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
   noteHooksAtBase(ctx, rules);
   // #3836: a point at base that cannot be asked fails the wave; the ledger never stands in for it.
   if (rules.pointRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`) };
+  // #4290: rules at base that cannot be read fail the wave; fewer approvers never stand in for them.
+  if (rules.quorumRefused) return { end: failed(ctx, `wave ${k} (${wave.name}): ${rules.quorumRefused}, so nothing in it was planned or applied`) };
+  if (rules.quorum && rules.point) return { end: failed(ctx, `wave ${k} (${wave.name}): approvals.quorum and a decision point are both set at ${base.slice(0, 12)}; a gate that asks a point takes its deciders from the point, so nothing in it was planned or applied`) };
+  if (JSON.stringify(spec.approvals?.quorum ?? null) !== JSON.stringify(rules.quorum ?? null)) {
+    log(`wave ${k} (${wave.name}): its approval rules are read at ${base.slice(0, 12)}, and this change's differ; the ones at base hold`);
+  }
   const own = opWavePointAt(spec, wave.name);
   if (JSON.stringify(own) !== JSON.stringify(rules.point)) {
     log(`wave ${k} (${wave.name}): its gate's decision point is read at ${base.slice(0, 12)} (${rules.point?.name ?? "none"}), and this change's differs (${own?.name ?? "none"}); the one at base holds`);
@@ -1445,7 +1343,7 @@ async function planOpWave(options: RunOpWaveOptions, { k, pass }: WaveAttempt<Ru
     ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
     ...(rules.point ? { point: { ...rules.point } } : {}),
   };
-  const before = await runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
+  const before = await runBeforePlanHooks(ctx, rules.hooks, wave.runs);
   if (before.failed) return { end: failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`) };
   if (before.waitingOn) return { end: await decided(ctx, decision, recordPath, before.waitingOn) };
   const { members, pending, overriders, overridersSource, extras, waves: found } = planRuns(ctx, wave.runs, wave.discover === true);
@@ -1519,11 +1417,16 @@ async function decideOpWave(
   const { policy, source, base } = planned.rules;
   decision.digest = digest;
   decision.members = members;
+  // #4290: the rules at base whose targets glob matches one of the wave's runs.
+  const takes = planned.rules.quorum ? quorumRulesFor(planned.rules.quorum, members.map((m) => m.member)) : [];
+  if (takes.length > 0) decision.quorum = takes;
   if (extras) decision.extras = extras;
   if (pending) decision.pending = pending;
   const after = await runHooks(ctx, "after-plan", planned.rules.hooks["after-plan"], wave.runs, planned.planned, digest);
   if (after.failed) return { end: failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`) };
   holds.push(...planned.before, ...after.holds);
+  // #4294: a run the product's policy holds makes the wave wait for a person, as a held hook does.
+  for (const m of members) if (m.held) holds.push(`policy on ${m.member} (${m.held.rules.join(", ")})${m.held.reason ? `: ${m.held.reason}` : ""}`);
   if (holds.length > 0) decision.heldBy = holds;
   if (after.waitingOn) return { end: await decided(ctx, decision, recordPath, after.waitingOn) };
   // #3821: a run the product's policy denied applies only under an override; with none the wave is refused, and no approval is waited for.
@@ -1779,6 +1682,7 @@ function failed(ctx: WaveContext, line: string): RunOpWaveResult {
  */
 async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<void> {
   if (decision.point) return settlePointGate(options, ctx, decision, decision.point);
+  if (decision.quorum?.length) return settleQuorumGate(options, ctx, decision, decision.quorum);
   const { spec, k, wave, cwd } = ctx;
   const { gate, digest, approval, base, policy, members } = decision;
   const { ledger, port } = await gatePort(options, cwd, gate, approval, base);
@@ -1833,6 +1737,116 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
   decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed");
 }
 
+/**
+ * Decide a gate under approval rules (#4290): the rules at base the wave's
+ * targets take, each met by distinct human approvers of the digest. Roles
+ * come from `.chant/trust.json` at base, for an approver a seal proves, or
+ * under `pr-review` the merged pull request's review read from the forge in
+ * this run. That review is written to the ledger once per approving
+ * reviewer, so each counts on their own. `notAuthor` reads the author from
+ * the same pull request; with none, no approver can show they are someone
+ * else and the rule waits.
+ */
+async function settleQuorumGate(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, rules: GateQuorumRule[]): Promise<void> {
+  const { spec, k, wave, cwd, log } = ctx;
+  const { gate, digest, approval, base, policy, members } = decision;
+  const { ledger, port } = await gatePort(options, cwd, gate, approval, base);
+  const now = options.now ?? new Date().toISOString();
+  const spent: AppliedGateRecord[] | undefined = decision.spend === "base" ? ((await ledger.readApplied?.(spec.name)) ?? []).filter((a) => a.gate === gate) : undefined;
+  const review = await import("./gate-review");
+  const trust = (options.trust ?? ((b) => review.trustPolicyAt(cwd, b)))(base);
+  const label = `wave ${k} (${wave.name})`;
+
+  // The merged pull request: its author for notAuthor, and its review under pr-review.
+  let merged: MergedReview | null = null;
+  let unknown: string | undefined;
+  const asks = approval === "pr-review" || rules.some((r) => r.notAuthor);
+  const head = asks ? (options.head ?? execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf-8" }).trim()) : "";
+  if (asks) {
+    try {
+      merged = await (options.reviews ?? review.reviewSourceFromEnv()).mergedReview(head);
+      if (!merged) unknown = `no merged pull request produced ${head.slice(0, 12)}`;
+    } catch (err) {
+      unknown = `the forge's review could not be read: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  }
+  if (unknown && rules.some((r) => r.notAuthor)) log(`${label}: ${unknown}, so the change's author is not known`);
+  if (approval === "pr-review" && unknown) decision.review = { reason: unknown };
+
+  let reviewed: { head: string; approvers: string[] } | undefined;
+  if (approval === "pr-review" && merged) {
+    const plans = merged.approvers.length === 0 ? null : await (options.headPlans ?? ((name, h) => readHeadPlans(name, h, cwd)))(spec.name, merged.head);
+    const { reviewApproval } = await import("../gate-decision");
+    const outcome = reviewApproval(merged, plans?.waves.find((w) => w.wave === k)?.digest, digest);
+    decision.review = outcome.review;
+    const reviewSpent = spent !== undefined && isApprovalSpent(spent, { gate, planDigest: digest, review: { head: merged.head } });
+    if (reviewSpent) decision.review = { ...outcome.review, reason: `a wave already applied ${digest} under the review of #${merged.pr} at ${merged.head.slice(0, 12)}, so the review is spent` };
+    if (outcome.approved && !reviewSpent) {
+      reviewed = { head: merged.head, approvers: merged.approvers };
+      // Each approving reviewer once, so the rules count them one by one.
+      const had = (await ledger.read(spec.name)).resolutions.filter((r) => r.gate === gate && r.review?.head === merged!.head && samePlanDigest(r.planDigest, digest));
+      const note = `approved by the review of #${merged.pr} at ${merged.head.slice(0, 12)}: ${merged.approvers.join(", ")}`;
+      for (const who of merged.approvers) {
+        if (had.some((r) => samePrincipal(r.resolvedBy, who))) continue;
+        await ledger.appendResolution?.({
+          op: spec.name,
+          gate,
+          resolvedBy: who,
+          timestamp: now,
+          planDigest: digest,
+          approver: { kind: "human" },
+          gitSha: head,
+          ...(ciRunIdFromEnv() ? { runId: ciRunIdFromEnv()! } : {}),
+          note,
+          ...(merged.url ? { url: merged.url } : {}),
+          review: { pr: merged.pr, head: merged.head, approvers: merged.approvers },
+        });
+      }
+    }
+  }
+
+  const judge = trustQuorumJudge({
+    signers: trust,
+    roles: trust.roles,
+    ...(merged ? { authors: [merged.author] } : {}),
+    ...(reviewed ? { review: reviewed } : {}),
+  });
+  const held = decision.heldBy?.length ? `, held by ${decision.heldBy.join(", ")}` : "";
+  const check = await decideWaveGate(port, {
+    op: spec.name,
+    gate,
+    digest,
+    description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
+    now,
+    ...(spent ? { spent } : {}),
+    fields: { ...decision.pending, approvalMode: approval },
+    ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
+    approval: { quorum: rules, mode: "log-only" },
+    judge,
+  });
+  if (check.satisfied) {
+    const by = (check.approvals ?? [check.resolution]).map((r) => r.resolvedBy);
+    decision.status = "approved";
+    decision.via = reviewed && check.resolution.review?.head === reviewed.head ? "pr-review" : "ledger";
+    decision.approvedBy = by.join(", ");
+    decision.approvedAt = check.resolution.timestamp;
+    log(`${label}: the approval rules at ${base.slice(0, 12)} are met by ${by.join(", ")}`);
+    return;
+  }
+  logRefused(log, label, check);
+  decision.pendingFact = check.pending;
+  decision.recorded = check.recorded;
+  decision.waitingSince = check.pending.timestamp;
+  if (check.mismatch) decision.mismatch = check.mismatch;
+  if (check.quorum?.rules) {
+    decision.quorumProgress = check.quorum.rules;
+    for (const p of check.quorum.rules) log(`${label}: approval rule ${quorumRuleLine(p)}`);
+    log(`${label}: the approval rules at ${base.slice(0, 12)} are not met (${quorumWaiting(check.quorum.rules)}), so it waits for more approvals of ${digest}`);
+  }
+  decision.status = "waiting";
+  decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed" || rules.some(ruleNeedsProof));
+}
+
 /**
  * Decide a gate that asks a decision point (#3836), as an Op gate with a
  * `point` is decided (#3170): ask it with `gate.planDigest` set to the set