@intentius/chant 0.115.0 → 0.117.0

package/dist/op/op-waves-run.d.ts

@@ -0,0 +1,115 @@
+/**
+ * What an Op waves job runs (#3679): `chant run wave --spec <file> --wave <k>`.
+ * `./op-waves.ts` holds the spec and the jobs; this plans a wave's runs,
+ * decides its gate and applies it.
+ *
+ * - Plan: each run's `plan` command writes a plan file; its `planDigest` is
+ *   the run's member digest, named by its target.
+ * - Decide: the wave's policy comes from the spec file at the base commit
+ *   (`git show <base>:<file>`), so a change cannot loosen its own gate. A
+ *   wave missing there, or a file missing there, is `always`. A wave that
+ *   needs an approval waits on `<gate>-wave-<k>` bound to
+ *   {@link waveSetDigest} over its members, and exits 3 when nobody approved
+ *   that digest.
+ * - Apply: each run's `apply` command. A share job (`--share i`) re-plans its
+ *   slice first and refuses, without applying it, a run whose plan digest is
+ *   not the one the deciding job recorded (exit 4).
+ */
+import { type WaveMember } from "../gated-waves.js";
+import { type GateLedgerPort } from "./gate.js";
+import { type OpWaveGatePolicy, type OpWavesSpec } from "./op-waves.js";
+/** What a run's plan command writes to `{plan}`. */
+export interface OpWavePlanFile {
+    planDigest: string;
+    /** The plan destroys, rewrites or otherwise needs a person under `on-destructive`. */
+    destructive?: boolean;
+    /** The plan changes nothing. */
+    empty?: boolean;
+}
+/** One run's plan, as the decision records it. */
+export interface OpWaveMember extends WaveMember {
+    op: string;
+    destructive?: boolean;
+    empty?: boolean;
+}
+/** Where a wave's policy came from. */
+export type OpWavePolicySource = "base" | "absent-at-base";
+/** A wave's decision: what was planned, the policy, and whether it may apply. */
+export interface OpWaveDecision {
+    wave: number;
+    name: string;
+    /** The op the gate is recorded under: the spec's name. */
+    op: string;
+    gate: string;
+    policy: OpWaveGatePolicy;
+    policySource: OpWavePolicySource;
+    /** The base commit the policy was read at. */
+    base: string;
+    digest: string;
+    members: OpWaveMember[];
+    /** `approved`: an approval of this digest stands. `not-required`: the policy lets it through. `waiting`: neither. */
+    status: "approved" | "not-required" | "waiting";
+    approvedBy?: string;
+    /** The command that approves this digest, when waiting. */
+    approve?: string;
+}
+/** Runs one argv; returns its exit code. Injected so tests run no processes. */
+export type OpWaveExec = (argv: string[], cwd: string) => number;
+/** Reads one file at one commit, or null when the commit has no such file. Injected for tests. */
+export type OpWaveShowAtBase = (base: string, path: string, cwd: string) => {
+    sha: string;
+    text: string | null;
+};
+/** Read a spec file, refusing anything that is not one. */
+export declare function parseOpWavesSpec(text: string, where: string): OpWavesSpec;
+/**
+ * The policy of wave `name`, as the spec file at `base` declares it. The
+ * file or the wave missing there reads as `always`: a change that adds a
+ * wave, or the file, waits for a person the first time.
+ */
+export declare function readOpWavePolicy(specFile: string, name: string, base: string, cwd: string, show?: OpWaveShowAtBase): {
+    policy: OpWaveGatePolicy;
+    source: OpWavePolicySource;
+    base: string;
+};
+/** Fill one argv template for one run. */
+export declare function opWaveArgv(template: readonly string[], values: {
+    op: string;
+    target: string;
+    wave: string;
+    plan: string;
+}): string[];
+/** Where a run's plan file goes. */
+export declare function opWavePlanPath(spec: Pick<OpWavesSpec, "name">, wave: number, target: string): string;
+export interface RunOpWaveOptions {
+    spec: OpWavesSpec;
+    specFile: string;
+    /** 1-based. */
+    wave: number;
+    /** Plan and decide only (a wide wave's deciding job). */
+    decide?: boolean;
+    /** Apply this 1-based share of a decided wave. */
+    share?: number;
+    /** Overrides the spec's base. */
+    base?: string;
+    cwd?: string;
+    gates?: GateLedgerPort;
+    exec?: OpWaveExec;
+    show?: OpWaveShowAtBase;
+    now?: string;
+    log?: (line: string) => void;
+}
+export interface RunOpWaveResult {
+    /** 0 applied (or decided), 1 a run failed, 3 waiting for an approval, 4 a plan moved since the decision. */
+    exitCode: number;
+    decision?: OpWaveDecision;
+    applied: string[];
+    failed: string[];
+    /** Runs a share job refused because their plan moved since the decision. */
+    moved: string[];
+}
+/** Whether `policy` lets a wave with these members through without an approval. */
+export declare function opWaveNeedsApproval(policy: OpWaveGatePolicy, members: readonly OpWaveMember[]): boolean;
+/** Plan, decide and apply one wave, or one part of a wide wave. */
+export declare function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveResult>;
+//# sourceMappingURL=op-waves-run.d.ts.map

package/dist/op/op-waves-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-waves-run.d.ts","sourceRoot":"","sources":["../../src/op/op-waves-run.ts"],"names":[],"mappings":"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"}

package/dist/op/op-waves.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Gated waves of Op runs (#3679): a pipeline that applies one Op per
+ * environment, or per target in a set, in order, each wave behind one gate.
+ *
+ * A product built on chant that applies a migration to dev, then staging, then
+ * prod, or the same change to every tenant database of an environment, used to
+ * render that ordering itself, once per forge, and compute each wave's set
+ * digest itself. This module holds the forge-neutral part: the spec, the jobs
+ * it becomes and the commands they run. Each forge lexicon (github, gitlab,
+ * forgejo) renders these jobs with its own transport, so the three cannot
+ * disagree about order or commands. `./op-waves-run.ts` is what the jobs run.
+ *
+ * ## Jobs
+ *
+ * A wave is one job, `wave-<k>-<name>`, running `chant run wave --spec <file>
+ * --wave <k>`: plan every run, decide the wave's gate, apply. A wide wave
+ * (`shares` > 1) is a deciding job that plans every run and decides the gate,
+ * plus `shares` jobs that each apply a slice of the runs and refuse a run
+ * whose plan moved since the decision. Each wave's jobs need the previous
+ * wave's last jobs, so a wave that waits (exit 3) or fails stops every later
+ * wave.
+ *
+ * ## The gate
+ *
+ * Wave k waits on `waveGateName(<gate>, k)`, recorded under the spec's name,
+ * bound to {@link waveSetDigest} over its runs' plan digests (`../gated-waves.ts`,
+ * the same digest a component fan-out's wave binds). Whether it waits at all
+ * is the wave's gate policy, read from the base commit's copy of the spec
+ * file, so a change cannot loosen the rule that gates its own merge.
+ */
+import type { OpEnvironment, OpSetupStep } from "../lexicon.js";
+/** When a wave waits for an approval. */
+export type OpWaveGatePolicy = 
+/** Whenever the wave changes something. */
+"always"
+/** When a run's plan says it is destructive. */
+ | "on-destructive"
+/** Never: only review and branch protection stand in front of the wave. */
+ | "never";
+export declare const OP_WAVE_GATE_POLICIES: readonly OpWaveGatePolicy[];
+/** One Op run in a wave: an Op applied to one target (an environment, a database, a tenant). */
+export interface OpWaveRun {
+    /** What the run applies to. Unique within its wave; it names the run in the set digest. */
+    target: string;
+    /** The Op to run. Default: the spec's `op`. */
+    op?: string;
+}
+/** One wave: runs that apply together, behind one gate. */
+export interface OpWave {
+    /** The wave's name, usually its environment. Lowercase letters, digits, `-` and `_`. */
+    name: string;
+    runs: OpWaveRun[];
+    /**
+     * When the wave waits. Default `"always"`. The runner reads this from the
+     * spec file at the base commit, never from the change being applied.
+     */
+    gate?: OpWaveGatePolicy;
+    /**
+     * 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
+     * applies.
+     */
+    shares?: number;
+    /** The forge deployment environment the wave's jobs run in (GitHub and GitLab; Forgejo has none). */
+    environment?: OpEnvironment;
+    /** Variables for this wave's jobs alone. */
+    variables?: Record<string, string>;
+    /** Steps this wave's jobs run after the checkout, as `ScheduledOpSpec.setup`. */
+    setup?: OpSetupStep[];
+}
+/**
+ * An ordered list of waves of Op runs, as a pipeline and as the file its jobs
+ * read. Commands are argv templates; each `{op}`, `{target}`, `{wave}` and
+ * `{plan}` is replaced per run.
+ */
+export interface OpWavesSpec {
+    /** The pipeline's name, and the op the wave gates are recorded under (`chant approve <name> <gate>-wave-<k>`). */
+    name: string;
+    /** The Op a run runs when it names none. */
+    op: string;
+    /** The base gate name. Default: `name`. */
+    gate?: string;
+    /** Branches whose pushes run the waves. Default `["main"]`. */
+    branches?: string[];
+    /**
+     * The commit the gate policy is read from. Default `HEAD^1`, the first
+     * parent: on a merge or squash onto the branch, the branch before the change.
+     */
+    base?: string;
+    /**
+     * Plan one run and write its plan file to `{plan}`: JSON `{ "planDigest":
+     * string, "destructive"?: boolean, "empty"?: boolean }`. `destructive` is
+     * what `on-destructive` waits on; a wave whose runs are all `empty` never
+     * waits.
+     */
+    plan: string[];
+    /** Apply one run whose plan is at `{plan}`. Default `chant run {op} --env {target}`. */
+    apply?: string[];
+    waves: OpWave[];
+    /**
+     * A scheduled job that starts again a wave job whose approval has arrived
+     * (#3683): it runs `chant run resume --op <name>`, which re-runs the
+     * GitHub run, retries the GitLab job or dispatches the Forgejo workflow.
+     * It approves nothing. Absent, no such job is rendered and an approval is
+     * followed by `chant approve --resume` or a re-run by hand.
+     */
+    resume?: OpWavesResume;
+}
+/** The scheduled resume job of an Op waves pipeline (#3683). */
+export interface OpWavesResume {
+    /**
+     * Five-field cron, such as `"*\/10 * * * *"`. GitHub and Forgejo put it
+     * in the workflow; GitLab runs the job in a pipeline schedule you create,
+     * which sets the cron.
+     */
+    schedule: string;
+}
+/** The command a resume job runs. */
+export declare function opWavesResumeCommand(spec: Pick<OpWavesSpec, "name">): string[];
+/** The default apply command. */
+export declare const OP_WAVE_DEFAULT_APPLY: string[];
+/** Where the runner keeps a wave's decision; a wide wave's deciding job hands it to its share jobs. */
+export declare function opWaveRecordPath(spec: Pick<OpWavesSpec, "name">, wave: number): string;
+/** One generated job. */
+export interface OpWaveJob {
+    jobName: string;
+    /** 1-based wave number. */
+    wave: number;
+    /** The wave's name. */
+    waveName: string;
+    /** `wave`: plan, decide and apply. `decide`: plan and decide. `share`: apply one slice. */
+    kind: "wave" | "decide" | "share";
+    /** 1-based, on a share job. */
+    share?: number;
+    /** Jobs this one waits on. */
+    needs: string[];
+    /** The job's command, as argv. */
+    command: string[];
+    /** On a share job: the decision record to download. On a deciding job: the one to upload. */
+    record?: string;
+}
+/** Refuse a spec no job could run, naming what is wrong. */
+export declare function assertOpWavesSpec(spec: OpWavesSpec): void;
+/**
+ * The runs share `share` (1-based) of `shares` applies: the wave's runs sorted
+ * by target, cut into contiguous slices whose sizes differ by at most one.
+ */
+export declare function opWaveShare<T extends {
+    target: string;
+}>(runs: readonly T[], share: number, shares: number): T[];
+/**
+ * The jobs of an Op waves pipeline, in order. `specFile` is the spec's path
+ * from the job's working directory, which every command names.
+ */
+export declare function opWaveJobs(spec: OpWavesSpec, specFile: string): OpWaveJob[];
+/** The wave a job belongs to. */
+export declare function opWaveOf(spec: OpWavesSpec, job: Pick<OpWaveJob, "wave">): OpWave;
+//# sourceMappingURL=op-waves.d.ts.map

package/dist/op/op-waves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"op-waves.d.ts","sourceRoot":"","sources":["../../src/op/op-waves.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.115.0",
+  "version": "0.117.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/gate-resume.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+import type { GateResolutionRecord, PendingGateRecord } from "../../lifecycle/gate-ledger";
+import type { ForgeFetch } from "../../pr-forge";
+import { parseArgs } from "../main";
+import { resumeStanding } from "./gate-resume";
+
+const DIGEST = `sha256:${"a".repeat(64)}`;
+const standing: PendingGateRecord = {
+  version: 1,
+  kind: "pending",
+  op: "migrations",
+  gate: "migrations-wave-2",
+  timestamp: "2026-10-01T00:00:00Z",
+  expiresAt: "2026-10-03T00:00:00Z",
+  planDigest: DIGEST,
+  resume: { forge: "github", api: "https://api.github.com", repo: "acme/db", run: "42", attempt: 1 },
+};
+const approval: GateResolutionRecord = { version: 1, op: "migrations", gate: "migrations-wave-2", resolvedBy: "alice", timestamp: "2026-10-01T01:00:00Z", planDigest: DIGEST };
+
+describe("resumeStanding (#3683)", () => {
+  test("no approval, no call", async () => {
+    const fetch: ForgeFetch = async () => {
+      throw new Error("no call expected");
+    };
+    expect(await resumeStanding(standing, [], { env: { GITHUB_TOKEN: "t" }, fetch })).toMatchObject({ status: "not-approved" });
+  });
+
+  test("approved: re-runs the run the pending fact names", async () => {
+    const calls: string[] = [];
+    const fetch: ForgeFetch = async (url, init) => {
+      calls.push(`${init.method} ${new URL(url).pathname}`);
+      const body = init.method === "GET" ? { status: "completed", conclusion: "failure", run_attempt: 1 } : null;
+      return { ok: true, status: 200, text: async () => (body ? JSON.stringify(body) : "") };
+    };
+    const report = await resumeStanding(standing, [approval], { env: { GITHUB_TOKEN: "t" }, fetch });
+    expect(report).toMatchObject({ status: "resumed", approvedBy: "alice" });
+    expect(calls).toEqual(["GET /repos/acme/db/actions/runs/42", "POST /repos/acme/db/actions/runs/42/rerun-failed-jobs"]);
+  });
+
+  test("a fact recorded outside CI, or no token, resumes nothing and says why", async () => {
+    const { resume: _none, ...local } = standing;
+    expect(await resumeStanding(local, [approval], { env: { GITHUB_TOKEN: "t" } })).toMatchObject({ status: "no-job" });
+    expect(await resumeStanding(standing, [approval], { env: {} })).toMatchObject({ status: "no-token" });
+  });
+
+  test("`--resume` takes no value on approve, and keeps its file on the applies", () => {
+    expect(parseArgs(["approve", "migrations", "migrations-wave-2", "--resume"]).resumeRun).toBe(true);
+    expect(parseArgs(["approve", "migrations", "g", "--resume", "--sign"])).toMatchObject({ resumeRun: true, sign: true });
+    expect(parseArgs(["components", "pr-apply", "--resume", "attempt.json"]).resume).toBe("attempt.json");
+  });
+});

package/src/cli/handlers/gate-resume.ts

@@ -0,0 +1,166 @@
+/**
+ * `chant approve <op> <gate> --resume` and `chant run resume` (#3683): start
+ * the CI job that waits at a gate again once its approval has arrived. See
+ * `../../op/gate-resume.ts` for what each forge is asked and the token it
+ * needs. Neither approves anything.
+ */
+
+import {
+  GATES_DIR,
+  isPendingGateExpired,
+  readGateLedger,
+  type GateResolutionRecord,
+  type PendingGateRecord,
+} from "../../lifecycle/gate-ledger";
+import { listFilesInDir, requireLifecycleLedger } from "../../lifecycle/git";
+import {
+  isGateRunLocator,
+  resolutionAnswering,
+  resumeGateRun,
+  resumeTokenFromEnv,
+  type GateResumeOutcome,
+} from "../../op/gate-resume";
+import type { ForgeFetch } from "../../pr-forge";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+
+/** One waiting gate and what resuming it did. */
+export interface GateResumeReport {
+  op: string;
+  gate: string;
+  environment?: string;
+  /** `resumed` and `skipped` come from the forge; the rest are decided before any call. */
+  status: GateResumeOutcome["status"] | "not-approved" | "no-job" | "no-token" | "failed";
+  message: string;
+  approvedBy?: string;
+  url?: string;
+}
+
+/** The newest pending fact per gate and environment: the facts a run still waits on. */
+function standingFacts(pending: readonly PendingGateRecord[], gate?: string): PendingGateRecord[] {
+  const newest = new Map<string, PendingGateRecord>();
+  for (const p of pending) {
+    if (gate !== undefined && p.gate !== gate) continue;
+    const key = `${p.gate}\u0000${p.environment ?? ""}`;
+    const prior = newest.get(key);
+    if (!prior || new Date(p.timestamp).getTime() >= new Date(prior.timestamp).getTime()) newest.set(key, p);
+  }
+  return [...newest.values()];
+}
+
+export interface ResumeGateOptions {
+  env?: Record<string, string | undefined>;
+  fetch?: ForgeFetch;
+  now?: string;
+  dryRun?: boolean;
+}
+
+/** Resume the job behind one standing pending fact, when an approval answers it. */
+export async function resumeStanding(
+  standing: PendingGateRecord,
+  resolutions: readonly GateResolutionRecord[],
+  opts: ResumeGateOptions = {},
+): Promise<GateResumeReport> {
+  const base = {
+    op: standing.op,
+    gate: standing.gate,
+    ...(standing.environment !== undefined ? { environment: standing.environment } : {}),
+    ...(standing.resume?.url ? { url: standing.resume.url } : {}),
+  };
+  const answer = resolutionAnswering(resolutions, standing);
+  if (!answer) return { ...base, status: "not-approved", message: "no approval answers it yet" };
+  const approvedBy = { approvedBy: answer.resolvedBy };
+  if (!isGateRunLocator(standing.resume)) {
+    return { ...base, ...approvedBy, status: "no-job", message: "its pending fact names no CI job (it was recorded outside CI); run it again by hand" };
+  }
+  const loc = standing.resume;
+  if (opts.dryRun) return { ...base, ...approvedBy, status: "skipped", message: `would resume ${loc.forge} run ${loc.run} (--dry-run)` };
+  const token = resumeTokenFromEnv(loc.forge, opts.env ?? process.env);
+  if (!token) {
+    return {
+      ...base,
+      ...approvedBy,
+      status: "no-token",
+      message: `no token to call ${loc.forge} with: set CHANT_FORGE_TOKEN (or ${loc.forge === "gitlab" ? "GITLAB_TOKEN" : "GITHUB_TOKEN"})`,
+    };
+  }
+  try {
+    const outcome = await resumeGateRun(loc, { token, since: answer.timestamp, ...(opts.fetch ? { fetch: opts.fetch } : {}) });
+    return { ...base, ...approvedBy, status: outcome.status, message: outcome.status === "resumed" ? outcome.how : outcome.reason };
+  } catch (err) {
+    return { ...base, ...approvedBy, status: "failed", message: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** Resume every job waiting on `op`'s gates (or one gate) whose approval arrived. */
+export async function resumeOpGates(op: string, gate: string | undefined, opts: ResumeGateOptions = {}): Promise<GateResumeReport[]> {
+  const ledger = await readGateLedger(op);
+  const now = opts.now ?? new Date().toISOString();
+  const reports: GateResumeReport[] = [];
+  for (const standing of standingFacts(ledger.pending, gate)) {
+    if (isPendingGateExpired(standing, now)) continue;
+    reports.push(await resumeStanding(standing, ledger.resolutions, opts));
+  }
+  return reports;
+}
+
+function printReport(r: GateResumeReport): void {
+  const where = `${r.op} / ${r.gate}${r.environment !== undefined ? ` (${r.environment})` : ""}`;
+  const by = r.approvedBy ? `, approved by ${r.approvedBy}` : "";
+  const link = r.url ? ` ${r.url}` : "";
+  if (r.status === "resumed") console.error(formatSuccess(`${where}${by}: ${r.message}${link}`));
+  else if (r.status === "failed" || r.status === "no-token") {
+    console.error(formatError({
+      message: `${where}${by}: not resumed: ${r.message}`,
+      hint: "GitHub needs actions: write; GitLab a token with the api scope and the Developer role; Forgejo a token with write:repository.",
+    }));
+  } else console.error(formatInfo(`${where}${by}: not resumed: ${r.message}${link}`));
+}
+
+/**
+ * What `chant approve --resume` runs once the approval is recorded and
+ * pushed. Returns the exit code: 0 when the job was resumed or had nothing to
+ * resume, 1 when a forge call failed or no token was found.
+ */
+export async function resumeAfterApproval(op: string, gate: string, environment: string | undefined, pushed: boolean): Promise<number> {
+  if (!pushed) {
+    console.error(formatWarning({
+      message: "Not resuming: the approval did not reach the remote, so the resumed job would not see it.",
+      hint: "Push chant/lifecycle, then run `chant run resume --op " + op + "`.",
+    }));
+    return 1;
+  }
+  const reports = (await resumeOpGates(op, gate)).filter((r) => environment === undefined || r.environment === environment);
+  if (reports.length === 0) {
+    console.error(formatInfo(`No pending fact for ${op} / ${gate} is waiting, so there is nothing to resume.`));
+    return 0;
+  }
+  for (const r of reports) printReport(r);
+  return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
+}
+
+/**
+ * `chant run resume [--op <op>] [--dry-run] [--json]`: the scheduled job.
+ * Reads every gate ledger on `chant/lifecycle` (or `--op`'s), and starts
+ * again each CI job that waits at a gate an approval now answers.
+ */
+export async function runResumeCommand(ctx: CommandContext): Promise<number> {
+  try {
+    await requireLifecycleLedger();
+  } catch (err) {
+    console.error(formatError({ message: `Cannot read the gate ledgers: ${err instanceof Error ? err.message : String(err)}` }));
+    return 1;
+  }
+  const ops = ctx.args.op
+    ? [ctx.args.op]
+    : (await listFilesInDir(GATES_DIR)).filter((f) => f.endsWith(".jsonl")).map((f) => f.slice(0, -".jsonl".length));
+  const reports: GateResumeReport[] = [];
+  for (const op of ops) reports.push(...(await resumeOpGates(op, undefined, { dryRun: ctx.args.dryRun === true })));
+  if (ctx.args.json) console.log(JSON.stringify({ reports }, null, 2));
+  else {
+    for (const r of reports.filter((r) => r.status !== "not-approved")) printReport(r);
+    const waiting = reports.filter((r) => r.status === "not-approved").length;
+    console.error(formatInfo(`${reports.filter((r) => r.status === "resumed").length} resumed, ${waiting} still waiting for an approval.`));
+  }
+  return reports.some((r) => r.status === "failed" || r.status === "no-token") ? 1 : 0;
+}

package/src/cli/handlers/operator.ts

@@ -911,6 +911,12 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
   });
   if (!outcome.ok) return 1;
 
+  // #3683: start the CI job that waits at this gate again.
+  if (ctx.args.resumeRun || ctx.args.resume !== undefined) {
+    const { resumeAfterApproval } = await import("./gate-resume");
+    return resumeAfterApproval(opName, gate, outcome.record.environment, outcome.pushed);
+  }
+
   console.error(formatInfo(
     `This records the resolution as a fact; it does not itself re-run anything. ` +
       (opName === FAN_OUT_GATE_OP
@@ -988,7 +994,7 @@ export interface GateApprovalOptions {
 }
 
 export type GateApprovalOutcome =
-  | { ok: true; record: GateResolutionRecord }
+  | { ok: true; record: GateResolutionRecord; pushed: boolean }
   | { ok: false };
 
 /**
@@ -1313,7 +1319,7 @@ export async function recordGateApproval(
       console.error(formatInfo(line));
     }
   }
-  return { ok: true, record };
+  return { ok: true, record, pushed };
 }
 
 /**

package/src/cli/handlers/run-generate.ts

@@ -26,7 +26,8 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
-import { generateOpsPipeline } from "../../op/generate-pipeline";
+import { generateOpsPipeline, generateOpWavesPipeline } from "../../op/generate-pipeline";
+import { parseOpWavesSpec } from "../../op/op-waves-run";
 import { GENERATED_MARKER } from "../../discovery/files";
 import { findWorkspaceRoot } from "../../project-root";
 import type { ComponentPipelineOptions, ScheduledOpSpec } from "../../lexicon";
@@ -71,10 +72,59 @@ export function readOpSpecFile(path: string): SpecFile {
   return { ops: ops as ScheduledOpSpec[], ...(options ? { options } : {}) };
 }
 
+/** True when a `--spec` file holds an Op waves spec (#3679) rather than a list of scheduled Ops. */
+function holdsOpWaves(path: string): boolean {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as { waves?: unknown } | null;
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && parsed.waves !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `chant run --generate <provider> --spec <waves.json>` (#3679): one pipeline
+ * file of ordered, gated waves of Op runs. Its jobs read the same file.
+ */
+async function runOpWavesGenerate(ctx: CommandContext, provider: string, specPath: string): Promise<number> {
+  const { args } = ctx;
+  let spec;
+  let options: Record<string, unknown> | undefined;
+  try {
+    const text = readFileSync(resolve(specPath), "utf-8");
+    spec = parseOpWavesSpec(text, `--spec ${specPath}`);
+    const parsed = JSON.parse(text) as { options?: Record<string, unknown> };
+    options = Array.isArray((parsed as { waves?: unknown }).waves) ? undefined : parsed.options;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+  const result = await generateOpWavesPipeline(spec, provider, { ...options, specFile: specPath.replace(/^\.\//, "") });
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? "Failed to generate the Op waves pipeline" }));
+    return 1;
+  }
+  const header = opPipelineHeader(provider, specPath);
+  const outDir = args.output ?? DEFAULT_OP_PIPELINE_DIRS[provider] ?? ".";
+  const files = (result.files ?? []).map((f) => ({ name: f.name, path: join(outDir, f.name), content: header + f.yaml }));
+  if (args.format === "json") {
+    console.log(JSON.stringify({ files, jobs: result.jobs ?? [] }, null, 2));
+    return 0;
+  }
+  for (const file of files) {
+    const target = resolve(file.path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content);
+    console.error(formatSuccess(`wrote ${formatBold(file.path)}`));
+  }
+  return 0;
+}
+
 export async function runOpGenerate(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const provider = args.generate as string;
   const specPath = args.opsSpec;
+  if (specPath && holdsOpWaves(resolve(specPath))) return runOpWavesGenerate(ctx, provider, specPath);
 
   let ops: ScheduledOpSpec[];
   let options: ComponentPipelineOptions | undefined;

package/src/cli/handlers/run-wave.ts

@@ -0,0 +1,43 @@
+/**
+ * `chant run wave --spec <file> --wave <k>` (#3679): the command each job of
+ * a generated Op waves pipeline runs. See `../../op/op-waves-run.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { parseOpWavesSpec, runOpWave } from "../../op/op-waves-run";
+import { formatError } from "../format";
+import type { CommandContext } from "../registry";
+
+export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const specFile = args.opsSpec;
+  if (!specFile || args.wave === undefined) {
+    console.error(formatError({
+      message: "`chant run wave` needs --spec <file> and --wave <k>",
+      hint: "Run it as a generated Op waves pipeline does: chant run wave --spec <file> --wave <k> [--decide | --share <i>]",
+    }));
+    return 1;
+  }
+  if (args.decide && args.share !== undefined) {
+    console.error(formatError({ message: "--decide and --share are two different jobs; pass one" }));
+    return 1;
+  }
+  try {
+    const path = resolve(specFile);
+    const spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
+    const result = await runOpWave({
+      spec,
+      specFile: relative(process.cwd(), path),
+      wave: args.wave,
+      ...(args.decide ? { decide: true } : {}),
+      ...(args.share !== undefined ? { share: args.share } : {}),
+      ...(args.base ? { base: args.base } : {}),
+    });
+    if (args.json) console.log(JSON.stringify(result, null, 2));
+    return result.exitCode;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+}