@intentius/chant 0.58.0 → 0.59.0

package/src/cli/commands/lint.ts

@@ -4,7 +4,7 @@ import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
 import { execFileSync } from "child_process";
 import { runLint, parseDisableComments } from "../../lint/engine";
 import type { LintRule, LintDiagnostic, LintFix } from "../../lint/rule";
-import type { IntrinsicDef } from "../../lexicon";
+import type { IntrinsicDef, LexiconPlugin } from "../../lexicon";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
 import { formatStylish, formatJson, formatSarif } from "../reporters/stylish";
 import { loadLocalRules } from "../../lint/rule-loader";
@@ -20,10 +20,12 @@ import { rule } from "../../lint/declarative";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 import { formatError, formatInfo } from "../format";
 import { GENERATED_MARKER } from "../../discovery/files";
+import { isNoLexiconDetected } from "../../detectLexicon";
 
 // Import config loader
 import { loadConfig, resolveRulesForFile, resolveConfiguredSeverity, findProjectRoot } from "../../lint/config";
 import { loadChantConfig, resolveKnowledgeDir } from "../../config";
+import { findProjectConfig } from "../../project-root";
 import type { LintProjectConfig } from "../../lint/rule";
 import { loadOkfBundle, type OkfBundle } from "../../okf-read";
 
@@ -91,6 +93,40 @@ export async function loadPluginRules(
   return pluginRules;
 }
 
+/**
+ * The diagnostic id `chant lint` reports a lexicon it could not resolve under
+ * (chant #2222).
+ *
+ * Deliberately outside the COR/EVL/COMP/OPS families: those are *rules*, each
+ * with a `check()` the engine runs per file, a documented page, a configurable
+ * severity and a `chant-disable` escape hatch. This is none of those. It is
+ * the lint run reporting that it could not assemble the rule set the project
+ * asked for, so it is not silenceable through `rules: { ... : "off" }` or a
+ * disable comment. Silencing it would put back the exact "green on a broken
+ * project" this id exists to prevent.
+ */
+export const LEXICON_RESOLUTION_RULE_ID = "LEX001";
+
+/**
+ * Turn a lexicon-resolution failure into the error diagnostic `chant lint`
+ * reports it as. The message is the underlying error's own, unwrapped, so it
+ * is character-for-character what `chant build` prints after `error: ` for the
+ * same project (`loadPluginsOrExit`, ../main.ts): one failure, one wording.
+ *
+ * Attributed to the project's `chant.config.*` where there is one, since that
+ * is the file that names the lexicon; to the project root otherwise.
+ */
+function lexiconResolutionDiagnostic(projectRoot: string, error: Error): LintDiagnostic {
+  return {
+    file: findProjectConfig(projectRoot).configPath ?? projectRoot,
+    line: 1,
+    column: 1,
+    ruleId: LEXICON_RESOLUTION_RULE_ID,
+    severity: "error",
+    message: error.message,
+  };
+}
+
 /**
  * Load all lint rules: core COR/EVL rules, then lexicon plugin rules.
  *
@@ -103,7 +139,7 @@ export async function loadPluginRules(
  */
 async function loadAllPluginRules(
   projectPath: string,
-): Promise<{ rules: Map<string, LintRule>; intrinsics: IntrinsicDef[] }> {
+): Promise<{ rules: Map<string, LintRule>; intrinsics: IntrinsicDef[]; lexiconError?: Error }> {
   const rules = new Map<string, LintRule>();
 
   // Load core COR/EVL rules directly
@@ -111,16 +147,47 @@ async function loadAllPluginRules(
     rules.set(r.id, r);
   }
 
-  // Resolve project lexicons (e.g. ["aws"]) from config or detection
+  // Resolve project lexicons (e.g. ["aws"]) from config or detection, then
+  // load their plugins.
+  //
+  // chant #2222: a failure in either step is handed back to `lintCommand`
+  // (which reports it as {@link LEXICON_RESOLUTION_RULE_ID}) rather than
+  // swallowed or thrown. Both steps fail on the same project state: a
+  // `chant.config.ts` that names a lexicon whose package is not installed
+  // throws out of `loadPlugins`, and one that *imports* that package throws
+  // out of `resolveProjectLexicons` before the names are ever read. Before
+  // this, the first case crashed `chant lint` with a stack trace and the
+  // second was caught here and discarded, so `chant lint` printed "No
+  // problems found" and exited 0 on a project `chant build` refuses to
+  // build. A CI job that lints before it builds reported green on a project
+  // whose lexicon was missing.
+  //
+  // The one failure that stays quiet is the one the original `catch` was
+  // written for and named in its comment: a project that declares no
+  // `lexicons` and imports none from its source files, where the detection
+  // fallback throws `NO_LEXICON_DETECTED_MESSAGE`. That project lints under
+  // the core rules alone and always has. It is told apart by the exported
+  // sentinel rather than by a string literal copied to this file, so the two
+  // cannot drift apart.
   let lexiconNames: string[] = [];
+  let lexiconError: Error | undefined;
   try {
     lexiconNames = await resolveProjectLexicons(projectPath);
-  } catch {
-    // No lexicons detected — core rules only
+  } catch (err) {
+    if (!isNoLexiconDetected(err)) {
+      lexiconError = err instanceof Error ? err : new Error(String(err));
+    }
   }
 
   // Load only project lexicon plugins (no "chant" injection)
-  const plugins = await loadPlugins(lexiconNames);
+  let plugins: LexiconPlugin[] = [];
+  if (!lexiconError) {
+    try {
+      plugins = await loadPlugins(lexiconNames);
+    } catch (err) {
+      lexiconError = err instanceof Error ? err : new Error(String(err));
+    }
+  }
 
   // chant #1106 — the same plugins' registered intrinsics (`Ref`, `GetAtt`,
   // ...), so EVL001 can answer "does this call fold?" exactly like fold()
@@ -150,7 +217,7 @@ async function loadAllPluginRules(
     rules.set(r.id, r);
   }
 
-  return { rules, intrinsics };
+  return { rules, intrinsics, ...(lexiconError ? { lexiconError } : {}) };
 }
 
 /**
@@ -695,6 +762,14 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     suppressed.push(...postOpResult.suppressed);
   }
 
+  // chant #2222: a lexicon the project declared but this run could not
+  // resolve. Appended here, after the `--fix` re-lint block above has finished
+  // reassigning `diagnostics`, so it survives every path; it is a property of
+  // the run, not of any file a fix could touch.
+  if (loaded.lexiconError) {
+    diagnostics.push(lexiconResolutionDiagnostic(projectRoot, loaded.lexiconError));
+  }
+
   // Count errors and warnings
   let errorCount = 0;
   let warningCount = 0;

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);