@intentius/chant 0.124.1 → 0.124.3

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, OpWavesSpec } from "./op-waves";
 export {
   opWaveHooksAtBase,
   opWaveNeedsApproval,
   opWavePlansPath,
   opWaveRunsPath,
+  opWaveSetDigest,
   parseOpWavesSpec,
+  recordOpWaveHeadPlans,
   readOpWaveHooksFile,
   readOpWavePolicy,
   runOpWave,
@@ -80,6 +84,7 @@ export type {
   OpWaveBaseRules,
   OpWaveDecision,
   OpWaveApplyHooksRun,
+  OpWaveExec,
   OpWaveHookOutcome,
   OpWaveHookRun,
   OpWaveHooksFile,
@@ -87,7 +92,11 @@ export type {
   OpWaveMember,
   OpWavePlanFile,
   OpWavePlansFile,
+  OpWavePolicySource,
   OpWaveRunsFile,
+  OpWaveShowAtBase,
+  RecordHeadPlansOptions,
+  RunOpWaveApplyHooksOptions,
   RunOpWaveOptions,
   RunOpWaveResult,
 } from "./op-waves-run";

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

@@ -42,7 +42,7 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, posix } from "node:path";
-import { waveGateName, waveSetDigest, type WaveMember } from "../gated-waves";
+import { waveSetDigest, type WaveMember } from "../gated-waves";
 import type { ReviewApproval } from "../gate-decision";
 import { approveCommand, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
 import { isApprovalSpent, type AppliedGateRecord } from "../lifecycle/gate-applied";
@@ -56,6 +56,7 @@ import {
   assertOpWaveHooks,
   assertOpWavesSpec,
   opWaveApplyHooksRunBy,
+  opWaveGateName,
   opWaveHooksAt,
   opWaveRecordPath,
   opWaveShare,
@@ -81,8 +82,21 @@ export interface OpWavePlanFile {
 /** What a wave-level plan command writes to `{plans}` (#3762): one plan per run, by target. The array alone is read too. */
 export interface OpWavePlansFile {
   runs: Array<OpWavePlanFile & { target: string }>;
+  /**
+   * Fields the product adds to the wave's pending fact (#3821), such as the
+   * commit it planned or the members its own readers expect. chant's own
+   * fields win: a key chant writes (`op`, `gate`, `planDigest`, `timestamp`,
+   * ...) is refused, except `description`.
+   */
+  pending?: Record<string, unknown>;
 }
 
+/** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
+export const OP_WAVE_PENDING_RESERVED = [
+  "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
+  "environment", "origin", "neverOverMcp", "approval", "answer",
+] as const;
+
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
 export interface OpWaveRunsFile {
   /** The wave's name. */
@@ -148,6 +162,12 @@ export interface OpWaveDecision {
   applyHooksRunBy?: "apply";
   /** Every hook's outcome so far in the job that wrote the record (#3804). */
   outcomes?: OpWaveHookOutcome[];
+  /** `changing`: the digest covers only the runs whose plan is not empty, as the spec's `digest.over` says (#3821). Absent: every run. */
+  digestOver?: "changing";
+  /** The fields the plans file added to the pending fact (#3821). */
+  pending?: Record<string, unknown>;
+  /** The pending fact carries `neverOverMcp`, set by the spec here or at base (#3821). */
+  neverOverMcp?: true;
 }
 
 /** One hook's run (#3762). */
@@ -216,6 +236,18 @@ export interface OpWaveHooksResult {
   outcomes: OpWaveHookOutcome[];
 }
 
+/** The options of {@link runOpWaveApplyHooks} (#3825). */
+export interface RunOpWaveApplyHooksOptions {
+  /** Where the hooks run. Default `process.cwd()`. */
+  cwd?: string;
+  /** Runs one hook. Default: spawn it with the job's environment. */
+  exec?: OpWaveExec;
+  /** Default: stderr. */
+  log?: (line: string) => void;
+  /** Run nothing and record the moment as skipped, with this reason (#3811). */
+  skip?: string;
+}
+
 /** One call of {@link runOpWaveApplyHooks}. */
 export interface OpWaveApplyHooksRun {
   moment: OpWaveHookMoment;
@@ -293,6 +325,8 @@ export interface OpWaveBaseRules {
   spend: boolean;
   /** Who runs the apply-stage hooks, as read at base (#3804). `chant` when the file, the wave or the hooks are missing there. */
   applyHooksRunBy: OpWaveApplyHooksRunner;
+  /** The spec at base sets `neverOverMcp` (#3821). */
+  neverOverMcp: boolean;
 }
 
 const noHooks = (): Record<OpWaveHookMoment, OpWaveHook[]> =>
@@ -313,7 +347,7 @@ export function readOpWavePolicy(
   show: OpWaveShowAtBase = gitShowAtBase,
 ): OpWaveBaseRules {
   const { sha, text } = show(base, specFile.replace(/^\.\//, "").split("\\").join(posix.sep), cwd);
-  const absent = { policy: "always" as const, approval: "ledger" as const, source: "absent-at-base" as const, base: sha, hooks: noHooks(), spend: false, applyHooksRunBy: "chant" as const };
+  const absent = { policy: "always" as const, approval: "ledger" as const, source: "absent-at-base" as const, base: sha, hooks: noHooks(), spend: false, applyHooksRunBy: "chant" as const, neverOverMcp: false };
   if (text === null) return absent;
   let spec: OpWavesSpec;
   try {
@@ -323,12 +357,13 @@ export function readOpWavePolicy(
   }
   // The spend rule is the spec's, so it holds for a wave the base does not have yet.
   const spend = (spec as { approvals?: { spend?: unknown } }).approvals?.spend === true;
+  const neverOverMcp = (spec as { neverOverMcp?: unknown }).neverOverMcp === true;
   const wave = spec.waves.find((w) => w.name === name);
-  if (!wave) return { ...absent, spend };
+  if (!wave) return { ...absent, spend, neverOverMcp };
   const policy = wave.gate ?? "always";
   // An approval mode this chant does not know reads as sealed: the strictest, so an unknown rule never loosens a gate.
   const approval = wave.approval === undefined ? "ledger" : GATE_APPROVAL_SOURCES.includes(wave.approval) ? wave.approval : "sealed";
-  const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, applyHooksRunBy: "chant" };
+  const rules: OpWaveBaseRules = { policy: OP_WAVE_GATE_POLICIES.includes(policy) ? policy : "always", approval, source: "base", base: sha, hooks: noHooks(), spend, applyHooksRunBy: "chant", neverOverMcp };
   try {
     assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}`, spec.hooks);
     assertOpWaveHooks(`${specFile} at ${sha.slice(0, 12)}, wave "${name}"`, wave.hooks);
@@ -481,9 +516,9 @@ function writeRunsFile(
  * for all of them (#3762). A wave plan is written out as each run's plan file
  * too, so a per-run `apply` or hook reads `{plan}` either way.
  */
-function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec }, runs: readonly OpWaveRun[]): OpWaveMember[] {
+function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string; exec: OpWaveExec }, runs: readonly OpWaveRun[]): PlannedRuns {
   const { spec, k, wave, cwd, exec } = at;
-  if (!spec.planWave) return runs.map((run) => planRun({ spec, wave: k, cwd, exec }, wave.name, run));
+  if (!spec.planWave) return { members: runs.map((run) => planRun({ spec, wave: k, cwd, exec }, wave.name, run)) };
   const runsPath = writeRunsFile(at, runs);
   const plans = opWavePlansPath(spec, k);
   rmSync(join(cwd, plans), { force: true });
@@ -510,12 +545,40 @@ function planRuns(at: { spec: OpWavesSpec; k: number; wave: OpWave; cwd: string;
   }
   const missing = runs.filter((r) => !byTarget.has(r.target)).map((r) => r.target);
   if (missing.length > 0) throw new Error(`the plans file of wave ${k} (${plans}) has no plan for ${missing.join(", ")}`);
-  return runs.map((run) => {
+  const pending = Array.isArray(parsed) ? undefined : pendingFields((parsed as { pending?: unknown }).pending, `the plans file of wave ${k} (${plans})`);
+  const members = runs.map((run) => {
     const m = member(run.target, run.op ?? spec.op, byTarget.get(run.target)!);
     const path = join(cwd, opWavePlanPath(spec, k, run.target));
     writeFileSync(path, JSON.stringify({ planDigest: m.planDigest, ...(m.destructive ? { destructive: true } : {}), ...(m.empty ? { empty: true } : {}) }) + "\n");
     return m;
   });
+  return { members, ...(pending ? { pending } : {}) };
+}
+
+/** What planning a wave's runs gave: each run's plan, and the product's pending-fact fields (#3821). */
+interface PlannedRuns {
+  members: OpWaveMember[];
+  pending?: Record<string, unknown>;
+}
+
+/** A plans file's `pending` (#3821): an object whose keys chant does not write itself, `description` aside. Undefined when absent or empty. */
+function pendingFields(value: unknown, where: string): Record<string, unknown> | undefined {
+  if (value === undefined) return undefined;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${where}: \`pending\` must be an object of fields for the pending fact`);
+  const reserved = Object.keys(value).filter((key) => (OP_WAVE_PENDING_RESERVED as readonly string[]).includes(key));
+  if (reserved.length > 0) throw new Error(`${where}: \`pending\` sets ${reserved.join(", ")}, which chant writes itself`);
+  if ("description" in value && typeof (value as { description?: unknown }).description !== "string") throw new Error(`${where}: pending.description must be a string`);
+  return Object.keys(value).length > 0 ? (value as Record<string, unknown>) : undefined;
+}
+
+/**
+ * A wave's set digest (#3821): {@link waveSetDigest} over its runs' plans,
+ * or under `digest.over: "changing"` over the runs whose plan is not empty,
+ * falling back to every run when all of them are empty.
+ */
+export function opWaveSetDigest(spec: Pick<OpWavesSpec, "digest">, members: ReadonlyArray<WaveMember & { empty?: boolean }>): string {
+  const changing = spec.digest?.over === "changing" ? members.filter((m) => m.empty !== true) : [];
+  return waveSetDigest(changing.length > 0 ? changing : members);
 }
 
 /** What one moment's hooks came to. */
@@ -647,11 +710,7 @@ export function readOpWaveHooksFile(path: string | undefined = process.env.CHANT
  * chant counts the moment as handled. A skip without a reason throws. `exec` runs one hook; inject it to run a hook
  * in process or to keep its output.
  */
-export function runOpWaveApplyHooks(
-  file: OpWaveHooksFile,
-  moment: OpWaveHookMoment,
-  options: { cwd?: string; exec?: OpWaveExec; log?: (line: string) => void; skip?: string } = {},
-): OpWaveApplyHooksRun {
+export function runOpWaveApplyHooks(file: OpWaveHooksFile, moment: OpWaveHookMoment, options: RunOpWaveApplyHooksOptions = {}): OpWaveApplyHooksRun {
   const cwd = options.cwd ?? process.cwd();
   const log = options.log ?? ((line: string) => console.error(line));
   let run: OpWaveApplyHooksRun;
@@ -786,7 +845,7 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
     const slice = opWaveShare(wave.runs, options.share, shares);
     const before = runHooks(ctx, "before-plan", decision.hooks?.["before-plan"], slice);
     if (before.failed) return failed(ctx, `a hook before the plan failed, so nothing in share ${options.share} of wave ${k} was planned or applied`);
-    const members = planRuns(ctx, slice);
+    const { members } = planRuns(ctx, slice);
     const planned = new Map(members.map((m) => [m.member, m]));
     const after = runHooks(ctx, "after-plan", decision.hooks?.["after-plan"], slice, planned);
     if (after.failed) return failed(ctx, `a hook after the plan failed, so nothing in share ${options.share} of wave ${k} was applied`);
@@ -820,13 +879,14 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
   }
   const before = runHooks(ctx, "before-plan", rules.hooks["before-plan"], wave.runs);
   if (before.failed) return failed(ctx, `a hook before the plan failed, so nothing in wave ${k} was planned or applied`);
-  const members = planRuns(ctx, wave.runs);
+  const { members, pending } = planRuns(ctx, wave.runs);
   const planned = new Map(members.map((m) => [m.member, m]));
-  const digest = waveSetDigest(members);
+  const digest = opWaveSetDigest(spec, members);
+  const neverOverMcp = rules.neverOverMcp || spec.neverOverMcp === true;
   const after = runHooks(ctx, "after-plan", rules.hooks["after-plan"], wave.runs, planned, digest);
   if (after.failed) return failed(ctx, `a hook after the plan failed, so nothing in wave ${k} was applied`);
   holds.push(...before.holds, ...after.holds);
-  const gate = waveGateName(spec.gate ?? spec.name, k);
+  const gate = opWaveGateName(spec, k);
   const hooks = Object.fromEntries(Object.entries(rules.hooks).filter(([, list]) => list.length > 0));
   const decision: OpWaveDecision = {
     wave: k,
@@ -844,6 +904,9 @@ export async function runOpWave(options: RunOpWaveOptions): Promise<RunOpWaveRes
     ...(holds.length > 0 ? { heldBy: holds } : {}),
     ...(rules.spend ? { spend: "base" as const } : spec.approvals?.spend === true ? { spend: "change" as const } : {}),
     ...(rules.applyHooksRunBy === "apply" ? { applyHooksRunBy: "apply" as const } : {}),
+    ...(spec.digest?.over === "changing" ? { digestOver: "changing" as const } : {}),
+    ...(pending ? { pending } : {}),
+    ...(neverOverMcp ? { neverOverMcp: true as const } : {}),
   };
   if (opWaveNeedsApproval(policy, members) || holds.length > 0) await settleGate(options, ctx, decision);
   // A wide wave's shares apply under the deciding job's approval, so it is spent here, once.
@@ -905,9 +968,11 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
     op: spec.name,
     gate,
     planDigest: digest,
-    description: `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
+    description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
     now,
     ...(spent ? { spent } : {}),
+    ...(decision.pending ? { fields: decision.pending } : {}),
+    ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
   });
   if (check.satisfied) {
     decision.status = "approved";
@@ -1279,8 +1344,8 @@ export async function recordOpWaveHeadPlans(options: RecordHeadPlansOptions): Pr
     head,
     timestamp: options.now ?? new Date().toISOString(),
     waves: spec.waves.map((wave, i) => {
-      const members = planRuns({ spec, k: i + 1, wave, cwd, exec }, wave.runs);
-      return { wave: i + 1, name: wave.name, digest: waveSetDigest(members) };
+      const { members } = planRuns({ spec, k: i + 1, wave, cwd, exec }, wave.runs);
+      return { wave: i + 1, name: wave.name, digest: opWaveSetDigest(spec, members) };
     }),
   };
   await (options.write ?? ((p) => writeHeadPlans(p, cwd)))(plans);