@intentius/chant 0.58.0 → 0.60.0

package/src/cli/handlers/lint.test.ts

@@ -0,0 +1,107 @@
+/**
+ * chant #2251 — `chant lint` resolves this invocation's declared build-time
+ * parameters before it lints.
+ *
+ * The gap this covers: `runLint` built its `LintOptions` without ever
+ * touching `chant.config.ts`'s `buildParams`, so the OPS* checks imported
+ * every `*.op.ts` file with `params` (`@intentius/chant/params`) still empty.
+ * An Op taking a step argument from `params.<name>` therefore read
+ * `undefined` and OPS012 reported the activity contract violated on source
+ * that builds and runs — reproducible on any project with an Op that reads a
+ * build parameter, `--param` and the declared `env` mapping alike (the
+ * resolution never ran at all, so no input could reach it).
+ *
+ * Mocks `lintCommand` and `loadChantConfigUpward` and drives the exported
+ * `runLint` dispatcher, the same shape ./build.test.ts uses for the matching
+ * #1108 gap in generate mode.
+ */
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import type { ParsedArgs } from "../registry";
+
+const lintCommandMock = vi.fn();
+const loadChantConfigUpwardMock = vi.fn();
+
+vi.mock("../commands/lint", async () => {
+  const actual = await vi.importActual<typeof import("../commands/lint")>("../commands/lint");
+  return {
+    ...actual,
+    lintCommand: (...args: unknown[]) => lintCommandMock(...args),
+    printLintResult: () => {},
+  };
+});
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfigUpward: (...args: unknown[]) => loadChantConfigUpwardMock(...args) };
+});
+
+const { runLint } = await import("./lint");
+
+function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return {
+    command: "lint",
+    path: ".",
+    format: "",
+    fix: false,
+    watch: false,
+    verbose: false,
+    help: false,
+    live: false,
+    ...overrides,
+  };
+}
+
+describe("runLint build-time parameters (#2251)", () => {
+  beforeEach(() => {
+    lintCommandMock.mockReset().mockResolvedValue({ success: true, errorCount: 0, warningCount: 0, diagnostics: [] });
+    loadChantConfigUpwardMock.mockReset().mockResolvedValue({ config: {} });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("a project declaring no buildParams lints with an empty provenance array", async () => {
+    const exit = await runLint({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(lintCommandMock.mock.calls[0][0].buildParams).toEqual([]);
+  });
+
+  test("declared buildParams resolve from their defaults and reach lintCommand", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({
+      config: { buildParams: { env: { type: "string", default: "local" } } },
+    });
+
+    const exit = await runLint({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(lintCommandMock.mock.calls[0][0].buildParams).toEqual([
+      { name: "env", value: "local", source: "default" },
+    ]);
+  });
+
+  test("--param overrides the declared default, the same precedence chant build applies", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({
+      config: { buildParams: { env: { type: "string", default: "local" } } },
+    });
+
+    const exit = await runLint({ args: makeArgs({ param: ["env=pr-42"] }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(lintCommandMock.mock.calls[0][0].buildParams).toEqual([
+      { name: "env", value: "pr-42", source: "cli" },
+    ]);
+  });
+
+  test("an unresolvable parameter exits non-zero without linting", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({
+      config: { buildParams: { env: { type: "string", required: true } } },
+    });
+
+    const exit = await runLint({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(lintCommandMock).not.toHaveBeenCalled();
+  });
+});

package/src/cli/handlers/lint.ts

@@ -1,6 +1,31 @@
+import { resolve } from "node:path";
 import { lintCommand, lintCommandWatch, printLintResult } from "../commands/lint";
 import { formatError, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
+import { commandBuildParams } from "../build-params-cli";
+import { loadChantConfigUpward, type ChantConfig } from "../../config";
+
+/**
+ * chant #2251 — `chant lint` resolves this invocation's declared build-time
+ * parameters (`chant.config.ts`'s `buildParams`) before it lints, the same
+ * way `chant build` and the lifecycle family do (`commandBuildParams`,
+ * ../build-params-cli.ts).
+ *
+ * The OPS* checks import every `*.op.ts` file to read the Op it declares
+ * (../commands/lint.ts's `runOpCheckDiagnostics`), and an Op that takes a
+ * step argument from `params.<name>` (`@intentius/chant/params`) evaluates
+ * that read at module load. With no parameters resolved, `params` is the
+ * empty object every such argument reads `undefined` out of, and OPS012
+ * reports the activity contract violated — `args.env: expected string,
+ * received undefined` — for source that builds and runs correctly. The
+ * config is loaded by walking up from the lint path, so linting a
+ * subdirectory still sees the project root's declarations.
+ */
+async function lintBuildParams(args: { path: string; param?: string[]; paramsFile?: string }) {
+  const { config } = await loadChantConfigUpward(resolve(args.path)).catch(() => ({ config: {} as ChantConfig }));
+  if (!config.buildParams) return [];
+  return commandBuildParams(config.buildParams, args);
+}
 
 export async function runLint(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
@@ -11,12 +36,16 @@ export async function runLint(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  const buildParams = await lintBuildParams(args);
+  if (buildParams === undefined) return 1;
+
   if (args.watch) {
     const cleanup = lintCommandWatch({
       path: args.path,
       fix: args.fix,
       format: lintFormat,
       sandbox: args.sandbox,
+      buildParams,
     });
     process.on("SIGINT", () => {
       cleanup();
@@ -31,6 +60,7 @@ export async function runLint(ctx: CommandContext): Promise<number> {
     fix: args.fix,
     format: lintFormat,
     sandbox: args.sandbox,
+    buildParams,
   });
 
   printLintResult(result);

package/src/cli/handlers/operator.ts

@@ -7,6 +7,9 @@
  * `loadProfiles` from the project's configured lexicons).
  */
 import { loadChantConfig } from "../../config";
+import { build } from "../../build";
+import { isResourceDeclarable } from "../../declarable";
+import { collectBuildRootContributors, collectChangeSubscribers } from "../plugins";
 import { discoverOps } from "../../op/discover";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { parseDuration } from "../../op/local-executor";
@@ -15,7 +18,10 @@ import {
   runOperatorRound,
   runOperatorForever,
   formatRoundLine,
+  formatSignalLine,
   DEFAULT_OPERATOR_INTERVAL_MS,
+  type ChangeSubscriber,
+  type OperatorSignalEvent,
   type OperatorTickEvent,
 } from "../../op/operator";
 import { readLease, DEFAULT_LEASE_TTL_MS } from "../../lifecycle/lease";
@@ -43,6 +49,76 @@ async function loadOperatorActivities() {
   return Promise.all([loadActivities(lexicons), loadProfiles()]);
 }
 
+/**
+ * Bind the change-signal seams (#1981) the daemon will keep subscribed, or an
+ * empty list.
+ *
+ * Three gates, in cost order, so a project that gains nothing from this pays
+ * nothing for it:
+ *
+ * 1. No configured lexicon implements `subscribeChanges`. Return immediately,
+ *    without loading config or building anything. This is every project today.
+ * 2. No `--env`. A subscription resolves the same cluster binding a read
+ *    does, and there is no binding to resolve without an environment. Said out
+ *    loud rather than silently skipped, because "why did it not wake" is
+ *    otherwise unanswerable.
+ * 3. The build that supplies the declared entities failed. Warn and fall back
+ *    to the timer. A subscription is an optimization; a build error here must
+ *    not stop the operator, which has its own per-tick build inside the tick.
+ */
+async function collectOperatorSubscribers(
+  ctx: CommandContext,
+  env: string | undefined,
+): Promise<ChangeSubscriber[]> {
+  if (!ctx.plugins.some((p) => typeof p.subscribeChanges === "function")) return [];
+
+  if (!env) {
+    console.error(formatWarning({
+      message: "a change signal needs an environment to resolve its binding, so this runs on the timer alone",
+      hint: "pass --env <env> to let a lexicon's subscribeChanges wake a tick early",
+    }));
+    return [];
+  }
+
+  const cwd = process.cwd();
+  try {
+    const { config } = await loadChantConfig(cwd);
+    const buildRoots = collectBuildRootContributors(
+      ctx.plugins,
+      config as unknown as Record<string, unknown>,
+      cwd,
+    );
+    const buildResult = await build(config.sourceDir ?? ".", ctx.serializers, undefined, { buildRoots });
+    if (buildResult.errors.length > 0) {
+      console.error(formatWarning({
+        message: "build failed while scoping the change signal, so this runs on the timer alone",
+      }));
+      return [];
+    }
+
+    // The declared estate, sliced per lexicon: the same slice
+    // `takeSnapshot` hands `describeResources`, and the bound on what any
+    // subscription may watch.
+    const entities = new Map<string, Map<string, { entityType: string; props: Record<string, unknown> }>>();
+    for (const [name, entity] of buildResult.entities) {
+      if (!isResourceDeclarable(entity)) continue;
+      let perLexicon = entities.get(entity.lexicon);
+      if (!perLexicon) entities.set(entity.lexicon, (perLexicon = new Map()));
+      perLexicon.set(name, {
+        entityType: entity.entityType,
+        props: (entity.props != null ? entity.props : {}) as Record<string, unknown>,
+      });
+    }
+
+    return collectChangeSubscribers(ctx.plugins, { environment: env, cwd, entities });
+  } catch (err) {
+    console.error(formatWarning({
+      message: `could not scope the change signal, so this runs on the timer alone (${err instanceof Error ? err.message : String(err)})`,
+    }));
+    return [];
+  }
+}
+
 // ── chant operator ──────────────────────────────────────────────────────────
 
 /**
@@ -98,6 +174,9 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(
       `chant operator: watching ${ops.length} ConvergeOp(s) every ${intervalMs}ms (Ctrl-C to stop)`,
     ));
+    // A change signal (#1981) only ever shortens the sleep above. Every round
+    // it wakes is the round the timer would have run.
+    const subscribers = await collectOperatorSubscribers(ctx, ctx.args.env);
     await runOperatorForever({
       env: ctx.args.env,
       intervalMs,
@@ -106,6 +185,8 @@ export async function runOperator(ctx: CommandContext): Promise<number> {
       profiles,
       signal: controller.signal,
       onRound: printRound,
+      subscribers,
+      onSignalEvent: (event: OperatorSignalEvent) => console.error(formatInfo(formatSignalLine(event))),
     });
     return 0;
   } finally {

package/src/cli/handlers/run.test.ts

@@ -1,4 +1,7 @@
-import { describe, test, expect, vi, beforeEach } from "vitest";
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { ParsedArgs } from "../registry";
 
 const discoverOpsMock = vi.fn();
@@ -208,7 +211,7 @@ describe("runOp dispatcher", () => {
   test("gate in local mode → exit 3 and the approve line (#2119)", async () => {
     gateLedger = memoryGateLedgerPort();
     discoverOpsMock.mockResolvedValue({
-      ops: new Map([localOp("gated", [{ kind: "gate", signalName: "approve-prod" }])]),
+      ops: new Map([localOp("gated", [{ kind: "gate", gate: "approve-prod" }])]),
       errors: [],
     });
     // `renderHuman` writes straight to process.stderr, not through console.error.
@@ -235,7 +238,7 @@ describe("runOp dispatcher", () => {
     });
     discoverOpsMock.mockResolvedValue({
       ops: new Map([localOp("gated", [
-        { kind: "gate", signalName: "approve-prod" },
+        { kind: "gate", gate: "approve-prod" },
         { kind: "activity", fn: "shellCmd", args: { cmd: "true" } },
       ])]),
       errors: [],
@@ -266,6 +269,132 @@ describe("runOp dispatcher", () => {
   });
 });
 
+/**
+ * chant #2243 — a gated run's exit code is the one thing `--gated-exit`
+ * remaps, and the gate is reported where CI can see it without opening a log.
+ *
+ * The motivating shape is a push-to-main terraform apply: GitHub Actions has
+ * no neutral conclusion for a `run:` step, so exit 3 paints the branch red on
+ * every merge until someone approves. `--gated-exit 0` says a pending
+ * approval is not a broken build; nothing else about the run changes, and a
+ * failure is still a failure.
+ */
+describe("runOp: --gated-exit (#2243)", () => {
+  const gateStep = { kind: "gate", gate: "approve-prod" };
+
+  function summaryFile(): string {
+    return join(mkdtempSync(join(tmpdir(), "chant-gated-exit-")), "summary.md");
+  }
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadChantConfigMock.mockReset().mockResolvedValue({ config: {} });
+    loadPluginsMock.mockReset().mockResolvedValue([]);
+    gateLedger = memoryGateLedgerPort();
+    delete process.env.GITHUB_STEP_SUMMARY;
+  });
+
+  afterEach(() => {
+    delete process.env.GITHUB_STEP_SUMMARY;
+    vi.restoreAllMocks();
+  });
+
+  test("unmapped: without the flag a gated run still exits 3", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("gated", [gateStep])]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const exit = await runOp({ args: makeArgs({ path: "gated" }), plugins: [], serializers: [] });
+    expect(exit).toBe(3);
+  });
+
+  test("mapped: --gated-exit 0 exits 0 and writes the gate to GITHUB_STEP_SUMMARY", async () => {
+    const file = summaryFile();
+    process.env.GITHUB_STEP_SUMMARY = file;
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("gated", [gateStep])]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({
+      args: makeArgs({ path: "gated", gatedExit: 0 }),
+      plugins: [], serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    // The run genuinely stopped: the pending fact is on the ledger, and
+    // nothing after the gate ran.
+    expect(gateLedger.appended).toHaveLength(1);
+    const summary = readFileSync(file, "utf8");
+    expect(summary).toContain("approve-prod");
+    expect(summary).toContain("chant approve gated approve-prod");
+    expect(summary).toContain("_gates/gated.jsonl");
+    // A green run that applied nothing says so on stderr too.
+    expect(stderr.join("\n")).toContain("exiting 0");
+  });
+
+  test("mapped: the --json payload still reports the gate, not a success", async () => {
+    const file = summaryFile();
+    process.env.GITHUB_STEP_SUMMARY = file;
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("gated", [gateStep])]), errors: [] });
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    makeStderrSpy();
+
+    const exit = await runOp({
+      args: makeArgs({ path: "gated", gatedExit: 0, json: true }),
+      plugins: [], serializers: [],
+    });
+
+    expect(exit).toBe(0);
+    const parsed = JSON.parse(stdoutWrite.mock.calls.map((c) => String(c[0])).join("").trim());
+    expect(parsed.status).toBe("gated");
+    expect(parsed.gate).toMatchObject({ name: "approve-prod" });
+    expect(parsed.approve).toBe("chant approve gated approve-prod");
+    // The summary is written whether or not stdout is machine-readable.
+    expect(readFileSync(file, "utf8")).toContain("chant approve gated approve-prod");
+  });
+
+  test("a run that fails for any other reason is still red under the flag", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("broken", [{ kind: "activity", fn: "shellCmd", args: { cmd: "exit 7" } }])]),
+      errors: [],
+    });
+    const file = summaryFile();
+    process.env.GITHUB_STEP_SUMMARY = file;
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const exit = await runOp({
+      args: makeArgs({ path: "broken", gatedExit: 0 }),
+      plugins: [], serializers: [],
+    });
+
+    expect(exit).toBe(1);
+    // Nothing is pending, so nothing is reported as pending.
+    expect(existsSync(file)).toBe(false);
+  });
+
+  test("a value that is not an exit status is refused before the Op runs", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("gated", [gateStep])]), errors: [] });
+    const stderr = makeStderrSpy();
+    const exit = await runOp({
+      args: makeArgs({ path: "gated", gatedExit: 300 }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("--gated-exit expects a whole number from 0 to 255");
+    expect(discoverOpsMock).not.toHaveBeenCalled();
+  });
+
+  test("no GITHUB_STEP_SUMMARY, no file: the variable is the whole forge coupling", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([localOp("gated", [gateStep])]), errors: [] });
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const exit = await runOp({
+      args: makeArgs({ path: "gated", gatedExit: 0 }),
+      plugins: [], serializers: [],
+    });
+    expect(exit).toBe(0);
+    expect(process.env.GITHUB_STEP_SUMMARY).toBeUndefined();
+  });
+});
+
 /**
  * chant #2003 — `--sandbox` is a global flag and `../main.ts` arms the
  * process-wide policy latch off it for every command, so `chant run <op>

package/src/cli/handlers/run.ts

@@ -6,6 +6,7 @@ import type { OpConfig } from "../../op/types";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
 import { runOpLocally, findPolicyGateStep, OpRunFailure, type StepRecord } from "../../op/local-executor";
 import { approveCommand } from "../../op/gate";
+import { writeGatedRunSummary, type GatedRunSummary } from "../../op/gate-summary";
 import { createLocalOpRuntime } from "../../op/runtimes/local";
 import type { OpRuntimeProvider, OpRunStatus } from "../../op/runtime";
 import { renderHuman, renderJson } from "../../op/local-output";
@@ -28,6 +29,54 @@ import type { DriverComponentResult } from "../../components/driver";
  */
 export const GATED_EXIT_CODE = 3;
 
+/**
+ * The exit code this invocation gives a gated run — {@link GATED_EXIT_CODE}
+ * unless `--gated-exit <code>` asked for another one (#2243).
+ *
+ * The mapping lives here rather than in a shell wrapper in every generated
+ * pipeline, so one rule covers every forge: GitHub Actions has no neutral
+ * conclusion for a `run:` step, so a push-to-main apply that stops at its gate
+ * paints the branch red on every merge until someone approves. `--gated-exit
+ * 0` is how the job that knows a pending approval is not a failure says so.
+ *
+ * Only the gated outcome is remapped. A failed run still returns 1, so the
+ * flag can never hide a broken apply. Returns `undefined` after printing the
+ * refusal when the value is not a process exit status.
+ */
+function resolveGatedExitCode(ctx: CommandContext): number | undefined {
+  const raw = ctx.args.gatedExit;
+  if (raw === undefined) return GATED_EXIT_CODE;
+  if (!Number.isInteger(raw) || raw < 0 || raw > 255) {
+    console.error(formatError({
+      message: "--gated-exit expects a whole number from 0 to 255",
+      hint: `Got ${Number.isNaN(raw) ? "a non-numeric value" : String(raw)}. ` +
+        `Pass --gated-exit 0 to make a run that stopped at a gate a success for CI; ` +
+        `omit the flag for the default ${GATED_EXIT_CODE}.`,
+    }));
+    return undefined;
+  }
+  return raw;
+}
+
+/**
+ * What a gated run leaves behind for CI, beyond the stderr block the renderers
+ * already print (#2243): the same gate, approve command and ledger path
+ * appended to whatever file `GITHUB_STEP_SUMMARY` names, so the run page says
+ * what is pending without anyone opening the log.
+ *
+ * Also says on stderr that the exit code was remapped, when it was. A job that
+ * passes `--gated-exit 0` reports success, and the one line that explains why
+ * a zero-exit run applied nothing belongs next to the gate itself.
+ */
+function reportGatedRun(summary: GatedRunSummary, exitCode: number): void {
+  writeGatedRunSummary(summary);
+  if (exitCode !== GATED_EXIT_CODE) {
+    console.error(formatInfo(
+      `gated: exiting ${exitCode} because --gated-exit asked for it. Nothing after the gate ran.`,
+    ));
+  }
+}
+
 /**
  * `run list/status/log/cancel --components` reported a component's *durable*
  * run state — a run that outlives the CLI process and can be queried, signalled
@@ -613,6 +662,9 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  const gatedExit = resolveGatedExitCode(ctx);
+  if (gatedExit === undefined) return 1;
+
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath).catch(() => ({ config: {} as ChantConfig }));
   const paramsResolution = resolveCliBuildParams(config.buildParams, {
@@ -692,7 +744,17 @@ export async function runOpComponents(ctx: CommandContext): Promise<number> {
     console.error(formatInfo(`approve : ${approveCommand(gate.op, gate.gate)}`));
     if (gate.url) console.error(formatInfo(`approve at: ${gate.url}`));
     console.error(formatInfo(`expires : ${gate.expiresAt}`));
-    return GATED_EXIT_CODE;
+    reportGatedRun(
+      {
+        op: gate.op,
+        gate: gate.gate,
+        ...(gate.description ? { description: gate.description } : {}),
+        expiresAt: gate.expiresAt,
+        ...(gate.url ? { url: gate.url } : {}),
+      },
+      gatedExit,
+    );
+    return gatedExit;
   }
 
   if (result.success && result.run) {
@@ -725,6 +787,9 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  const gatedExit = resolveGatedExitCode(ctx);
+  if (gatedExit === undefined) return 1;
+
   const { ops, errors } = await discoverOps();
   for (const err of errors) console.error(formatWarning({ message: err }));
 
@@ -786,8 +851,27 @@ export async function runOpOnRuntime(ctx: CommandContext): Promise<number> {
 
     // Exit 3 for a gated run (#2119) — a distinct code so CI can tell
     // "waiting on a human" from a broken op, and retry the one but not the
-    // other.
-    if (status.state === "gated") return GATED_EXIT_CODE;
+    // other. `--gated-exit <code>` remaps that one outcome and nothing else
+    // (#2243).
+    if (status.state === "gated") {
+      // The local runtime carries the whole pending fact on its result; a
+      // runtime that reports only a state carries the gate's name alone.
+      const pending = status.result?.gate;
+      const gate = pending?.gate ?? status.gate?.name;
+      if (gate) {
+        reportGatedRun(
+          {
+            op: opName,
+            gate,
+            ...(pending?.description ? { description: pending.description } : {}),
+            ...(pending?.expiresAt ? { expiresAt: pending.expiresAt } : {}),
+            ...(pending?.url ? { url: pending.url } : {}),
+          },
+          gatedExit,
+        );
+      }
+      return gatedExit;
+    }
     return status.state === "completed" ? 0 : 1;
   } catch (err) {
     if (err instanceof OpRunFailure) {

package/src/cli/main.test.ts

@@ -1,6 +1,6 @@
 import { describe, test, expect } from "vitest";
 import { EventEmitter } from "node:events";
-import { parseArgs, waitForStreamDrain, usesRemovedTemporalFlag, REMOVED_TEMPORAL_FLAG, REMOVED_FLAG_EXIT_CODE } from "./main";
+import { parseArgs, waitForStreamDrain } from "./main";
 import { resolveCommand, type CommandDef, type ParsedArgs } from "./registry";
 
 describe("parseArgs", () => {
@@ -590,16 +590,14 @@ describe("resolveCommand", () => {
 });
 
 describe("--temporal, removed in #2116", () => {
-  test("the flag is caught before parseArgs, with the line that says where the runtime went", () => {
-    expect(usesRemovedTemporalFlag(["run", "alb-deploy", "--temporal"])).toBe(true);
-    expect(usesRemovedTemporalFlag(["run", "alb-deploy", "--temporal=true"])).toBe(true);
-    expect(REMOVED_TEMPORAL_FLAG).toBe("--temporal was removed in #2116; use --on fountain");
-    expect(REMOVED_FLAG_EXIT_CODE).toBe(2);
-  });
-
-  test("an invocation without it is untouched, and the parser has forgotten the flag", () => {
-    expect(usesRemovedTemporalFlag(["run", "alb-deploy", "--on", "fountain"])).toBe(false);
-    expect(() => parseArgs(["run", "alb-deploy", "--temporal"])).toThrow(/Unknown flag/);
+  // #2204 removed the bridge that caught the flag ahead of the parser and
+  // exited 2. Both spellings now take the same route any other unrecognised
+  // flag takes, and nothing in the CLI knows the word.
+  test("both spellings fail as an unknown flag, like any other unrecognised flag", () => {
+    expect(() => parseArgs(["run", "alb-deploy", "--temporal"])).toThrow(/Unknown flag: --temporal/);
+    expect(() => parseArgs(["run", "alb-deploy", "--temporal=true"])).toThrow(/Unknown flag: --temporal/);
+    // The message and the throw match what an invented flag gets.
+    expect(() => parseArgs(["run", "alb-deploy", "--nonesuch"])).toThrow(/Unknown flag: --nonesuch/);
   });
 });
 

package/src/cli/main.ts

@@ -95,27 +95,6 @@ const BOOLEAN_FLAGS = new Set([
 /**
  * Parse command line arguments
  */
-/**
- * `--temporal` picked the Temporal runtime, which #2116 deleted. It is caught
- * ahead of {@link parseArgs} — which no longer knows the flag at all — for one
- * minor version, so an invocation that still carries it is told where the
- * runtime went instead of getting "Unknown flag: --temporal" and a pointer at
- * `--help`. Delete this, its test and the constants below once that version
- * has shipped.
- */
-export const REMOVED_TEMPORAL_FLAG = "--temporal was removed in #2116; use --on fountain";
-
-/**
- * Not 1: a removed flag means the command never started, so a CI job that
- * retries a failed run has nothing to retry here.
- */
-export const REMOVED_FLAG_EXIT_CODE = 2;
-
-/** Matches the bare flag and the joined `--temporal=…` form `splitJoinedFlags` would otherwise split. */
-export function usesRemovedTemporalFlag(argv: string[]): boolean {
-  return argv.some((arg) => arg === "--temporal" || arg.startsWith("--temporal="));
-}
-
 export function parseArgs(args: string[]): ParsedArgs {
   // Local mutable copy — chant #1127's joined-`--flag=value` splitting below
   // rewrites the array in place (one token becomes two), so this must not
@@ -328,6 +307,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.json = true;
     } else if (arg === "--progress-json") {
       result.progressJson = true;
+    } else if (arg === "--gated-exit") {
+      // `chant run <op> --gated-exit <code>` (#2243) — remap only the gated
+      // outcome's exit code. Parsed as a number here and range-checked in the
+      // handler, where the refusal can name the flag alongside the run.
+      result.gatedExit = Number(args[++i]);
     } else if (arg === "--durable-requests") {
       // `chant run approve ... --on <lexicon> --durable-requests` (#2126) —
       // resolve the gate on the hosting runtime's own request path rather
@@ -1006,12 +990,6 @@ export const commandRegistry: CommandDef[] = [
 async function main(): Promise<void> {
   const rawArgv = process.argv.slice(2);
 
-  if (usesRemovedTemporalFlag(rawArgv)) {
-    console.error(formatError({ message: REMOVED_TEMPORAL_FLAG }));
-    await flushAndExit(REMOVED_FLAG_EXIT_CODE);
-    return;
-  }
-
   let args: ParsedArgs;
   try {
     args = parseArgs(rawArgv);