@intentius/chant 0.124.8 → 0.124.10

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();
@@ -836,6 +836,8 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     expect(result).toMatchObject({ exitCode: 7, decision: { status: "refused", refused: { reason: "policy", runs: ["vpc"] } } });
     expect(gates.appended).toHaveLength(1);
     expect(gates.appended[0]).toMatchObject({ op: "policy-override", gate: "vpc", plan: digest("1"), rules: ["no-public-s3"], members: [{ member: "vpc", planDigest: digest("1") }] });
+    // #3839: the denial names its wave as a field.
+    expect(gates.appended[0]).toMatchObject({ wave: { number: 1, name: expect.any(String), op: tg.name } });
     expect(h.envs.find((e) => e.CHANT_HOOK === "after-gate")).toMatchObject({ CHANT_GATE_STATUS: "refused" });
     expect(h.calls.some((c) => c.startsWith("tg apply"))).toBe(false);
     const { opWaveNotifyFields } = await import("./op-waves-notify");
@@ -862,13 +864,28 @@ 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 } };
     const hook = (argv: string[], env: Record<string, string>, dir: string) => {
       if (argv[0] !== "migrate") return 0;
       if (env.CHANT_HOLD_APPROVED) return 0;
-      writeFileSync(join(dir, env.CHANT_HOLD!), JSON.stringify({ op: "tf-migrate", gate: "split-queues", digest: digest("m"), pending: { members: [] } }));
+      writeFileSync(join(dir, env.CHANT_HOLD!), JSON.stringify({ op: "tf-migrate", gate: "split-queues", digest: digest("m"), description: "move the queues", pending: { members: [] } }));
       return 3;
     };
     const h = harness({ vpc: { planDigest: digest("1") }, dns: { planDigest: digest("2") } }, { hook, atBase: spec });
@@ -877,6 +894,8 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     expect(waiting).toMatchObject({ exitCode: 3, decision: { status: "waiting", heldOn: { op: "tf-migrate", gate: "split-queues", digest: digest("m"), status: "waiting" } } });
     expect(waiting.decision!.approve).toBe(`chant approve tf-migrate split-queues --plan ${digest("m")}`);
     expect(gates.appended[0]).toMatchObject({ op: "tf-migrate", gate: "split-queues", planDigest: digest("m"), members: [] });
+    // #3839: the hold names its wave as a field, even when the hook wrote the description.
+    expect(gates.appended[0]).toMatchObject({ description: "move the queues", wave: { number: 1, name: expect.any(String), op: tg.name } });
     expect(h.calls.some((c) => c.startsWith("tg plan"))).toBe(false);
     expect(h.envs.find((e) => e.CHANT_HOOK === "after-gate")).toMatchObject({ CHANT_GATE_STATUS: "waiting", CHANT_GATE_OP: "tf-migrate", CHANT_GATE: "split-queues" });
     h.done();
@@ -891,6 +910,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)", () => {

package/src/op/op-waves.ts

@@ -53,9 +53,21 @@
  * apply; like the policy they are read from the spec at the base commit, and
  * one whose `onFailure` is `approve` holds the wave for an approval whatever
  * its policy says.
+ *
+ * ## A gate that asks a decision point (#3836)
+ *
+ * With `point` (on the spec, or on a wave, whose own wins), read at base like
+ * the policy, a wave that needs an approval asks that workspace decision
+ * point instead of reading the ledger for a `chant approve`, the way an Op
+ * gate with a `point` does (#3170): `gate.planDigest` is the wave's set
+ * digest, so each plan is its own question. An open question waits (exit 3,
+ * the pending fact cites it), an answer the gate passes on records the
+ * resolution that cites it and the wave goes on, and any other answer refuses
+ * the wave (exit 8). See `./op-waves-run.ts`.
  */
 
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
+import { gatePointProblems, type GatePoint } from "./gate-point";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
 
 /**
@@ -92,6 +104,40 @@ export const GATE_APPROVAL_SOURCES: readonly GateApprovalSource[] = ["ledger", "
 /** What a failing hook does: fail the wave, or hold it for an approval of its set digest. */
 export type OpWaveHookFailure = "fail" | "approve";
 
+/**
+ * The decision point a wave's gate asks (#3836): a point's name, or `{ name,
+ * inputs?, pass?, store?, timeout? }` as an Op gate's `point` takes, plus the
+ * pending fact's `timeout` (default 48h). The point must declare the input
+ * `gate.planDigest`, which is the wave's set digest.
+ */
+export type OpWavePoint = GatePoint & {
+  /** How long the pending fact that cites an open question stands, such as `"48h"`. */
+  timeout?: string;
+};
+
+/** A wave's or a spec's `point` as an {@link OpWavePoint}, or undefined when it names none. */
+export function opWavePointOf(point: string | OpWavePoint | undefined): OpWavePoint | undefined {
+  if (point === undefined) return undefined;
+  return typeof point === "string" ? { name: point } : point;
+}
+
+/** What is wrong with a wave's `point`, empty when nothing is (#3836). */
+export function opWavePointProblems(point: unknown): string[] {
+  if (point !== null && typeof point === "object" && !Array.isArray(point) && "timeout" in point) {
+    const { timeout, ...rest } = point as Record<string, unknown>;
+    const problems = gatePointProblems(rest);
+    if (typeof timeout !== "string" || !/^(\d+(ms|s|m|h|d))+$/.test(timeout)) problems.push("`point.timeout` is a duration such as \"48h\"");
+    return problems;
+  }
+  return gatePointProblems(point);
+}
+
+/** The point wave `name`'s gate asks (#3836): the wave's own, else the spec's, else none. */
+export function opWavePointAt(spec: Pick<OpWavesSpec, "point" | "waves">, name: string): OpWavePoint | undefined {
+  const wave = spec.waves.find((w) => w.name === name);
+  return opWavePointOf(wave?.point ?? spec.point);
+}
+
 export const OP_WAVE_HOOK_FAILURES: readonly OpWaveHookFailure[] = ["fail", "approve"];
 
 /** One stage hook (#3762): a command run before or after a wave's plan or apply. */
@@ -181,6 +227,11 @@ export interface OpWave {
    * Like `gate`, the runner reads it from the spec file at the base commit.
    */
   approval?: GateApprovalSource;
+  /**
+   * The decision point this wave's gate asks (#3836), in place of the spec's.
+   * Read at base like `gate`. See {@link OpWavesSpec.point}.
+   */
+  point?: string | OpWavePoint;
   /**
    * Split the wave into a deciding job and this many share jobs, each
    * applying a slice of the runs. Default 1: one job plans, decides and
@@ -266,6 +317,15 @@ export interface OpWavesSpec {
    * the rules (`@intentius/chant/override-gate`).
    */
   override?: OpWavesOverride;
+  /**
+   * The decision point every wave's gate asks (#3836), unless a wave names its
+   * own. Read at the base commit, like the policy: a wave that needs an
+   * approval asks the point with `gate.planDigest` set to its set digest, and
+   * only an answer the point's `pass` names (default yes) for that digest
+   * lets it apply. `chant approve` does not pass such a gate, and the wave's
+   * `approval` mode does not apply: the point's deciders and quorum decide.
+   */
+  point?: string | OpWavePoint;
   waves: OpWave[];
   /**
    * A scheduled job that starts again a wave job whose approval has arrived
@@ -442,6 +502,10 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       if (typeof value !== "string" || value.trim() === "") throw new Error(`${where}: override.overriders must be a path, such as ".chant/overriders".`);
     }
   }
+  if (spec.point !== undefined) {
+    const problems = opWavePointProblems(spec.point);
+    if (problems.length > 0) throw new Error(`${where}: ${problems.join("; ")}.`);
+  }
   if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean") throw new Error(`${where}: neverOverMcp must be true or false.`);
   if (spec.notify !== undefined) {
     const problem = notifyConfigProblem(spec.notify, "notify");
@@ -461,6 +525,10 @@ export function assertOpWavesSpec(spec: OpWavesSpec): void {
       throw new Error(`${where}: wave "${wave.name}" has approval "${wave.approval}"; use ${GATE_APPROVAL_SOURCES.join(", ")}.`);
     }
     assertOpWaveHooks(`${where}, wave "${wave.name}"`, wave.hooks);
+    if (wave.point !== undefined) {
+      const problems = opWavePointProblems(wave.point);
+      if (problems.length > 0) throw new Error(`${where}: wave "${wave.name}": ${problems.join("; ")}.`);
+    }
     if (wave.discover !== undefined && typeof wave.discover !== "boolean") throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
     if (wave.rest !== undefined && typeof wave.rest !== "boolean") throw new Error(`${where}: wave "${wave.name}" has rest ${JSON.stringify(wave.rest)}; use true or false.`);
     if (wave.discover) {

package/src/workspace/identity.test.ts

@@ -202,7 +202,10 @@ describe.skipIf(!hasSshKeygen)("identity.gates", () => {
 
     const roster = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex")] });
     expect((await evaluateGate(roster, input)).satisfied).toBe(true);
-    expect((await evaluateGate({ ...roster, approvalRule: async () => rule }, input)).satisfied).toBe(false);
+    const held = await evaluateGate({ ...roster, approvalRule: async () => rule }, input);
+    expect(held.satisfied).toBe(false);
+    // #3841: the approval the rule refused is named, with why.
+    expect(!held.satisfied && held.refused?.map((x) => [x.resolution.resolvedBy, x.reason])).toEqual([["alex", expect.stringMatching(/not signed/)]]);
     const sealed = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex"), signed(alice, approval("github:alice"))] });
     const check = await evaluateGate({ ...sealed, approvalRule: async () => rule }, input);
     expect(check.satisfied && check.resolution.resolvedBy).toBe("github:alice");

package/src/workspace/identity.ts

@@ -179,8 +179,9 @@ export function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdm
  * The rule for `gate` in the workspace holding `cwd`, read at base (the
  * target branch tip), or null when there is no declaration or it names none.
  * What a run, `chant approve` and `workspace status` ask before counting an
- * approval.
+ * approval. `base` names the commit to read at instead, as an op wave reads
+ * every rule at its `--base` (#3841).
  */
-export function gateAdmission(cwd: string, gate: string): GateAdmission | null {
-  return gateAdmissionFrom(scopeSource(cwd), gate);
+export function gateAdmission(cwd: string, gate: string, base?: string): GateAdmission | null {
+  return gateAdmissionFrom(scopeSource(cwd, base), gate);
 }

package/src/workspace/write-scope.ts

@@ -368,11 +368,12 @@ function readAt(cwd: string, at?: string): { declaration: Declaration; rootOnDis
  * The scope for a write from `cwd`: the declaration and the trust policy at
  * the base revision (`origin/HEAD`, `main` or `master`), so a write can't
  * widen its own scope by editing its copy of the declaration. Without a base,
- * or without a declaration at it, the working tree's declaration.
+ * or without a declaration at it, the working tree's declaration. `at` names
+ * the base instead, as an op wave's `--base` does (#3841).
  */
-export function scopeSource(cwd: string): ScopeSource {
+export function scopeSource(cwd: string, at?: string): ScopeSource {
   const top = gitRoot(cwd);
-  const base = top ? resolveBase(top) : null;
+  const base = top ? resolveBase(top, at) : null;
   const policy = top && base ? policyAtBase(top, base) : emptyPolicy(null);
   const withClasses = (read: NonNullable<ReturnType<typeof readAt>>) => {
     const { tree, ...rest } = read;