@intentius/chant 0.124.8 → 0.124.9

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

@@ -37,6 +37,15 @@
  *   {@link runOpWaveApplyHooks}, and their outcomes come back through
  *   `CHANT_HOOKS_RESULT`. A non-wave apply reads the same hooks at base with
  *   {@link opWaveHooksAtBase}.
+ * - Point (#3836): with `point` at base (the wave's, else the spec's), a wave
+ *   that needs an approval asks that decision point through
+ *   `evaluatePointGate` (`../point-decision.ts`) with `gate.planDigest` set to
+ *   its set digest: an open question waits (exit 3, the pending fact cites
+ *   it, `approve` is the `points answer` line), an answer the gate passes on
+ *   records the resolution that cites it and the wave goes on, and any other
+ *   answer refuses the wave (`refused.reason: "point"`, exit 8). Once the
+ *   question is answered, `chant run resume --op <name>` starts the job again
+ *   (`pointGateResumable`, #3835).
  */
 
 import { execFileSync, spawnSync } from "node:child_process";
@@ -44,8 +53,10 @@ 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 GateDigestMismatch, type GateLedgerPort } from "./gate";
-import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+import { approveCommand, evaluateGate, gitGateLedgerPort, type GateCheck, type GateDigestMismatch, type GateLedgerPort } from "./gate";
+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 type { HeadPlans, MergedReview, ReviewSource } from "./gate-review";
 import type { TrustPolicy } from "../workspace/trust/policy";
@@ -60,6 +71,8 @@ import {
   opWaveApplyHooksRunBy,
   opWaveGateName,
   opWaveHooksAt,
+  opWavePointAt,
+  opWavePointProblems,
   opWaveRecordPath,
   opWaveShare,
   type GateApprovalSource,
@@ -68,6 +81,7 @@ import {
   type OpWaveGatePolicy,
   type OpWaveHook,
   type OpWaveHookMoment,
+  type OpWavePoint,
   type OpWaveRun,
   type OpWavesSpec,
 } from "./op-waves";
@@ -169,8 +183,14 @@ export interface OpWaveDecision {
    */
   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";
+  /** How the approval arrived: a resolution on the ledger, the merged pull request's review (#3684), or a decision point's answer (#3836). */
+  via?: "ledger" | "pr-review" | "point";
+  /**
+   * The decision point the gate asks, as read at base (#3836), and what it
+   * said: the open `question` while the wave waits, the `answer` once it is
+   * answered (the one that passed, or the one that refused the wave).
+   */
+  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 command that approves this digest, when waiting. */
@@ -208,8 +228,19 @@ export interface OpWaveDecision {
   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[] };
+  /**
+   * Why a `refused` wave applies nothing: the runs the policy denied, and
+   * whether an override stands for an earlier plan or other rules (#3821,
+   * exit 7); or `point`, the gate's decision point answered with an answer
+   * it does not pass on (#3836, exit 8), with every run and the `message`.
+   */
+  refused?: {
+    reason: "policy" | "override-moved" | "point";
+    runs: string[];
+    message?: string;
+    /** Where the plans file said its overriders come from (#3848), when it did. */
+    overridersSource?: 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
@@ -267,6 +298,20 @@ export interface OpWaveHeldOn {
   waitingSince?: string;
   recorded?: boolean;
   mismatch?: GateDigestMismatch;
+  /**
+   * The gates the same hook call held the wave on before this one, each
+   * approved, oldest first (#3847): its approved re-runs asked for this one.
+   */
+  after?: OpWaveHeldOnApproval[];
+}
+
+/** An approved hold on another gate (#3847), as `CHANT_HOLD_APPROVED` and `CHANT_HOLDS_APPROVED` carry it. */
+export interface OpWaveHeldOnApproval {
+  op: string;
+  gate: string;
+  digest: string;
+  approvedBy: string;
+  approvedAt: string;
 }
 
 /** One hook's run (#3762). */
@@ -426,6 +471,10 @@ export interface OpWaveBaseRules {
   applyHooksRunBy: OpWaveApplyHooksRunner;
   /** The spec at base sets `neverOverMcp` (#3821). */
   neverOverMcp: boolean;
+  /** The decision point the wave's gate asks, as read at base (#3836): the wave's, else the spec's. */
+  point?: OpWavePoint;
+  /** Set when the point at base cannot be asked: the wave fails rather than fall back to the ledger (#3836). */
+  pointRefused?: string;
 }
 
 const noHooks = (): Record<OpWaveHookMoment, OpWaveHook[]> =>
@@ -457,12 +506,14 @@ export function readOpWavePolicy(
   // The spend rule is the spec's, so it holds for a wave the base does not have yet.
   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 wave = spec.waves.find((w) => w.name === name);
-  if (!wave) return { ...absent, spend, neverOverMcp };
+  if (!wave) return { ...absent, spend, neverOverMcp, ...asks };
   const policy = wave.gate ?? "always";
   // An approval mode this chant does not know reads as sealed: the strictest, so an unknown rule never loosens a gate.
   const approval = wave.approval === undefined ? "ledger" : GATE_APPROVAL_SOURCES.includes(wave.approval) ? wave.approval : "sealed";
-  const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, applyHooksRunBy: "chant", neverOverMcp };
+  const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, applyHooksRunBy: "chant", neverOverMcp, ...asks };
   try {
     assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}`, spec.hooks);
     assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}, wave "${name}"`, wave.hooks);
@@ -475,6 +526,15 @@ export function readOpWavePolicy(
   return rules;
 }
 
+/** 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;
+  if (raw === undefined) return {};
+  const problems = opWavePointProblems(raw);
+  if (problems.length > 0) return { pointRefused: `the decision point at base cannot be asked (${where}: ${problems.join("; ")})` };
+  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[],
@@ -533,6 +593,8 @@ export interface RunOpWaveOptions {
   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;
+  /** How a gate with a `point` asks it (#3836). Default: `workspaceGatePointAsker` over `cwd`. A tool that bundles chant passes `chantGatePointAsker`. */
+  points?: GatePointAsker;
 }
 
 export interface RunOpWaveResult {
@@ -541,7 +603,8 @@ export interface RunOpWaveResult {
    * 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).
+   * (5, 6 and 7: #3821), 8 the gate's decision point was answered with an
+   * answer it does not pass on (#3836).
    */
   exitCode: number;
   /** Set when the apply applied nothing and stood down or was held by another run (#3821): not a failure. */
@@ -690,6 +753,10 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
     return m;
   });
   const overriders = Array.isArray(parsed) ? undefined : (parsed as { overriders?: unknown }).overriders;
+  const overridersSource = Array.isArray(parsed) ? undefined : (parsed as { overridersSource?: unknown }).overridersSource;
+  if (overridersSource !== undefined && (typeof overridersSource !== "string" || overridersSource.trim() === "")) {
+    throw new Error(`the plans file of wave ${k} (${plans}): \`overridersSource\` must be a label for where the overriders come from, such as "policy.override in terragucci.yml"`);
+  }
   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`);
   }
@@ -697,6 +764,7 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
     members,
     ...(pending ? { pending } : {}),
     ...(overriders ? { overriders: overriders as string[] } : {}),
+    ...(overriders && overridersSource ? { overridersSource: overridersSource as string } : {}),
     ...(extras ? { extras } : {}),
     ...(count !== undefined ? { waves: count as number } : {}),
   };
@@ -708,6 +776,8 @@ interface PlannedRuns {
   pending?: Record<string, unknown>;
   /** The plans file's overriders (#3821). */
   overriders?: string[];
+  /** A label for where those overriders come from, used in refusals (#3848). */
+  overridersSource?: 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. */
@@ -870,7 +940,9 @@ const hookRuns = (spec: OpWavesSpec, k: number, runs: readonly OpWaveRun[], memb
  * 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.
+ * `CHANT_HOLD_APPROVED`; otherwise the wave waits on it. The re-run passes,
+ * or holds the wave on a further gate (#3847), settled the same way, up to
+ * {@link OP_WAVE_MAX_CHAINED_HOLDS} gates per hook call.
  */
 async function runHooks(
   ctx: WaveContext,
@@ -887,35 +959,74 @@ async function runHooks(
   ctx.result.hooks.push(...out.outcomes);
   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;
+  for (const first of out.otherGates) {
+    // #3847: an approved re-run may hold the wave on a further gate (a second state migration that plans against the first one's states), settled in turn.
+    let hold = first;
+    const approved: OpWaveHeldOnApproval[] = [];
+    for (;;) {
+      const held = await settleOtherGate(ctx, hold);
+      if (held.status === "waiting") {
+        if (approved.length > 0) held.after = approved;
+        back.waitingOn ??= held;
+        break;
+      }
+      const now: OpWaveHeldOnApproval = { op: held.op, gate: held.gate, digest: held.digest, approvedBy: held.approvedBy!, approvedAt: held.approvedAt! };
+      approved.push(now);
+      const approvedEnv = {
+        ...hold.env,
+        CHANT_HOLD_APPROVED: JSON.stringify(now),
+        // Every hold this hook call was approved through so far, oldest first (#3847).
+        CHANT_HOLDS_APPROVED: JSON.stringify(approved),
+      };
+      const holdPath = join(ctx.cwd, hold.env.CHANT_HOLD!);
+      rmSync(holdPath, { force: true });
+      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;
+      }
+      const target = hold.target ? { target: hold.target } : {};
+      if (code === 0) {
+        ctx.result.hooks.push({ moment, name: hold.name, ...target, exit: code, outcome: "passed" });
+        ctx.log(`${hold.label}: ${held.approvedBy} approved ${held.op} / ${held.gate} at ${held.digest}, and the hook ran again and passed`);
+        break;
+      }
+      const next = readHoldRequest(holdPath, ctx.log, hold.label);
+      const problem = !next
+        ? `${hold.label} exited ${code} after ${held.approvedBy} approved ${held.gate}`
+        : approved.some((a) => a.op === (next.op ?? ctx.spec.name) && a.gate === next.gate && a.digest === next.digest)
+          ? `${hold.label} exited ${code} after ${held.approvedBy} approved ${held.gate}, and holds the wave again on ${next.op ?? ctx.spec.name} / ${next.gate} at ${next.digest}, which is already approved`
+          : approved.length >= OP_WAVE_MAX_CHAINED_HOLDS
+            ? `${hold.label} held the wave on ${approved.length} gates in turn and asks for one more; a hook call holds on at most ${OP_WAVE_MAX_CHAINED_HOLDS}`
+            : undefined;
+      if (problem) {
+        ctx.result.hooks.push({ moment, name: hold.name, ...target, exit: code, outcome: "failed" });
+        back.failed = problem;
+        ctx.log(back.failed);
+        return back;
+      }
+      ctx.result.hooks.push({ moment, name: hold.name, ...target, exit: code, outcome: "held" });
+      ctx.log(`${hold.label}: ${held.approvedBy} approved ${held.op} / ${held.gate}; the hook ran again, exited ${code} and holds wave ${ctx.k} (${ctx.wave.name}) on gate ${next!.op ?? ctx.spec.name} / ${next!.gate}, digest ${next!.digest}`);
+      hold = { ...hold, request: next! };
     }
-    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`. */
+/** 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;
+
+/**
+ * The gate ledger a wave decides by: the job's port, its `identity.gates`
+ * rule read at the wave's base (#3841), and the signers at base as a second
+ * 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 };
+  const atBase = (g: string) => ledger.approvalRule?.(g, { base }) ?? Promise.resolve(null);
+  if (approval !== "sealed") return { ledger, port: ledger.approvalRule ? { ...ledger, approvalRule: atBase } : 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));
@@ -924,13 +1035,19 @@ async function gatePort(options: RunOpWaveOptions, cwd: string, gate: string, ap
     port: {
       ...ledger,
       async approvalRule(g) {
-        const own = (await ledger.approvalRule?.(g)) ?? null;
+        const own = await atBase(g);
         return g === gate ? review.bothRules(own, sealed) : own;
       },
     },
   };
 }
 
+/** Log each approval of the digest a rule did not count (#3841), so a wait says why. */
+function logRefused(log: (line: string) => void, label: string, check: GateCheck): void {
+  if (check.satisfied) return;
+  for (const { resolution: r, reason } of check.refused ?? []) log(`${label}: the approval by ${r.resolvedBy} at ${r.timestamp} does not count: ${reason}`);
+}
+
 /**
  * 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
@@ -954,6 +1071,7 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold): Promise<O
     ...(neverOverMcp ? { neverOverMcp: true } : {}),
   });
   const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };
+  logRefused(log, `${op} / ${hold.request.gate}`, check);
   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}`);
@@ -1171,7 +1289,7 @@ async function runOneWave(options: RunOpWaveOptions, k: number, prior: OpWaveDec
     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 };
+      return { ...result, exitCode: decision.status === "refused" ? refusedExit(decision) : 3 };
     }
     // The share runs the hooks its deciding job read at base, around its own slice.
     if (wave.discover) {
@@ -1213,6 +1331,12 @@ async function runOneWave(options: RunOpWaveOptions, k: number, prior: OpWaveDec
   const neverOverMcp = rules.neverOverMcp || spec.neverOverMcp === true;
   ctx.gateRule = { approval, base, neverOverMcp };
   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 failed(ctx, `wave ${k} (${wave.name}): ${rules.pointRefused}, so nothing in it was planned or applied`);
+  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`);
+  }
   const holds: string[] = [];
   if (rules.hooksRefused) {
     holds.push(rules.hooksRefused);
@@ -1237,11 +1361,12 @@ async function runOneWave(options: RunOpWaveOptions, k: number, prior: OpWaveDec
     ...(rules.applyHooksRunBy === "apply" ? { applyHooksRunBy: "apply" as const } : {}),
     ...(spec.digest?.over === "changing" ? { digestOver: "changing" as const } : {}),
     ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
+    ...(rules.point ? { point: { ...rules.point } } : {}),
   };
   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);
+  const { members, pending, overriders, overridersSource, 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;
@@ -1267,7 +1392,7 @@ async function runOneWave(options: RunOpWaveOptions, k: number, prior: OpWaveDec
     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 (members.some((m) => m.denied && !m.override)) await settleDenials(ctx, decision, overriders, overridersSource);
   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];
@@ -1314,6 +1439,10 @@ async function decided(ctx: WaveContext, decision: OpWaveDecision, recordPath: s
     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 (decision.status === "refused" && decision.refused?.reason === "point") {
+    log(`Nothing in wave ${k} (${wave.name}) or after it ran: ${decision.refused.message}`);
+    return { ...result, exitCode: 8 };
+  }
   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 };
@@ -1381,7 +1510,7 @@ function relativeTo(cwd: string, path: string): string {
  * 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> {
+async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed: string[] | undefined, source?: string): Promise<void> {
   const { spec, k, wave, cwd, log, options } = ctx;
   const og = await import("../override-gate");
   const port = options.gates ?? gitGateLedgerPort({ cwd });
@@ -1403,7 +1532,7 @@ async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed:
       planDigest: m.planDigest,
       rules: m.denied.rules,
       overriders,
-      overridersPath: listed ? "the overriders the plans file names" : path,
+      overridersPath: listed ? (source ?? "the overriders the plans file names") : path,
       mode: sealed ? "sealed" : "ledger",
       ...(signers ? { signers } : {}),
       now,
@@ -1439,7 +1568,7 @@ async function settleDenials(ctx: WaveContext, decision: OpWaveDecision, listed:
   }
   if (still.length > 0) {
     decision.status = "refused";
-    decision.refused = { reason: moved ? "override-moved" : "policy", runs: still.sort() };
+    decision.refused = { reason: moved ? "override-moved" : "policy", runs: still.sort(), ...(listed && source ? { overridersSource: source } : {}) };
   }
 }
 
@@ -1471,6 +1600,11 @@ async function spendOverrides(ctx: WaveContext, decision: OpWaveDecision): Promi
   return true;
 }
 
+/** The exit code of a refused wave: 8 when its decision point refused it (#3836), 7 when the product's policy did (#3821). */
+function refusedExit(decision: OpWaveDecision): number {
+  return decision.refused?.reason === "point" ? 8 : 7;
+}
+
 function failed(ctx: WaveContext, line: string): RunOpWaveResult {
   ctx.log(line);
   ctx.result.exitCode = 1;
@@ -1483,6 +1617,7 @@ function failed(ctx: WaveContext, line: string): RunOpWaveResult {
  * asks for one, or when a hook holds the wave (#3762).
  */
 async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision): Promise<void> {
+  if (decision.point) return settlePointGate(options, ctx, decision, decision.point);
   const { spec, k, wave, cwd } = ctx;
   const { gate, digest, approval, base, policy, members } = decision;
   const { ledger, port } = await gatePort(options, cwd, gate, approval, base);
@@ -1507,6 +1642,7 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
     decision.approvedAt = check.resolution.timestamp;
     return;
   }
+  logRefused(ctx.log, `wave ${k} (${wave.name})`, check);
   // #3821: what the wait is, for the after-gate hooks and the record.
   decision.pendingFact = check.pending;
   decision.recorded = check.recorded;
@@ -1535,6 +1671,54 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
   decision.approve = approveCommand(spec.name, gate, undefined, digest, approval === "sealed");
 }
 
+/**
+ * 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
+ * digest, then wait on an open question, pass on an answer the gate passes
+ * on, or refuse the wave on any other. The wave's `approval` mode and spent
+ * approvals do not apply: the point's deciders and quorum decide, and a
+ * `chant approve` of the digest does not pass it.
+ */
+async function settlePointGate(options: RunOpWaveOptions, ctx: WaveContext, decision: OpWaveDecision, point: NonNullable<OpWaveDecision["point"]>): Promise<void> {
+  const { spec, k, wave, cwd, log } = ctx;
+  const { gate, digest, policy, members } = decision;
+  if (decision.approval !== "ledger") log(`wave ${k} (${wave.name}): its gate asks decision point ${point.name}, so its approval mode (${decision.approval}) does not apply`);
+  const { evaluatePointGate } = await import("../point-decision");
+  const asker = options.points ?? (await import("./gate-point-run")).workspaceGatePointAsker(cwd);
+  const held = decision.heldBy?.length ? `, held by ${decision.heldBy.join(", ")}` : "";
+  const check = await evaluatePointGate(options.gates ?? gitGateLedgerPort({ cwd }), asker, {
+    op: spec.name,
+    gate,
+    point: { name: point.name, ...(point.pass ? { pass: point.pass } : {}), ...(point.store ? { store: point.store } : {}) },
+    ...(point.inputs ? { inputs: point.inputs } : {}),
+    description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, decision point ${point.name}${held}`,
+    ...(point.timeout ? { timeout: point.timeout } : {}),
+    planDigest: digest,
+    ...(options.now ? { now: options.now } : {}),
+  });
+  if (check.satisfied) {
+    decision.status = "approved";
+    decision.via = "point";
+    decision.approvedBy = check.resolution.resolvedBy;
+    decision.approvedAt = check.resolution.timestamp;
+    point.answer = check.answer;
+    return;
+  }
+  if ("refused" in check) {
+    decision.status = "refused";
+    decision.refused = { reason: "point", runs: members.map((m) => m.member), message: check.refused };
+    point.answer = check.answer;
+    return;
+  }
+  decision.status = "waiting";
+  decision.pendingFact = check.pending;
+  decision.recorded = check.recorded;
+  decision.waitingSince = check.pending.timestamp;
+  point.question = check.waiting;
+  decision.approve = `chant workspace points answer ${check.waiting.id} --answer <answer> --by <your name>`;
+  log(`wave ${k} (${wave.name}) asks decision point ${point.name} about ${digest}: question ${check.waiting.id} is ${check.waiting.state}`);
+}
+
 /** Write the decision record, with every hook's outcome so far (#3804). */
 function writeRecord(recordPath: string, decision: OpWaveDecision, result: RunOpWaveResult): void {
   if (result.hooks.length > 0) decision.outcomes = [...result.hooks];
@@ -1557,6 +1741,13 @@ async function settleHolds(
   decision.heldBy = [...(decision.heldBy ?? []), ...holds];
   await settleGate(options, ctx, decision);
   if (recordPath) writeRecord(recordPath, decision, result);
+  if (decision.status === "refused") {
+    // #3836: the gate's decision point refused the held wave.
+    if (recordPath) await runGateHooks(ctx, decision, recordPath);
+    log(`wave ${k} (${wave.name}) is held by ${holds.join(", ")}; nothing applied: ${decision.refused?.message ?? "refused"}`);
+    result.exitCode = refusedExit(decision);
+    return false;
+  }
   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);
@@ -1786,7 +1977,7 @@ async function applyStage(
     return;
   }
   if (waiting) {
-    result.exitCode = 3;
+    result.exitCode = decision.status === "refused" ? refusedExit(decision) : 3;
     return;
   }
   if (result.failed.length > 0) {

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

@@ -788,8 +788,8 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(opts.atBase ?? tg) });
     return { cwd, calls, envs, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
   }
-  const run = (h: ReturnType<typeof harness>, gates = memoryGateLedgerPort(), spec: OpWavesSpec = tg) =>
-    runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00.000Z", log: () => {} });
+  const run = (h: ReturnType<typeof harness>, gates = memoryGateLedgerPort(), spec: OpWavesSpec = tg, log: (m: string) => void = () => {}) =>
+    runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates, now: "2026-10-11T00:00:00.000Z", log });
 
   test("the spec checks after.gate hooks and override", () => {
     expect(() => assertOpWavesSpec(tg)).not.toThrow();
@@ -862,6 +862,21 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     other.done();
   });
 
+  test("a plans file's overridersSource names the list in the refusal and the decision record (#3848)", async () => {
+    const mk = (extra: Record<string, unknown>) => harness({ vpc: { planDigest: digest("1"), denied: { rules: ["no-public-s3"] } }, dns: { planDigest: digest("2") } }, { extra });
+    const logs: string[] = [];
+    const h = mk({ overriders: ["github:dave"], overridersSource: "policy.override in terragucci.yml" });
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "policy-override", gate: "vpc", resolvedBy: "github:carol", timestamp: "2026-10-10T00:00:00Z", planDigest: (await import("../override-gate")).overrideDigest("vpc", digest("1"), ["no-public-s3"]), note: "ok" }] });
+    const result = await run(h, gates, tg, (m) => logs.push(m));
+    expect(result.decision!.refused).toMatchObject({ reason: "policy", overridersSource: "policy.override in terragucci.yml" });
+    expect(logs.join("\n")).toContain("github:carol is not listed in policy.override in terragucci.yml at base");
+    h.done();
+    const d = mk({ overriders: ["github:dave"] });
+    const r2 = await run(d, memoryGateLedgerPort());
+    expect(r2.decision!.refused).not.toHaveProperty("overridersSource");
+    d.done();
+  });
+
   test("a hook holds the wave on another gate: it waits on that gate's digest, then runs again once approved", async () => {
     const migrate = { name: "migrate", command: ["migrate", "{runs}"], onFailure: "approve" as const };
     const spec: OpWavesSpec = { ...tg, hooks: { before: { plan: [migrate] }, after: tg.hooks!.after } };
@@ -891,6 +906,84 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     expect(result.hooks.filter((o) => o.name === "migrate").map((o) => o.outcome)).toEqual(["held", "passed"]);
     again.done();
   });
+
+  test("an approved re-run holds the wave on a further gate: two migrations wait, then apply in turn (#3847)", async () => {
+    const migrate = { name: "migrate", command: ["migrate", "{runs}"], onFailure: "approve" as const };
+    const spec: OpWavesSpec = { ...tg, hooks: { before: { plan: [migrate] }, after: tg.hooks!.after } };
+    // The first migration holds on its gate; once approved it applies, and the second (whose digest is known only now) holds on its own.
+    const applied: string[] = [];
+    const hook = (argv: string[], env: Record<string, string>, dir: string) => {
+      if (argv[0] !== "migrate") return 0;
+      const done = env.CHANT_HOLDS_APPROVED ? (JSON.parse(env.CHANT_HOLDS_APPROVED) as Array<{ gate: string }>).map((a) => a.gate) : [];
+      for (const gate of done) if (!applied.includes(gate)) applied.push(gate);
+      const next = ["split-queues", "move-topics"].find((g) => !done.includes(g));
+      if (!next) return 0;
+      writeFileSync(join(dir, env.CHANT_HOLD!), JSON.stringify({ op: "tf-migrate", gate: next, digest: digest(next === "split-queues" ? "m" : "n") }));
+      return 3;
+    };
+    const plans = { vpc: { planDigest: digest("1"), empty: true }, dns: { planDigest: digest("2"), empty: true } };
+    const first = { version: 1 as const, op: "tf-migrate", gate: "split-queues", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: digest("m") };
+
+    // Only the first is approved: it applies, and the wave waits on the second (exit 3), naming it.
+    const h = harness(plans, { hook, atBase: spec });
+    const gates = memoryGateLedgerPort({ resolutions: [first] });
+    const waiting = await run(h, gates, spec);
+    expect(waiting.exitCode).toBe(3);
+    expect(waiting.decision).toMatchObject({
+      status: "waiting",
+      approve: `chant approve tf-migrate move-topics --plan ${digest("n")}`,
+      heldOn: { op: "tf-migrate", gate: "move-topics", digest: digest("n"), status: "waiting", after: [{ gate: "split-queues", digest: digest("m"), approvedBy: "alice" }] },
+    });
+    expect(gates.appended).toEqual([expect.objectContaining({ op: "tf-migrate", gate: "move-topics", planDigest: digest("n") })]);
+    expect(applied).toEqual(["split-queues"]);
+    expect(h.calls.some((c) => c.startsWith("tg plan"))).toBe(false);
+    expect(waiting.hooks.filter((o) => o.name === "migrate").map((o) => o.outcome)).toEqual(["held", "held"]);
+    h.done();
+
+    // Both approved: the hook runs three times, the last with both approvals, and the wave applies.
+    applied.length = 0;
+    const again = harness(plans, { hook, atBase: spec });
+    const both = memoryGateLedgerPort({ resolutions: [first, { ...first, gate: "move-topics", resolvedBy: "bob", planDigest: digest("n") }] });
+    const result = await run(again, both, spec);
+    expect(result.exitCode).toBe(0);
+    expect(applied).toEqual(["split-queues", "move-topics"]);
+    const reruns = again.envs.filter((_, i) => again.calls[i]!.startsWith("migrate"));
+    expect(reruns).toHaveLength(3);
+    expect(JSON.parse(reruns[2]!.CHANT_HOLD_APPROVED!)).toMatchObject({ gate: "move-topics", approvedBy: "bob" });
+    expect(JSON.parse(reruns[2]!.CHANT_HOLDS_APPROVED!).map((a: { gate: string }) => a.gate)).toEqual(["split-queues", "move-topics"]);
+    expect(result.hooks.filter((o) => o.name === "migrate").map((o) => o.outcome)).toEqual(["held", "held", "passed"]);
+    again.done();
+  });
+
+  test("an approved re-run that holds again on the same gate and digest, or past the bound, fails the wave (#3847)", async () => {
+    const migrate = { name: "migrate", command: ["migrate", "{runs}"], onFailure: "approve" as const };
+    const spec: OpWavesSpec = { ...tg, hooks: { before: { plan: [migrate] }, after: tg.hooks!.after } };
+    const plans = { vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") } };
+    const same = (argv: string[], env: Record<string, string>, dir: string) => {
+      if (argv[0] !== "migrate") return 0;
+      writeFileSync(join(dir, env.CHANT_HOLD!), JSON.stringify({ op: "tf-migrate", gate: "split-queues", digest: digest("m") }));
+      return 3;
+    };
+    const h = harness(plans, { hook: same, atBase: spec });
+    const gates = memoryGateLedgerPort({ resolutions: [{ version: 1, op: "tf-migrate", gate: "split-queues", resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: digest("m") }] });
+    expect((await run(h, gates, spec)).exitCode).toBe(1);
+    expect(h.calls.filter((c) => c.startsWith("migrate"))).toHaveLength(2);
+    h.done();
+
+    const { OP_WAVE_MAX_CHAINED_HOLDS } = await import("./op-waves-run");
+    let n = 0;
+    const endless = (argv: string[], env: Record<string, string>, dir: string) => {
+      if (argv[0] !== "migrate") return 0;
+      writeFileSync(join(dir, env.CHANT_HOLD!), JSON.stringify({ op: "tf-migrate", gate: `step-${n}`, digest: digest("m") }));
+      n++;
+      return 3;
+    };
+    const many = harness(plans, { hook: endless, atBase: spec });
+    const all = memoryGateLedgerPort({ resolutions: Array.from({ length: 20 }, (_, i) => ({ version: 1 as const, op: "tf-migrate", gate: `step-${i}`, resolvedBy: "alice", timestamp: "2026-10-10T00:00:00Z", planDigest: digest("m") })) });
+    expect((await run(many, all, spec)).exitCode).toBe(1);
+    expect(many.calls.filter((c) => c.startsWith("migrate"))).toHaveLength(OP_WAVE_MAX_CHAINED_HOLDS + 1);
+    many.done();
+  });
 });
 
 describe("discovered waves, a cost member and applies that apply nothing (#3821)", () => {