@intentius/chant 0.122.0 → 0.123.0

package/src/op/gate-approval.ts

@@ -26,7 +26,9 @@
  * on the resolution with the policy's version, and a run counts a recorded
  * permit only while the gate still declares that same version. Editing the
  * policy invalidates every permit recorded under the old one, the way a new
- * plan invalidates every approval recorded for the old plan (#2300).
+ * plan invalidates every approval recorded for the old plan (#2300). The
+ * decision also records the digest of the context it was asked about, and a
+ * permit counts only while the run resolves that same context (#3774).
  *
  * The trust boundary is unchanged from `../lifecycle/gate-ledger.ts`: a
  * resolution is a local fact, not a signed one, and roles on it are what the
@@ -134,6 +136,14 @@ export interface GatePolicyDecision extends GatePolicyAnswer {
    * an allow recorded under `log-only` never binds after a switch.
    */
   mode: GateApprovalMode;
+  /**
+   * {@link gateContextDigest} of the resolved context the policy was asked
+   * about (#3774). A permit passes a gate only while the run's resolved
+   * context has this same digest, so a permit given for `risk: "low"` does
+   * not pass a run that now resolves `risk: "high"`. A decision recorded
+   * before #3774 has none and does not pass an enforced gate.
+   */
+  contextDigest?: string;
 }
 
 /** What a lexicon's `gate-policy` module exports. */
@@ -146,6 +156,22 @@ export function gatePolicyVersion(text: string): string {
   return `sha256:${createHash("sha256").update(text).digest("hex")}`;
 }
 
+/**
+ * The digest of a gate's resolved approval context (#3774): `sha256:` and the
+ * hex digest of its JSON with keys sorted at every level. No context and an
+ * empty one digest the same.
+ */
+export function gateContextDigest(context: Record<string, unknown> | undefined): string {
+  return `sha256:${createHash("sha256").update(JSON.stringify(context ?? {}, sortedKeys)).digest("hex")}`;
+}
+
+function sortedKeys(_key: string, value: unknown): unknown {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+  }
+  return value;
+}
+
 export function isGatePolicyRef(value: unknown): value is GatePolicyRef {
   if (typeof value !== "object" || value === null) return false;
   const v = value as Record<string, unknown>;

package/src/op/gate-name.ts

@@ -37,6 +37,13 @@ export const FAN_OUT_GATE_OP = "fan-out";
  */
 export const WORKSPACE_UPGRADE_GATE_OP = "workspace-upgrade";
 
+/**
+ * The op name the override gate records denials and overrides under (#3760):
+ * `_gates/policy-override.jsonl`, gate the subject a policy denied. Like a
+ * fan-out it has no `*.op.ts`, and an override is a person's, never a model's.
+ */
+export const OVERRIDE_GATE_OP = "policy-override";
+
 /**
  * The pull-request loop records its gate under `pr-<number>`, or
  * `pr-<number>-<member>` in a workspace member (`prOp` in `pr-loop.ts`), and
@@ -47,11 +54,12 @@ const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
 /**
  * Whether gates recorded under this op name are never resolved over MCP or ACP
  * (chant#3485, chant#3513). These are the gate-only names MCP cannot discover:
- * `fan-out`, `workspace-upgrade` and the pull-request gate `pr-<number>`. With
+ * `fan-out`, `workspace-upgrade`, `policy-override` (#3760) and the
+ * pull-request gate `pr-<number>`. With
  * no Op config to read `neverOverMcp` from, the pending record carries it.
  */
 export function isNeverOverMcpGateOp(op: string): boolean {
-  return op === FAN_OUT_GATE_OP || op === WORKSPACE_UPGRADE_GATE_OP || PR_GATE_OP.test(op);
+  return op === FAN_OUT_GATE_OP || op === WORKSPACE_UPGRADE_GATE_OP || op === OVERRIDE_GATE_OP || PR_GATE_OP.test(op);
 }
 
 /** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */

package/src/op/gate-resume.ts

@@ -35,7 +35,7 @@
 import { ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { latestResolutionForPlan } from "../lifecycle/gate-ledger";
-import { tallyGateApprovals } from "./gate";
+import { humanQuorumSince, tallyGateApprovals } from "./gate";
 
 /** Where the job that recorded a pending fact runs, and what its forge needs to start it again. */
 export interface GateRunLocator {
@@ -237,18 +237,21 @@ export async function resumeGateRun(loc: GateRunLocator, opts: ResumeGateRunOpti
 
 /**
  * The resolution that answers `standing`, read the way a run decides the gate
- * (the plan, the environment, the quorum), or undefined. A workspace's
+ * (the plan, the environment, the quorum), or undefined. `pending` is the
+ * gate ledger's pending facts, which place the human quorum's anchor (#3206);
+ * without them it is `standing` itself. A workspace's
  * `identity.gates` rule is not applied here: the resumed job applies it, and
  * waits again when the approval does not count.
  */
 export function resolutionAnswering(
   resolutions: readonly GateResolutionRecord[],
   standing: PendingGateRecord,
+  pending: readonly PendingGateRecord[] = [standing],
 ): GateResolutionRecord | undefined {
   const env = standing.environment;
   const mine = resolutions.filter((r) => env === undefined || r.environment === env);
   if (standing.approval) {
-    const tally = tallyGateApprovals(mine, standing.gate, standing.timestamp, standing.planDigest, standing.approval);
+    const tally = tallyGateApprovals(mine, standing.gate, standing.timestamp, standing.planDigest, standing.approval, humanQuorumSince(pending, standing));
     if (tally.permit) return tally.permit;
     return tally.counted.length >= tally.need ? tally.counted[tally.counted.length - 1] : undefined;
   }

package/src/op/gate-review.ts

@@ -30,7 +30,7 @@
  */
 
 import { readFileSync } from "node:fs";
-import { checkGateSeal } from "../workspace/trust/seal";
+import { gateSealRefusal } from "../workspace/trust/gate-seal";
 import { readTrustPolicy, type TrustPolicy } from "../workspace/trust/policy";
 import { gitRevisionSource } from "../workspace/record-source";
 import { forgePrincipalOf, ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";
@@ -48,18 +48,15 @@ export function trustPolicyAt(cwd: string, base: string): TrustPolicy {
 
 /**
  * The rule a `sealed` gate judges approvals by: a seal that verifies for the
- * approver against `policy`, the signers at base. With no signers file at
+ * approver against `policy`, the signers at base, checked with node:crypto
+ * (#3785), so an apply job needs no ssh-keygen. With no signers file at
  * base nothing verifies, so nothing passes the gate.
  */
 export function sealedApprovalRule(gate: string, policy: TrustPolicy): GateApprovalRule {
   return {
     requirement: { gate, class: null },
     refuses(approval: GateResolutionRecord): string | null {
-      if (!policy.active) {
-        return `the gate is sealed, and there is no signers file (${policy.signersPath}) at base ${policy.base?.slice(0, 12) ?? ""}`.trim();
-      }
-      const check = checkGateSeal(policy, approval);
-      return check.attested === true ? null : check.message;
+      return gateSealRefusal(policy, approval);
     },
   };
 }

package/src/op/gate.ts

@@ -48,9 +48,10 @@ import {
 } from "../lifecycle/gate-ledger";
 import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
 import { isModelAuthored } from "../lifecycle/gate-origin";
+import { appliedGatePath, isApprovalSpent, parseAppliedGateLines, type AppliedGateRecord } from "../lifecycle/gate-applied";
 import { sortedJsonReplacer } from "../utils";
-import type { GateApprover, ResolvedGateApproval } from "./gate-approval";
-import { pushLifecycleReport, requireLifecycleLedger } from "../lifecycle/git";
+import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from "./gate-approval";
+import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git";
 import { parseDuration } from "./duration";
 import { resolveGateRunLocator } from "./gate-resume";
 
@@ -92,6 +93,10 @@ export interface GateLedgerPort {
    * Absent, every approval is judged as before.
    */
   approvalRule?(gate: string): Promise<GateApprovalRule | null>;
+  /** The approvals a wave applied under (#3784), from `_gates/<op>/applied.jsonl`. Absent on a port that never spends approvals. */
+  readApplied?(op: string): Promise<AppliedGateRecord[]>;
+  /** Record that a wave is about to apply under an approval (#3784), which spends it. */
+  appendApplied?(record: AppliedGateRecord): Promise<{ pushed: boolean; pushWarning?: string }>;
 }
 
 /** A workspace's rule for which approvals of a gate count (#3163): a signed approval, from a class when it names one. */
@@ -140,20 +145,56 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { record } = await appendPendingGate(input, opts);
       return { record, ...(await pushLifecycleReport(opts)) };
     },
+    async readApplied(op) {
+      await requireLifecycleLedger(opts);
+      const { dir, file } = appliedGatePath(op);
+      const text = await readBlobFromPath(dir, file, opts);
+      return text ? parseAppliedGateLines(text) : [];
+    },
+    async appendApplied(record) {
+      const { dir, file } = appliedGatePath(record.op);
+      const line = JSON.stringify(record, sortedJsonReplacer);
+      let lastErr: unknown;
+      // The same append-and-retry as a ledger line: another writer to the branch is the ordinary case.
+      for (let attempt = 1; attempt <= 5; attempt++) {
+        try {
+          const prior = await readPathSha(dir, file, opts);
+          const existing = prior ? await readBlobBySha(prior, opts) : null;
+          await writeBlobToPath(dir, file, existing ? `${existing.replace(/\n$/, "")}\n${line}\n` : `${line}\n`, `Applied under ${record.gate}`, {
+            ...opts,
+            expectPriorPathSha: prior,
+          });
+          return pushLifecycleReport(opts);
+        } catch (err) {
+          if (!(err instanceof RefCASConflictError)) throw err;
+          lastErr = err;
+        }
+      }
+      throw lastErr;
+    },
   };
 }
 
 /** A gate ledger held in memory — what a test, or a caller that has already read the ledger, hands {@link evaluateGate}. */
 export function memoryGateLedgerPort(
-  seed: { resolutions?: GateResolutionRecord[]; pending?: PendingGateRecord[] } = {},
-): GateLedgerPort & { appended: PendingGateRecord[]; resolved: GateResolutionRecord[] } {
+  seed: { resolutions?: GateResolutionRecord[]; pending?: PendingGateRecord[]; applied?: AppliedGateRecord[] } = {},
+): GateLedgerPort & { appended: PendingGateRecord[]; resolved: GateResolutionRecord[]; applied: AppliedGateRecord[] } {
   const resolutions = [...(seed.resolutions ?? [])];
   const pending = [...(seed.pending ?? [])];
   const appended: PendingGateRecord[] = [];
   const resolved: GateResolutionRecord[] = [];
+  const applied: AppliedGateRecord[] = [...(seed.applied ?? [])];
   return {
     appended,
     resolved,
+    applied,
+    async readApplied(op) {
+      return applied.filter((a) => a.op === op);
+    },
+    async appendApplied(record) {
+      applied.push(record);
+      return { pushed: true };
+    },
     async read() {
       return { resolutions: [...resolutions], pending: [...pending] };
     },
@@ -213,6 +254,12 @@ export interface GateCheckInput {
   approval?: ResolvedGateApproval;
   /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
   now?: string;
+  /**
+   * The approvals a wave already applied under (#3784). Given, an approval
+   * one of them spent counts for nothing: it neither satisfies the gate nor
+   * stands as a mismatch. Absent, nothing is spent.
+   */
+  spent?: readonly AppliedGateRecord[];
 }
 
 /**
@@ -314,7 +361,7 @@ export interface GateTally {
   counted: GateResolutionRecord[];
   /** The quorum's count, 1 when the gate declares none. */
   need: number;
-  /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, only for a permit recorded under `enforce`, and only under the gate's current policy version. */
+  /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, only for a permit recorded under `enforce`, and only under the gate's current policy version and resolved context. */
   permit?: GateResolutionRecord;
   /** The newest approval of this gate for a different plan, when the gate binds one. */
   mismatched?: GateResolutionRecord;
@@ -326,13 +373,17 @@ export interface GateTally {
  * An approval counts only if it is newer than `sinceIso` (the standing pending
  * fact) and, on a plan-bound gate, recorded for `planDigest`. So a changed
  * plan invalidates every approval collected for the old one, the rule #2300
- * set for a single approval.
+ * set for a single approval. A human's approval may be older than the
+ * standing fact, back to `humansSinceIso` ({@link humanQuorumSince}), so a
+ * pending fact re-recorded for a changed mode or context keeps a partly
+ * filled quorum (#3206). It defaults to `sinceIso`.
  *
  * Of those, only a human's counts toward the quorum, once per `resolvedBy`,
  * and only with one of the quorum's roles when it names any. An agent counts
  * only through a recorded `allow` in `enforce` mode, evaluated under the
- * policy version the gate declares now and recorded while the gate was in
- * `enforce` (#2512). A `log-only` decision never changes the outcome, even
+ * policy version the gate declares now, recorded while the gate was in
+ * `enforce` (#2512), and evaluated under the context the gate resolves now
+ * (#3774). A `log-only` decision never changes the outcome, even
  * after the gate switches to `enforce`, and a `deny` never removes a human's approval: a policy can add
  * a way through the gate but cannot take one away.
  */
@@ -342,29 +393,38 @@ export function tallyGateApprovals(
   sinceIso: string,
   planDigest: string | undefined,
   approval: ResolvedGateApproval,
+  humansSinceIso: string = sinceIso,
 ): GateTally {
   const since = new Date(sinceIso).getTime();
+  const humansSince = Math.min(since, new Date(humansSinceIso).getTime());
   const at = (r: GateResolutionRecord) => new Date(r.timestamp).getTime();
   const roles = approval.quorum?.roles;
+  const context = gateContextDigest(approval.context);
 
   const byActor = new Map<string, GateResolutionRecord>();
   let permit: GateResolutionRecord | undefined;
   let mismatched: GateResolutionRecord | undefined;
   for (const r of records) {
-    if (r.gate !== gate || at(r) < since) continue;
+    if (r.gate !== gate || at(r) < humansSince) continue;
     if (planDigest !== undefined && !samePlanDigest(r.planDigest, planDigest)) {
-      if (!mismatched || at(r) >= at(mismatched)) mismatched = r;
+      if (at(r) >= since && (!mismatched || at(r) >= at(mismatched))) mismatched = r;
       continue;
     }
 
     const decision = r.policyDecision;
+    // #3206: an approval from before the standing fact can only be a human's
+    // toward the quorum. A permit is anchored on the standing fact, the one
+    // `chant approve` evaluated it under.
+    const sinceStanding = at(r) >= since;
     // #2512: the decision must also have been recorded under `enforce`. An
     // allow recorded while the gate was log-only was never binding, and a
-    // later switch to enforce does not make it binding.
+    // later switch to enforce does not make it binding. #3774: and under
+    // the context this run resolved, since the run checks approvals before it
+    // re-records the pending fact for a changed context.
     if (
-      approval.mode === "enforce" && approval.policy && decision?.decision === "allow" &&
-      decision.mode === "enforce" &&
-      decision.version === approval.policy.version && (!permit || at(r) >= at(permit))
+      sinceStanding && approval.mode === "enforce" && approval.policy && decision?.decision === "allow" &&
+      decision.mode === "enforce" && decision.version === approval.policy.version &&
+      decision.contextDigest === context && (!permit || at(r) >= at(permit))
     ) {
       permit = r;
     }
@@ -385,6 +445,38 @@ export function tallyGateApprovals(
   };
 }
 
+/**
+ * Where a gate's human quorum starts counting (#3206): the oldest pending fact
+ * in the unbroken run of facts, newest first from `standing`, recorded for
+ * `standing`'s plan and policy version.
+ *
+ * A pending fact is re-recorded when anything in the approval block changes,
+ * the mode and the context included, so `chant approve` evaluates the policy
+ * under what the gate now declares. A human's approval counts for the plan
+ * it names whatever the mode or context was, so re-recording for one of
+ * those must not drop it. The run stops at a fact for another plan or policy
+ * version, which needs fresh approvals, and at one that had expired by the
+ * time the next was recorded, which expiry already closed.
+ *
+ * `pending` may hold every pending fact in the ledger; only `standing`'s gate
+ * and environment are read.
+ */
+export function humanQuorumSince(pending: readonly PendingGateRecord[], standing: PendingGateRecord): string {
+  const at = (p: PendingGateRecord) => new Date(p.timestamp).getTime();
+  const version = (p: PendingGateRecord) => p.approval?.policy?.version;
+  const sameKey = (p: PendingGateRecord) =>
+    samePlanDigest(p.planDigest, standing.planDigest) && version(p) === version(standing);
+  const older = pending
+    .filter((p) => p !== standing && p.gate === standing.gate && p.environment === standing.environment && at(p) <= at(standing))
+    .sort((a, b) => at(b) - at(a));
+  let anchor = standing;
+  for (const p of older) {
+    if (!sameKey(p) || isPendingGateExpired(p, anchor.timestamp)) break;
+    anchor = p;
+  }
+  return anchor.timestamp;
+}
+
 /** Whether two resolved approval blocks are the same, so a standing pending fact still describes this gate. */
 function sameApproval(a: ResolvedGateApproval | undefined, b: ResolvedGateApproval | undefined): boolean {
   return JSON.stringify(a ?? null, sortedJsonReplacer) === JSON.stringify(b ?? null, sortedJsonReplacer);
@@ -431,7 +523,9 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
     env === undefined
       ? ledger.resolutions
       : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)
-  ).filter((r) => rule === null || r.gate !== input.gate || rule.refuses(r) === null);
+  )
+    .filter((r) => rule === null || r.gate !== input.gate || rule.refuses(r) === null)
+    .filter((r) => input.spent === undefined || r.gate !== input.gate || !isApprovalSpent(input.spent, r));
 
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;
@@ -439,7 +533,14 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   let mismatched: GateResolutionRecord | undefined;
   let quorum: GateQuorumProgress | undefined;
   if (input.approval) {
-    const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval);
+    // #3206: the humans' anchor reaches back past facts re-recorded for this
+    // plan and policy version, so a mode or context change keeps the quorum.
+    const humansSince =
+      standing && samePlanDigest(standing.planDigest, input.planDigest) &&
+      standing.approval?.policy?.version === input.approval.policy?.version
+        ? humanQuorumSince(pending, standing)
+        : since;
+    const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval, humansSince);
     if (tally.permit) {
       return { satisfied: true, resolution: tally.permit, via: "policy", approvals: tally.counted };
     }

package/src/op/index.ts

@@ -54,14 +54,29 @@ export type { GenerateOpsPipelineResult, GenerateOpWavesPipelineResult } from ".
 export {
   OP_WAVE_DEFAULT_APPLY,
   OP_WAVE_GATE_POLICIES,
+  OP_WAVE_HOOK_MOMENTS,
+  assertOpWaveHooks,
   assertOpWavesSpec,
+  opWaveHooksAt,
   opWaveJobs,
   opWaveRecordPath,
   opWaveShare,
 } from "./op-waves";
-export type { OpWave, OpWaveGatePolicy, OpWaveJob, OpWaveRun, OpWavesSpec } from "./op-waves";
-export { opWaveNeedsApproval, parseOpWavesSpec, readOpWavePolicy, runOpWave } from "./op-waves-run";
-export type { OpWaveDecision, OpWaveMember, OpWavePlanFile, RunOpWaveOptions, RunOpWaveResult } from "./op-waves-run";
+export type { OpWave, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesSpec } from "./op-waves";
+export { opWaveNeedsApproval, opWavePlansPath, opWaveRunsPath, parseOpWavesSpec, readOpWavePolicy, runOpWave } from "./op-waves-run";
+export type {
+  OpWaveBaseRules,
+  OpWaveDecision,
+  OpWaveHookOutcome,
+  OpWaveMember,
+  OpWavePlanFile,
+  OpWavePlansFile,
+  OpWaveRunsFile,
+  RunOpWaveOptions,
+  RunOpWaveResult,
+} from "./op-waves-run";
+export { notifyOpWave, opWaveNotifyFields } from "./op-waves-notify";
+export type { OpWaveOutcome } from "./op-waves-notify";
 export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry";
 export type { ActivityFn } from "./activity-registry";
 export { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry";
@@ -75,9 +90,9 @@ export { currentOpRun, withOpRunContext } from "./run-context";
 export type { OpRunContext, PassedGate } from "./run-context";
 export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch, gateIsSealed } from "./gate";
 export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch, GateQuorumProgress, GateTally } from "./gate";
-export { tallyGateApprovals, approverOf } from "./gate";
+export { tallyGateApprovals, humanQuorumSince, approverOf } from "./gate";
 export {
-  gateApprovalProblems, gatePolicyRequest, gatePolicyVersion, isGatePolicyRef, loadGatePolicyEvaluator, GATE_APPROVAL_MODES,
+  gateApprovalProblems, gateContextDigest, gatePolicyRequest, gatePolicyVersion, isGatePolicyRef, loadGatePolicyEvaluator, GATE_APPROVAL_MODES,
 } from "./gate-approval";
 export type {
   GateApproval, GateApprovalMode, GateApprover, GateContextValue, GatePolicyAnswer, GatePolicyDecision,

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

@@ -0,0 +1,127 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { verifyWebhook, type NotifyEvent, type NotifyFetch } from "../notify";
+import { memoryGateLedgerPort } from "./gate";
+import { assertOpWavesSpec, type OpWavesSpec } from "./op-waves";
+import { notifyOpWave, opWaveNotifyFields } from "./op-waves-notify";
+import { runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+
+const spec: OpWavesSpec = {
+  name: "migrations",
+  op: "migrate",
+  plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+  apply: ["tool", "apply", "{target}", "--plan", "{plan}"],
+  waves: [
+    { name: "dev", runs: [{ target: "dev" }], gate: "never" },
+    { name: "prod", runs: [{ target: "t2" }, { target: "t1" }], shares: 2 },
+  ],
+  notify: { webhook: "CHANT_WEBHOOK", key: "CHANT_WEBHOOK_KEY", slack: "CHANT_SLACK_WEBHOOK" },
+};
+const env = { CHANT_WEBHOOK: "https://hooks.example/chant", CHANT_WEBHOOK_KEY: "k", CHANT_SLACK_WEBHOOK: "https://hooks.slack.com/services/x", GITHUB_SERVER_URL: "https://github.com", GITHUB_REPOSITORY: "acme/db", GITHUB_RUN_ID: "7" };
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+function harness(plans: Record<string, { planDigest: string }>, failApply = false) {
+  const cwd = mkdtempSync(join(tmpdir(), "op-waves-notify-"));
+  const exec: OpWaveExec = (argv, dir) => {
+    if (argv[1] === "plan") writeFileSync(join(dir, argv[4]!), JSON.stringify(plans[argv[2]!]));
+    return argv[1] === "apply" && failApply ? 2 : 0;
+  };
+  const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec) });
+  return { cwd, exec, show, done: () => rmSync(cwd, { recursive: true, force: true }) };
+}
+
+function recorder(status = 200) {
+  const calls: Array<{ url: string; headers: Record<string, string>; body: string }> = [];
+  const fetch: NotifyFetch = async (url, init) => {
+    calls.push({ url, headers: init.headers, body: init.body });
+    return { ok: status < 300, status };
+  };
+  return { calls, fetch };
+}
+
+describe("an Op waves job's notify", () => {
+  test("a waiting wave sends the approve command, the digest, the targets and the run, signed", async () => {
+    const h = harness({ t1: { planDigest: digest("1") }, t2: { planDigest: digest("2") } });
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 2, decide: true, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} });
+    h.done();
+    expect(result.exitCode).toBe(3);
+    const { calls, fetch } = recorder();
+    const out = await notifyOpWave(spec, 2, { result }, {}, { env, fetch, sleep: async () => {}, log: () => {} });
+    expect(out.map((d) => d.ok)).toEqual([true, true]);
+    const event = JSON.parse(calls[0]!.body) as NotifyEvent;
+    expect(event).toMatchObject({
+      schema: "chant.notify/v1",
+      source: "chant",
+      event: "waiting",
+      project: "acme/db",
+      summary: "wave 2 (prod) of migrations waits for an approval",
+      wave: { number: 2, name: "prod", gate: "migrations-wave-2" },
+      targets: ["t2", "t1"],
+      digest: result.decision!.digest,
+      approve: { command: result.decision!.approve },
+      exitCode: 3,
+      run: { url: "https://github.com/acme/db/actions/runs/7" },
+    });
+    expect(event.approve!.command).toMatch(/^chant approve migrations migrations-wave-2 --plan (jcs1-)?sha256:/);
+    expect(verifyWebhook({ body: calls[0]!.body, headers: calls[0]!.headers, key: "k" }).ok).toBe(true);
+    expect(JSON.parse(calls[1]!.body).text).toContain("Approve: `chant approve migrations migrations-wave-2");
+  });
+
+  test("a share job of a waiting wave sends nothing; its deciding job did", () => {
+    const decision = { wave: 2, name: "prod", op: "migrations", gate: "migrations-wave-2", policy: "always" as const, approval: "ledger" as const, policySource: "base" as const, base: "b", digest: digest("d"), members: [], status: "waiting" as const };
+    expect(opWaveNotifyFields(spec, 2, { result: { exitCode: 3, decision, applied: [], failed: [], moved: [], hooks: [] } }, { share: 1 })).toBeUndefined();
+    expect(opWaveNotifyFields(spec, 2, { result: { exitCode: 0, applied: ["t1"], failed: [], moved: [], hooks: [] } })).toBeUndefined();
+  });
+
+  test("a share job held by its own hook sends waiting, and a failed hook is named (#3762)", () => {
+    const decision = { wave: 2, name: "prod", op: "migrations", gate: "migrations-wave-2", policy: "always" as const, approval: "ledger" as const, policySource: "base" as const, base: "b", digest: digest("d"), members: [], status: "waiting" as const, heldBy: ["smoke"], approve: "chant approve migrations migrations-wave-2 --plan x" };
+    const held = { moment: "before-apply" as const, name: "smoke", exit: 2, outcome: "held" as const };
+    expect(opWaveNotifyFields(spec, 2, { result: { exitCode: 3, decision, applied: [], failed: [], moved: [], hooks: [held] } }, { share: 1 })).toMatchObject({ event: "waiting", reason: "held by smoke" });
+    const broke = { moment: "after-apply" as const, name: "verify", exit: 1, outcome: "failed" as const };
+    expect(opWaveNotifyFields(spec, 1, { result: { exitCode: 1, applied: ["dev"], failed: [], moved: [], hooks: [broke] } })).toMatchObject({
+      event: "failed",
+      summary: "wave 1 (dev) of migrations failed: after-apply hook verify failed",
+    });
+  });
+
+  test("a share that refused a moved plan sends refused, and a failed apply sends failed", () => {
+    expect(opWaveNotifyFields(spec, 2, { result: { exitCode: 4, applied: ["t1"], failed: [], moved: ["t2"], hooks: [] } }, { share: 1 })).toMatchObject({
+      event: "refused",
+      summary: "wave 2 (prod) of migrations, share 1, refused 1 run whose plan moved since the wave was decided",
+      targets: ["t2"],
+      exitCode: 4,
+    });
+    expect(opWaveNotifyFields(spec, 1, { result: { exitCode: 1, applied: [], failed: ["dev"], moved: [], hooks: [] } })).toMatchObject({
+      event: "failed",
+      summary: "wave 1 (dev) of migrations failed: dev did not apply",
+      targets: ["dev"],
+    });
+    expect(opWaveNotifyFields(spec, 1, { error: "planning dev exited 2" })).toMatchObject({ event: "failed", reason: "planning dev exited 2", exitCode: 1 });
+  });
+
+  test("a failed apply's exit code stays 1 when every delivery fails", async () => {
+    const h = harness({ dev: { planDigest: digest("1") } }, true);
+    const result = await runOpWave({ spec, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: h.show, gates: memoryGateLedgerPort(), log: () => {} });
+    h.done();
+    const { fetch } = recorder(500);
+    const lines: string[] = [];
+    const out = await notifyOpWave(spec, 1, { result }, {}, { env, fetch, sleep: async () => {}, log: (l) => lines.push(l) });
+    expect(result.exitCode).toBe(1);
+    expect(out.every((d) => !d.ok)).toBe(true);
+    expect(lines).toEqual([
+      "notify: the failed event was not delivered to the webhook: HTTP 500",
+      "notify: the failed event was not delivered to Slack: HTTP 500",
+    ]);
+  });
+
+  test("the spec refuses a URL where a variable name goes, and such a spec sends nothing", async () => {
+    const bad = { ...spec, notify: { slack: "https://hooks.slack.com/services/x" } };
+    expect(() => assertOpWavesSpec(bad)).toThrow(/Op waves "migrations": notify\.slack: the name of the environment variable/);
+    const { calls, fetch } = recorder();
+    expect(await notifyOpWave(bad, 1, { error: "x" }, {}, { env, fetch })).toEqual([]);
+    expect(calls).toEqual([]);
+    expect(await notifyOpWave({ ...spec, notify: undefined }, 1, { error: "x" }, {}, { env, fetch })).toEqual([]);
+  });
+});

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

@@ -0,0 +1,101 @@
+/**
+ * What an Op waves job tells people (#3761), when the spec has `notify`.
+ *
+ * A wave that waits for an approval (exit 3) sends `waiting` with the
+ * 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
+ * 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.
+ */
+
+import { makeNotifyEvent, notifyConfigProblem, sendNotify, type NotifyDelivery, type NotifyFields, type SendNotifyOptions } from "../notify";
+import type { OpWavesSpec } from "./op-waves";
+import type { RunOpWaveResult } from "./op-waves-run";
+
+/** How the job ended: the wave's result, or the error that stopped it. */
+export type OpWaveOutcome = { result: RunOpWaveResult; error?: undefined } | { result?: undefined; error: string };
+
+/** The event a wave job sends, or undefined when it sends none. */
+export function opWaveNotifyFields(spec: OpWavesSpec, k: number, outcome: OpWaveOutcome, job: { share?: number } = {}): NotifyFields | undefined {
+  const wave = spec.waves[k - 1];
+  const name = wave?.name;
+  const label = `wave ${k}${name ? ` (${name})` : ""} of ${spec.name}`;
+  if (outcome.error !== undefined) {
+    return { source: "chant", event: "failed", summary: `${label} failed`, wave: { number: k, ...(name ? { name } : {}) }, targets: [], reason: outcome.error, exitCode: 1 };
+  }
+  const { result } = outcome;
+  const decision = result.decision;
+  const base = {
+    source: "chant",
+    wave: { number: k, ...(name ? { name } : {}), ...(decision?.gate ? { gate: decision.gate } : {}) },
+    ...(decision?.digest ? { digest: decision.digest } : {}),
+    exitCode: result.exitCode,
+  };
+  if (result.exitCode === 3) {
+    if (!decision) return undefined;
+    // A share job's wait was announced by its deciding job, unless a hook in this job held it (#3762).
+    const heldHere = result.hooks.filter((h) => h.outcome === "held");
+    if (job.share !== undefined && heldHere.length === 0) return undefined;
+    const review = decision.review?.pr !== undefined && decision.review.url ? { review: { pr: decision.review.pr, url: decision.review.url } } : {};
+    return {
+      ...base,
+      event: "waiting",
+      status: "waiting",
+      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
+        ? { reason: `held by ${decision.heldBy.join(", ")}` }
+        : decision.review?.reason
+          ? { reason: decision.review.reason }
+          : {}),
+    };
+  }
+  if (result.exitCode === 4) {
+    return {
+      ...base,
+      event: "refused",
+      status: "moved",
+      summary: `${label}${job.share !== undefined ? `, share ${job.share},` : ""} refused ${result.moved.length} run${result.moved.length === 1 ? "" : "s"} whose plan moved since the wave was decided`,
+      targets: result.moved,
+      reason: "their plans moved since the wave was decided, so they were not applied",
+    };
+  }
+  if (result.exitCode !== 0) {
+    const hooks = result.hooks.filter((h) => h.outcome === "failed").map((h) => `${h.moment} hook ${h.name}${h.target ? ` (${h.target})` : ""}`);
+    if (result.failed.length === 0 && hooks.length > 0) {
+      return { ...base, event: "failed", status: "failed", summary: `${label} failed: ${hooks.join(", ")} failed`, targets: [], reason: `${hooks.join(", ")} exited non-zero` };
+    }
+    return {
+      ...base,
+      event: "failed",
+      status: "failed",
+      summary: `${label} failed: ${result.failed.length > 0 ? `${result.failed.join(", ")} did not apply` : `exit ${result.exitCode}`}`,
+      targets: result.failed,
+      ...(result.failed.length > 0 ? { reason: `the apply command failed for ${result.failed.join(", ")}` } : {}),
+    };
+  }
+  return undefined;
+}
+
+/** Send what the job's outcome calls for to what `spec.notify` names. Never throws. */
+export async function notifyOpWave(
+  spec: OpWavesSpec,
+  k: number,
+  outcome: OpWaveOutcome,
+  job: { share?: number } = {},
+  options: SendNotifyOptions = {},
+): Promise<NotifyDelivery[]> {
+  // A spec whose notify the run refused (it may name a URL in place of a variable) sends nothing.
+  if (!spec.notify || notifyConfigProblem(spec.notify) !== undefined) return [];
+  try {
+    const fields = opWaveNotifyFields(spec, k, outcome, job);
+    if (!fields) return [];
+    return await sendNotify(spec.notify, makeNotifyEvent(fields, { ...(options.env ? { env: options.env } : {}) }), options);
+  } catch (e) {
+    (options.log ?? ((line: string) => process.stderr.write(line + "\n")))(`notify: nothing was sent: ${e instanceof Error ? e.message : String(e)}`);
+    return [];
+  }
+}