@intentius/chant 0.124.14 → 0.124.16

package/src/lifecycle/gate-ledger.ts

@@ -228,6 +228,21 @@ export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">
  * ledger by a line a minute. Once `expiresAt` passes, the fact is stale and
  * the next run records a fresh one.
  */
+export interface PendingGateWave {
+  number: number;
+  name: string;
+  /** The Op waves spec's name. */
+  op?: string;
+}
+
+/** The hook that holds a wave on a gate (#3886): which hook asked, at which moment, and for which run. */
+export interface PendingGateHeldBy {
+  hook: string;
+  moment: string;
+  /** The run, for a `perRun` hook. */
+  target?: string;
+}
+
 export interface PendingGateRecord {
   /** Schema version, so an incompatible future shape is detected before being misread. */
   version: 1;
@@ -296,6 +311,17 @@ export interface PendingGateRecord {
    * than inferring it from config. Not the quorum block in `approval`.
    */
   approvalMode?: GateApprovalSource;
+  /**
+   * The Op wave this gate belongs to (#3839): a hold on another gate or a
+   * policy denial. Absent on a gate that is not a wave's.
+   */
+  wave?: PendingGateWave;
+  /**
+   * The hook that holds the wave on this gate (#3886), on a hold only: its
+   * name, the moment it ran at and its run. A reader names the holder from it
+   * rather than from `description`, which the hook writes.
+   */
+  heldBy?: PendingGateHeldBy;
   /**
    * The open question this gate waits on, on a gate that asks a decision
    * point (#3170). It is answered with `chant workspace points answer <id>`,
@@ -449,7 +475,13 @@ export function parseGateLedger(
           malformed++;
           continue;
         }
-        pending.push(parsed as PendingGateRecord);
+        // #3887: a `wave` or `heldBy` of the wrong shape is dropped, so a reader can trust the type.
+        const rec = parsed as PendingGateRecord;
+        const w = (parsed as { wave?: unknown }).wave as Partial<PendingGateWave> | null | undefined;
+        if (w !== undefined && !(w && typeof w === "object" && typeof w.number === "number" && typeof w.name === "string")) delete rec.wave;
+        const h = (parsed as { heldBy?: unknown }).heldBy as Partial<PendingGateHeldBy> | null | undefined;
+        if (h !== undefined && !(h && typeof h === "object" && typeof h.hook === "string" && typeof h.moment === "string")) delete rec.heldBy;
+        pending.push(rec);
         continue;
       }
       if (typeof parsed.resolvedBy !== "string") {

package/src/op/activities/activity-contracts.ts

@@ -271,7 +271,7 @@ export const lifecyclePlanChangeSetContract = activityContract(
 
 export const readChangeSetPartContract = activityContract(
   "readChangeSetPart",
-  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden"]), file: z.string(), lexicon: z.string().optional() }),
+  z.strictObject({ member: z.string(), planner: z.enum(["chant", "warden", "sql"]), file: z.string(), lexicon: z.string().optional() }),
   z.object({ part: changeSetPart }),
 );
 

package/src/op/activities/change-set.ts

@@ -25,6 +25,7 @@ import { promisify } from "node:util";
 import {
   composeChangeSet as compose,
   lifecyclePlanPart,
+  readChangeSetPartFile,
   reconcilePlanPart,
   type ChangeSetDocument,
   type ChangeSetPart,
@@ -87,8 +88,12 @@ export async function lifecyclePlanChangeSet(args: LifecyclePlanChangeSetArgs, s
 
 export interface ReadChangeSetPartArgs {
   member: string;
-  /** Which planner wrote the file: `chant` (`lifecycle plan --json`) or `warden` (its reconcile change sets). */
-  planner: "chant" | "warden";
+  /**
+   * Which planner wrote the file: `chant` (`lifecycle plan --json`), `warden`
+   * (its reconcile change sets), or `sql` (a part the sql lexicon's
+   * `change-set` adapters produced, written as JSON).
+   */
+  planner: "chant" | "warden" | "sql";
   /** The plan file, relative to the current directory. */
   file: string;
   /** The lexicon the entries belong to, when the plan does not say. */
@@ -98,7 +103,8 @@ export interface ReadChangeSetPartArgs {
 /**
  * A plan another step or job wrote to a file, as a member's part. A warden
  * plan is the reconcile `ChangeSet` (`@intentius/chant/reconcile`), or an
- * array of them, one per cycle and org.
+ * array of them, one per cycle and org. A sql plan is already a part
+ * (`@intentius/chant-lexicon-sql/change-set`), renamed to `member` here.
  */
 export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<ChangeSetPartResult> {
   const plan: unknown = JSON.parse(readFileSync(resolve(args.file), "utf-8"));
@@ -108,6 +114,8 @@ export async function readChangeSetPart(args: ReadChangeSetPartArgs): Promise<Ch
       return { part: lifecyclePlanPart({ member: args.member, plan: plan as LifecycleChangeSet, ...lexicon }) };
     case "warden":
       return { part: reconcilePlanPart({ member: args.member, plan: plan as ReconcileChangeSet | ReconcileChangeSet[], ...lexicon }) };
+    case "sql":
+      return { part: readChangeSetPartFile(plan, "sql", args.member, args.lexicon) };
     default:
       throw new Error(`readChangeSetPart: no adapter for planner ${String(args.planner)}; terraform-family plans come from terraformPlan's changeSet`);
   }

package/src/op/activities/lexicon-upgrade.test.ts

@@ -317,6 +317,8 @@ describe("lexiconUpgrade issue mode", () => {
 
     vi.stubEnv("GITHUB_REPOSITORY", "acme/infra");
     vi.stubEnv("GITHUB_API_URL", "");
+    // A Forgejo run, since CHANT_FORGEJO_TOKEN is only read there (#3807).
+    vi.stubEnv("FORGEJO_ACTIONS", "true");
     // The cross-instance case (#2320): a Forgejo token that must outrank the
     // job's own `github.token`, on the path that used to forward neither.
     vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-cross-instance");

package/src/op/activities/reconcile.test.ts

@@ -21,6 +21,7 @@ import {
   ghCredentialEnv,
   githubShapedForgeFrom,
 } from "./reconcile";
+import { FORGE_TOKEN_ORDER } from "../../pr-forge";
 
 // ── The `gh` stub (chant #2291) ──────────────────────────────────────────────
 //
@@ -338,12 +339,46 @@ describe("commentTokenFrom (#2291)", () => {
     expect(commentTokenFrom({ GITHUB_TOKEN: "ghs_y" })).toEqual({ value: "ghs_y", source: "GITHUB_TOKEN" });
   });
 
-  test("CHANT_FORGEJO_TOKEN wins over both, for the cross-instance case", () => {
+  test("on Forgejo CHANT_FORGEJO_TOKEN wins, then FORGEJO_TOKEN, then GH_TOKEN, then GITHUB_TOKEN", () => {
+    const base = { FORGEJO_ACTIONS: "true" };
+    const all = { CHANT_FORGEJO_TOKEN: "a", FORGEJO_TOKEN: "b", GH_TOKEN: "c", GITHUB_TOKEN: "d" };
+    expect(commentTokenFrom({ ...base, ...all })?.source).toBe("CHANT_FORGEJO_TOKEN");
+    expect(commentTokenFrom({ ...base, FORGEJO_TOKEN: "b", GH_TOKEN: "c", GITHUB_TOKEN: "d" })?.source).toBe("FORGEJO_TOKEN");
+    expect(commentTokenFrom({ ...base, GH_TOKEN: "c", GITHUB_TOKEN: "d" })?.source).toBe("GH_TOKEN");
+  });
+
+  test("a /api/v1 API base is Forgejo even without FORGEJO_ACTIONS", () => {
     expect(
-      commentTokenFrom({ CHANT_FORGEJO_TOKEN: "a", GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source,
+      commentTokenFrom({ GITHUB_API_URL: "https://f.example/api/v1", CHANT_FORGEJO_TOKEN: "a", GH_TOKEN: "b" })?.source,
     ).toBe("CHANT_FORGEJO_TOKEN");
   });
 
+  test("on GitHub CHANT_GITHUB_TOKEN wins, then GH_TOKEN, then GITHUB_TOKEN (#3807)", () => {
+    const base = { GITHUB_ACTIONS: "true" };
+    expect(commentTokenFrom({ ...base, CHANT_GITHUB_TOKEN: "a", GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source).toBe("CHANT_GITHUB_TOKEN");
+    expect(commentTokenFrom({ ...base, GH_TOKEN: "b", GITHUB_TOKEN: "c" })?.source).toBe("GH_TOKEN");
+  });
+
+  test("on GitHub CHANT_FORGEJO_TOKEN and FORGEJO_TOKEN are not read (#3807)", () => {
+    expect(
+      commentTokenFrom({ GITHUB_ACTIONS: "true", CHANT_FORGEJO_TOKEN: "a", FORGEJO_TOKEN: "b", GH_TOKEN: "c" }),
+    ).toEqual({ value: "c", source: "GH_TOKEN" });
+    expect(commentTokenFrom({ GITHUB_ACTIONS: "true", CHANT_FORGEJO_TOKEN: "a" })).toBeUndefined();
+  });
+
+  test("agrees with FORGE_TOKEN_ORDER for each forge", () => {
+    for (const [kind, env] of [
+      ["github", { GITHUB_ACTIONS: "true" }],
+      ["forgejo", { FORGEJO_ACTIONS: "true" }],
+    ] as const) {
+      for (const name of FORGE_TOKEN_ORDER[kind]) {
+        const rest = FORGE_TOKEN_ORDER[kind].slice(FORGE_TOKEN_ORDER[kind].indexOf(name));
+        const vars = Object.fromEntries(rest.map((n) => [n, `v-${n}`]));
+        expect(commentTokenFrom({ ...env, ...vars })?.source).toBe(name);
+      }
+    }
+  });
+
   test("no token at all is undefined rather than an empty value", () => {
     expect(commentTokenFrom({})).toBeUndefined();
     expect(commentTokenFrom({ GH_TOKEN: "", GITHUB_TOKEN: "" })).toBeUndefined();
@@ -469,6 +504,31 @@ describe("reconcilePr comment mode posts through the forge client (#2291, #3757)
     }
   });
 
+  test("on a GitHub run CHANT_FORGEJO_TOKEN is ignored and GH_TOKEN is sent (#3807)", async () => {
+    stubPrEnv("https://api.github.com");
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("CHANT_FORGEJO_TOKEN", "forgejo-token-set-on-github");
+    try {
+      await reconcilePr({ env: "app", mode: "comment", body: "the plan" });
+      expect(forgeCalls.length).toBeGreaterThan(0);
+      for (const call of forgeCalls) expect(call.authorization).toBe("Bearer forgejo-actions-token");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
+  test("on a GitHub run CHANT_GITHUB_TOKEN outranks GH_TOKEN (#3807)", async () => {
+    stubPrEnv("https://api.github.com");
+    vi.stubEnv("GITHUB_ACTIONS", "true");
+    vi.stubEnv("CHANT_GITHUB_TOKEN", "other-github-token");
+    try {
+      await reconcilePr({ env: "app", mode: "comment", body: "the plan" });
+      for (const call of forgeCalls) expect(call.authorization).toBe("Bearer other-github-token");
+    } finally {
+      vi.unstubAllEnvs();
+    }
+  });
+
   test("FORGEJO_ACTIONS marks a Forgejo run whatever its API base looks like", async () => {
     stubPrEnv("https://code.example/api/forgejo");
     vi.stubEnv("FORGEJO_ACTIONS", "true");

package/src/op/activities/reconcile.ts

@@ -1,7 +1,15 @@
 import { exec } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
-import { ForgeApiError, forgejoForge, githubForge, type ForgeFetch, type GithubShapedForge } from "../../pr-forge";
+import {
+  detectForge,
+  FORGE_TOKEN_ORDER,
+  ForgeApiError,
+  forgejoForge,
+  githubForge,
+  type ForgeFetch,
+  type GithubShapedForge,
+} from "../../pr-forge";
 import { ghHostEnv } from "./gh-host";
 import { restPullRequestForge } from "./forge-pull-request";
 
@@ -49,9 +57,11 @@ const execAsync = promisify(exec);
  * of opening a second one.
  *
  * Both modes resolve the GitHub/Forgejo credential the same way, through
- * {@link commentTokenFrom}: `CHANT_FORGEJO_TOKEN`, then `GH_TOKEN`, then
- * `GITHUB_TOKEN` (chant #2320), refusing by name before any call when none
- * is set ({@link noCommentTokenMessage}, {@link noIssueTokenMessage}).
+ * {@link commentTokenFrom}, in pr-forge's `FORGE_TOKEN_ORDER` for the forge the
+ * run is on (chant #2320, #3807): `CHANT_GITHUB_TOKEN`, `GH_TOKEN`,
+ * `GITHUB_TOKEN` on GitHub; `CHANT_FORGEJO_TOKEN`, `FORGEJO_TOKEN`,
+ * `GH_TOKEN`, `GITHUB_TOKEN` on Forgejo. It refuses by name before any call
+ * when none is set ({@link noCommentTokenMessage}, {@link noIssueTokenMessage}).
  *
  * Until #3757 these two modes shelled to `gh api`. That reached Forgejo only
  * after two fixes: a full URL, because `gh` resolves a relative path against
@@ -451,24 +461,38 @@ export interface CommentToken {
   source: string;
 }
 
+/**
+ * Which GitHub-shaped forge a run is on: Forgejo when `detectForge` says so
+ * (`FORGEJO_ACTIONS`/`GITEA_ACTIONS`, or a `GITHUB_API_URL` ending in
+ * `/api/v1`), or when the API base ends in `/api/v1`, which is how a step
+ * posting to some other Forgejo instance names it. GitHub serves `/api/v3`
+ * or `api.github.com`, never `/api/v1`. Anything else is GitHub.
+ */
+export function githubShapedKindFrom(env: Record<string, string | undefined>): "github" | "forgejo" {
+  if (detectForge(env) === "forgejo") return "forgejo";
+  return /\/api\/v1$/.test(githubApiBaseFrom(env)) ? "forgejo" : "github";
+}
+
 /**
  * Resolve the token the `comment` and `issue` modes post with on GitHub and
- * Forgejo, most specific first (chant #2291). The generated workflow sets
- * `GH_TOKEN` and `GITHUB_TOKEN` to `${{ github.token }}` for every
- * non-`report` finding mode — on
- * Forgejo the same way as on GitHub, and the real-instance read confirmed
- * `github.token` is populated there and good for a 200 read and a 201 write,
- * authored as `forgejo-actions`. So the common case needs nothing set beyond
- * what the generator already emits.
+ * Forgejo (chant #2291), in pr-forge's `FORGE_TOKEN_ORDER` for the forge the
+ * run is on (#3807), so this and `forgeTargetFromEnv` cannot drift apart.
+ * GitHub reads `CHANT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`; Forgejo reads
+ * `CHANT_FORGEJO_TOKEN`, `FORGEJO_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`. The
+ * generated workflow sets `GH_TOKEN` and `GITHUB_TOKEN` to
+ * `${{ github.token }}` for every non-`report` finding mode, on Forgejo the
+ * same way as on GitHub, so the common case needs nothing set beyond what the
+ * generator already emits.
  *
- * `CHANT_FORGEJO_TOKEN` is checked first for the case that ambient token
- * cannot cover: a run posting to a Forgejo instance other than the one the
- * job executes on, where `github.token`'s scope stops at its own instance.
- * A run with none of the three is refused by name before any call, in place
- * of the forge's own opaque 401.
+ * The chant-specific variable comes first for the case that ambient token
+ * cannot cover: a run posting to an instance other than the one the job
+ * executes on, where `github.token`'s scope stops at its own instance.
+ * `CHANT_FORGEJO_TOKEN` is no longer read on a GitHub run. A run with none of
+ * the names is refused by name before any call, in place of the forge's own
+ * opaque 401.
  */
 export function commentTokenFrom(env: Record<string, string | undefined>): CommentToken | undefined {
-  for (const source of ["CHANT_FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
+  for (const source of FORGE_TOKEN_ORDER[githubShapedKindFrom(env)]) {
     const value = env[source]?.trim();
     if (value) return { value, source };
   }
@@ -543,8 +567,8 @@ export function noCommentTokenMessage(repo: string, number: number): string {
   return (
     `reconcilePr mode "comment" has pull request ${repo}#${number} to post its finding on and no token to ` +
     "post it with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions " +
-    "or Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
-    "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ."
+    "or Forgejo Actions run — set CHANT_GITHUB_TOKEN (GitHub) or CHANT_FORGEJO_TOKEN (Forgejo) to post " +
+    "against a different instance than the one the job runs on. It is read first where the two must differ."
   );
 }
 
@@ -553,8 +577,8 @@ export function noIssueTokenMessage(repo: string): string {
   return (
     `reconcilePr mode "issue" has repository ${repo} to open or edit its finding in and no token to do it ` +
     "with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions or " +
-    "Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
-    "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ."
+    "Forgejo Actions run — set CHANT_GITHUB_TOKEN (GitHub) or CHANT_FORGEJO_TOKEN (Forgejo) to post " +
+    "against a different instance than the one the job runs on. It is read first where the two must differ."
   );
 }
 
@@ -582,7 +606,7 @@ export function githubShapedForgeFrom(
   signal?: AbortSignal,
 ): GithubShapedForge {
   const apiBase = githubApiBaseFrom(env);
-  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true" || /\/api\/v1$/.test(apiBase);
+  const forgejo = githubShapedKindFrom(env) === "forgejo";
   // Read at call time, so a test that stubs the global sees its stub.
   const fetchImpl: ForgeFetch = (url, init) => globalThis.fetch(url, { ...init, ...(signal ? { signal } : {}) });
   const opts = { apiBase, repo, token: token.value, fetch: fetchImpl };

package/src/op/builders.ts

@@ -428,7 +428,7 @@ export const lifecyclePlanChangeSet = (args: WithStepRefs<LifecyclePlanChangeSet
   return activity("lifecyclePlanChangeSet", rest, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
 };
 
-/** A member's change-set part from a plan file a chant or warden run wrote (#3181). Its `part` feeds {@link composeChangeSet}. */
+/** A member's change-set part from a plan file a chant, warden or sql run wrote (#3181, #3767). Its `part` feeds {@link composeChangeSet}. */
 export const readChangeSetPart = (args: WithStepRefs<ReadChangeSetPartArgs> & StepOpts): NamedActivityStep => {
   const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
   return activity("readChangeSetPart", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });

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

@@ -51,7 +51,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, posix } from "node:path";
-import { waveSetDigest, type WaveMember } from "../gated-waves";
+import { decideWaveGate, waveDigestMembers, waveSetDigest, writeWaveRecordFile, type WaveMember } from "../wave-engine";
 import type { ReviewApproval } from "../gate-decision";
 import { approveCommand, evaluateGate, gitGateLedgerPort, type GateCheck, type GateDigestMismatch, type GateLedgerPort } from "./gate";
 import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger";
@@ -130,7 +130,7 @@ export interface OpWavePlansFile {
 /** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
 export const OP_WAVE_PENDING_RESERVED = [
   "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
-  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer",
+  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer", "wave", "heldBy",
 ] as const;
 
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
@@ -817,8 +817,7 @@ function pendingFields(value: unknown, where: string): Record<string, unknown> |
  * 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 }>, extras: readonly WaveMember[] = []): string {
-  const changing = spec.digest?.over === "changing" ? members.filter((m) => m.empty !== true) : [];
-  return waveSetDigest([...(changing.length > 0 ? changing : members), ...extras]);
+  return waveSetDigest(waveDigestMembers(members, { ...(spec.digest?.over ? { over: spec.digest.over } : {}), extras }));
 }
 
 /** What one moment's hooks came to. */
@@ -835,6 +834,7 @@ interface HooksOutcome {
 interface OtherGateHold {
   label: string;
   name: string;
+  moment: OpWaveHookMoment;
   target?: string;
   argv: string[];
   env: Record<string, string>;
@@ -914,7 +914,7 @@ function runHookList(
         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 });
+          out.otherGates.push({ label, name, moment, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
           log(`${label} exited ${code} and holds wave ${k} (${waveName}) on gate ${request.op ?? specName} / ${request.gate}, digest ${request.digest}`);
           continue;
         }
@@ -1068,7 +1068,7 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold): Promise<O
     description: hold.request.description ?? `wave ${k} (${wave.name}) of ${spec.name} is held on it by ${hold.label}`,
     now,
     // #3839: the wave a hold belongs to, as a field, whatever the hook's own description says.
-    fields: { ...hold.request.pending, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name } },
+    fields: { ...hold.request.pending, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name }, heldBy: { hook: hold.name, moment: hold.moment, ...(hold.target ? { target: hold.target } : {}) } },
     ...(neverOverMcp ? { neverOverMcp: true } : {}),
   });
   const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };
@@ -1626,10 +1626,10 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
   // #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;
   const held = decision.heldBy?.length ? `, held by ${decision.heldBy.join(", ")}` : "";
-  const check = await evaluateGate(port, {
+  const check = await decideWaveGate(port, {
     op: spec.name,
     gate,
-    planDigest: digest,
+    digest,
     description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
     now,
     ...(spent ? { spent } : {}),
@@ -1727,7 +1727,7 @@ async function settlePointGate(options: RunOpWaveOptions, ctx: WaveContext, deci
 /** 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];
-  writeFileSync(recordPath, JSON.stringify(decision, null, 2) + "\n");
+  writeWaveRecordFile(recordPath, decision);
 }
 
 /**

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

@@ -910,6 +910,8 @@ describe("gates and holds a product's wave needs (#3821)", () => {
     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 } });
+    // #3886: and the hook that holds it, as a field.
+    expect(gates.appended[0]).toMatchObject({ heldBy: { hook: "migrate", moment: expect.any(String) } });
     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();

package/src/op/op-waves.ts

@@ -69,6 +69,7 @@
 import type { OpEnvironment, OpSetupStep } from "../lexicon";
 import { gatePointProblems, type GatePoint } from "./gate-point";
 import { notifyConfigProblem, type NotifyConfig } from "../notify";
+import { WAVE_GATE_NAME_PATTERN, waveGateNameFrom, waveShare } from "../wave-layout";
 
 /**
  * The variables a wave job reads its notify secrets from, for the lexicons
@@ -361,11 +362,11 @@ export interface OpWavesDigest {
 export const OP_WAVES_DIGEST_OVER = ["all", "changing"] as const;
 
 /** The default gate name pattern. */
-export const OP_WAVE_DEFAULT_GATE_NAME = "{gate}-wave-{k}";
+export const OP_WAVE_DEFAULT_GATE_NAME = WAVE_GATE_NAME_PATTERN;
 
 /** The gate wave `k` waits on (#3821): the spec's `gateName` pattern, by default `<gate>-wave-<k>`. */
 export function opWaveGateName(spec: Pick<OpWavesSpec, "name" | "gate" | "gateName">, k: number): string {
-  return (spec.gateName ?? OP_WAVE_DEFAULT_GATE_NAME).replaceAll("{gate}", spec.gate ?? spec.name).replaceAll("{k}", String(k));
+  return waveGateNameFrom(spec.gateName, spec.gate ?? spec.name, k);
 }
 
 /** Where a wave reads who may override a policy denial (#3821). */
@@ -638,12 +639,7 @@ export function opWaveApplyHooksRunBy(spec: Pick<OpWavesSpec, "hooks" | "waves">
  * by target, cut into contiguous slices whose sizes differ by at most one.
  */
 export function opWaveShare<T extends { target: string }>(runs: readonly T[], share: number, shares: number): T[] {
-  const sorted = [...runs].sort((a, b) => (a.target < b.target ? -1 : a.target > b.target ? 1 : 0));
-  const base = Math.floor(sorted.length / shares);
-  const extra = sorted.length % shares;
-  const start = (share - 1) * base + Math.min(share - 1, extra);
-  const size = base + (share <= extra ? 1 : 0);
-  return sorted.slice(start, start + size);
+  return waveShare(runs, share, shares, (run) => run.target);
 }
 
 /**

package/src/op/work-lease-run.test.ts

@@ -4,7 +4,7 @@
  * when it ends, and a lost lease stopping the run. An Op that changes the
  * checkout runs its leased steps in a worktree of its own.
  */
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -230,6 +230,11 @@ describe("a run under a work lease", () => {
   }, 30_000);
 
   test("a lease lost mid-step stops the step and the run, which fails lease-lost and releases nothing", async () => {
+    // The heartbeat is the only timer faked: the test fires its beat itself
+    // once the thief holds the lease, instead of waiting a wall-clock second
+    // for a renewal that a loaded machine can delay past any fixed bound.
+    vi.useFakeTimers({ toFake: ["setInterval", "clearInterval"] });
+    try {
     await withTestDir(async (dir) => {
       await initRepo(dir);
       const log: string[] = [];
@@ -241,9 +246,9 @@ describe("a run under a work lease", () => {
             // The lease runs out from under this run and another worker takes it.
             await releaseWorkLease(lease.item, lease.holder, { cwd: dir, token: lease.token });
             expect((await claimWorkLease(lease.item, "thief", { cwd: dir, ttlMs: 60_000 })).ok).toBe(true);
-            await new Promise<void>((resolve, reject) => {
-              const t = setTimeout(() => reject(new Error("never stopped")), 20_000);
-              signal?.addEventListener("abort", () => { clearTimeout(t); log.push("stopped"); reject(new Error("aborted")); }, { once: true });
+            await new Promise<void>((_resolve, reject) => {
+              signal?.addEventListener("abort", () => { log.push("stopped"); reject(new Error("aborted")); }, { once: true });
+              void vi.advanceTimersByTimeAsync(1_000);
             });
             return {};
           },
@@ -270,6 +275,9 @@ describe("a run under a work lease", () => {
       expect((await listWorkLeases({ cwd: dir, memberPrefix: "" }))[0]).toMatchObject({ holder: "thief", state: "active" });
       expect((await readRunLedger("local", "dispatch", { cwd: dir })).records.at(-1)?.status).toBe("fail");
     });
+    } finally {
+      vi.useRealTimers();
+    }
   }, 30_000);
 
   test("a run whose lease was lost before it is recorded is never recorded as done", async () => {

package/src/package-version.ts

@@ -0,0 +1,11 @@
+/**
+ * `@intentius/chant`'s own version, read from its package.json as a file. The
+ * path is the same from `src/` and `dist/`. The slim wave-job runtime (#3896)
+ * has no package.json beside it, and its build writes the version in here.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export function readChantPackageVersion(): string {
+  return (JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf-8")) as { version: string }).version;
+}

package/src/wave-engine.test.ts

@@ -0,0 +1,107 @@
+/**
+ * One wave engine under both runners (#3766): the same runs, planned to the
+ * same digests, are the same set digest and the same gate name whether
+ * `chant run wave` (an Op waves spec) or `chant components fan-out
+ * --wave-gate` decides the wave. An approval recorded through one matches a
+ * wave the other plans.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "vitest";
+import { memoryGateLedgerPort } from "./op/gate";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op/op-waves-run";
+import { opWaveGateName, opWaveShare, type OpWavesSpec } from "./op/op-waves";
+import { planFanOut } from "./components/fan-out";
+import { runFanOut } from "./components/fan-out-run";
+import { CapabilityRegistry } from "./components/capability";
+import type { DriverComponent } from "./components/driver";
+import { waveGateName, waveGateNameFrom, waveSetDigest, waveShare, WAVE_GATE_NAME_PATTERN } from "./wave-engine";
+
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+/** The runs both runners plan: a member name and its plan digest. */
+const RUNS: Record<string, string> = { "tenant-b": digest("b"), "tenant-a": digest("a"), "tenant-c": digest("c") };
+const NOW = "2026-10-11T00:00:00Z";
+
+async function throughOpWaves(): Promise<{ digest: string; gate: string; pending: string | undefined }> {
+  const spec: OpWavesSpec = {
+    name: "rollout",
+    op: "migrate",
+    plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+    apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+    waves: [{ name: "tenants", runs: Object.keys(RUNS).map((target) => ({ target })) }],
+  };
+  const cwd = mkdtempSync(join(tmpdir(), "wave-engine-"));
+  try {
+    const exec: OpWaveExec = (argv, dir) => {
+      if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify({ planDigest: RUNS[argv[2]!] }));
+      return 0;
+    };
+    const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd, exec, show, gates, now: NOW });
+    expect(result.exitCode).toBe(3);
+    return { digest: result.decision!.digest, gate: result.decision!.gate, pending: gates.appended[0]?.planDigest };
+  } finally {
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+async function throughFanOut(): Promise<{ digest: string; gate: string; pending: string | undefined }> {
+  const components: DriverComponent[] = Object.keys(RUNS).map((name) => ({ name, deploy: [{ phase: "Apply", steps: [] }] }));
+  const plan = planFanOut({ components, changed: Object.keys(RUNS) });
+  const gates = memoryGateLedgerPort();
+  const result = await runFanOut(plan, components, new CapabilityRegistry(), {
+    env: "prod",
+    gates,
+    now: NOW,
+    waveGate: {
+      op: "rollout",
+      gate: "rollout",
+      planComponent: async (component) => ({
+        component: component.name,
+        members: [{ member: component.name, planDigest: RUNS[component.name]! }],
+        plans: {},
+        parts: [],
+      }),
+    },
+  });
+  expect(result.status).toBe("gated");
+  const wave = result.waves![0]!;
+  return { digest: wave.digest, gate: wave.gate, pending: gates.appended[0]?.planDigest };
+}
+
+describe("one wave engine (#3766)", () => {
+  test("the same runs bind the same set digest and gate through both runners", async () => {
+    const expected = waveSetDigest(Object.entries(RUNS).map(([member, planDigest]) => ({ member, planDigest })));
+    const op = await throughOpWaves();
+    const fan = await throughFanOut();
+    expect(op.digest).toBe(expected);
+    expect(fan.digest).toBe(expected);
+    expect(op.pending).toBe(expected);
+    expect(fan.pending).toBe(expected);
+    expect(op.gate).toBe("rollout-wave-1");
+    expect(fan.gate).toBe(op.gate);
+  });
+
+  test("gate names: the default pattern is waveGateName's name, and a spec's pattern still wins", () => {
+    for (const k of [1, 2, 12]) {
+      expect(waveGateNameFrom(undefined, "deploy", k)).toBe(waveGateName("deploy", k));
+      expect(waveGateNameFrom(WAVE_GATE_NAME_PATTERN, "deploy", k)).toBe(`deploy-wave-${k}`);
+      expect(opWaveGateName({ name: "deploy" }, k)).toBe(waveGateName("deploy", k));
+    }
+    expect(opWaveGateName({ name: "x", gate: "tg", gateName: "wave-{k}" }, 3)).toBe("wave-3");
+    expect(opWaveGateName({ name: "x", gateName: "{gate}/{k}" }, 3)).toBe("x/3");
+  });
+
+  test("the share split is the Op waves split by target", () => {
+    const runs = ["t5", "t1", "t4", "t2", "t3"].map((target) => ({ target }));
+    for (const shares of [1, 2, 3, 5]) {
+      for (let share = 1; share <= shares; share++) {
+        expect(waveShare(runs, share, shares, (r) => r.target)).toEqual(opWaveShare(runs, share, shares));
+      }
+    }
+    expect(opWaveShare(runs, 1, 2).map((r) => r.target)).toEqual(["t1", "t2", "t3"]);
+  });
+});