@intentius/chant 0.124.40 → 0.124.41

package/src/cli/handlers/promote.ts

@@ -26,6 +26,7 @@ import { dirname, join, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { loadChantConfig, type ChantConfig } from "../../config";
 import { promotionOrder } from "../../workspace/promotion-order";
+import { releaseTargetRefusal } from "../../components/pr-environment";
 import { resolvePromotionSource } from "../../components/promote-order";
 import { fetchLifecycle, getHeadCommit, pushLifecycle } from "../../lifecycle/git";
 import {
@@ -897,6 +898,14 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
     console.error(formatError({ message: "--to <env> is required", hint: PROMOTE_USAGE }));
     return 1;
   }
+  // #4298: a pull request's environment is neither a release's target nor its source.
+  for (const env of [to, args.migrateFrom]) {
+    const refusal = env ? releaseTargetRefusal(env) : undefined;
+    if (refusal) {
+      console.error(formatError({ message: refusal }));
+      return 1;
+    }
+  }
   const who = actorOrRefuse(ctx);
   if (typeof who === "number") return who;
 

package/src/cli/handlers/query.ts

@@ -0,0 +1,78 @@
+/**
+ * `chant query "<sql>" [dir] [--member <name>] [--json]` (#4297): one
+ * read-only SQL statement over the snapshots, Op runs, gates, deploys and
+ * releases on the local `chant/lifecycle` branch. The tables and the engine
+ * live in `../../lifecycle/query.ts`; this reads the ledgers and prints.
+ *
+ * Inside a workspace every member's ledger is read, each row naming its
+ * member; `--member` keeps the members it names. Outside one the project's
+ * own ledger is read and `member` is NULL. It reads the local branch and
+ * never fetches.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import type { QueryLedger } from "../../lifecycle/query";
+import { findWorkspaceRoot } from "../../project-root";
+
+const USAGE = 'chant query "<sql>" [dir] [--member <name>] [--json]';
+
+/** The ledgers `chant query` reads from `cwd`: every member's in a workspace, else the project's own. */
+export async function queryLedgers(cwd: string, members?: readonly string[]): Promise<QueryLedger[]> {
+  const { gitLedgerReadPort } = await import("../../lifecycle/git");
+  const found = findWorkspaceRoot(cwd);
+  if (!found) return [{ member: null, port: gitLedgerReadPort({ cwd }) }];
+  // Workspace code loads only when there is a workspace, so a level-0 project never pays for it.
+  const { readDeclaration, WorkspaceReadError } = await import("../../workspace/declaration");
+  const { workingTree } = await import("../../workspace/tree");
+  const { QueryError } = await import("../../lifecycle/query");
+  let declaration;
+  try {
+    declaration = readDeclaration(workingTree(found.dir), "");
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) throw new QueryError(`${err.code}: ${err.message}`);
+    throw err;
+  }
+  const wanted = members && members.length > 0 ? new Set(members) : null;
+  if (wanted) {
+    const unknown = [...wanted].filter((n) => !declaration.members.some((m) => m.name === n));
+    if (unknown.length > 0) throw new QueryError(`--member ${unknown.join(", ")} names no member of the workspace`);
+  }
+  return declaration.members
+    .filter((m) => !wanted || wanted.has(m.name))
+    .map((m) => ({ member: m.name, port: gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }) }));
+}
+
+export async function runQueryCommand(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const sql = args.positionals?.[0];
+  if (sql === undefined || sql.trim() === "") {
+    console.error(formatError({ message: "chant query needs a statement", hint: `${USAGE}, such as chant query "SELECT env, count(*) FROM resources GROUP BY env"` }));
+    return 1;
+  }
+  const cwd = resolve(args.positionals?.[1] ?? ".");
+  if (!existsSync(cwd)) {
+    console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+    return 1;
+  }
+  const { loadQueryData, runQuery, formatQueryResult, QueryError } = await import("../../lifecycle/query");
+  try {
+    const load = await loadQueryData(await queryLedgers(cwd, args.members));
+    const result = await runQuery(sql, load);
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatQueryResult(result));
+      const bad = Object.entries(result.malformed).filter(([, n]) => n > 0);
+      if (bad.length > 0) console.error(formatWarning({ message: `left out what could not be read: ${bad.map(([t, n]) => `${n} in ${t}`).join(", ")}` }));
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof QueryError) {
+      console.error(formatError({ message: err.message, hint: USAGE }));
+      return 1;
+    }
+    throw err;
+  }
+}

package/src/cli/main.ts

@@ -173,6 +173,11 @@ Commands:
                         terms; --live or --at <ref> with --env <name> reads the
                         estate or a recorded snapshot; --show <attr>,
                         --check-live, --check-snapshot, --fail-on-drift)
+  query "<sql>" [dir]   Run one read-only SQL statement over chant/lifecycle:
+                        the resources and snapshots each lexicon observed, Op
+                        runs, gates, deploys, releases and cuts, loaded into
+                        node:sqlite (schema v1, listed in chant_schema).
+                        --member <name> keeps members; --json prints rows
   generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
@@ -558,6 +563,15 @@ Ops:
                         applies it once, if .chant/overriders at base lists
                         --actor
 
+  lock <target>...      Lock targets for a pull request on chant/lifecycle
+                        (--pr <n>, --stage plan|apply|lock, --head <sha>,
+                        --by <who>, --gate <name>, --json). --from-report
+                        <pr-plan.json> locks the components a plan selected.
+                        --forge <kind> reads which holders are still open and
+                        posts chant/lock on --head. Exits 3 when another open
+                        pull request holds a target. --list prints the locks
+  unlock [<target>...]  Release the locks a pull request holds (--pr <n>,
+                        --gate <name>, --json)
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
                         a Mermaid flowchart, Graphviz DOT, or node positions;
@@ -1003,11 +1017,26 @@ Component release ledger + status:
                             report and note (--base <ref> --pr <n>
                             [--forge github|gitlab|forgejo] posts them);
                             applies nothing
+  components pr-post       Post the plan note and the chant/plan status
+                            from the report pr-plan --no-status wrote
+                            (--pr <n> --head <sha> --env <env> --forge
+                            <kind>), in a job that runs none of the
+                            change's code (#4295)
   components pr-record     On merge (#4168): plan the same members again,
                             store the change set and write the merge record
                             _merges/<commit>.json; applies and refuses
                             nothing, and a plan that differs from the
                             approved one sets a failing chant/record status
+  components pr-env        An environment per open pull request (#4298): up
+                            --base <ref> --pr <n> applies the change to pr-<n>,
+                            derived from ci.prEnvironment.template, once an
+                            approval of its plan stands (chant approve pr-<n>
+                            pr-env --plan <digest>); post --pr <n> --head
+                            <sha> keeps the record up --no-push handed on and
+                            posts the note; down --pr <n> tears down
+                            only what carries pr-<n>'s ownership marker; sweep
+                            tears down each one whose TTL passed or whose pull
+                            request closed. Never a release target
   components pr-apply      With --apply-on-merge: plan the same members again and apply
                             them only if an approval stands for that digest
                             (chant approve pr-<n> pr-apply --plan <digest>);
@@ -1201,7 +1230,8 @@ Options:
                         chant.config.ts's build.sandbox: true; #1045)
   --param <name=value>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy, release cut) Bind a
+                        components redeploy, components pr-env up,
+                        release cut) Bind a
                         declared build-time parameter (chant.config.ts's buildParams)
                         to a value, for source to read as params.<name>
                         (#1064) instead of process.env — repeatable.
@@ -1213,7 +1243,8 @@ Options:
                         chant.template.json declares instead (#2627).
   --params-file <path>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy, release cut) JSON file
+                        components redeploy, components pr-env up,
+                        release cut) JSON file
                         of { "name": value } build-time parameter values
                         (#1064). Second precedence, after --param.
                         init --from refuses it: pass --param instead.
@@ -1441,6 +1472,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "describe", handler: runDescribe },
   { name: "explain", handler: runExplain },
   { name: "search", handler: runSearch },
+  // #4297 — SQL over the snapshots, runs, gates, deploys and releases on chant/lifecycle. Imported on first use.
+  { name: "query", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/query")).runQueryCommand(ctx) },
   // chant#2591 — `import --agents` and `audit` read chant.config statically
   // and never evaluate it (chant#2589 for audit, which audits code it must not run).
   { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
@@ -1524,6 +1557,9 @@ export const commandRegistry: CommandDef[] = [
   { name: "operator log", handler: runOperatorLog },
   { name: "operator", handler: runOperator },
   { name: "approve", handler: runApprove },
+  // #4293 — target locks a pull request holds on chant/lifecycle. Imported on first use.
+  { name: "lock", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/lock")).runLock(ctx) },
+  { name: "unlock", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/lock")).runUnlock(ctx) },
 
   { name: "graph", handler: runGraph },
   { name: "vendor", handler: runVendor },
@@ -1613,7 +1649,10 @@ export const commandRegistry: CommandDef[] = [
   // #3183 — the pull-request loop the generated CI runs. Imported on first use.
   { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPlan(ctx) },
   { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrApply(ctx) },
+  // #4295: posts from the plan report in a job that runs none of the change's code, so it loads no plugins.
+  { name: "components pr-post", handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPost(ctx) },
   { name: "components pr-record", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrRecord(ctx) },
+  { name: "components pr-env", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr-env")).runComponentsPrEnv(ctx) },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },

package/src/cli/parse-args.ts

@@ -43,6 +43,7 @@ const BOOLEAN_FLAGS = new Set([
   "--stacks",
   "--components",
   "--pr-build",
+  "--pr-env",
   "--up",
   "--down",
   "--include-dependents",
@@ -72,6 +73,7 @@ const BOOLEAN_FLAGS = new Set([
   "--in-place",
   "--require-runner-start",
   "--no-push",
+  "--list",
   "--no-require-review",
   "--expire",
   "--check-live",
@@ -396,11 +398,26 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.forge || result.forge.startsWith("-")) throw new Error("--forge needs a forge: --forge github|gitlab|forgejo");
     } else if (arg === "--require-review") {
       result.requireReview = true;
+    } else if (arg === "--list") {
+      // `chant lock --list` (#4293): print the target locks instead of taking any.
+      result.list = true;
+    } else if (arg === "--stage") {
+      // `chant lock --stage plan|apply|lock` (#4293): how the lock was taken.
+      result.lockStage = args[++i];
+      if (!result.lockStage || result.lockStage.startsWith("-")) throw new Error("--stage needs plan, apply or lock: --stage <stage>");
+    } else if (arg === "--from-report") {
+      // `chant lock --from-report <pr-plan.json>` (#4293): lock the components a pull-request report lists.
+      result.fromReport = args[++i];
+      if (!result.fromReport || result.fromReport.startsWith("-")) throw new Error("--from-report needs a report file: --from-report <pr-plan.json>");
     } else if (arg === "--report-url") {
       // `chant components pr-plan|pr-apply --report-url <url>` (#4007).
       const url = args[++i];
       if (!url || url.startsWith("-")) throw new Error("--report-url needs a URL: --report-url s3://<bucket>/<prefix> or file://<directory>");
       result.reportUrl = url;
+    } else if (arg === "--result") {
+      // `chant components pr-post --result <result>` (#4295): the plan job's own result, which fails the status when it failed.
+      result.planResult = args[++i];
+      if (!result.planResult || result.planResult.startsWith("-")) throw new Error("--result needs the plan job's result: --result success|failure|cancelled");
     } else if (arg === "--no-status") {
       // `chant ci run|serve --no-status` (#4097): post no commit status for the job.
       result.noStatus = true;
@@ -422,6 +439,9 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--apply-on-merge") {
       // `chant build --pr-loop --apply-on-merge` and `chant ci serve --apply-on-merge` (#4168): opt into applying on merge.
       result.applyOnMerge = true;
+    } else if (arg === "--pr-env") {
+      // `chant build --pr-loop --pr-env` (#4298): add the pull request environment's jobs.
+      result.prEnv = true;
     } else if (arg === "--pr-build") {
       // `chant build --pr-loop --pr-build` (#4088), and `chant ci run --pr-build` (#4094).
       result.prBuild = true;
@@ -864,8 +884,9 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--expire") {
       result.expire = true;
     } else if (arg === "--role") {
-      // #2508 — a role the approver holds, for a gate whose quorum names
-      // roles. Repeatable, and a comma list works too.
+      // #2508 — a role the approver claims, which a gate's policy sees. A
+      // quorum reads roles from .chant/trust.json at base instead (#4290).
+      // Repeatable, and a comma list works too.
       const value = args[++i] ?? "";
       result.roles = [...(result.roles ?? []), ...value.split(",").map((r) => r.trim()).filter(Boolean)];
     } else if (arg === "--agent") {

package/src/cli/registry.ts

@@ -302,6 +302,12 @@ export interface ParsedArgs {
    * pr-apply finds it from the commit through `--forge` when omitted.
    */
   pr?: number;
+  /** `chant lock --list` (#4293): print the target locks instead of taking any. */
+  list?: boolean;
+  /** `chant lock --stage plan|apply|lock` (#4293): how the lock is taken. Default `lock`. */
+  lockStage?: string;
+  /** `chant lock --from-report <file>` (#4293): lock the components a `pr-plan.json` lists. */
+  fromReport?: string;
   /** Every `--pr <n>`, in order: `chant release compose` (#4168 4.3) takes several. */
   prs?: number[];
   /** `chant release cut --channel <tag>` (#4168 4.3): the tag a publish of the release moves in place of `latest`. */
@@ -345,6 +351,8 @@ export interface ParsedArgs {
    * approved plans of the merges between or a gate of its own.
    */
   green?: boolean;
+  /** `chant build --pr-loop --pr-env` (#4298) — add the env-up, env-down and env-sweep jobs of a pull request's environment. */
+  prEnv?: boolean;
   /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
   prBuild?: boolean;
   /** `chant ci serve --build-command <line>` (#4169) — the line that builds a commit a `ci/build/<sha>` tag asks for, in a worktree of it. */
@@ -477,7 +485,7 @@ export interface ParsedArgs {
   records?: boolean;
   /** `chant workspace wip save --label <text>` (#3172): what the caller calls the snapshot, such as a turn id. */
   label?: string;
-  /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. */
+  /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. `chant components pr-apply|pr-record --branch <branch>` (#4292): the branch pushed, which `ci.branches` routes members by; default the forge's GITHUB_REF_NAME or CI_COMMIT_BRANCH. */
   branch?: string;
   /** `chant ci workflow --workflow <name>`, repeatable (#3573): a workflow whose completion triggers a tick, beside those the scan finds. Also `chant ci init --workflow <name>` (#4168 step 6), the prescribed workflow to set up. */
   ciWorkflows?: string[];
@@ -491,6 +499,8 @@ export interface ParsedArgs {
   ciSecrets?: string;
   /** `chant ci workflow --chant <command>` (#3573): the command the tick step runs chant with, in place of the npx pin. Also `chant ci run --chant` (#4094): what runs chant in the job. */
   ciChant?: string;
+  /** `chant components pr-post --result <result>` (#4295): the plan job's own result. `failure` or `cancelled` fails the `chant/plan` status. */
+  planResult?: string;
   /** `chant ci run|serve --no-status` (#4097): post no commit status for the job. `chant components pr-plan|pr-apply --no-status` (#4161): post neither the status nor the note. */
   noStatus?: boolean;
   /** `chant ci run|serve --status-url <template>` (#4097): the link a job's status carries. `{key}` is `<pr>/<commit>[/<member>]`, as `--report-url` keys it. */
@@ -737,7 +747,7 @@ export interface ParsedArgs {
    * on a model-authored channel.
    */
   allowSameOrigin?: boolean;
-  /** `chant approve --role <name>` (#2508) — roles the approver claims, for a gate whose quorum counts only some roles. Repeatable; a comma list also works. */
+  /** `chant approve --role <name>` (#2508) — roles the approver claims, which a gate's policy sees. A quorum never counts them (#4290): its roles come from `.chant/trust.json` at base. Repeatable; a comma list also works. */
   roles?: string[];
   /** `chant approve --agent` (#2508) — record the approval as an agent's. An agent never counts toward a quorum; it passes a gate only through a policy permit in `enforce` mode. */
   agent?: boolean;

package/src/components/fan-out-run.ts

@@ -129,6 +129,19 @@ export interface FanOutWaveGate {
    * do not exist yet. A later wave is left for its own job.
    */
   only?: number;
+  /**
+   * With `only` (#4291): members of earlier waves the record says failed to
+   * plan or to apply. Each blocks its dependents in this wave and names
+   * itself as what blocked them; the rest of the wave runs. An earlier
+   * member that neither applied nor failed still refuses the run.
+   */
+  failedEarlier?: readonly string[];
+  /**
+   * With `only` (#4291): earlier waves the record says stopped at their gate.
+   * A member left in one of them stops this wave too ({@link EarlierWaveWaitingError}),
+   * since a gate nobody approved stops every wave after it.
+   */
+  waitingEarlier?: ReadonlyArray<{ wave: number; gate: string; components: readonly string[] }>;
 }
 
 /** Thrown when `FanOutWaveGate.only` names a wave whose predecessors have not all applied. */
@@ -146,6 +159,22 @@ export class EarlierWaveNotAppliedError extends Error {
   }
 }
 
+/**
+ * Thrown when `FanOutWaveGate.only` names a wave after one that waits at its
+ * gate (#4291): nothing in this wave runs until that gate is approved and
+ * its job runs again. The CLI exits 3, as the waiting wave's job does.
+ */
+export class EarlierWaveWaitingError extends Error {
+  constructor(
+    readonly wave: number,
+    readonly earlier: number,
+    readonly gate: string,
+  ) {
+    super(`wave ${wave} does not run yet: wave ${earlier} waits at its gate ${gate}. Approve it and run wave ${earlier} again, then this wave.`);
+    this.name = "EarlierWaveWaitingError";
+  }
+}
+
 /** The single gate over a whole fan-out. Omit it to run without one. */
 export interface FanOutGate {
   /** The name `chant approve <op> <gate>` takes — the fan-out's name, not a component's. */
@@ -518,7 +547,13 @@ async function runGatedWaves(
       if (!wave) return { end: "stop" };
       const runnable = wave.filter((name) => left.has(name) && !blockedBy.has(name));
       if (waveGate.only !== undefined && waveNum < waveGate.only) {
-        if (runnable.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, runnable);
+        // #4291: an earlier member that failed blocks only its dependents; one that waits at its gate stops this wave.
+        const failedBefore = new Set(waveGate.failedEarlier ?? []);
+        const open = runnable.filter((name) => !failedBefore.has(name));
+        const waiting = waveGate.waitingEarlier?.find((w) => w.wave === waveNum && open.some((name) => w.components.includes(name)));
+        if (waiting) throw new EarlierWaveWaitingError(waveGate.only, waveNum, waiting.gate);
+        if (open.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, open);
+        for (const name of runnable) markBlocked(name);
         return { end: "next" };
       }
       if (waveGate.only !== undefined && waveNum > waveGate.only) return { end: "stop" };
@@ -664,7 +699,9 @@ async function runGatedWaves(
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([component, by]) => ({ component, reason: "blocked" as const, blockedBy: by }));
 
-  const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+  // #4291: a member of this job's wave that an earlier job's failure blocked fails the job, though the rest of the wave applied.
+  const blockedHere = waveGate.only !== undefined && (plan.waves[waveGate.only - 1] ?? []).some((name) => blockedBy.has(name));
+  const status: FanOutRunResult["status"] = failed.length > 0 || blockedHere ? "fail" : gatedFact ? "gated" : "ok";
   emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {

package/src/components/fan-out-waves.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, test } from "vitest";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { memoryGateLedgerPort } from "../op/gate";
 import { planFanOut } from "./fan-out";
-import { EarlierWaveNotAppliedError, runFanOut, type FanOutRunOptions } from "./fan-out-run";
+import { EarlierWaveNotAppliedError, EarlierWaveWaitingError, runFanOut, type FanOutRunOptions } from "./fan-out-run";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { DriverComponent } from "./driver";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
@@ -354,6 +354,50 @@ describe("one wave per CI job", () => {
   });
 });
 
+describe("a failed member blocks only its dependents across wave jobs (#4291)", () => {
+  /** net, then a and b, then app (reads a) and web (reads b). */
+  const WIDE: DriverComponent[] = [...ESTATE, root("web", ["b"])];
+
+  test("wave 3's job blocks what an earlier job's failure holds, and plans the rest", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    const result = await runFanOut(plan, WIDE, w.registry, {
+      ...waveOptions(ledger()),
+      waveGate: { op: "fan-out", gate: "release", only: 3, failedEarlier: ["a"] },
+      progress: { completed: ["net", "b"] },
+    });
+    expect(result.blocked).toEqual([{ component: "app", reason: "blocked", blockedBy: "a" }]);
+    expect(w.planned.map((p) => p.root)).toEqual(["web"]);
+    // A member of the job's own wave was blocked, so the job fails though web went on to its gate.
+    expect(result.status).toBe("fail");
+  });
+
+  test("an earlier member that neither applied nor failed still refuses the job", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, WIDE, w.registry, {
+        ...waveOptions(ledger()),
+        waveGate: { op: "fan-out", gate: "release", only: 3, failedEarlier: ["a"] },
+        progress: { completed: ["net"] },
+      }),
+    ).rejects.toThrow(EarlierWaveNotAppliedError);
+  });
+
+  test("an earlier wave that waits at its gate stops the job", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, WIDE, w.registry, {
+        ...waveOptions(ledger()),
+        waveGate: { op: "fan-out", gate: "release", only: 3, waitingEarlier: [{ wave: 2, gate: "release-wave-2", components: ["a", "b"] }] },
+        progress: { completed: ["net"] },
+      }),
+    ).rejects.toThrow(EarlierWaveWaitingError);
+    expect(w.planned).toEqual([]);
+  });
+});
+
 describe("both modes", () => {
   test("a run takes one gate over the set or one per wave, not both", async () => {
     const w = world();