@intentius/chant 0.124.3 → 0.124.5

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

@@ -44,10 +44,12 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { dirname, isAbsolute, join, posix } from "node:path";
 import { waveSetDigest, type WaveMember } from "../gated-waves";
 import type { ReviewApproval } from "../gate-decision";
-import { approveCommand, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import { approveCommand, evaluateGate, gitGateLedgerPort, type GateDigestMismatch, type GateLedgerPort } from "./gate";
+import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isApprovalSpent, type AppliedGateRecord } from "../lifecycle/gate-applied";
 import type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
 import type { TrustPolicy } from "../workspace/trust/policy";
+import type { GateSigners } from "../workspace/trust/gate-seal";
 import {
   OP_WAVE_DEFAULT_APPLY,
   OP_WAVE_GATE_POLICIES,
@@ -77,6 +79,12 @@ export interface OpWavePlanFile {
   destructive?: boolean;
   /** The plan changes nothing. */
   empty?: boolean;
+  /**
+   * The product's policy denied this plan (#3821): the ids of the rules that
+   * denied it. The wave applies nothing unless an override of this run, its
+   * plan digest and these rules counts (`@intentius/chant/override-gate`).
+   */
+  denied?: { 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. */
@@ -89,6 +97,20 @@ export interface OpWavePlansFile {
    * ...) is refused, except `description`.
    */
   pending?: Record<string, unknown>;
+  /**
+   * Who may override a denial (#3821), for a product that keeps the list in
+   * its own config at base and read it there. Absent: the spec's
+   * `override.overriders` file at base, else `.chant/overriders` at base.
+   */
+  overriders?: string[];
+  /**
+   * Digest members that are not runs (#3821), such as the wave's monthly cost
+   * when a cost threshold applies, so an approval at one cost does not apply
+   * at another. Each needs a name no run has.
+   */
+  members?: WaveMember[];
+  /** On a discovering wave (#3821): how many waves the product found, which a `rest` wave walks to. */
+  waves?: number;
 }
 
 /** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
@@ -105,6 +127,8 @@ export interface OpWaveRunsFile {
   number: number;
   /** The wave's set digest, once it is decided. On `applyWave`, the digest the set was approved or let through at. */
   digest?: string;
+  /** Set when the wave discovers its runs (#3821): `runs` is empty, and the plan command plans the runs it finds for this wave. */
+  discover?: true;
   /** Each run, with its plan once planned. On `applyWave`, the runs to apply. */
   runs: Array<{ target: string; op: string; planDigest?: string; destructive?: boolean; empty?: boolean }>;
 }
@@ -114,6 +138,10 @@ export interface OpWaveMember extends WaveMember {
   op: string;
   destructive?: boolean;
   empty?: boolean;
+  /** The product's policy denied the plan (#3821). */
+  denied?: { rules: string[]; reason?: string };
+  /** The override that lets the denied plan through (#3821). */
+  override?: { by: string; at: string; digest: string; reason: string };
 }
 
 /** Where a wave's policy came from. */
@@ -134,8 +162,12 @@ export interface OpWaveDecision {
   base: string;
   digest: string;
   members: OpWaveMember[];
-  /** `approved`: an approval of this digest stands. `not-required`: the policy lets it through. `waiting`: neither. */
-  status: "approved" | "not-required" | "waiting";
+  /**
+   * `approved`: an approval of this digest stands. `not-required`: the policy
+   * lets it through. `waiting`: neither. `refused`: the product's policy
+   * denied a run and no override counts (#3821, exit 7).
+   */
+  status: "approved" | "not-required" | "waiting" | "refused";
   approvedBy?: string;
   /** How the approval arrived: a resolution on the ledger, or the merged pull request's review (#3684). */
   via?: "ledger" | "pr-review";
@@ -168,6 +200,73 @@ export interface OpWaveDecision {
   pending?: Record<string, unknown>;
   /** The pending fact carries `neverOverMcp`, set by the spec here or at base (#3821). */
   neverOverMcp?: true;
+  /** While waiting (#3821): the pending fact that stands for the digest, this run's own when `recorded`. */
+  pendingFact?: PendingGateRecord;
+  /** While waiting: whether this run recorded the pending fact, rather than finding one standing. */
+  recorded?: boolean;
+  /** While waiting: when the wait began, the standing pending fact's time. */
+  waitingSince?: string;
+  /** While waiting: the newest approval of this gate for another digest, which the plans moved away from. */
+  mismatch?: GateDigestMismatch;
+  /** Why a `refused` wave applies nothing (#3821): the runs the policy denied, and whether an override stands for an earlier plan or other rules. */
+  refused?: { reason: "policy" | "override-moved"; runs: string[] };
+  /**
+   * A hook held the wave on another gate (#3821), such as a state migration
+   * behind its own: that gate, its digest, and how it came out. While it
+   * waits, the wave waits (exit 3) and `approve` approves it.
+   */
+  heldOn?: OpWaveHeldOn;
+  /** When the wave recorded the overrides it applies under (#3821), which spent them. */
+  overridesSpentAt?: string;
+  /** Digest members that are no run, from the plans file (#3821), such as the wave's cost. */
+  extras?: WaveMember[];
+  /** On a discovering wave (#3821): how many waves the plan command found. */
+  discovered?: { waves?: number };
+}
+
+/**
+ * What an apply call writes to `CHANT_APPLY_OUTCOME` when it applied nothing
+ * for a reason that is not a failure (#3821). `stood-down`: a newer run (a
+ * newer push on the branch) applies instead, exit 6. `held`: another run
+ * holds what the apply changes and the apply does not wait for it, exit 5.
+ * `replan`: the run it waited for let go, so the plans may have moved and
+ * the wave plans again in the same job. An apply that applied writes nothing.
+ */
+export interface OpWaveApplyOutcome {
+  outcome: "stood-down" | "held" | "replan";
+  reason?: string;
+  /** The run holding what the apply changes, for `held`. */
+  holder?: { run: string; url?: string };
+}
+
+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;
+  gate: string;
+  digest: string;
+  /** The hook that asked. */
+  hook: string;
+  status: "approved" | "waiting";
+  approvedBy?: string;
+  approvedAt?: string;
+  approve?: string;
+  waitingSince?: string;
+  recorded?: boolean;
+  mismatch?: GateDigestMismatch;
 }
 
 /** One hook's run (#3762). */
@@ -432,11 +531,25 @@ export interface RunOpWaveOptions {
   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;
+  /** The signers at base, for a sealed override of a policy denial (#3821). Default: `gateSignersAt` from `@intentius/chant/gate-decision`. */
+  signers?: (base: string) => GateSigners;
 }
 
 export interface RunOpWaveResult {
-  /** 0 applied (or decided), 1 a run or a hook failed, 3 waiting for an approval, 4 a plan moved since the decision. */
+  /**
+   * 0 applied (or decided), 1 a run or a hook failed, 3 waiting for an
+   * approval, 4 a plan moved since the decision, 5 the apply applied nothing
+   * because another run holds what it changes, 6 the apply stood down for a
+   * newer run, 7 the product's policy denied a run and no override counts
+   * (5, 6 and 7: #3821).
+   */
   exitCode: number;
+  /** Set when the apply applied nothing and stood down or was held by another run (#3821): not a failure. */
+  outcome?: OpWaveApplyOutcome;
+  /** Set when the apply asked to plan again (#3821); {@link runOpWave} does, so a caller sees it only on a pass that gave up. */
+  replan?: { reason?: string };
+  /** The waves a `rest` wave's job ran (#3821), in order, with how each ended. */
+  rest?: Array<{ wave: number; exitCode: number; digest?: string }>;
   decision?: OpWaveDecision;
   applied: string[];
   failed: string[];
@@ -455,6 +568,9 @@ interface WaveContext {
   exec: OpWaveExec;
   log: (line: string) => void;
   result: RunOpWaveResult;
+  options: RunOpWaveOptions;
+  /** How another gate a hook holds the wave on is decided (#3821): the approval mode and base the wave's rules were read at, and whether pending facts carry neverOverMcp. */
+  gateRule: { approval: GateApprovalSource; base: string; neverOverMcp: boolean };
 }
 
 function planRun(opts: { spec: OpWavesSpec; wave: number; cwd: string; exec: OpWaveExec }, waveName: string, run: OpWaveRun): OpWaveMember {
@@ -476,12 +592,20 @@ 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;
+    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>" }`);
+    }
+  }
   return {
     member: target,
     planDigest: file.planDigest,
     op,
     ...(file.destructive === true ? { destructive: true } : {}),
     ...(file.empty === true ? { empty: true } : {}),
+    ...(file.denied ? { denied: { rules: file.denied.rules, ...(file.denied.reason ? { reason: file.denied.reason } : {}) } } : {}),
   };
 }
 
@@ -492,11 +616,13 @@ function writeRunsFile(
   members?: ReadonlyMap<string, OpWaveMember>,
   digest?: string,
   path: string = opWaveRunsPath(at.spec, at.k),
+  discover = false,
 ): string {
   const file: OpWaveRunsFile = {
     wave: at.wave.name,
     number: at.k,
     ...(digest ? { digest } : {}),
+    ...(discover ? { discover: true as const } : {}),
     runs: runs.map((run) => {
       const m = members?.get(run.target);
       return {
@@ -516,10 +642,10 @@ function writeRunsFile(
  * for all of them (#3762). A wave plan is written out as each run's plan file
  * too, so a per-run `apply` or hook reads `{plan}` either way.
  */
-function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec }, runs: readonly OpWaveRun[]): PlannedRuns {
+function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec }, runs: readonly OpWaveRun[], discover = false): PlannedRuns {
   const { spec, k, wave, cwd, exec } = at;
   if (!spec.planWave) return { members: runs.map((run) => planRun({ spec, wave: k, cwd, exec }, wave.name, run)) };
-  const runsPath = writeRunsFile(at, runs);
+  const runsPath = writeRunsFile(at, runs, undefined, undefined, undefined, discover);
   const plans = opWavePlansPath(spec, k);
   rmSync(join(cwd, plans), { force: true });
   const code = exec(opWaveArgv(spec.planWave, { op: spec.op, wave: wave.name, runs: runsPath, plans }), cwd);
@@ -534,8 +660,15 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
   if (!Array.isArray(entries)) throw new Error(`the plans file of wave ${k} (${plans}) must hold { "runs": [{ "target", "planDigest" }] }`);
   const wanted = new Set(runs.map((r) => r.target));
   const byTarget = new Map<string, OpWavePlanFile>();
-  for (const entry of entries as Array<Partial<OpWavePlanFile & { target: string }>>) {
+  // #3821: a discovering wave's runs are the ones the plans file names.
+  const found: OpWaveRun[] = [];
+  for (const entry of entries as Array<Partial<OpWavePlanFile & { target: string; op: string }>>) {
     const target = entry?.target;
+    if (discover && typeof target === "string" && target !== "" && !byTarget.has(target)) {
+      if (entry.op !== undefined && (typeof entry.op !== "string" || entry.op === "")) throw new Error(`the plans file of wave ${k} (${plans}) gives ${target} an op that is not a name`);
+      found.push({ target, ...(entry.op && entry.op !== spec.op ? { op: entry.op } : {}) });
+      wanted.add(target);
+    }
     if (typeof target !== "string" || !wanted.has(target)) {
       throw new Error(`the plans file of wave ${k} (${plans}) plans ${JSON.stringify(target)}, which is not a run it was asked to plan`);
     }
@@ -545,20 +678,56 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
   }
   const missing = runs.filter((r) => !byTarget.has(r.target)).map((r) => r.target);
   if (missing.length > 0) throw new Error(`the plans file of wave ${k} (${plans}) has no plan for ${missing.join(", ")}`);
+  if (discover) runs = found;
+  const extras = Array.isArray(parsed) ? undefined : extraMembers((parsed as { members?: unknown }).members, new Set(runs.map((r) => r.target)), `the plans file of wave ${k} (${plans})`);
+  const count = Array.isArray(parsed) ? undefined : (parsed as { waves?: unknown }).waves;
+  if (count !== undefined && (!Number.isInteger(count) || (count as number) < 0)) throw new Error(`the plans file of wave ${k} (${plans}): \`waves\` must be the number of waves found, a whole number`);
   const pending = Array.isArray(parsed) ? undefined : pendingFields((parsed as { pending?: unknown }).pending, `the plans file of wave ${k} (${plans})`);
   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 } : {}) }) + "\n");
+    writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}), ...(m.denied ? { denied: m.denied } : {}) }) + "\n");
     return m;
   });
-  return { members, ...(pending ? { pending } : {}) };
+  const overriders = Array.isArray(parsed) ? undefined : (parsed as { overriders?: unknown }).overriders;
+  if (overriders !== undefined && (!Array.isArray(overriders) || !overriders.every((o) => typeof o === "string"))) {
+    throw new Error(`the plans file of wave ${k} (${plans}): \`overriders\` must be a list of principals`);
+  }
+  return {
+    members,
+    ...(pending ? { pending } : {}),
+    ...(overriders ? { overriders: overriders as string[] } : {}),
+    ...(extras ? { extras } : {}),
+    ...(count !== undefined ? { waves: count as number } : {}),
+  };
 }
 
 /** What planning a wave's runs gave: each run's plan, and the product's pending-fact fields (#3821). */
 interface PlannedRuns {
   members: OpWaveMember[];
   pending?: Record<string, unknown>;
+  /** The plans file's overriders (#3821). */
+  overriders?: string[];
+  /** Digest members that are not runs, such as the wave's cost (#3821). */
+  extras?: WaveMember[];
+  /** How many waves the product found (#3821), for a `rest` wave. */
+  waves?: number;
+}
+
+/** A plans file's `members` (#3821): digest members that are no run, each named once and by no run's target. */
+function extraMembers(value: unknown, targets: ReadonlySet<string>, where: string): WaveMember[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new Error(`${where}: \`members\` must be a list of { "member", "planDigest" }`);
+  const seen = new Set<string>();
+  const out: WaveMember[] = [];
+  for (const m of value as Array<Partial<WaveMember>>) {
+    if (!m || typeof m.member !== "string" || m.member === "" || typeof m.planDigest !== "string" || m.planDigest === "") throw new Error(`${where}: each of \`members\` needs a member and a planDigest`);
+    if (targets.has(m.member)) throw new Error(`${where}: member ${m.member} is also a run's target; a digest member that is no run needs a name of its own`);
+    if (seen.has(m.member)) throw new Error(`${where}: names member ${m.member} twice`);
+    seen.add(m.member);
+    out.push({ member: m.member, planDigest: m.planDigest });
+  }
+  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. */
@@ -574,11 +743,12 @@ function pendingFields(value: unknown, where: string): Record<string, unknown> |
 /**
  * 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,
- * falling back to every run when all of them are empty.
+ * falling back to every run when all of them are empty. `extras`, the plans
+ * file's members that are no run (a cost), are always in it.
  */
-export function opWaveSetDigest(spec: Pick<OpWavesSpec, "digest">, members: ReadonlyArray<WaveMember & { empty?: boolean }>): string {
+export function opWaveSetDigest(spec: Pick<OpWavesSpec, "digest">, members: ReadonlyArray<WaveMember & { empty?: boolean }>, extras: readonly WaveMember[] = []): string {
   const changing = spec.digest?.over === "changing" ? members.filter((m) => m.empty !== true) : [];
-  return waveSetDigest(changing.length > 0 ? changing : members);
+  return waveSetDigest([...(changing.length > 0 ? changing : members), ...extras]);
 }
 
 /** What one moment's hooks came to. */
@@ -587,6 +757,32 @@ interface HooksOutcome {
   failed?: string;
   /** The `onFailure: approve` hooks that failed. */
   holds: string[];
+  /** A hook held the wave on another gate that nobody approved yet (#3821): the wave waits. */
+  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;
+  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. */
@@ -612,11 +808,14 @@ function runHookList(
   hooks: readonly OpWaveHook[] | undefined,
   runs: readonly OpWaveHookRun[],
   runsPath: string,
-): HooksOutcome & { outcomes: OpWaveHookOutcome[] } {
-  const out: HooksOutcome & { outcomes: OpWaveHookOutcome[] } = { holds: [], outcomes: [] };
+  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;
-  const env = { CHANT_OP_WAVES: specName, CHANT_WAVE: waveName, CHANT_WAVE_NUMBER: String(k), CHANT_HOOK: moment, CHANT_RUNS: runsPath };
+  // #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
@@ -629,6 +828,7 @@ function runHookList(
     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) {
@@ -642,6 +842,12 @@ function runHookList(
       }
       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, ...(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;
@@ -660,20 +866,105 @@ const placeOf = (ctx: WaveContext): HookPlace => ({ name: ctx.spec.name, op: ctx
 const hookRuns = (spec: OpWavesSpec, k: number, runs: readonly OpWaveRun[], members?: ReadonlyMap<string, OpWaveMember>): OpWaveHookRun[] =>
   runs.map((run) => ({ target: run.target, op: run.op ?? spec.op, ...(members?.has(run.target) ? { plan: opWavePlanPath(spec, k, run.target) } : {}) }));
 
-/** Run one moment's hooks in the wave job (#3762), recording each outcome on the result. */
-function runHooks(
+/**
+ * Run one moment's hooks in the wave job (#3762), recording each outcome on
+ * the result. A hook that held the wave on another gate (#3821) has that
+ * gate settled here: approved, the hook runs again with
+ * `CHANT_HOLD_APPROVED` and must pass; otherwise the wave waits on it.
+ */
+async function runHooks(
   ctx: WaveContext,
   moment: OpWaveHookMoment,
   hooks: readonly OpWaveHook[] | undefined,
   runs: readonly OpWaveRun[],
   members?: ReadonlyMap<string, OpWaveMember>,
   digest?: string,
-): HooksOutcome {
+  extraEnv: Record<string, string> = {},
+): Promise<HooksOutcome> {
   if (!hooks || hooks.length === 0) return { holds: [] };
   const runsPath = writeRunsFile(ctx, runs, members, digest);
-  const out = runHookList(placeOf(ctx), moment, hooks, hookRuns(ctx.spec, ctx.k, runs, members), runsPath);
+  const out = runHookList(placeOf(ctx), moment, hooks, hookRuns(ctx.spec, ctx.k, runs, members), runsPath, extraEnv);
   ctx.result.hooks.push(...out.outcomes);
-  return { holds: out.holds, ...(out.failed ? { failed: out.failed } : {}) };
+  const back: HooksOutcome = { holds: out.holds, ...(out.failed ? { failed: out.failed } : {}) };
+  if (out.failed) return back;
+  for (const hold of out.otherGates) {
+    const held = await settleOtherGate(ctx, hold);
+    if (held.status === "waiting") {
+      back.waitingOn ??= held;
+      continue;
+    }
+    const approvedEnv = { ...hold.env, CHANT_HOLD_APPROVED: JSON.stringify({ op: held.op, gate: held.gate, digest: held.digest, approvedBy: held.approvedBy, approvedAt: held.approvedAt }) };
+    let code: number;
+    try {
+      code = ctx.exec(hold.argv, ctx.cwd, approvedEnv);
+    } catch (err) {
+      ctx.log(`${hold.label} did not run: ${err instanceof Error ? err.message : String(err)}`);
+      code = 127;
+    }
+    ctx.result.hooks.push({ moment, name: hold.name, ...(hold.target ? { target: hold.target } : {}), exit: code, outcome: code === 0 ? "passed" : "failed" });
+    if (code !== 0) {
+      back.failed = `${hold.label} exited ${code} after ${held.approvedBy} approved ${held.gate}`;
+      ctx.log(back.failed);
+      return back;
+    }
+    ctx.log(`${hold.label}: ${held.approvedBy} approved ${held.op} / ${held.gate} at ${held.digest}, and the hook ran again and passed`);
+  }
+  return back;
+}
+
+/** The gate ledger a wave decides by: the job's port, with the signers at base as the rule when `approval` is `sealed`. */
+async function gatePort(options: RunOpWaveOptions, cwd: string, gate: string, approval: GateApprovalSource, base: string): Promise<{ ledger: GateLedgerPort; port: GateLedgerPort }> {
+  const ledger = options.gates ?? gitGateLedgerPort({ cwd });
+  if (approval !== "sealed") return { ledger, port: ledger };
+  // #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));
+  return {
+    ledger,
+    port: {
+      ...ledger,
+      async approvalRule(g) {
+        const own = (await ledger.approvalRule?.(g)) ?? null;
+        return g === gate ? review.bothRules(own, sealed) : own;
+      },
+    },
+  };
+}
+
+/**
+ * Settle a hold on another gate (#3821): an approval of that gate and digest
+ * under the wave's approval mode (`pr-review` counts the ledger alone, since
+ * no review planned that digest), else a pending fact for it.
+ */
+async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold): Promise<OpWaveHeldOn> {
+  const { spec, k, wave, log } = ctx;
+  const rules = ctx.gateRule;
+  const op = hold.request.op ?? spec.name;
+  const mode: GateApprovalSource = rules.approval === "sealed" ? "sealed" : "ledger";
+  const { port } = await gatePort(ctx.options, ctx.cwd, hold.request.gate, mode, rules.base);
+  const neverOverMcp = rules.neverOverMcp;
+  const now = ctx.options.now ?? new Date().toISOString();
+  const check = await evaluateGate(port, {
+    op,
+    gate: hold.request.gate,
+    planDigest: hold.request.digest,
+    description: hold.request.description ?? `wave ${k} (${wave.name}) of ${spec.name} is held on it by ${hold.label}`,
+    now,
+    ...(hold.request.pending ? { fields: hold.request.pending } : {}),
+    ...(neverOverMcp ? { neverOverMcp: true } : {}),
+  });
+  const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };
+  if (check.satisfied) return { ...base, status: "approved", approvedBy: check.resolution.resolvedBy, approvedAt: check.resolution.timestamp };
+  const approve = approveCommand(op, hold.request.gate, undefined, hold.request.digest, mode === "sealed");
+  log(`wave ${k} (${wave.name}) waits on ${op} / ${hold.request.gate}, which ${hold.label} holds it on: nobody approved ${hold.request.digest}. Approve: ${approve}`);
+  return {
+    ...base,
+    status: "waiting",
+    approve,
+    waitingSince: check.pending.timestamp,
+    recorded: check.recorded,
+    ...(check.mismatch ? { mismatch: check.mismatch } : {}),
+  };
 }
 
 /**
@@ -725,12 +1016,14 @@ export function runOpWaveApplyHooks(file: OpWaveHooksFile, moment: OpWaveHookMom
   } else {
     const place: HookPlace = { name: file.opWaves, op: file.op, waveName: file.wave, k: file.number, cwd, exec: options.exec ?? spawnExec, log };
     const out = runHookList(place, moment, file.hooks[moment], file.runs, file.runsFile);
+    // A hold on another gate (#3821) is settled only by the wave job; under the apply's lock it stops the apply.
+    const others = out.otherGates.map((o) => `${o.label} on ${o.request.op ?? file.opWaves} / ${o.request.gate}`);
     run = {
       moment,
       outcomes: out.outcomes,
       ...(out.failed ? { failed: out.failed } : {}),
-      held: out.holds,
-      proceed: !out.failed && (out.holds.length === 0 || file.approved),
+      held: [...out.holds, ...others],
+      proceed: !out.failed && others.length === 0 && (out.holds.length === 0 || file.approved),
     };
   }
   if (file.result) {
@@ -814,12 +1107,49 @@ function noteHooksAtBase(ctx: WaveContext, rules: OpWaveBaseRules): void {
 
 /** Plan, decide and apply one wave, or one part of a wide wave. */
 export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveResult> {
-  const { spec, wave: k } = options;
+  const { spec } = options;
   assertOpWavesSpec(spec);
+  const log = options.log ?? ((line: string) => console.error(line));
+  const last = spec.waves[spec.waves.length - 1]!;
+  const applied: string[] = [];
+  const rest: NonNullable<RunOpWaveResult["rest"]> = [];
+  for (let k = options.wave; ; k++) {
+    let result: RunOpWaveResult | undefined;
+    let prior: OpWaveDecision | undefined;
+    // #3821: an apply that came back "replan" plans the wave again, a bounded number of times.
+    for (let pass = 0; ; pass++) {
+      result = await runOneWave(options, k, prior, pass);
+      if (!result.replan) break;
+      if (pass + 1 >= OP_WAVE_MAX_REPLANS) {
+        log(`wave ${k}: its apply asked to plan again ${OP_WAVE_MAX_REPLANS} times, so the wave stops here`);
+        result.exitCode = 1;
+        break;
+      }
+      log(`wave ${k}: the apply applied nothing and asks to plan again${result.replan.reason ? ` (${result.replan.reason})` : ""}; planning again`);
+      prior = result.decision;
+    }
+    applied.push(...result.applied);
+    // #3821: a `rest` wave goes on through the waves its plan command found.
+    const found = result.decision?.discovered?.waves;
+    const onward = k >= spec.waves.length && last.rest === true && options.share === undefined && !options.decide && result.exitCode === 0 && found !== undefined && k < found;
+    if (rest.length > 0 || onward) rest.push({ wave: k, exitCode: result.exitCode, ...(result.decision ? { digest: result.decision.digest } : {}) });
+    if (!onward) return { ...result, applied, ...(rest.length > 0 ? { rest } : {}) };
+    log(`wave ${k} applied; the plan found ${found} waves, so this job goes on to wave ${k + 1}`);
+  }
+}
+
+/** How many times one wave job plans again when its apply asks to (#3821). */
+export const OP_WAVE_MAX_REPLANS = 10;
+
+/** Plan, decide and apply wave `k`, or one part of a wide wave. `prior`: the decision of the pass whose apply asked to plan again. */
+async function runOneWave(options: RunOpWaveOptions, k: number, prior: OpWaveDecision | undefined, pass: number): Promise<RunOpWaveResult> {
+  const { spec } = options;
   const cwd = options.cwd ?? process.cwd();
   const exec = options.exec ?? spawnExec;
   const log = options.log ?? ((line: string) => console.error(line));
-  const wave = spec.waves[k - 1];
+  const last = spec.waves[spec.waves.length - 1]!;
+  // #3821: past the spec's waves, a `rest` wave stands for each wave its plan command found.
+  let wave = spec.waves[k - 1] ?? (last.rest ? last : undefined);
   if (!wave) throw new Error(`Op waves "${spec.name}" has ${spec.waves.length} waves; there is no wave ${k}.`);
   const shares = wave.shares ?? 1;
   if (options.share !== undefined && (options.share < 1 || options.share > shares)) {
@@ -827,7 +1157,8 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
   }
   const recordPath = join(cwd, opWaveRecordPath(spec, k));
   const result: RunOpWaveResult = { exitCode: 0, applied: [], failed: [], moved: [], hooks: [] };
-  const ctx: WaveContext = { spec, k, wave, cwd, exec, log, result };
+  const ctx: WaveContext = { spec, k, wave, cwd, exec, log, result, options, gateRule: { approval: "ledger", base: "HEAD", neverOverMcp: spec.neverOverMcp === true } };
+  if (pass > 0) log(`wave ${k} (${wave.name}): plan ${pass + 1}`);
 
   if (options.share !== undefined) {
     let decision: OpWaveDecision;
@@ -837,18 +1168,26 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
       throw new Error(`share ${options.share} of wave ${k} (${wave.name}) found no decision at ${opWaveRecordPath(spec, k)}. Run the deciding job first.`);
     }
     result.decision = decision;
-    if (decision.status === "waiting") {
-      log(`wave ${k} (${wave.name}) is waiting on ${decision.gate}; nothing applied. ${decision.approve ?? ""}`.trim());
-      return { ...result, exitCode: 3 };
+    ctx.gateRule = { approval: decision.approval, base: decision.base, neverOverMcp: decision.neverOverMcp === true };
+    if (decision.status === "waiting" || decision.status === "refused") {
+      log(`wave ${k} (${wave.name}) is ${decision.status === "refused" ? "refused by its policy" : `waiting on ${decision.heldOn?.gate ?? decision.gate}`}; nothing applied. ${decision.approve ?? ""}`.trim());
+      return { ...result, exitCode: decision.status === "refused" ? 7 : 3 };
     }
     // The share runs the hooks its deciding job read at base, around its own slice.
+    if (wave.discover) {
+      // #3821: a discovering wave's runs are the ones its deciding job planned.
+      wave = { ...wave, runs: decision.members.map((m) => ({ target: m.member, ...(m.op !== spec.op ? { op: m.op } : {}) })) };
+      ctx.wave = wave;
+    }
     const slice = opWaveShare(wave.runs, options.share, shares);
-    const before = runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
+    const before = await runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
     if (before.failed) return failed(ctx, `a hook before the plan failed, so nothing in share ${options.share} of wave ${k} was planned or applied`);
+    if (before.waitingOn) return waitOnOther(ctx, decision, before.waitingOn);
     const { members } = planRuns(ctx, slice);
     const planned = new Map(members.map((m) => [m.member, m]));
-    const after = runHooks(ctx, "after-plan", decision.hooks?.["after-plan"], slice, planned);
+    const after = await runHooks(ctx, "after-plan", decision.hooks?.["after-plan"], slice, planned);
     if (after.failed) return failed(ctx, `a hook after the plan failed, so nothing in share ${options.share} of wave ${k} was applied`);
+    if (after.waitingOn) return waitOnOther(ctx, decision, after.waitingOn);
     const decided = new Map(decision.members.map((m) => [m.member, m.planDigest]));
     const unmoved: OpWaveRun[] = [];
     for (const run of slice) {
@@ -871,21 +1210,14 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
   // The policy, the approval mode and the hooks, read at base before anything runs.
   const rules = readOpWavePolicy(options.specFile, wave.name, options.base ?? spec.base ?? "HEAD^1", cwd, options.show);
   const { policy, approval, source, base } = rules;
+  const neverOverMcp = rules.neverOverMcp || spec.neverOverMcp === true;
+  ctx.gateRule = { approval, base, neverOverMcp };
   noteHooksAtBase(ctx, rules);
   const holds: string[] = [];
   if (rules.hooksRefused) {
     holds.push(rules.hooksRefused);
     log(`wave ${k} (${wave.name}): ${rules.hooksRefused}, so none run and the wave waits for an approval`);
   }
-  const before = runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
-  if (before.failed) return failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`);
-  const { members, pending } = planRuns(ctx, wave.runs);
-  const planned = new Map(members.map((m) => [m.member, m]));
-  const digest = opWaveSetDigest(spec, members);
-  const neverOverMcp = rules.neverOverMcp || spec.neverOverMcp === true;
-  const after = runHooks(ctx, "after-plan", rules.hooks["after-plan"], wave.runs, planned, digest);
-  if (after.failed) return failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`);
-  holds.push(...before.holds, ...after.holds);
   const gate = opWaveGateName(spec, k);
   const hooks = Object.fromEntries(Object.entries(rules.hooks).filter(([, list]) => list.length > 0));
   const decision: OpWaveDecision = {
@@ -897,41 +1229,248 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
     approval,
     policySource: source,
     base,
-    digest,
-    members,
+    digest: "",
+    members: [],
     status: "not-required",
     ...(Object.keys(hooks).length > 0 ? { hooks } : {}),
-    ...(holds.length > 0 ? { heldBy: holds } : {}),
     ...(rules.spend ? { spend: "base" as const } : spec.approvals?.spend === true ? { spend: "change" as const } : {}),
     ...(rules.applyHooksRunBy === "apply" ? { applyHooksRunBy: "apply" as const } : {}),
     ...(spec.digest?.over === "changing" ? { digestOver: "changing" as const } : {}),
-    ...(pending ? { pending } : {}),
     ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
   };
-  if (opWaveNeedsApproval(policy, members) || holds.length > 0) await settleGate(options, ctx, decision);
-  // A wide wave's shares apply under the deciding job's approval, so it is spent here, once.
-  if (options.decide && !(await spendApproval(options, ctx, decision))) return ctx.result;
-  mkdirSync(dirname(recordPath), { recursive: true });
-  writeRecord(recordPath, decision, result);
-  result.decision = decision;
+  const before = await runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
+  if (before.failed) return failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`);
+  if (before.waitingOn) return decided(ctx, decision, recordPath, before.waitingOn);
+  const { members, pending, overriders, extras, waves: found } = planRuns(ctx, wave.runs, wave.discover === true);
+  if (wave.discover) {
+    wave = { ...wave, runs: members.map((m) => ({ target: m.member, ...(m.op !== spec.op ? { op: m.op } : {}) })) };
+    ctx.wave = wave;
+    decision.discovered = { ...(found !== undefined ? { waves: found } : {}) };
+    log(`wave ${k} (${wave.name}): the plan found ${members.length} run${members.length === 1 ? "" : "s"}${found !== undefined ? ` of ${found} waves` : ""}${members.length ? `: ${members.map((m) => m.member).join(", ")}` : ""}`);
+  }
+  const planned = new Map(members.map((m) => [m.member, m]));
+  const digest = opWaveSetDigest(spec, members, extras);
+  decision.digest = digest;
+  decision.members = members;
+  if (extras) decision.extras = extras;
+  if (pending) decision.pending = pending;
+  const after = await runHooks(ctx, "after-plan", rules.hooks["after-plan"], wave.runs, planned, digest);
+  if (after.failed) return failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`);
+  holds.push(...before.holds, ...after.holds);
+  if (holds.length > 0) decision.heldBy = holds;
+  if (after.waitingOn) return 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.
+  const kept = prior !== undefined && (prior.status === "approved" || prior.status === "not-required") && prior.digest === digest;
+  if (kept) {
+    // The overrides this job applied under, and spent, still let the same plans through.
+    const byRun = new Map(prior.members.map((m) => [m.member, m.override]));
+    for (const m of members) if (m.denied && byRun.get(m.member)) m.override = byRun.get(m.member);
+    if (prior.overridesSpentAt) decision.overridesSpentAt = prior.overridesSpentAt;
+  }
+  if (members.some((m) => m.denied && !m.override)) await settleDenials(ctx, decision, overriders);
+  if (kept && prior.status === "approved" && decision.status !== "refused") {
+    // #3821: planned again after the apply asked to, to the same digest: the approval this job found still holds, and is not spent twice.
+    for (const key of ["via", "approvedBy", "approvedAt", "review", "spentAt"] as const) if (prior[key] !== undefined) (decision as unknown as Record<string, unknown>)[key] = prior[key];
+    decision.status = "approved";
+    log(`wave ${k} (${wave.name}): planned again to the same digest, so the approval by ${prior.approvedBy} still holds`);
+  } else if (decision.status !== "refused" && (opWaveNeedsApproval(policy, members) || holds.length > 0)) await settleGate(options, ctx, decision);
+  const code = await decided(ctx, decision, recordPath);
+  if (code.exitCode !== 0) return code;
   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}` : ""}` +
       (decision.via === "pr-review" ? ` (review of #${decision.review?.pr})` : "") +
       (holds.length > 0 ? `; held by ${holds.join(", ")}` : ""),
   );
-  if (approval === "pr-review" && decision.status === "waiting" && decision.review?.reason) {
+  // A wide wave's shares apply under the deciding job's approval and overrides, so they are spent here, once.
+  if (options.decide) {
+    if (!(await spendApproval(options, ctx, decision)) || !(await spendOverrides(ctx, decision))) return ctx.result;
+    if (decision.spentAt || decision.overridesSpentAt) writeRecord(recordPath, decision, result);
+    return result;
+  }
+  await applyStage(options, ctx, decision, wave.runs, planned, [], recordPath);
+  return result;
+}
+
+/**
+ * The gate has decided (#3821): write the decision record, run the
+ * `after-gate` hooks with the decision in their environment, and say whether
+ * the wave goes on. Returns the result with exit 3 when it waits, 7 when its
+ * policy refused it, 1 when an `after-gate` hook failed on a wave that would
+ * apply; exit 0 to go on. A hook that fails while the wave waits or is
+ * refused is logged and leaves the exit code alone.
+ */
+async function decided(ctx: WaveContext, decision: OpWaveDecision, recordPath: string, heldOn?: OpWaveHeldOn): Promise<RunOpWaveResult> {
+  const { k, wave, log, result } = ctx;
+  if (heldOn) markHeldOn(decision, heldOn);
+  mkdirSync(dirname(recordPath), { recursive: true });
+  writeRecord(recordPath, decision, result);
+  result.decision = decision;
+  if (decision.approval === "pr-review" && decision.status === "waiting" && decision.review?.reason) {
     log(`The pull request's review does not approve wave ${k}: ${decision.review.reason}`);
   }
+  const hook = await runGateHooks(ctx, decision, recordPath);
   if (decision.status === "waiting") {
-    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)`);
+    log(`Nothing in wave ${k} or after it ran. ${decision.heldOn ? `It waits on ${decision.heldOn.op} / ${decision.heldOn.gate}.` : "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;
-  await applyStage(options, ctx, decision, wave.runs, planned, [], recordPath);
+  if (decision.status === "refused") {
+    log(`Nothing in wave ${k} (${wave.name}) or after it ran: the policy denied ${decision.refused?.runs.join(", ")}, and no override counts for ${decision.refused?.runs.length === 1 ? "it" : "them"}.`);
+    return { ...result, exitCode: 7 };
+  }
+  if (hook.failed) return failed(ctx, `wave ${k} (${wave.name}): ${hook.failed}, so nothing in it was applied`);
   return result;
 }
 
+/** A hold on another gate that waits makes the wave wait on it (#3821). */
+function markHeldOn(decision: OpWaveDecision, heldOn: OpWaveHeldOn): void {
+  decision.heldOn = heldOn;
+  decision.status = "waiting";
+  decision.approve = heldOn.approve;
+  if (heldOn.waitingSince) decision.waitingSince = heldOn.waitingSince;
+  if (heldOn.recorded !== undefined) decision.recorded = heldOn.recorded;
+}
+
+/** A share job held on another gate that waits (#3821). */
+async function waitOnOther(ctx: WaveContext, decision: OpWaveDecision, heldOn: OpWaveHeldOn): Promise<RunOpWaveResult> {
+  markHeldOn(decision, heldOn);
+  ctx.log(`share ${ctx.options.share} of wave ${ctx.k} (${ctx.wave.name}) waits on ${heldOn.op} / ${heldOn.gate}; nothing in it applied. Approve: ${heldOn.approve}`);
+  return { ...ctx.result, decision, exitCode: 3 };
+}
+
+/**
+ * Run the `after-gate` hooks (#3821) once the gate decided. Their
+ * environment carries the decision: `CHANT_GATE_STATUS` (`approved`,
+ * `not-required`, `waiting` or `refused`), `CHANT_GATE_OP`, `CHANT_GATE`,
+ * `CHANT_GATE_DIGEST`, `CHANT_DECISION` (the decision record, with the
+ * standing pending fact, the approval of another digest and the denials),
+ * and when set `CHANT_GATE_APPROVE`, `CHANT_GATE_WAITING_SINCE` and
+ * `CHANT_GATE_RECORDED` (`true` when this run recorded the pending fact).
+ */
+async function runGateHooks(ctx: WaveContext, decision: OpWaveDecision, recordPath: string): Promise<HooksOutcome> {
+  const list = decision.hooks?.["after-gate"];
+  if (!list?.length) return { holds: [] };
+  const on = decision.heldOn;
+  const env: Record<string, string> = {
+    CHANT_GATE_STATUS: decision.status,
+    CHANT_GATE_OP: on?.op ?? decision.op,
+    CHANT_GATE: on?.gate ?? decision.gate,
+    CHANT_GATE_DIGEST: on?.digest ?? decision.digest,
+    CHANT_DECISION: relativeTo(ctx.cwd, recordPath),
+    ...(decision.approve ? { CHANT_GATE_APPROVE: decision.approve } : {}),
+    ...(decision.waitingSince ? { CHANT_GATE_WAITING_SINCE: decision.waitingSince } : {}),
+    ...(decision.recorded !== undefined ? { CHANT_GATE_RECORDED: String(decision.recorded) } : {}),
+  };
+  const planned = new Map(decision.members.map((m) => [m.member, m]));
+  const out = await runHooks(ctx, "after-gate", list, ctx.wave.runs, planned.size > 0 ? planned : undefined, decision.digest || undefined, env);
+  writeRecord(recordPath, decision, ctx.result);
+  if (out.failed && decision.status !== "approved" && decision.status !== "not-required") ctx.log(`${out.failed}; the wave is ${decision.status} whatever the hook came to`);
+  return out;
+}
+
+function relativeTo(cwd: string, path: string): string {
+  return path.startsWith(cwd + "/") ? path.slice(cwd.length + 1) : path;
+}
+
+/**
+ * Decide each run the product's policy denied (#3821) against the override
+ * ledger, `_gates/policy-override.jsonl`, as `@intentius/chant/override-gate`
+ * decides: an override counts when a listed overrider wrote it for this run,
+ * its plan digest and its rules, gave a reason, and (under `sealed`) sealed
+ * it. Overridden runs carry their override; with any run still denied the
+ * decision is `refused`, and each such run gets a pending fact on the
+ * override ledger unless one stands.
+ */
+async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed: string[] | undefined): Promise<void> {
+  const { spec, k, wave, cwd, log, options } = ctx;
+  const og = await import("../override-gate");
+  const port = options.gates ?? gitGateLedgerPort({ cwd });
+  const path = spec.override?.overriders ?? og.OVERRIDERS_PATH;
+  const overriders = listed ?? og.overridersAt(cwd, decision.base, path).principals;
+  const sealed = decision.approval === "sealed";
+  const signers = sealed ? (options.signers ?? (await import("../gate-decision")).gateSignersAt.bind(null, cwd))(decision.base) : undefined;
+  const ledger = await port.read(og.OVERRIDE_OP);
+  const applied = ((await port.readApplied?.(og.OVERRIDE_OP)) ?? []) as unknown as import("../override-gate").AppliedOverrideRecord[];
+  const now = options.now ?? new Date().toISOString();
+  const still: string[] = [];
+  let moved = false;
+  for (const m of decision.members) {
+    if (!m.denied || m.override) continue;
+    const verdict = og.decideOverride({
+      ledger,
+      applied,
+      subject: m.member,
+      planDigest: m.planDigest,
+      rules: m.denied.rules,
+      overriders,
+      overridersPath: listed ? "the overriders the plans file names" : path,
+      mode: sealed ? "sealed" : "ledger",
+      ...(signers ? { signers } : {}),
+      now,
+    });
+    if (verdict.status === "overridden") {
+      const o = verdict.override;
+      m.override = { by: o.by, at: o.at, digest: o.digest, reason: o.reason };
+      log(`${m.member}: the policy denial (${o.rules.join(", ")}) is overridden by ${o.by} at ${o.at}${o.sealed ? ", sealed" : ""}: ${o.reason}`);
+      continue;
+    }
+    still.push(m.member);
+    for (const why of verdict.refusals) log(`${m.member}: an override does not count: ${why}`);
+    if (verdict.status === "moved") {
+      moved = true;
+      log(`${m.member}: ${verdict.by} overrode an earlier plan or other rules (${verdict.was ?? "no digest"}); this plan and its rules give ${verdict.digest}, so that override counts for nothing`);
+    }
+    if (!verdict.standing) {
+      const { version: _v, kind: _k, ...fact } = og.overridePending({
+        subject: m.member,
+        planDigest: m.planDigest,
+        rules: m.denied.rules,
+        timestamp: now,
+        expiresAt: new Date(new Date(now).getTime() + 48 * 3600 * 1000).toISOString(),
+        description: m.denied.reason ?? `wave ${k} (${wave.name}) of ${spec.name}: ${m.member}: plan ${m.planDigest} denied by ${og.sortedRules(m.denied.rules).join(", ")}`,
+      });
+      try {
+        await port.appendPending({ ...fact, members: [{ member: m.member, planDigest: m.planDigest }] } as typeof fact);
+      } catch (err) {
+        log(`${m.member}: the denial was not recorded for an override: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    log(`${m.member}: ${overriders.length ? `${overriders.join(", ")} may` : "nobody listed may"} override it with: ${og.overrideCommand(m.member, m.denied.rules, sealed)}`);
+  }
+  if (still.length > 0) {
+    decision.status = "refused";
+    decision.refused = { reason: moved ? "override-moved" : "policy", runs: still.sort() };
+  }
+}
+
+/**
+ * Record each override the wave is about to apply under (#3821), in
+ * `_gates/policy-override/applied.jsonl`, which spends it: written before
+ * anything applies, once. False when the lines could not be written: the
+ * wave then fails and applies nothing.
+ */
+async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promise<boolean> {
+  const used = decision.members.filter((m) => m.override);
+  if (used.length === 0 || decision.overridesSpentAt) return true;
+  const { k, wave, cwd, log, options } = ctx;
+  const og = await import("../override-gate");
+  const port = options.gates ?? gitGateLedgerPort({ cwd });
+  const now = options.now ?? new Date().toISOString();
+  try {
+    if (!port.appendApplied) throw new Error("this gate ledger cannot record an applied override");
+    for (const m of used) {
+      const record = og.appliedOverride({ subject: m.member, digest: m.override!.digest, at: m.override!.at, by: m.override!.by }, { timestamp: now });
+      await port.appendApplied(record as unknown as AppliedGateRecord);
+    }
+  } catch (err) {
+    failed(ctx, `wave ${k} (${wave.name}) could not record the overrides it applies under, so nothing applied: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+  decision.overridesSpentAt = now;
+  log(`wave ${k} (${wave.name}) applies ${used.map((m) => m.member).join(", ")} under their overrides, which are now spent`);
+  return true;
+}
+
 function failed(ctx: WaveContext, line: string): RunOpWaveResult {
   ctx.log(line);
   ctx.result.exitCode = 1;
@@ -946,20 +1485,7 @@ function failed(ctx: WaveContext, line: string): RunOpWaveResult {
 async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<void> {
   const { spec, k, wave, cwd } = ctx;
   const { gate, digest, approval, base, policy, members } = decision;
-  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 { ledger, port } = await gatePort(options, cwd, gate, approval, base);
   const now = options.now ?? new Date().toISOString();
   // #3784: under the spend rule at base, an approval a wave already applied under counts for nothing.
   const spent: AppliedGateRecord[] | undefined = decision.spend === "base" ? ((await ledger.readApplied?.(spec.name)) ?? []).filter((a) => a.gate === gate) : undefined;
@@ -981,6 +1507,11 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
     decision.approvedAt = check.resolution.timestamp;
     return;
   }
+  // #3821: what the wait is, for the after-gate hooks and the record.
+  decision.pendingFact = check.pending;
+  decision.recorded = check.recorded;
+  decision.waitingSince = check.pending.timestamp;
+  if (check.mismatch) decision.mismatch = check.mismatch;
   const used = spent?.filter((a) => isApprovalSpent([a], { gate, planDigest: digest, timestamp: a.approvedAt })).pop();
   if (used) {
     ctx.log(`wave ${k} (${wave.name}): the approval of ${digest} by ${used.approvedBy} at ${used.approvedAt} is spent: a wave applied under it at ${used.timestamp}. Applying it again needs a new approval`);
@@ -989,6 +1520,7 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
     const byReview = await approveByReview(options, { op: spec.name, gate, k, digest, cwd, now, port: ledger, ...(spent ? { spent } : {}) });
     decision.review = byReview.review;
     if (byReview.approved) {
+      for (const key of ["pendingFact", "recorded", "waitingSince", "mismatch"] as const) delete decision[key];
       decision.status = "approved";
       decision.via = "pr-review";
       decision.approvedBy = byReview.review.approvers!.join(", ");
@@ -1026,6 +1558,8 @@ async function settleHolds(
   await settleGate(options, ctx, decision);
   if (recordPath) writeRecord(recordPath, decision, result);
   if (decision.status === "waiting") {
+    // #3821: the gate decided again, and the wave now waits: the after-gate hooks hear so.
+    if (recordPath) await runGateHooks(ctx, decision, recordPath);
     log(`wave ${k} (${wave.name}) is held by ${holds.join(", ")}, and nobody approved ${decision.digest}; nothing applied. Approve: ${decision.approve}`);
     result.exitCode = 3;
     return false;
@@ -1034,8 +1568,23 @@ async function settleHolds(
   return true;
 }
 
-/** How one apply call came out. `applied` with a `problem`: the runs applied, and the wave still fails. */
-type ApplyCall = { outcome: "applied"; problem?: string } | { outcome: "failed" | "waiting" };
+/** How one apply call came out. `applied` with a `problem`: the runs applied, and the wave still fails. `applied-nothing`: the apply said why (#3821). */
+type ApplyCall = { outcome: "applied"; problem?: string } | { outcome: "failed" | "waiting" } | { outcome: "applied-nothing"; said: OpWaveApplyOutcome };
+
+/** Read what an apply wrote to `CHANT_APPLY_OUTCOME` (#3821), or undefined when it wrote nothing. A file that says something else is logged and ignored. */
+function readApplyOutcome(path: string, label: string, log: (line: string) => void): OpWaveApplyOutcome | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const o = JSON.parse(readFileSync(path, "utf-8")) as Partial<OpWaveApplyOutcome>;
+    if (!OP_WAVE_APPLY_OUTCOMES.includes(o.outcome as "held")) throw new Error(`outcome ${JSON.stringify(o.outcome)} is none of ${OP_WAVE_APPLY_OUTCOMES.join(", ")}`);
+    if (o.reason !== undefined && typeof o.reason !== "string") throw new Error("its reason is not text");
+    const holder = o.holder && typeof o.holder === "object" && typeof o.holder.run === "string" ? { run: o.holder.run, ...(typeof o.holder.url === "string" ? { url: o.holder.url } : {}) } : undefined;
+    return { outcome: o.outcome as OpWaveApplyOutcome["outcome"], ...(o.reason ? { reason: o.reason } : {}), ...(holder ? { holder } : {}) };
+  } catch (err) {
+    log(`${label}: the apply wrote an outcome that cannot be read (${err instanceof Error ? err.message : String(err)}), so its exit code decides`);
+    return undefined;
+  }
+}
 
 /**
  * Call one apply command (#3804) with `CHANT_HOOKS` and `CHANT_HOOKS_RESULT`.
@@ -1059,6 +1608,7 @@ async function callApply(
   const dir = `.chant/op-waves/${spec.name}/wave-${k}`;
   const filePath = `${dir}/${call.key}.json`;
   const resultPath = `${dir}/${call.key}-result.json`;
+  const outcomePath = `${dir}/${call.key}-outcome.json`;
   const handed: Partial<Record<OpWaveHookMoment, OpWaveHook[]>> = {};
   if (byApply) {
     for (const m of ["before-apply", "after-apply"] as const) if (decision.hooks?.[m]?.length) handed[m] = decision.hooks[m];
@@ -1085,13 +1635,28 @@ async function callApply(
     mkdirSync(join(cwd, dir), { recursive: true });
     writeFileSync(join(cwd, filePath), JSON.stringify(file, null, 2) + "\n");
     rmSync(join(cwd, resultPath), { force: true });
+    rmSync(join(cwd, outcomePath), { force: true });
     let code: number;
     try {
-      code = exec(argv, cwd, { CHANT_HOOKS: filePath, ...(byApply ? { CHANT_HOOKS_RESULT: resultPath } : {}) });
+      code = exec(argv, cwd, { CHANT_HOOKS: filePath, CHANT_APPLY_OUTCOME: outcomePath, ...(byApply ? { CHANT_HOOKS_RESULT: resultPath } : {}) });
     } catch (err) {
       log(`${call.label}: the apply did not run: ${err instanceof Error ? err.message : String(err)}`);
       code = 127;
     }
+    // #3821: an apply that applied nothing, and says why, is not a failure.
+    const said = readApplyOutcome(join(cwd, outcomePath), call.label, log);
+    if (said) {
+      if (byApply) {
+        try {
+          const back = JSON.parse(readFileSync(join(cwd, resultPath), "utf-8")) as OpWaveHooksResult;
+          if (Array.isArray(back?.outcomes)) result.hooks.push(...back.outcomes);
+        } catch {
+          // No hooks ran.
+        }
+      }
+      log(`${call.label}: the apply applied nothing: ${said.outcome}${said.reason ? ` (${said.reason})` : ""}${said.holder ? `, held by run ${said.holder.run}` : ""}`);
+      return { outcome: "applied-nothing", said };
+    }
     if (!byApply) return { outcome: code === 0 ? "applied" : "failed" };
     let back: OpWaveHooksResult | null = null;
     try {
@@ -1147,23 +1712,36 @@ async function applyStage(
   const byApply = decision.applyHooksRunBy === "apply";
   const holds = [...earlierHolds];
   if (!byApply) {
-    const before = runHooks(ctx, "before-apply", decision.hooks?.["before-apply"], runs, planned, decision.digest);
+    const before = await runHooks(ctx, "before-apply", decision.hooks?.["before-apply"], runs, planned, decision.digest);
     if (before.failed) {
       failed(ctx, `a hook before the apply failed, so nothing in wave ${k} was applied`);
       return;
     }
+    if (before.waitingOn) {
+      markHeldOn(decision, before.waitingOn);
+      if (recordPath) {
+        writeRecord(recordPath, decision, result);
+        await runGateHooks(ctx, decision, recordPath);
+      }
+      result.decision = decision;
+      result.exitCode = 3;
+      return;
+    }
     holds.push(...before.holds);
   }
   if (!(await settleHolds(options, ctx, decision, holds, recordPath))) return;
   if (!(await spendApproval(options, ctx, decision))) return;
-  if (recordPath && decision.spentAt) writeRecord(recordPath, decision, result);
+  if (!(await spendOverrides(ctx, decision))) return;
+  if (recordPath && (decision.spentAt || decision.overridesSpentAt)) writeRecord(recordPath, decision, result);
   const problems: string[] = [];
   let waiting = false;
+  let nothing: OpWaveApplyOutcome | undefined;
   if (spec.applyWave) {
     const runsPath = writeRunsFile(ctx, runs, planned, decision.digest);
     const argv = opWaveArgv(spec.applyWave, { op: spec.op, wave: wave.name, runs: runsPath, plans: opWavePlansPath(spec, k) });
     const got = await callApply(options, ctx, decision, runs, planned, argv, { label: `wave ${k} (${wave.name})`, key: "hooks", runsPath }, recordPath);
-    if (got.outcome === "applied") {
+    if (got.outcome === "applied-nothing") nothing = got.said;
+    else if (got.outcome === "applied") {
       result.applied.push(...runs.map((r) => r.target));
       if (got.problem) problems.push(got.problem);
     } else if (got.outcome === "waiting") waiting = true;
@@ -1178,6 +1756,10 @@ async function applyStage(
       const runsPath = byApply ? writeRunsFile(ctx, [run], planned, decision.digest, `.chant/op-waves/${spec.name}/wave-${k}/${key}.runs.json`) : opWaveRunsPath(spec, k);
       const argv = opWaveArgv(spec.apply ?? OP_WAVE_DEFAULT_APPLY, { op: run.op ?? spec.op, target: run.target, wave: wave.name, plan: opWavePlanPath(spec, k, run.target) });
       const got = await callApply(options, ctx, decision, [run], planned, argv, { label: run.target, key: `${key}.hooks`, runsPath }, recordPath);
+      if (got.outcome === "applied-nothing") {
+        nothing = got.said;
+        break;
+      }
       if (got.outcome === "waiting") {
         waiting = true;
         break;
@@ -1192,6 +1774,17 @@ async function applyStage(
     }
   }
   if (recordPath && byApply) writeRecord(recordPath, decision, result);
+  if (nothing) {
+    // #3821: no run counts as failed; the wave stops here, or plans again.
+    if (nothing.outcome === "replan") {
+      result.replan = { ...(nothing.reason ? { reason: nothing.reason } : {}) };
+      return;
+    }
+    result.outcome = nothing;
+    result.exitCode = nothing.outcome === "stood-down" ? 6 : 5;
+    if (recordPath) writeRecord(recordPath, decision, result);
+    return;
+  }
   if (waiting) {
     result.exitCode = 3;
     return;
@@ -1206,7 +1799,7 @@ async function applyStage(
     return;
   }
   if (!byApply) {
-    const after = runHooks(ctx, "after-apply", decision.hooks?.["after-apply"], runs, planned, decision.digest);
+    const after = await runHooks(ctx, "after-apply", decision.hooks?.["after-apply"], runs, planned, decision.digest);
     if (after.failed) failed(ctx, `wave ${k} (${wave.name}) applied, and then a hook after the apply failed`);
   }
   if (recordPath && result.hooks.length > 0) writeRecord(recordPath, decision, result);
@@ -1343,11 +1936,16 @@ export async function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Pr
     name: spec.name,
     head,
     timestamp: options.now ?? new Date().toISOString(),
-    waves: spec.waves.map((wave, i) => {
-      const { members } = planRuns({ spec, k: i + 1, wave, cwd, exec }, wave.runs);
-      return { wave: i + 1, name: wave.name, digest: opWaveSetDigest(spec, members) };
-    }),
+    waves: [],
   };
+  // A `rest` wave (#3821) goes on through the waves the plan command found.
+  const last = spec.waves[spec.waves.length - 1]!;
+  for (let k = 1; ; k++) {
+    const wave = spec.waves[k - 1] ?? last;
+    const { members, extras, waves: found } = planRuns({ spec, k, wave, cwd, exec }, wave.runs, wave.discover === true);
+    plans.waves.push({ wave: k, name: wave.name, digest: opWaveSetDigest(spec, members, extras) });
+    if (k >= spec.waves.length && !(last.rest && found !== undefined && k < found)) break;
+  }
   await (options.write ?? ((p) => writeHeadPlans(p, cwd)))(plans);
   return plans;
 }