@intentius/chant 0.122.0 → 0.124.0

package/src/cli/commands/lint.ts

@@ -705,10 +705,13 @@ async function runLexiconPostSynthDiagnostics(
   let result: Awaited<ReturnType<typeof build>>;
   let env: string | undefined;
   let telemetry: Awaited<ReturnType<typeof resolveTelemetryAttribution>>;
+  let configDir = infraPath;
+  let loadedConfig: Record<string, unknown> | undefined;
   try {
     const loaded = await loadChantConfigUpward(infraPath);
     const config = loaded.config;
-    const configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
+    loadedConfig = config as unknown as Record<string, unknown>;
+    configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
     if (loaded.configPath) fallbackFile = loaded.configPath;
     // The caller's parameters when it resolved them (the CLI does, from the
     // same upward config walk); otherwise the declared defaults and `env`
@@ -766,7 +769,7 @@ async function runLexiconPostSynthDiagnostics(
     message: `${d.entity ? `[${d.entity}] ` : ""}${d.message}`,
   });
 
-  for (const { plugin, diagnostics: raw } of runLexiconPostSynthChecks(withChecks, result, env, { activityContracts, telemetry })) {
+  for (const { plugin, diagnostics: raw } of runLexiconPostSynthChecks(withChecks, result, env, { activityContracts, telemetry, projectDir: configDir, ...(loadedConfig ? { projectConfig: loadedConfig } : {}) })) {
     const presetIds = resolvePresetIds(plugin.lintPresets?.(), lintConfig.presets?.[plugin.name] ?? "recommended");
     const afterPreset = applyConfiguredPreset(raw, presetIds, lintConfig.rules).diagnostics;
     const afterConfig = applyConfiguredSeverity(afterPreset, lintConfig.rules).diagnostics;

package/src/cli/discovery-skip.e2e.test.ts

@@ -37,8 +37,8 @@ describe("CLI end-to-end — discovery skips a side-effecting script (#2519)", (
   let ranPath: string;
 
   /** Write the project config; `extra` is spliced into the default export. */
-  async function writeConfig(extra: string): Promise<void> {
-    await writeFile(join(testDir, "chant.config.ts"), `export default { lexicons: ["k8s"]${extra} };\n`);
+  async function writeConfig(extra: string, lexicons = '"k8s"'): Promise<void> {
+    await writeFile(join(testDir, "chant.config.ts"), `export default { lexicons: [${lexicons}]${extra} };\n`);
   }
 
   /** The runner from the issue, optionally headed by `header`. */
@@ -158,11 +158,26 @@ describe("CLI end-to-end — discovery skips a side-effecting script (#2519)", (
   }, TIMEOUT);
 
   test("the control: without exclude, `chant lint` lints the script", async () => {
-    await writeConfig("");
+    // No lexicon, so lint runs its source rules only. With a lexicon that ships
+    // post-synth checks, `chant lint` also builds the target (#3750) and imports
+    // the script, which ends the process before any diagnostic prints; the next
+    // test covers that.
+    await writeConfig("", "");
     await writeRunner();
 
     const lint = runCli(["lint", testDir, "--format", "json"]);
     const diagnostics = JSON.parse(lint.stdout) as Array<{ file: string; ruleId: string }>;
     expect(diagnostics.some((d) => d.file.endsWith(join("ops", "run.ts")) && d.ruleId === "EVL003")).toBe(true);
   }, TIMEOUT);
+
+  test("the control: without exclude, `chant lint` with a lexicon imports the script, as build does", async () => {
+    await writeConfig("");
+    await writeRunner();
+
+    const { status, stderr } = runCli(["lint", testDir, "--format", "json"]);
+
+    expect(status).toBe(2);
+    expect(stderr).toContain("no op named");
+    expect(existsSync(ranPath)).toBe(true);
+  }, TIMEOUT);
 });

package/src/cli/handlers/__snapshots__/build-member.test.ts.snap

@@ -12,7 +12,7 @@ env:
 jobs:
   shared-alb:
     runs-on: ubuntu-latest
-    container: node:22-slim
+    container: node:22
     steps:
       - uses: actions/checkout@v7
       - run: chant run --components shared-alb --env staging --dump-outputs shared-alb.outputs.json
@@ -25,7 +25,7 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - shared-alb
-    container: node:22-slim
+    container: node:22
     steps:
       - uses: actions/checkout@v7
       - name: Download shared-alb outputs

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

@@ -60,6 +60,7 @@ export async function resumeStanding(
   standing: PendingGateRecord,
   resolutions: readonly GateResolutionRecord[],
   opts: ResumeGateOptions = {},
+  pending: readonly PendingGateRecord[] = [standing],
 ): Promise<GateResumeReport> {
   const base = {
     op: standing.op,
@@ -67,7 +68,7 @@ export async function resumeStanding(
     ...(standing.environment !== undefined ? { environment: standing.environment } : {}),
     ...(standing.resume?.url ? { url: standing.resume.url } : {}),
   };
-  const answer = resolutionAnswering(resolutions, standing);
+  const answer = resolutionAnswering(resolutions, standing, pending);
   if (!answer) return { ...base, status: "not-approved", message: "no approval answers it yet" };
   const approvedBy = { approvedBy: answer.resolvedBy };
   if (!isGateRunLocator(standing.resume)) {
@@ -99,7 +100,7 @@ export async function resumeOpGates(op: string, gate: string | undefined, opts:
   const reports: GateResumeReport[] = [];
   for (const standing of standingFacts(ledger.pending, gate)) {
     if (isPendingGateExpired(standing, now)) continue;
-    reports.push(await resumeStanding(standing, ledger.resolutions, opts));
+    reports.push(await resumeStanding(standing, ledger.resolutions, opts, ledger.pending));
   }
   return reports;
 }

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

@@ -77,6 +77,7 @@ vi.mock("../../op/gate-approval", async () => {
 
 // Imported after the mocks above are registered.
 const { runOperator, runOperatorStatus, runOperatorLog, runApprove } = await import("./operator");
+const { gateContextDigest } = await import("../../op/gate-approval");
 
 function ctx(args: Partial<ParsedArgs>) {
   return {
@@ -386,6 +387,16 @@ describe("runApprove", () => {
     errSpy.mockRestore();
   });
 
+  // #3760: --rule and --reason belong to an override of a denied plan.
+  test("refuses --rule and --reason on a gate that is not the override gate", async () => {
+    seedPending("fountain-apply", "rollout-gate", PLAN_A);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", rules: ["no-drop"], reason: "why" }))).toBe(1);
+    expect(errSpy.mock.calls.flat().join("\n")).toMatch(/--rule and --reason override a denied plan: chant approve policy-override <subject>/);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+
   test("appends a gate-resolution record and pushes, resolving --actor over env fallbacks", async () => {
     seedPending("fountain-apply", "rollout-gate", PLAN_A);
     appendGateResolutionMock.mockResolvedValue({
@@ -1115,7 +1126,7 @@ describe("runApprove — a gate with an approval policy (#2508)", () => {
     expect(appendGateResolutionMock).toHaveBeenCalledWith(expect.objectContaining({
       approver: { kind: "agent" },
       policyDecision: {
-        policy: "ship", version: "sha256:v1", mode: "enforce",
+        policy: "ship", version: "sha256:v1", mode: "enforce", contextDigest: gateContextDigest({ risk: "low" }),
         decision: "allow", determining: ["agent-low-risk"], errors: [],
       },
     }));

package/src/cli/handlers/operator.ts

@@ -42,13 +42,13 @@ import {
   latestResolutionSince, latestPendingGate, isPendingGateExpired,
   resolveApprovalUrl, isApprovalUrl,
 } from "../../lifecycle/gate-ledger";
-import { isPlanDigest } from "../../lifecycle/plan-digest";
+import { isPlanDigest, samePlanDigest } from "../../lifecycle/plan-digest";
 import {
-  gatePolicyRequest, loadGatePolicyEvaluator,
+  gateContextDigest, gatePolicyRequest, loadGatePolicyEvaluator,
   type GateApprover, type GatePolicyDecision, type GatePolicyEvaluator, type ResolvedGateApproval,
 } from "../../op/gate-approval";
-import { approverOf, tallyGateApprovals } from "../../op/gate";
-import { FAN_OUT_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
+import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate";
+import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
 import { PR_GATE_OP } from "../../pr-loop";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
 import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
@@ -888,6 +888,19 @@ export async function runApprove(ctx: CommandContext): Promise<number> {
     return 0;
   }
 
+  // #3760: an override of a denied plan names its rules and gives a reason.
+  if (opName === OVERRIDE_GATE_OP) {
+    const { runOverrideApprove } = await import("./override-approve");
+    return runOverrideApprove(ctx);
+  }
+  if (ctx.args.rules !== undefined || ctx.args.reason !== undefined) {
+    console.error(formatError({
+      message: `--rule and --reason override a denied plan: chant approve ${OVERRIDE_GATE_OP} <subject> --rule <id> --reason <text>`,
+      hint: `To approve gate "${gate}" on "${opName}", put any prose in --note.`,
+    }));
+    return 1;
+  }
+
   // `--approver` wins over `--actor`, the same precedence `chant run approve`
   // has applied since #2126 (`../handlers/run.ts`'s `runOpApprove`). Reading
   // only `--actor` here meant every README that teaches `--approver you`
@@ -1016,7 +1029,7 @@ export async function recordGateApproval(
   // `fan-out` is the op name every `chant components fan-out` gate is recorded
   // under (../handlers/fan-out.ts). It is a command rather than a declaration,
   // so there is no `*.op.ts` to find and nothing is wrong when none is there.
-  if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP) {
+  if (!ops.has(opName) && opName !== FAN_OUT_GATE_OP && opName !== WORKSPACE_UPGRADE_GATE_OP && opName !== OVERRIDE_GATE_OP) {
     console.error(formatWarning({
       message: `Op "${opName}" was not found among discovered *.op.ts declarations — recording the resolution anyway`,
     }));
@@ -1260,6 +1273,7 @@ export async function recordGateApproval(
         policy: approval.policy.name,
         version: approval.policy.version,
         mode: approval.mode,
+        contextDigest: gateContextDigest(approval.context),
         decision: answer.decision,
         determining: answer.determining,
         errors: answer.errors,
@@ -1310,7 +1324,7 @@ export async function recordGateApproval(
     ));
   }
   if (approval) {
-    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin)) {
+    for (const line of describeApprovalProgress(approval, record, ledger.resolutions, standingForOrigin, ledger.pending)) {
       console.error(formatInfo(line));
     }
   }
@@ -1328,6 +1342,7 @@ export function describeApprovalProgress(
   record: GateResolutionRecord,
   prior: GateResolutionRecord[],
   standing: PendingGateRecord | undefined,
+  pending: readonly PendingGateRecord[] = standing ? [standing] : [],
 ): string[] {
   const lines: string[] = [];
   const decision = record.policyDecision;
@@ -1343,13 +1358,10 @@ export function describeApprovalProgress(
     for (const error of decision.errors) lines.push(`Policy evaluation error: ${error}`);
   }
 
-  const tally = tallyGateApprovals(
-    [...prior, record],
-    record.gate,
-    standing?.timestamp ?? new Date(0).toISOString(),
-    record.planDigest,
-    approval,
-  );
+  const since = standing?.timestamp ?? new Date(0).toISOString();
+  // #3206: count the humans the way the run will, back past facts re-recorded for this plan.
+  const humansSince = standing && samePlanDigest(standing.planDigest, record.planDigest) ? humanQuorumSince(pending, standing) : since;
+  const tally = tallyGateApprovals([...prior, record], record.gate, since, record.planDigest, approval, humansSince);
   const roles = approval.quorum?.roles ? ` with role ${approval.quorum.roles.join(" or ")}` : "";
   const who = tally.counted.map((r) => r.resolvedBy).join(", ") || "none yet";
   lines.push(`Quorum: ${tally.counted.length} of ${tally.need} human approval(s)${roles} for this plan (${who}).`);

package/src/cli/handlers/override-approve.test.ts

@@ -0,0 +1,87 @@
+/**
+ * #3760: `chant approve policy-override <subject> --rule <id> --reason <text>`
+ * records an override of the subject's recorded denial, for exactly that
+ * plan and those rules.
+ */
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import type { ParsedArgs } from "../registry";
+import { overrideDigest, overridePending, OVERRIDE_OP } from "../../override-gate";
+
+const recordGateApprovalMock = vi.fn();
+const readOverrideLedgerMock = vi.fn();
+const requireLifecycleLedgerMock = vi.fn();
+const originMock = vi.fn(() => "cli");
+
+vi.mock("./operator", () => ({ recordGateApproval: (...a: unknown[]) => recordGateApprovalMock(...a) }));
+vi.mock("../../lifecycle/override-ledger", () => ({ readOverrideLedger: (...a: unknown[]) => readOverrideLedgerMock(...a) }));
+vi.mock("../../lifecycle/git", () => ({ requireLifecycleLedger: (...a: unknown[]) => requireLifecycleLedgerMock(...a) }));
+vi.mock("../../lifecycle/gate-origin", async () => {
+  const actual = await vi.importActual<typeof import("../../lifecycle/gate-origin")>("../../lifecycle/gate-origin");
+  return { ...actual, currentGateOrigin: () => originMock() };
+});
+
+const { runOverrideApprove } = await import("./override-approve");
+
+const PLAN = `sha256:${"a".repeat(64)}`;
+const DENIAL = overridePending({ subject: "prod", planDigest: PLAN, rules: ["no-drop", "no-lock"], timestamp: "2026-10-11T10:00:00.000Z", expiresAt: "2099-01-01T00:00:00.000Z" });
+
+function ctx(args: Partial<ParsedArgs>) {
+  return {
+    args: { command: "approve", path: OVERRIDE_OP, extraPositional: "prod", format: "", fix: false, watch: false, verbose: false, help: false, live: false, ...args } as ParsedArgs,
+    plugins: [],
+    serializers: [],
+  };
+}
+
+let err: ReturnType<typeof vi.spyOn>;
+const printed = () => err.mock.calls.flat().join("\n");
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  err = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  originMock.mockReturnValue("cli");
+  requireLifecycleLedgerMock.mockResolvedValue(undefined);
+  readOverrideLedgerMock.mockResolvedValue({ resolutions: [], pending: [DENIAL], applied: [] });
+  recordGateApprovalMock.mockResolvedValue({ ok: true, pushed: true, record: { version: 1, op: OVERRIDE_OP, gate: "prod", resolvedBy: "github:alice", timestamp: "2026-10-11T11:00:00.000Z" } });
+});
+
+describe("chant approve policy-override", () => {
+  test("approves the denial's override digest with the reason as its note", async () => {
+    const code = await runOverrideApprove(ctx({ rules: ["no-lock", "no-drop"], reason: " the table is empty ", actor: "github:alice", sign: true }));
+    expect(code).toBe(0);
+    expect(recordGateApprovalMock).toHaveBeenCalledWith(OVERRIDE_OP, "prod", expect.objectContaining({
+      actor: "github:alice", note: "the table is empty", plan: overrideDigest("prod", PLAN, ["no-drop", "no-lock"]), sign: true,
+    }));
+    expect(printed()).toMatch(/overrides the denial of prod by no-drop, no-lock for the plan sha256:a{64}/);
+  });
+
+  test("--note is the same field as --reason", async () => {
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], note: "empty table" }))).toBe(0);
+    expect(recordGateApprovalMock).toHaveBeenCalledWith(OVERRIDE_OP, "prod", expect.objectContaining({ note: "empty table" }));
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], note: "a", reason: "b" }))).toBe(1);
+  });
+
+  test.each<[string, Partial<ParsedArgs>, RegExp]>([
+    ["no rule", { reason: "why" }, /names each rule it overrides with --rule/],
+    ["no reason", { rules: ["no-drop", "no-lock"], reason: "  " }, /needs --reason/],
+    ["other rules", { rules: ["no-drop"], reason: "why" }, /denied by no-drop, no-lock; an override names exactly those rules, and --rule gave no-drop/],
+    ["another plan", { rules: ["no-drop", "no-lock"], reason: "why", plan: `sha256:${"b".repeat(64)}` }, /is not the plan denied for prod/],
+    ["an agent", { rules: ["no-drop", "no-lock"], reason: "why", agent: true }, /An override is a person.s/],
+    ["no denial", { rules: ["x"], reason: "why", extraPositional: "staging" }, /No denial of staging is recorded on policy-override; denied: prod/],
+  ])("refuses %s, and records nothing", async (_name, args, why) => {
+    expect(await runOverrideApprove(ctx(args))).toBe(1);
+    expect(printed()).toMatch(why);
+    expect(recordGateApprovalMock).not.toHaveBeenCalled();
+  });
+
+  test("is refused over MCP", async () => {
+    originMock.mockReturnValue("mcp");
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], reason: "why" }))).toBe(1);
+    expect(recordGateApprovalMock).not.toHaveBeenCalled();
+  });
+
+  test("--plan may name the denied plan or the override digest", async () => {
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], reason: "why", plan: PLAN }))).toBe(0);
+    expect(await runOverrideApprove(ctx({ rules: ["no-drop", "no-lock"], reason: "why", plan: DENIAL.planDigest }))).toBe(0);
+  });
+});

package/src/cli/handlers/override-approve.ts

@@ -0,0 +1,103 @@
+/**
+ * `chant approve policy-override <subject> --rule <id>... --reason <text>`
+ * (#3760): record a person's override of the denial a run recorded for
+ * `subject`. The override is an approval of the denial's override digest
+ * (`../../override-gate.ts`), with the reason as its note, written by the
+ * same `recordGateApproval` every `chant approve` uses, so `--sign`,
+ * `--actor`, `--relayed-by` and `--url` work as they do there.
+ *
+ * It names the rules it overrides, which must be exactly the rules the denial
+ * recorded: the approver says what they are letting through. Whether the
+ * override counts is decided by the run, against the overriders and signers
+ * at base; this command only warns when the checkout's own overriders file
+ * would not count it.
+ */
+
+import { currentGateOrigin, isModelAuthored } from "../../lifecycle/gate-origin";
+import { requireLifecycleLedger } from "../../lifecycle/git";
+import { readOverrideLedger } from "../../lifecycle/override-ledger";
+import { samePlanDigest } from "../../lifecycle/plan-digest";
+import { OVERRIDE_OP, OVERRIDERS_PATH, overrideCommand, overridersAt, recordedDenials, sortedRules } from "../../override-gate";
+import { formatError, formatInfo, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import { recordGateApproval } from "./operator";
+
+const norm = (s: string): string => s.normalize("NFKC").trim().toLowerCase();
+
+export async function runOverrideApprove(ctx: CommandContext): Promise<number> {
+  const subject = ctx.args.extraPositional!;
+  const usage = overrideCommand(subject, ctx.args.rules?.length ? ctx.args.rules : ["<id>"]);
+  if (ctx.args.reason !== undefined && ctx.args.note !== undefined && ctx.args.reason.trim() !== ctx.args.note.trim()) {
+    console.error(formatError({ message: "Give the override's reason once: --reason <text> (--note is the same field)", hint: usage }));
+    return 1;
+  }
+  const reason = (ctx.args.reason ?? ctx.args.note)?.trim();
+  const rules = sortedRules(ctx.args.rules ?? []);
+  if (rules.length === 0) {
+    console.error(formatError({ message: `An override names each rule it overrides with --rule <id>`, hint: usage }));
+    return 1;
+  }
+  if (!reason) {
+    console.error(formatError({ message: `An override needs --reason <text>: why this plan goes out although the policy denies it`, hint: usage }));
+    return 1;
+  }
+  if (ctx.args.agent || isModelAuthored(currentGateOrigin())) {
+    console.error(formatError({ message: `An override is a person's: it is never recorded by an agent or over MCP or ACP`, hint: `${usage}, at a shell.` }));
+    return 1;
+  }
+
+  try {
+    await requireLifecycleLedger();
+  } catch (err) {
+    console.error(formatError({ message: `Cannot record the override: ${err instanceof Error ? err.message : String(err)}` }));
+    return 1;
+  }
+  const ledger = await readOverrideLedger();
+  const denials = recordedDenials(ledger.pending);
+  const denial = denials.find((d) => d.gate === subject);
+  if (!denial) {
+    console.error(formatError({
+      message: `No denial of ${subject} is recorded on ${OVERRIDE_OP}` + (denials.length ? `; denied: ${denials.map((d) => d.gate).join(", ")}` : ""),
+      hint: "A run records one when its policy denies the plan. An override answers that denial, for that plan.",
+    }));
+    return 1;
+  }
+  if (denial.rules.join("\n") !== rules.join("\n")) {
+    console.error(formatError({
+      message: `${subject} was denied by ${denial.rules.join(", ") || "no rule it named"}; an override names exactly those rules, and --rule gave ${rules.join(", ")}`,
+      hint: overrideCommand(subject, denial.rules),
+    }));
+    return 1;
+  }
+  if (ctx.args.plan !== undefined && !samePlanDigest(ctx.args.plan, denial.plan) && !samePlanDigest(ctx.args.plan, denial.planDigest)) {
+    console.error(formatError({
+      message: `--plan ${ctx.args.plan} is not the plan denied for ${subject}: the newest denial is of ${denial.plan || denial.planDigest}`,
+      hint: "Run the plan again, or override the denial that stands.",
+    }));
+    return 1;
+  }
+
+  const outcome = await recordGateApproval(OVERRIDE_OP, subject, {
+    actor: ctx.args.approver ?? ctx.args.actor,
+    note: reason,
+    url: ctx.args.url,
+    plan: denial.planDigest!,
+    allowSameOrigin: ctx.args.allowSameOrigin,
+    ...(ctx.args.roles ? { roles: ctx.args.roles } : {}),
+    ...(ctx.args.sign !== undefined ? { sign: ctx.args.sign } : {}),
+    ...(ctx.args.relayedBy !== undefined ? { relayedBy: ctx.args.relayedBy } : {}),
+  });
+  if (!outcome.ok) return 1;
+
+  console.error(formatInfo(
+    `This overrides the denial of ${subject} by ${rules.join(", ")} for the plan ${denial.plan || denial.planDigest}. ` +
+      `The next run that plans it applies it once; a plan that moves, or rules that change, need their own override.`,
+  ));
+  const here = overridersAt(process.cwd(), "HEAD");
+  if (!here.active) {
+    console.error(formatWarning({ message: `This checkout has no ${OVERRIDERS_PATH}: unless the run reads its overriders from elsewhere at base, no override counts` }));
+  } else if (!here.principals.map(norm).includes(norm(outcome.record.resolvedBy))) {
+    console.error(formatWarning({ message: `${outcome.record.resolvedBy} is not in ${OVERRIDERS_PATH} here (${here.principals.join(", ") || "nobody"}), so a run that reads it at base does not count this override` }));
+  }
+  return 0;
+}

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

@@ -5,7 +5,9 @@
 
 import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
+import { notifyOpWave } from "../../op/op-waves-notify";
 import { parseOpWavesSpec, recordOpWaveHeadPlans, runOpWave } from "../../op/op-waves-run";
+import type { OpWavesSpec } from "../../op/op-waves";
 import { formatError } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -35,9 +37,11 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: "--decide and --share are two different jobs; pass one" }));
     return 1;
   }
+  let spec: OpWavesSpec | undefined;
+  const job = args.share !== undefined ? { share: args.share } : {};
   try {
     const path = resolve(specFile);
-    const spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
+    spec = parseOpWavesSpec(readFileSync(path, "utf-8"), `--spec ${specFile}`);
     const result = await runOpWave({
       spec,
       specFile: relative(process.cwd(), path),
@@ -47,9 +51,13 @@ export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
       ...(args.base ? { base: args.base } : {}),
     });
     if (args.json) console.log(JSON.stringify(result, null, 2));
+    // #3761: tell people, when the spec says where. Delivery never changes the exit code.
+    await notifyOpWave(spec, args.wave, { result }, job);
     return result.exitCode;
   } catch (err) {
-    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(formatError({ message }));
+    if (spec) await notifyOpWave(spec, args.wave, { error: message }, job);
     return 1;
   }
 }

package/src/cli/main.test.ts

@@ -346,6 +346,14 @@ describe("parseArgs", () => {
     expect(result.url).toBe("https://github.com/org/repo/pull/1");
   });
 
+  test("parses --rule (repeated) and --reason for an override (#3760)", () => {
+    const result = parseArgs(["approve", "policy-override", "prod", "--rule", "no-drop", "--rule", "no-lock", "--reason", "the table is empty"]);
+    expect(result.rules).toEqual(["no-drop", "no-lock"]);
+    expect(result.reason).toBe("the table is empty");
+    expect(() => parseArgs(["approve", "policy-override", "prod", "--rule"])).toThrow(/--rule needs a rule id/);
+    expect(() => parseArgs(["approve", "policy-override", "prod", "--reason"])).toThrow(/--reason needs the text/);
+  });
+
   // ── --no-release-record (#597) ───────────────────────────────────────────
 
   test("--promote-to <env> sets promoteTo, and a missing value is refused (#2575)", () => {

package/src/cli/main.ts

@@ -696,6 +696,15 @@ export function parseArgs(args: string[]): ParsedArgs {
       result[arg.slice(2) as "unit" | "decision"] = value;
     } else if (arg === "--note") {
       result.note = args[++i];
+    } else if (arg === "--reason") {
+      // `chant approve policy-override <subject> --reason <text>` (#3760): why the denied plan goes out anyway.
+      result.reason = args[++i];
+      if (result.reason === undefined || result.reason.startsWith("-")) throw new Error("--reason needs the text of the reason: --reason <text>");
+    } else if (arg === "--rule") {
+      // `chant approve policy-override <subject> --rule <id>` (#3760), once per rule that denied the plan.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--rule needs a rule id: --rule <id>");
+      (result.rules ??= []).push(value);
     } else if (arg === "--expire") {
       result.expire = true;
     } else if (arg === "--role") {
@@ -999,6 +1008,12 @@ Ops:
                         --resume then starts the CI job that waits at the
                         gate again (GitHub re-run, GitLab retry, Forgejo
                         dispatch) with CHANT_FORGE_TOKEN
+                        On op policy-override the gate is the subject a
+                        policy denied: --rule <id> names each rule that
+                        denied it and --reason <text> says why the plan goes
+                        out anyway; the next run that plans the same digest
+                        applies it once, if .chant/overriders at base lists
+                        --actor
 
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,

package/src/cli/registry.ts

@@ -598,6 +598,10 @@ export interface ParsedArgs {
   once?: boolean;
   /** `chant approve <op> <gate> --note <text>` (#1485) — optional free-text prose recorded on the gate-resolution fact. The PR link belongs in `--url` since #2028; this is for everything that isn't the link. */
   note?: string;
+  /** `chant approve policy-override <subject> --reason <text>` (#3760): why a denied plan goes out anyway, recorded as the override's note. */
+  reason?: string;
+  /** `chant approve policy-override <subject> --rule <id>` (#3760), repeated: the rules that denied the plan, which the override names. */
+  rules?: string[];
   /** `chant approve <op> <gate> --expire` (#2119) — clear the gate's standing pending fact instead of approving it, so the next run decides the gate from scratch and records a fresh one. Writes no resolution: nothing is approved, the wait is only restarted. */
   expire?: boolean;
   /**

package/src/config-import.ts

@@ -9,7 +9,7 @@ import { join } from "node:path";
  * — one narrow module whose only job is "execute project-authored code here",
  * so that the question "did any project code run in this process?" has one
  * place to look and one place to instrument (see
- * `examples/sandbox-execution-boundary.test.ts`, which spies on both).
+ * `examples/sandbox-execution-boundary.e2e.test.ts`, which spies on both).
  *
  * Callers must not `import()` a config file directly. `./config-sandbox.ts`
  * decides whether a given load is allowed to come through here at all: under

package/src/discovery/sandbox/run.test.ts

@@ -14,7 +14,7 @@ const runtimePath = resolve(thisDir, "../../runtime");
 
 /**
  * chant #1045 Phase 2 — proves the actual isolation properties (not just
- * byte-identical output, which `examples/sandbox-differential.test.ts`
+ * byte-identical output, which `examples/sandbox-differential.e2e.test.ts`
  * already covers): a run-fallback file cannot read outside the project
  * directory, write anywhere, spawn a process, or read the ambient
  * environment, and a permission denial names the file and the operation

package/src/gate-decision-bundle.test.ts

@@ -0,0 +1,56 @@
+/**
+ * The gate decision bundles small (#3763, ruling #3421).
+ *
+ * terragucci decides its wave gates from one bundled file with no TypeScript
+ * toolchain, and checked sealed approvals with its own copy of chant's seal
+ * rule because `@intentius/chant/op/gate` pulls in zod and the git ledger
+ * code. `@intentius/chant/gate-decision` holds the decision for a plan digest
+ * under `ledger`, `pr-review` and `sealed`, and the seal check over
+ * node:crypto. This bundles it the way terragucci would and reads esbuild's
+ * own list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+const FORBIDDEN = [/node_modules\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//, /\/src\/lifecycle\/git\.ts$/, /\/src\/lifecycle\/gate-ledger\.ts$/];
+
+describe("the gate-decision bundle", () => {
+  test("holds the decision, the seal check and the plan digest, and no package or git code", async () => {
+    const result = await build({
+      entryPoints: [join(REPO, "packages", "core", "src", "gate-decision.ts")],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/gate-decision.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/gate-applied.ts",
+      "packages/core/src/lifecycle/gate-ledger-select.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+      "packages/core/src/notify-verify.ts",
+      "packages/core/src/notify.ts",
+      "packages/core/src/op/op-waves.ts",
+      "packages/core/src/workspace/jsonc.ts",
+      "packages/core/src/workspace/trust/gate-seal.ts",
+      "packages/core/src/workspace/trust/trust-files.ts",
+    ]);
+    // About 27 KB today.
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(40 * 1024);
+  });
+});