@intentius/chant 0.124.4 → 0.124.6

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

@@ -0,0 +1,203 @@
+/**
+ * #3835: an answered decision point resumes the job waiting on it. A gate
+ * that asks a point writes its resolution only when the run asks again, so
+ * `chant run resume` used to see no approval and leave the job stopped. Now a
+ * pending fact that cites a question is resumable once the question has an
+ * answer the gate passes on, and `points answer --resume` resumes right after
+ * the answer.
+ *
+ * Clones of one bare remote stand for the CI job's checkout, the person's
+ * clone the answer comes from, the scheduled resume job's checkout and the
+ * resumed job's. The gate ledger is the real one on `chant/lifecycle`, so the
+ * pending fact, the question and its answer all travel through the remote.
+ * The forge is a stubbed `fetch` that answers as GitHub does for a failed run.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test, vi } from "vitest";
+import { cleanScratch, workspace } from "../workspace/__fixtures__/decide-workspace";
+import { runWorkspacePoints } from "../workspace/points-cli";
+import { runResumeCommand } from "../cli/handlers/gate-resume";
+import type { CommandContext } from "../cli/registry";
+import { readGateLedger } from "../lifecycle/gate-ledger";
+import { pointGateResumable } from "../point-decision";
+import { ApplyOp } from "./composites/apply-op";
+import { gitGateLedgerPort } from "./gate";
+import 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:${"6".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 }],
+    },
+  },
+};
+
+const GITHUB = { GITHUB_ACTIONS: "true", GITHUB_REPOSITORY: "acme/infra", GITHUB_RUN_ID: "42", GITHUB_RUN_ATTEMPT: "1", GITHUB_API_URL: "https://api.github.test" };
+
+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: 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;
+let n = 0;
+
+function clone(): string {
+  const dir = join(home, `clone-${++n}`);
+  execFileSync("git", ["clone", "-q", remote, dir], { stdio: "ignore" });
+  return dir;
+}
+
+/** A wave's run in `cwd`, on the real gate ledger. */
+const run = (op: OpConfig, cwd: string) => runOpLocally(op, activities, {}, undefined, { gates: gitGateLedgerPort({ cwd }), cwd, now: new Date().toISOString() });
+
+/** Run a command handler in `cwd`; returns what it printed on standard output, parsed, and its exit code. */
+async function inDir<T>(cwd: string, handler: (ctx: CommandContext) => Promise<number>, args: Record<string, unknown>): Promise<{ code: number; doc: T }> {
+  const printed: string[] = [];
+  const log = vi.spyOn(console, "log").mockImplementation((line: unknown) => {
+    printed.push(String(line));
+  });
+  const err = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  const was = process.cwd();
+  process.chdir(cwd);
+  try {
+    const code = await handler({ args, plugins: [], serializers: [] } as unknown as CommandContext);
+    return { code, doc: JSON.parse(printed.join("\n")) as T };
+  } finally {
+    process.chdir(was);
+    log.mockRestore();
+    err.mockRestore();
+  }
+}
+
+/** The forge: a GitHub run that ended in failure (the job exited 3 at the gate). Records each call. */
+let calls: string[];
+function stubForge(): void {
+  calls = [];
+  vi.stubGlobal("fetch", async (url: string, init: { method: string }) => {
+    calls.push(`${init.method} ${new URL(url).pathname}`);
+    const body = init.method === "GET" ? JSON.stringify({ status: "completed", conclusion: "failure", run_attempt: 1 }) : "";
+    return { ok: true, status: 200, text: async () => body };
+  });
+}
+
+type Report = { op: string; gate: string; status: string; message: string; approvedBy?: string };
+
+/** The job waits at the gate in CI; returns the question's id. */
+async function waitInCi(op: OpConfig): Promise<string> {
+  for (const [k, v] of Object.entries(GITHUB)) vi.stubEnv(k, v);
+  const first = await run(op, clone());
+  expect(first.status).toBe("waiting");
+  for (const k of Object.keys(GITHUB)) vi.stubEnv(k, "");
+  return first.point!.id;
+}
+
+const answer = (id: string, value: string, extra: Record<string, unknown> = {}) =>
+  inDir<Record<string, unknown>>(clone(), runWorkspacePoints, { extraPositional: "answer", extraPositional2: id, answer: value, bys: ["alice"], ...extra });
+
+beforeAll(() => {
+  home = realpathSync(mkdtempSync(join(tmpdir(), "chant-gate-point-resume-")));
+  const root = workspace(POINTS);
+  remote = join(home, "remote.git");
+  execFileSync("git", ["clone", "-q", "--bare", root, remote], { stdio: "ignore" });
+});
+
+beforeEach(() => {
+  vi.stubEnv("CI", "");
+  vi.stubEnv("GITHUB_TOKEN", "t");
+  stubForge();
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+afterAll(() => {
+  cleanScratch();
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("an answered decision point resumes the wave waiting on it (#3835)", () => {
+  test("the wave waits on its point; the point is answered; chant run resume resumes it, and the resumed run passes", async () => {
+    const op = config("resume-apply", { name: "prod-apply", store: "ledger" });
+    const id = await waitInCi(op);
+
+    // Before the answer, nothing is resumed.
+    const before = await inDir<{ reports: Report[] }>(clone(), runResumeCommand, { op: "resume-apply", json: true });
+    expect(before.doc.reports).toEqual([expect.objectContaining({ gate: "approve-apply", status: "not-approved", message: expect.stringContaining("not answered yet") })]);
+    expect(calls).toEqual([]);
+
+    expect((await answer(id, "yes")).doc).toMatchObject({ written: true, question: { state: "answered", answer: true } });
+
+    // The scheduled resume job, in its own checkout.
+    const resumed = await inDir<{ reports: Report[] }>(clone(), runResumeCommand, { op: "resume-apply", json: true });
+    expect(resumed.code).toBe(0);
+    expect(resumed.doc.reports).toEqual([expect.objectContaining({ gate: "approve-apply", status: "resumed", approvedBy: "alice" })]);
+    expect(calls).toEqual(["GET /repos/acme/infra/actions/runs/42", "POST /repos/acme/infra/actions/runs/42/rerun-failed-jobs"]);
+
+    // The resumed job asks again, finds the answer, writes the resolution that cites it, and applies.
+    const job = clone();
+    const next = await run(op, job);
+    expect(next.status).toBe("ok");
+    expect(applied).toContain(PLAN);
+    const ledger = await readGateLedger("resume-apply", { cwd: job });
+    expect(ledger.resolutions).toEqual([expect.objectContaining({ gate: "approve-apply", resolvedBy: "alice", answer: expect.objectContaining({ id, answer: true }) })]);
+  }, 120_000);
+
+  test("an answer that does not pass the gate resumes nothing", async () => {
+    const op = config("refuse-apply", { name: "prod-apply", store: "ledger" });
+    const id = await waitInCi(op);
+    await answer(id, "no");
+
+    const resumed = await inDir<{ reports: Report[] }>(clone(), runResumeCommand, { op: "refuse-apply", json: true });
+    expect(resumed.code).toBe(0);
+    expect(resumed.doc.reports).toEqual([expect.objectContaining({ status: "not-approved", message: expect.stringContaining("passes only on true") })]);
+    expect(calls).toEqual([]);
+  }, 120_000);
+
+  test("a gate's own pass list is on the pending fact: an answer it names resumes, others don't", async () => {
+    const op = config("pass-apply", { name: "prod-apply", store: "ledger", pass: [false] });
+    const id = await waitInCi(op);
+    const { pending } = await gitGateLedgerPort({ cwd: clone() }).read("pass-apply");
+    expect(pending[0]!.answer).toMatchObject({ id, pass: [false] });
+    expect(pending[0]!.resume).toMatchObject({ forge: "github", run: "42" });
+
+    const answered = { id, state: "answered" as const, answeredBy: ["alice"], answeredOn: null };
+    expect(pointGateResumable(pending[0]!, { ...answered, answer: false })).toMatchObject({ resumable: true, answeredBy: "alice" });
+    expect(pointGateResumable(pending[0]!, { ...answered, answer: true })).toMatchObject({ resumable: false, why: "refused" });
+    expect(pointGateResumable(pending[0]!, { ...answered, state: "escalated", answer: null })).toMatchObject({ resumable: false, why: "open" });
+    expect(pointGateResumable(pending[0]!, undefined)).toMatchObject({ resumable: false, why: "unknown" });
+  }, 120_000);
+
+  test("points answer --resume resumes the job waiting at the gate the question names", async () => {
+    const op = config("answer-resume-apply", { name: "prod-apply", store: "ledger" });
+    const id = await waitInCi(op);
+
+    const answered = await answer(id, "yes", { resumeRun: true });
+    expect(answered.code).toBe(0);
+    expect(answered.doc).toMatchObject({ written: true, question: { state: "answered", subject: "gate:answer-resume-apply/approve-apply" } });
+    expect(calls).toEqual(["GET /repos/acme/infra/actions/runs/42", "POST /repos/acme/infra/actions/runs/42/rerun-failed-jobs"]);
+  }, 120_000);
+});

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

@@ -32,7 +32,10 @@ import type { GatePointAsker } from "../point-decision";
 // The decision itself bundles without the workspace (#3816): `@intentius/chant/point-decision`.
 export {
   evaluatePointGate,
+  pointGateResumable,
   type GatePointAsker,
+  type PointQuestionState,
+  type PointResumeCheck,
   type GatePointQuestion,
   type GatePointRequest,
   type PointGateCheck,

package/src/op/gate-point.ts

@@ -141,3 +141,14 @@ export function gatePointInputs(point: string, declared: readonly string[], fact
 export function gateSubject(op: string, gate: string, env?: string | null): string {
   return `gate:${op}/${gate}${env ? `@${env}` : ""}`;
 }
+
+/** The gate a {@link gateSubject} names, or undefined for a subject that names none (#3835). */
+export function parseGateSubject(subject: string | null | undefined): { op: string; gate: string; env?: string } | undefined {
+  if (!subject || !subject.startsWith("gate:")) return undefined;
+  const rest = subject.slice("gate:".length);
+  const at = rest.lastIndexOf("@");
+  const named = at > 0 ? rest.slice(0, at) : rest;
+  const slash = named.indexOf("/");
+  if (slash <= 0 || slash === named.length - 1) return undefined;
+  return { op: named.slice(0, slash), gate: named.slice(slash + 1), ...(at > 0 ? { env: rest.slice(at + 1) } : {}) };
+}

package/src/op/gate-resume.ts

@@ -36,102 +36,10 @@ import { ForgeApiError, type ForgeFetch, type ForgeKind } from "../pr-forge";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { latestResolutionForPlan } from "../lifecycle/gate-ledger";
 import { humanQuorumSince, tallyGateApprovals } from "./gate";
+import type { GateRunLocator } from "./gate-run-locator";
 
-/** Where the job that recorded a pending fact runs, and what its forge needs to start it again. */
-export interface GateRunLocator {
-  forge: ForgeKind;
-  /** The forge's API base: `$GITHUB_API_URL` (GitHub and Forgejo) or `$CI_API_V4_URL` (GitLab). */
-  api: string;
-  /** `owner/name` on GitHub and Forgejo, the project id on GitLab. */
-  repo: string;
-  /** The run: GitHub's and Forgejo's run id, GitLab's pipeline id. */
-  run: string;
-  /** GitHub: the run attempt that waited. A later attempt means it was already re-run. */
-  attempt?: number;
-  /** GitLab: the job that waited. */
-  job?: string;
-  /** GitLab: that job's name, to find a retry of it. */
-  jobName?: string;
-  /** Forgejo: the workflow file the run came from, which a dispatch names. */
-  workflow?: string;
-  /** Forgejo: the branch a dispatch runs on. */
-  ref?: string;
-  /** The run's page, for a person. */
-  url?: string;
-}
-
-const trimSlash = (s: string): string => s.replace(/\/+$/, "");
-
-/**
- * The locator of the CI job this process runs in, or undefined outside CI or
- * when the environment lacks a part a resume needs. Forgejo Actions sets the
- * `GITHUB_*` variables too, and is told apart by `FORGEJO_ACTIONS` or
- * `GITEA_ACTIONS`.
- */
-export function resolveGateRunLocator(env: Record<string, string | undefined> = process.env): GateRunLocator | undefined {
-  if (env.GITLAB_CI === "true") {
-    if (!env.CI_API_V4_URL || !env.CI_PROJECT_ID || !env.CI_PIPELINE_ID || !env.CI_JOB_ID) return undefined;
-    return {
-      forge: "gitlab",
-      api: trimSlash(env.CI_API_V4_URL),
-      repo: env.CI_PROJECT_ID,
-      run: env.CI_PIPELINE_ID,
-      job: env.CI_JOB_ID,
-      ...(env.CI_JOB_NAME ? { jobName: env.CI_JOB_NAME } : {}),
-      ...(env.CI_JOB_URL ? { url: env.CI_JOB_URL } : {}),
-    };
-  }
-  if (env.GITHUB_ACTIONS !== "true" || !env.GITHUB_REPOSITORY || !env.GITHUB_RUN_ID) return undefined;
-  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true";
-  const server = env.GITHUB_SERVER_URL ? trimSlash(env.GITHUB_SERVER_URL) : undefined;
-  const url = server ? `${server}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : undefined;
-  if (forgejo) {
-    const workflow = forgejoWorkflowFile(env);
-    const api = env.GITHUB_API_URL ?? (server ? `${server}/api/v1` : undefined);
-    if (!api || !workflow || !env.GITHUB_REF_NAME) return undefined;
-    return {
-      forge: "forgejo",
-      api: trimSlash(api),
-      repo: env.GITHUB_REPOSITORY,
-      run: env.GITHUB_RUN_ID,
-      workflow,
-      ref: env.GITHUB_REF_NAME,
-      ...(url ? { url } : {}),
-    };
-  }
-  const attempt = Number(env.GITHUB_RUN_ATTEMPT);
-  return {
-    forge: "github",
-    api: trimSlash(env.GITHUB_API_URL ?? "https://api.github.com"),
-    repo: env.GITHUB_REPOSITORY,
-    run: env.GITHUB_RUN_ID,
-    ...(Number.isInteger(attempt) && attempt > 0 ? { attempt } : {}),
-    ...(url ? { url } : {}),
-  };
-}
-
-/**
- * The workflow file a Forgejo run came from, by its base name. Forgejo names
- * a workflow by its file (`GITHUB_WORKFLOW`, `deploy.yml`); `GITHUB_WORKFLOW_REF`
- * (`owner/repo/.forgejo/workflows/deploy.yml@refs/heads/main`) says it too.
- */
-function forgejoWorkflowFile(env: Record<string, string | undefined>): string | undefined {
-  const fromRef = env.GITHUB_WORKFLOW_REF?.split("@")[0]?.split("/").pop();
-  if (fromRef && /\.ya?ml$/.test(fromRef)) return fromRef;
-  const name = env.GITHUB_WORKFLOW;
-  return name && /\.ya?ml$/.test(name) ? name.split("/").pop() : undefined;
-}
-
-/** Whether `value` is a {@link GateRunLocator} a resume can use. */
-export function isGateRunLocator(value: unknown): value is GateRunLocator {
-  if (!value || typeof value !== "object") return false;
-  const v = value as Record<string, unknown>;
-  if (typeof v.api !== "string" || typeof v.repo !== "string" || typeof v.run !== "string") return false;
-  if (v.forge === "github") return true;
-  if (v.forge === "gitlab") return typeof v.job === "string";
-  if (v.forge === "forgejo") return typeof v.workflow === "string" && typeof v.ref === "string";
-  return false;
-}
+// The locator is read where a pending fact is recorded, which `@intentius/chant/point-decision` does too, so it lives on its own (#3835).
+export { isGateRunLocator, resolveGateRunLocator, type GateRunLocator } from "./gate-run-locator";
 
 /** What {@link resumeGateRun} did. */
 export type GateResumeOutcome =
@@ -145,6 +53,8 @@ export interface ResumeGateRunOptions {
   fetch?: ForgeFetch;
 }
 
+const trimSlash = (s: string): string => s.replace(/\/+$/, "");
+
 const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
 
 function client(base: string, headers: Record<string, string>, fetchImpl: ForgeFetch) {

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

@@ -0,0 +1,105 @@
+/**
+ * Where a CI job that waits at a gate runs, and what its forge needs to start
+ * it again (#3683). Read from the job's environment when a pending fact is
+ * recorded; `./gate-resume.ts` uses it to resume the job. It imports nothing
+ * at run time, so `@intentius/chant/point-decision` records it on the pending
+ * fact of a gate that asks a decision point too (#3835).
+ */
+
+import type { ForgeKind } from "../pr-forge";
+
+/** Where the job that recorded a pending fact runs, and what its forge needs to start it again. */
+export interface GateRunLocator {
+  forge: ForgeKind;
+  /** The forge's API base: `$GITHUB_API_URL` (GitHub and Forgejo) or `$CI_API_V4_URL` (GitLab). */
+  api: string;
+  /** `owner/name` on GitHub and Forgejo, the project id on GitLab. */
+  repo: string;
+  /** The run: GitHub's and Forgejo's run id, GitLab's pipeline id. */
+  run: string;
+  /** GitHub: the run attempt that waited. A later attempt means it was already re-run. */
+  attempt?: number;
+  /** GitLab: the job that waited. */
+  job?: string;
+  /** GitLab: that job's name, to find a retry of it. */
+  jobName?: string;
+  /** Forgejo: the workflow file the run came from, which a dispatch names. */
+  workflow?: string;
+  /** Forgejo: the branch a dispatch runs on. */
+  ref?: string;
+  /** The run's page, for a person. */
+  url?: string;
+}
+
+const trimSlash = (s: string): string => s.replace(/\/+$/, "");
+
+/**
+ * The locator of the CI job this process runs in, or undefined outside CI or
+ * when the environment lacks a part a resume needs. Forgejo Actions sets the
+ * `GITHUB_*` variables too, and is told apart by `FORGEJO_ACTIONS` or
+ * `GITEA_ACTIONS`.
+ */
+export function resolveGateRunLocator(env: Record<string, string | undefined> = process.env): GateRunLocator | undefined {
+  if (env.GITLAB_CI === "true") {
+    if (!env.CI_API_V4_URL || !env.CI_PROJECT_ID || !env.CI_PIPELINE_ID || !env.CI_JOB_ID) return undefined;
+    return {
+      forge: "gitlab",
+      api: trimSlash(env.CI_API_V4_URL),
+      repo: env.CI_PROJECT_ID,
+      run: env.CI_PIPELINE_ID,
+      job: env.CI_JOB_ID,
+      ...(env.CI_JOB_NAME ? { jobName: env.CI_JOB_NAME } : {}),
+      ...(env.CI_JOB_URL ? { url: env.CI_JOB_URL } : {}),
+    };
+  }
+  if (env.GITHUB_ACTIONS !== "true" || !env.GITHUB_REPOSITORY || !env.GITHUB_RUN_ID) return undefined;
+  const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true";
+  const server = env.GITHUB_SERVER_URL ? trimSlash(env.GITHUB_SERVER_URL) : undefined;
+  const url = server ? `${server}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : undefined;
+  if (forgejo) {
+    const workflow = forgejoWorkflowFile(env);
+    const api = env.GITHUB_API_URL ?? (server ? `${server}/api/v1` : undefined);
+    if (!api || !workflow || !env.GITHUB_REF_NAME) return undefined;
+    return {
+      forge: "forgejo",
+      api: trimSlash(api),
+      repo: env.GITHUB_REPOSITORY,
+      run: env.GITHUB_RUN_ID,
+      workflow,
+      ref: env.GITHUB_REF_NAME,
+      ...(url ? { url } : {}),
+    };
+  }
+  const attempt = Number(env.GITHUB_RUN_ATTEMPT);
+  return {
+    forge: "github",
+    api: trimSlash(env.GITHUB_API_URL ?? "https://api.github.com"),
+    repo: env.GITHUB_REPOSITORY,
+    run: env.GITHUB_RUN_ID,
+    ...(Number.isInteger(attempt) && attempt > 0 ? { attempt } : {}),
+    ...(url ? { url } : {}),
+  };
+}
+
+/**
+ * The workflow file a Forgejo run came from, by its base name. Forgejo names
+ * a workflow by its file (`GITHUB_WORKFLOW`, `deploy.yml`); `GITHUB_WORKFLOW_REF`
+ * (`owner/repo/.forgejo/workflows/deploy.yml@refs/heads/main`) says it too.
+ */
+function forgejoWorkflowFile(env: Record<string, string | undefined>): string | undefined {
+  const fromRef = env.GITHUB_WORKFLOW_REF?.split("@")[0]?.split("/").pop();
+  if (fromRef && /\.ya?ml$/.test(fromRef)) return fromRef;
+  const name = env.GITHUB_WORKFLOW;
+  return name && /\.ya?ml$/.test(name) ? name.split("/").pop() : undefined;
+}
+
+/** Whether `value` is a {@link GateRunLocator} a resume can use. */
+export function isGateRunLocator(value: unknown): value is GateRunLocator {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.api !== "string" || typeof v.repo !== "string" || typeof v.run !== "string") return false;
+  if (v.forge === "github") return true;
+  if (v.forge === "gitlab") return typeof v.job === "string";
+  if (v.forge === "forgejo") return typeof v.workflow === "string" && typeof v.ref === "string";
+  return false;
+}

package/src/op/index.ts

@@ -68,6 +68,8 @@ export {
 } from "./op-waves";
 export type { OpWave, OpWaveApplyHooksRunner, OpWaveGatePolicy, OpWaveHook, OpWaveHookFailure, OpWaveHookMoment, OpWaveHooks, OpWaveJob, OpWaveRun, OpWavesDigest, OpWavesOverride, OpWavesSpec } from "./op-waves";
 export {
+  OP_WAVE_APPLY_OUTCOMES,
+  OP_WAVE_MAX_REPLANS,
   opWaveHooksAtBase,
   opWaveNeedsApproval,
   opWavePlansPath,
@@ -84,6 +86,7 @@ export type {
   OpWaveBaseRules,
   OpWaveDecision,
   OpWaveApplyHooksRun,
+  OpWaveApplyOutcome,
   OpWaveExec,
   OpWaveHeldOn,
   OpWaveHoldRequest,

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

@@ -6,7 +6,9 @@
  * 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 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
+ * `refused` with the runs it denied, and one whose apply was held by another
+ * run (exit 5) sends `refused` with status `held`; one that stood down for a
+ * newer run (exit 6) sends nothing. 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.
  */
@@ -70,6 +72,19 @@ export function opWaveNotifyFields(spec: OpWavesSpec, k: number, outcome: OpWave
           : "the policy denied these runs, and no override counts for them",
     };
   }
+  // #3821: an apply that stood down for a newer run is no news; one held by another run is refused.
+  if (result.exitCode === 6 && result.outcome?.outcome === "stood-down") return undefined;
+  if (result.exitCode === 5 && result.outcome?.outcome === "held") {
+    const holder = result.outcome.holder;
+    return {
+      ...base,
+      event: "refused",
+      status: "held",
+      summary: `${label} applied nothing: another run${holder ? ` (${holder.run})` : ""} holds what it changes`,
+      targets: decision?.members.map((m) => m.member) ?? [],
+      reason: result.outcome.reason ?? `another run${holder ? `, ${holder.run},` : ""} holds what the apply changes; apply again once it is done`,
+    };
+  }
   if (result.exitCode === 4) {
     return {
       ...base,