@intentius/chant 0.124.2 → 0.124.4

package/src/op/gate-point-ci.e2e.test.ts

@@ -0,0 +1,171 @@
+/**
+ * #3815: a gate's decision-point question survives a CI job. Outside a
+ * steward's turn a question used to go to the working tree, which a CI
+ * checkout throws away, so `points answer` elsewhere found nothing and the
+ * next run asked again. Asked into the ledger (`--store ledger`, a gate's
+ * `point.store`, or by default when `CI` is set), it lands on
+ * `chant/lifecycle`, is pushed, and is found and answered from another clone;
+ * the job's next run, in a fresh clone, passes on that answer.
+ *
+ * Three clones of one bare remote stand for the CI job's checkout, the
+ * person's clone the answer comes from, and the next job's checkout. The gate
+ * ledger the runs write is the in-memory port, so only the question and its
+ * answer travel through the remote.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from "vitest";
+import { cleanScratch, git, workspace } from "../workspace/__fixtures__/decide-workspace";
+import { runWorkspacePoints } from "../workspace/points-cli";
+import type { CommandContext } from "../cli/registry";
+import { ApplyOp } from "./composites/apply-op";
+import { memoryGateLedgerPort } from "./gate";
+import { defaultGatePointStore, type GatePoint } from "./gate-point";
+import { runOpLocally } from "./local-executor";
+import type { ActivityFn } from "./activity-registry";
+import type { OpConfig } from "./types";
+
+const PLAN = `jcs1-sha256:${"4".repeat(64)}`;
+
+const POINTS = {
+  points: {
+    "prod-apply": {
+      title: "Apply this plan to prod",
+      question: { type: "noul", instructions: "Should this plan be applied to prod?", criteria: { true: "Apply it.", false: "Do not apply it." } },
+      inputs: { "gate.component": "the Op the gate belongs to", "gate.planDigest": "the plan the gate binds" },
+      deciders: [{ kind: "quorum", count: 1 }],
+    },
+    "ship-it": {
+      title: "Ship it",
+      question: { type: "noul", instructions: "Ship it?", criteria: { true: "Ship.", false: "Hold." } },
+      inputs: { "release.version": "the version" },
+      deciders: [{ kind: "quorum", count: 1 }],
+    },
+  },
+};
+
+const applied: string[] = [];
+const activities = new Map<string, ActivityFn>([
+  ["chantBuild", async () => ({ ok: true })],
+  ["lifecycleDiff", async () => ({ planDigest: PLAN, drifted: true })],
+  ["nativeApply", async () => {
+    applied.push(PLAN);
+    return { ok: true };
+  }],
+]);
+
+const config = (name: string, point: string | GatePoint): OpConfig =>
+  (ApplyOp({ name, env: "prod", target: "kubectl", gate: { gate: "approve-apply", point } }).op as unknown as { props: OpConfig }).props;
+
+let home: string;
+let remote: string;
+
+/** A fresh clone of the remote: a CI job's checkout, or a person's. */
+function clone(name: string): string {
+  const dir = join(home, name);
+  execFileSync("git", ["clone", "-q", remote, dir], { stdio: "ignore" });
+  return dir;
+}
+
+/** `chant workspace points <argv>` through the command's handler, in `cwd`. Returns the document it prints. */
+async function points(cwd: string, args: Record<string, unknown>): Promise<Record<string, unknown> & { error?: { code: string } }> {
+  const printed: string[] = [];
+  const log = vi.spyOn(console, "log").mockImplementation((line: unknown) => {
+    printed.push(String(line));
+  });
+  const was = process.cwd();
+  process.chdir(cwd);
+  try {
+    await runWorkspacePoints({ args, plugins: [], serializers: [] } as unknown as CommandContext);
+  } finally {
+    process.chdir(was);
+    log.mockRestore();
+  }
+  return JSON.parse(printed.join("\n"));
+}
+
+const answersIn = (dir: string): string[] => (existsSync(join(dir, "answers")) ? readdirSync(join(dir, "answers")).filter((f) => f.endsWith(".md")) : []);
+const run = (op: OpConfig, cwd: string) => runOpLocally(op, activities, {}, undefined, { gates: memoryGateLedgerPort(), cwd, now: "2026-10-11T12:00:00.000Z" });
+
+beforeAll(() => {
+  home = realpathSync(mkdtempSync(join(tmpdir(), "chant-gate-ci-")));
+  const root = workspace(POINTS);
+  remote = join(home, "remote.git");
+  execFileSync("git", ["clone", "-q", "--bare", root, remote], { stdio: "ignore" });
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+afterAll(() => {
+  cleanScratch();
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("a gate's question outlives the CI job that asked it (#3815)", () => {
+  test("a gate with point.store ledger: asked in one clone, answered from another, and the next job's clone passes on it", async () => {
+    vi.stubEnv("CI", "");
+    const op = config("prod-apply", { name: "prod-apply", store: "ledger" });
+
+    const job = clone("job-1");
+    const first = await run(op, job);
+    expect(first.status).toBe("waiting");
+    const id = first.point!.id;
+    // Nothing was written to the job's working tree, which goes away with the job.
+    expect(answersIn(job)).toEqual([]);
+    expect(git(job, "status", "--porcelain")).toBe("");
+
+    // A person's clone, which never ran the job, finds the question and answers it.
+    const person = clone("person");
+    const answered = await points(person, { extraPositional: "answer", extraPositional2: id, answer: "yes", bys: ["alice"] });
+    expect(answered).toMatchObject({ verb: "answer", id, written: true, question: { state: "answered", answer: true, ledger: expect.stringContaining("chant/lifecycle:") } });
+
+    // The next job, in a fresh checkout, passes on that answer.
+    const next = await run(op, clone("job-2"));
+    expect(next.status).toBe("ok");
+    expect(applied).toEqual([PLAN]);
+  });
+
+  test("with CI set, a gate that names no store asks into the ledger", async () => {
+    expect(defaultGatePointStore({ CI: "true" })).toBe("ledger");
+    expect(defaultGatePointStore({ CI: "false" })).toBeUndefined();
+    expect(defaultGatePointStore({})).toBeUndefined();
+
+    vi.stubEnv("CI", "true");
+    const op = config("ci-apply", "prod-apply");
+    const job = clone("job-3");
+    const first = await run(op, job);
+    expect(first.status).toBe("waiting");
+    expect(answersIn(job)).toEqual([]);
+
+    const person = clone("person-2");
+    expect(await points(person, { extraPositional: "answer", extraPositional2: first.point!.id, answer: "yes", bys: ["alice"] })).toMatchObject({ written: true });
+    expect((await run(op, clone("job-4"))).status).toBe("ok");
+  });
+
+  test("chant workspace points ask --store ledger holds the question on chant/lifecycle, and another clone answers it", async () => {
+    vi.stubEnv("CI", "");
+    const job = clone("ask-job");
+    const asked = await points(job, { extraPositional: "ask", extraPositional2: "ship-it", inputs: JSON.stringify({ "release.version": "1.2.3" }), store: "ledger" });
+    expect(asked).toMatchObject({ verb: "ask", written: true, question: { state: "escalated", ledger: expect.stringContaining("chant/lifecycle:") } });
+    expect(answersIn(job)).toEqual([]);
+
+    const id = asked.id as string;
+    const person = clone("ask-person");
+    expect(await points(person, { extraPositional: "answer", extraPositional2: id, answer: "no", bys: ["bob"] })).toMatchObject({ written: true, question: { state: "answered", answer: false } });
+
+    // Asked again from a fresh checkout, the question is the answered one.
+    const again = await points(clone("ask-job-2"), { extraPositional: "ask", extraPositional2: "ship-it", inputs: JSON.stringify({ "release.version": "1.2.3" }), store: "ledger" });
+    expect(again).toMatchObject({ reused: true, question: { state: "answered", answer: false } });
+
+    // Without --store ledger the same ask in a clone with no ledger history goes to the tree, as before.
+    const tree = clone("ask-tree");
+    const local = await points(tree, { extraPositional: "ask", extraPositional2: "ship-it", inputs: JSON.stringify({ "release.version": "9.9.9" }) });
+    expect(local).toMatchObject({ written: true, question: { ledger: null } });
+    expect(answersIn(tree)).toHaveLength(1);
+  });
+});

package/src/op/gate-point-mcp.e2e.test.ts

@@ -85,6 +85,8 @@ async function shell(verb: "answer" | "retract", id: string, by: string[], answe
 
 beforeAll(() => {
   root = workspace(POINTS);
+  // The questions go to the working tree, as outside CI: a CI job asks into the ledger by default (#3815).
+  vi.stubEnv("CI", "");
   mkdirSync(join(root, ".chant"), { recursive: true });
   writeFileSync(join(root, ".chant", "trust.json"), JSON.stringify({ schema: 1, roles: { agent: ["bot"], lead: ["alice", "bob"] } }));
   git(root, "add", "-A");

package/src/op/gate-point-run.ts

@@ -25,51 +25,28 @@
  * and, when the point declares them, in its `gate.*` inputs.
  */
 
-import { isPendingGateExpired, latestPendingGate, DEFAULT_GATE_EXPIRY, resolveApprovalUrl, type GateAnswerRef, type GateResolutionRecord, type PendingGateRecord } from "../lifecycle/gate-ledger";
-import { samePlanDigest } from "../lifecycle/plan-digest";
-import { parseDuration } from "./duration";
-import type { GateLedgerPort } from "./gate";
-import { DEFAULT_GATE_POINT_PASS, gatePointInputs, gateSubject, type GatePoint, type GatePointFacts } from "./gate-point";
-import { isPointWait, type WaitingPoint } from "./steward-points";
+import { defaultGatePointStore, gatePointInputs } from "./gate-point";
+import { isPointWait } from "./steward-points";
+import type { GatePointAsker } from "../point-decision";
 
-/** The question a gate's point was asked, as the gate reads it. */
-export interface GatePointQuestion {
-  /** The answer record's id: what `points answer` takes. */
-  id: string;
-  point: string;
-  /** The record, from the repository root. */
-  path: string;
-  state: "escalated" | "proposed" | "answered";
-  /** The answer, or null while the question is open. */
-  answer: string | boolean | null;
-  /** The decider that gave the recorded state: table, model or quorum. */
-  decider: string;
-  answeredBy: string[];
-  subject: string | null;
-  /** The steward whose turn asked it, or null. */
-  steward: string | null;
-}
-
-/** What a gate asks its point with. */
-export interface GatePointRequest {
-  point: string;
-  /** The authored inputs, references resolved. */
-  inputs: Record<string, unknown>;
-  facts: GatePointFacts;
-  /** What the answer record's `constrains` names: {@link gateSubject}. */
-  subject: string;
-}
-
-/** How a gate asks its point. A test passes a stub; {@link workspaceGatePointAsker} is the real one. */
-export interface GatePointAsker {
-  ask(request: GatePointRequest): Promise<GatePointQuestion>;
-}
+// The decision itself bundles without the workspace (#3816): `@intentius/chant/point-decision`.
+export {
+  evaluatePointGate,
+  type GatePointAsker,
+  type GatePointQuestion,
+  type GatePointRequest,
+  type PointGateCheck,
+  type PointGateInput,
+  type PointGateLedgerPort,
+} from "../point-decision";
 
 /**
  * The real asker: the workspace that holds `cwd`. It reads the point's
  * declared inputs from `points`, adds the `gate.*` ones the point declares,
  * and asks through the decide activity. A point with no model decider is
- * asked with no backends, so the run needs no `decide.backends`.
+ * asked with no backends, so the run needs no `decide.backends`. A question
+ * goes where the gate's `point.store` says, and to the ledger in a CI job
+ * when it says nothing (`defaultGatePointStore`, #3815).
  */
 export function workspaceGatePointAsker(cwd: string): GatePointAsker {
   return {
@@ -86,7 +63,8 @@ export function workspaceGatePointAsker(cwd: string): GatePointAsker {
       const { runDecide } = await import("./activities/decide");
       const asksModel = point.deciders.some((d) => d.kind === "model");
       try {
-        const r = await runDecide({ point: request.point, inputs, subject: request.subject, cwd, ...(asksModel ? {} : { backends: {} }) });
+        const store = request.store ?? defaultGatePointStore();
+        const r = await runDecide({ point: request.point, inputs, subject: request.subject, cwd, ...(store ? { store } : {}), ...(asksModel ? {} : { backends: {} }) });
         return { id: r.id, point: request.point, path: r.path, state: r.state, answer: r.answer, decider: r.decider, answeredBy: r.answeredBy, subject: request.subject, steward: null };
       } catch (err) {
         if (!isPointWait(err)) throw err;
@@ -96,112 +74,3 @@ export function workspaceGatePointAsker(cwd: string): GatePointAsker {
     },
   };
 }
-
-/** What the run needs to decide a gate that asks a point. */
-export interface PointGateInput {
-  op: string;
-  gate: string;
-  point: GatePoint;
-  /** The authored inputs, references resolved. */
-  inputs?: Record<string, unknown>;
-  description?: string;
-  timeout?: string;
-  runId?: string;
-  planDigest?: string;
-  /** The environment the run was started for: the `gate.env` input. Op gate facts on the ledger record none. */
-  env?: string;
-  now?: string;
-}
-
-/** What reaching a gate that asks a point decided. */
-export type PointGateCheck =
-  | {
-      satisfied: true;
-      /** The resolution that cites the answer: this run's, or one an earlier run wrote for the same answer and plan. */
-      resolution: GateResolutionRecord;
-      answer: GateAnswerRef;
-      /** Whether this run appended the resolution. */
-      recorded: boolean;
-      pushed?: boolean;
-      pushWarning?: string;
-    }
-  | {
-      satisfied: false;
-      /** The question is answered, with an answer the gate does not pass on. */
-      refused: string;
-      answer: GateAnswerRef;
-    }
-  | {
-      satisfied: false;
-      /** The open question the run waits on. */
-      waiting: WaitingPoint;
-      /** The pending fact that cites it. */
-      pending: PendingGateRecord;
-      recorded: boolean;
-      pushed?: boolean;
-      pushWarning?: string;
-    };
-
-/** Who a resolution written for an answer is by: the people who answered, or the decider that did. */
-function resolvedByOf(q: GatePointQuestion): string {
-  return q.answeredBy.length > 0 ? q.answeredBy.join(", ") : q.decider;
-}
-
-/** Decide a gate that asks a point: ask it, then record the pending fact or the resolution that cites the answer. */
-export async function evaluatePointGate(port: GateLedgerPort, asker: GatePointAsker, input: PointGateInput): Promise<PointGateCheck> {
-  const now = input.now ?? new Date().toISOString();
-  const facts: GatePointFacts = { component: input.op, name: input.gate, env: input.env ?? null, planDigest: input.planDigest ?? null };
-  const q = await asker.ask({ point: input.point.name, inputs: input.inputs ?? {}, facts, subject: gateSubject(input.op, input.gate, input.env) });
-  const ref: GateAnswerRef = { point: q.point, id: q.id, path: q.path };
-
-  if (q.state === "answered" && q.answer !== null) {
-    const answer: GateAnswerRef = { ...ref, answer: q.answer, decider: q.decider, ...(q.answeredBy.length > 0 ? { answeredBy: q.answeredBy } : {}) };
-    const pass = input.point.pass ?? DEFAULT_GATE_POINT_PASS;
-    if (!pass.includes(q.answer)) {
-      return {
-        satisfied: false,
-        answer,
-        refused:
-          `decision point ${q.point} answered ${JSON.stringify(q.answer)} (${q.id}, by ${resolvedByOf(q)}), and gate "${input.gate}" passes only on ${pass.map((a) => JSON.stringify(a)).join(" or ")}. ` +
-          `To ask again, take the answer back: chant workspace points retract ${q.id} --by <name>`,
-      };
-    }
-    const ledger = await port.read(input.op);
-    const standing = ledger.resolutions.find(
-      (r) => r.gate === input.gate && r.answer?.id === q.id && r.environment === undefined && samePlanDigest(r.planDigest, input.planDigest),
-    );
-    if (standing) return { satisfied: true, resolution: standing, answer, recorded: false };
-    if (!port.appendResolution) throw new Error(`gate "${input.gate}" asks decision point ${q.point}, and this gate ledger cannot record the resolution that cites its answer`);
-    const { record, pushed, pushWarning } = await port.appendResolution({
-      op: input.op,
-      gate: input.gate,
-      resolvedBy: resolvedByOf(q),
-      timestamp: now,
-      note: `answered through decision point ${q.point} (${q.id})`,
-      ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
-      approver: { kind: q.decider === "quorum" || q.answeredBy.length > 0 ? "human" : "agent" },
-      answer,
-    });
-    return { satisfied: true, resolution: record, answer, recorded: true, pushed, ...(pushWarning ? { pushWarning } : {}) };
-  }
-
-  const waiting: WaitingPoint = { id: q.id, point: q.point, state: q.state === "proposed" ? "proposed" : "escalated", path: q.path, subject: q.subject, steward: q.steward };
-  const ledger = await port.read(input.op);
-  const standing = latestPendingGate(ledger.pending.filter((p) => p.environment === undefined), input.gate);
-  if (standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) && standing.answer?.id === q.id) {
-    return { satisfied: false, waiting, pending: standing, recorded: false };
-  }
-  const url = resolveApprovalUrl();
-  const { record, pushed, pushWarning } = await port.appendPending({
-    op: input.op,
-    gate: input.gate,
-    timestamp: now,
-    expiresAt: new Date(new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY)).toISOString(),
-    ...(input.description ? { description: input.description } : {}),
-    ...(input.runId ? { runId: input.runId } : {}),
-    ...(url ? { url } : {}),
-    ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
-    answer: ref,
-  });
-  return { satisfied: false, waiting, pending: record, recorded: true, pushed, ...(pushWarning ? { pushWarning } : {}) };
-}

package/src/op/gate-point.e2e.test.ts

@@ -75,6 +75,8 @@ async function pointsAnswer(id: string, answer: string, by: string): Promise<Rec
 
 beforeAll(() => {
   root = workspace(POINTS);
+  // The questions go to the working tree, as outside CI: a CI job asks into the ledger by default (#3815).
+  vi.stubEnv("CI", "");
 });
 
 afterAll(cleanScratch);

package/src/op/gate-point.test.ts

@@ -61,7 +61,7 @@ describe("a gate's point declaration (#3170)", () => {
     expect(() => gate("apply", { point: "Prod Apply" })).toThrow(/decision point's name/);
     expect(() => gate("apply", { point: { name: "prod-apply", inputs: { "gate.planDigest": PLAN } } })).toThrow(/which the gate passes itself/);
     expect(gatePointProblems({ name: "prod-apply", pass: [] })).toEqual(["`point.pass` is a non-empty list of the answers that pass the gate"]);
-    expect(gatePointProblems({ name: "prod-apply", quorum: 2 })).toEqual(["`point` takes name, inputs and pass, not quorum"]);
+    expect(gatePointProblems({ name: "prod-apply", quorum: 2 })).toEqual(["`point` takes name, inputs, pass and store, not quorum"]);
   });
 
   test("the gate passes the gate.* inputs the point declares, beside the authored ones", () => {

package/src/op/gate-point.ts

@@ -31,6 +31,29 @@ export interface GatePoint {
   inputs?: Record<string, unknown>;
   /** The answers that pass the gate. Default `[true]`: a noul point's yes. Any other answer fails the step. */
   pass?: Array<string | boolean>;
+  /**
+   * Where the question goes when the run asks it (#3815): `"tree"`, the
+   * answer kind's directory in the working tree, or `"ledger"`,
+   * `chant/lifecycle`, pushed, so a person can answer it after a checkout
+   * that does not outlive the run is gone. Default: the ledger in a steward's
+   * turn or a CI job (`CI` set), and the tree otherwise.
+   */
+  store?: GatePointStore;
+}
+
+/** Where a gate's question is held: the working tree or `chant/lifecycle`. */
+export type GatePointStore = "tree" | "ledger";
+
+/**
+ * Where a gate's question goes when its `point` names no `store` (#3815): the
+ * ledger in a CI job, whose checkout is thrown away when the job ends, so the
+ * question outlives it; otherwise undefined, and `points ask`'s own rule
+ * holds (the ledger in a steward's turn, the tree otherwise). A CI job is one
+ * whose environment sets `CI`, as GitHub Actions and GitLab CI do.
+ */
+export function defaultGatePointStore(env: Readonly<Record<string, string | undefined>> = process.env): GatePointStore | undefined {
+  const ci = env.CI?.trim().toLowerCase();
+  return ci && ci !== "false" && ci !== "0" ? "ledger" : undefined;
 }
 
 /** The answers a gate passes on when it names none: a noul point's yes. */
@@ -49,8 +72,8 @@ export function gatePointProblems(point: unknown, withApproval = false): string[
   const problems: string[] = [];
   if (withApproval) problems.push("a gate that asks a decision point takes its quorum from the point: give `approval` or `point`, not both");
   const p = typeof point === "string" ? { name: point } : point;
-  if (p === null || typeof p !== "object" || Array.isArray(p)) return [...problems, "`point` is a decision point's name or { name, inputs?, pass? }"];
-  const { name, inputs, pass, ...rest } = p as Record<string, unknown>;
+  if (p === null || typeof p !== "object" || Array.isArray(p)) return [...problems, "`point` is a decision point's name or { name, inputs?, pass?, store? }"];
+  const { name, inputs, pass, store, ...rest } = p as Record<string, unknown>;
   if (typeof name !== "string" || !POINT_NAME.test(name)) problems.push("`point.name` is a decision point's name: lower case letters, digits and hyphens, starting with a letter");
   if (inputs !== undefined && (inputs === null || typeof inputs !== "object" || Array.isArray(inputs))) problems.push("`point.inputs` is an object of input name to value");
   if (inputs && typeof inputs === "object") {
@@ -60,8 +83,9 @@ export function gatePointProblems(point: unknown, withApproval = false): string[
   if (pass !== undefined && (!Array.isArray(pass) || pass.length === 0 || pass.some((a) => typeof a !== "string" && typeof a !== "boolean"))) {
     problems.push("`point.pass` is a non-empty list of the answers that pass the gate");
   }
+  if (store !== undefined && store !== "tree" && store !== "ledger") problems.push("`point.store` is tree or ledger: where the question is held");
   const extra = Object.keys(rest);
-  if (extra.length > 0) problems.push(`\`point\` takes name, inputs and pass, not ${extra.join(", ")}`);
+  if (extra.length > 0) problems.push(`\`point\` takes name, inputs, pass and store, not ${extra.join(", ")}`);
   return problems;
 }
 

package/src/op/gate.ts

@@ -260,6 +260,14 @@ export interface GateCheckInput {
    * stands as a mismatch. Absent, nothing is spent.
    */
   spent?: readonly AppliedGateRecord[];
+  /**
+   * Fields a caller adds to the pending fact it records (#3821), such as an
+   * Op waves product's commit and members. Every field this function writes
+   * itself wins over one of the same name.
+   */
+  fields?: Record<string, unknown>;
+  /** The pending fact it records carries `neverOverMcp` (#3821, chant#3485). */
+  neverOverMcp?: boolean;
 }
 
 /**
@@ -592,6 +600,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // #3683: in CI, where this job runs, so an approval can start it again.
   const resume = resolveGateRunLocator();
   const { record, pushed, pushWarning } = await port.appendPending({
+    ...(input.fields as Partial<PendingGateInput> | undefined),
     op: input.op,
     gate: input.gate,
     timestamp: now,
@@ -605,6 +614,7 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
     ...(env !== undefined ? { environment: env } : {}),
     ...(input.approval ? { approval: input.approval } : {}),
+    ...(input.neverOverMcp ? { neverOverMcp: true as const } : {}),
   });
   return {
     satisfied: false,

package/src/op/index.ts

@@ -54,23 +54,27 @@ export type { GenerateOpsPipelineResult, GenerateOpWavesPipelineResult } from ".
 export {
   OP_WAVE_APPLY_HOOKS_RUNNERS,
   OP_WAVE_DEFAULT_APPLY,
+  OP_WAVE_DEFAULT_GATE_NAME,
   OP_WAVE_GATE_POLICIES,
   OP_WAVE_HOOK_MOMENTS,
   assertOpWaveHooks,
   assertOpWavesSpec,
   opWaveApplyHooksRunBy,
+  opWaveGateName,
   opWaveHooksAt,
   opWaveJobs,
   opWaveRecordPath,
   opWaveShare,
 } from "./op-waves";
-export type { OpWave, OpWaveApplyHooksRunner, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesSpec } from "./op-waves";
+export type { OpWave, OpWaveApplyHooksRunner, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesDigest, OpWavesOverride, OpWavesSpec } from "./op-waves";
 export {
   opWaveHooksAtBase,
   opWaveNeedsApproval,
   opWavePlansPath,
   opWaveRunsPath,
+  opWaveSetDigest,
   parseOpWavesSpec,
+  recordOpWaveHeadPlans,
   readOpWaveHooksFile,
   readOpWavePolicy,
   runOpWave,
@@ -80,6 +84,9 @@ export type {
   OpWaveBaseRules,
   OpWaveDecision,
   OpWaveApplyHooksRun,
+  OpWaveExec,
+  OpWaveHeldOn,
+  OpWaveHoldRequest,
   OpWaveHookOutcome,
   OpWaveHookRun,
   OpWaveHooksFile,
@@ -87,7 +94,11 @@ export type {
   OpWaveMember,
   OpWavePlanFile,
   OpWavePlansFile,
+  OpWavePolicySource,
   OpWaveRunsFile,
+  OpWaveShowAtBase,
+  RecordHeadPlansOptions,
+  RunOpWaveApplyHooksOptions,
   RunOpWaveOptions,
   RunOpWaveResult,
 } from "./op-waves-run";

package/src/op/op-waves-notify.ts

@@ -5,7 +5,8 @@
  * approval command, the digest and, under `pr-review`, the pull request to
  * review. A share job that refused a run whose plan moved (exit 4) sends
  * `refused`. A wave whose plan, apply or stage hook failed (exit 1) sends
- * `failed`. A share job of a waiting wave sends nothing, since its deciding
+ * `failed`. A wave the product's policy refused (exit 7, #3821) sends
+ * `refused` with the runs it denied. A share job of a waiting wave sends nothing, since its deciding
  * job already did, unless a hook in the share job itself held it (#3762). Delivery is `../notify.ts`: it never throws, and the job's exit code
  * is what the wave decided.
  */
@@ -46,13 +47,29 @@ export function opWaveNotifyFields(spec: OpWavesSpec, k: number, outcome: OpWave
       summary: `${label} waits for an approval`,
       targets: decision.members.map((m) => m.member),
       approve: { command: decision.approve ?? `chant approve ${decision.op} ${decision.gate} --plan ${decision.digest}`, ...review },
-      ...(decision.heldBy?.length
+      ...(decision.heldOn
+        ? { reason: `held on ${decision.heldOn.op} / ${decision.heldOn.gate} by ${decision.heldOn.hook}` }
+        : decision.heldBy?.length
         ? { reason: `held by ${decision.heldBy.join(", ")}` }
         : decision.review?.reason
           ? { reason: decision.review.reason }
           : {}),
     };
   }
+  if (result.exitCode === 7 && decision?.refused) {
+    // #3821: the product's policy denied a run, and no override counts for it.
+    return {
+      ...base,
+      event: "refused",
+      status: decision.refused.reason === "override-moved" ? "override-moved" : "denied",
+      summary: `${label} refused: the policy denied ${decision.refused.runs.join(", ")}`,
+      targets: decision.refused.runs,
+      reason:
+        decision.refused.reason === "override-moved"
+          ? "an override stands for an earlier plan or other rules, so it counts for nothing"
+          : "the policy denied these runs, and no override counts for them",
+    };
+  }
   if (result.exitCode === 4) {
     return {
       ...base,