@intentius/chant 0.124.41 → 0.124.43

package/src/components/wave-plan.ts

@@ -27,11 +27,11 @@
  * `@<component>.publish.*`) resolves.
  */
 
-import { resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
+import { assertTargetsAccepted, resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { componentDeployInputs, type ComponentDeployInputs } from "./deploy-inputs";
 import { computePlanDigest } from "../lifecycle/plan-digest";
-import type { CapabilityRegistry, DeployContext, PlannedOutputs } from "./capability";
+import type { CapabilityPlan, CapabilityRegistry, DeployContext, PlannedOutputs } from "./capability";
 import type { WaveMember } from "../gated-waves";
 import type { ChangeSetPart } from "../change-set";
 
@@ -101,12 +101,13 @@ export async function planWaveComponent(
     const plans: Record<string, unknown> = {};
     const parts: ChangeSetPart[] = [];
     let outputs: PlannedOutputs | undefined;
+    assertTargetsAccepted(component, registry, ctx);
     for (const step of capabilitySteps(component.deploy)) {
       const capability = registry.resolve(step.kind);
       if (!capability.plan) continue;
       const { kind: _kind, ...rest } = step;
       const input = resolveStepInput(rest, {}, componentOutputs);
-      const planned = await capability.plan(planContext(ctx, rest, componentOutputs), input as never);
+      const planned = bindTargets(step.kind, ctx, await capability.plan(planContext(ctx, rest, componentOutputs), input as never));
       const member = { member: planned.member, planDigest: planned.planDigest };
       members.push(member);
       parts.push(planned.changeSet ?? emptyPart(member));
@@ -124,6 +125,7 @@ export async function planWaveComponent(
           component,
           ...(ctx.vars ? { vars: ctx.vars } : {}),
           inputs: read.inputs,
+          ...(ctx.targets ? { targets: ctx.targets } : {}),
         }),
       };
       members.push(member);
@@ -145,6 +147,39 @@ export async function planWaveComponent(
   }
 }
 
+/**
+ * A member's digest with its targets in it (#4300), the way terragucci's
+ * cone plan digest binds a cone: the digest over the plan's own digest and
+ * the sorted targets, so an approval of one narrowing covers no other.
+ */
+export function targetedPlanDigest(planDigest: string, targets: readonly string[]): string {
+  return computePlanDigest("capability-targets", { plan: planDigest, targets: [...new Set(targets)].sort() });
+}
+
+/**
+ * A step's plan made with `ctx.targets` (#4300), its digest bound to them.
+ * The plan must give back the targets it was asked for, which says it planned
+ * those alone; one that gives back others, or none, refuses. Without
+ * `ctx.targets`, the plan as it came.
+ */
+export function bindTargets(kind: string, ctx: DeployContext, planned: CapabilityPlan): CapabilityPlan {
+  const asked = ctx.targets;
+  if (!asked || asked.length === 0) return planned;
+  const want = [...new Set(asked)].sort();
+  const got = [...new Set(planned.targets ?? [])].sort();
+  if (got.length !== want.length || got.some((t, i) => t !== want[i])) {
+    throw new Error(
+      `component "${ctx.component}": ${kind} was asked to plan ${want.join(", ")} but its plan of ${planned.member} ` +
+        (got.length === 0 ? "names no targets" : `names ${got.join(", ")}`),
+    );
+  }
+  const planDigest = targetedPlanDigest(planned.planDigest, want);
+  const changeSet = planned.changeSet
+    ? { ...planned.changeSet, member: { ...planned.changeSet.member, planDigest } }
+    : undefined;
+  return { ...planned, planDigest, targets: want, ...(changeSet ? { changeSet } : {}) };
+}
+
 /** `next` over `prior`, as a later step's outputs win over an earlier one's in a run. */
 function mergePlannedOutputs(prior: PlannedOutputs | undefined, next: PlannedOutputs): PlannedOutputs {
   const known = { ...(prior?.known ?? {}), ...next.known };

package/src/op/activities/pr-refs.ts

@@ -0,0 +1,28 @@
+/**
+ * The pull request's base and head branch names, read off the run's own
+ * event (#4299). Its own module so the review agent bundles without
+ * predict-behaviour's estate code.
+ */
+
+/** Where the base branch name comes from, most specific first. Pure — exported for testing. */
+export function baseRefFrom(
+  env: Record<string, string | undefined>,
+  explicit?: string,
+): string | undefined {
+  const fromArgs = explicit?.trim();
+  if (fromArgs) return fromArgs;
+  for (const source of ["GITHUB_BASE_REF", "CI_MERGE_REQUEST_TARGET_BRANCH_NAME"]) {
+    const value = env[source]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+}
+
+/** What the head side is called in the finding: the source branch when the run names one, else the short commit. */
+export function headRefFrom(env: Record<string, string | undefined>, shortSha?: string): string {
+  for (const source of ["GITHUB_HEAD_REF", "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"]) {
+    const value = env[source]?.trim();
+    if (value) return value;
+  }
+  return shortSha?.trim() || "head";
+}

package/src/op/activities/predict-behaviour.ts

@@ -85,6 +85,9 @@ import type { BehaviourKinds } from "../../behaviour-kinds";
 import { createBehaviourPredict } from "../../behaviour-predict";
 import type { SerializerResult } from "../../serializer";
 import { markerSlug, reconcilePr, suppliedMarker, type ReconcileResult } from "./reconcile";
+import { baseRefFrom, headRefFrom } from "./pr-refs";
+
+export { baseRefFrom, headRefFrom };
 
 const execAsync = promisify(exec);
 
@@ -294,29 +297,6 @@ export function noBaseRefMessage(): string {
   );
 }
 
-/** Where the base branch name comes from, most specific first. Pure — exported for testing. */
-export function baseRefFrom(
-  env: Record<string, string | undefined>,
-  explicit?: string,
-): string | undefined {
-  const fromArgs = explicit?.trim();
-  if (fromArgs) return fromArgs;
-  for (const source of ["GITHUB_BASE_REF", "CI_MERGE_REQUEST_TARGET_BRANCH_NAME"]) {
-    const value = env[source]?.trim();
-    if (value) return value;
-  }
-  return undefined;
-}
-
-/** What the head side is called in the finding: the source branch when the run names one, else the short commit. */
-export function headRefFrom(env: Record<string, string | undefined>, shortSha?: string): string {
-  for (const source of ["GITHUB_HEAD_REF", "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"]) {
-    const value = env[source]?.trim();
-    if (value) return value;
-  }
-  return shortSha?.trim() || "head";
-}
-
 /** A checked-out base branch: where its project root is, and how to remove it. */
 export interface BaseCheckout {
   /** The base branch's counterpart of the working directory. */

package/src/op/activities/review-agent.ts

@@ -27,7 +27,7 @@ import { spawn, execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { readFile } from "node:fs/promises";
 import type { ChangeSetDocument, ChangeSetEntry } from "../../change-set";
-import { baseRefFrom } from "./predict-behaviour";
+import { baseRefFrom } from "./pr-refs";
 import { markerSlug, reconcilePr, suppliedMarker } from "./reconcile";
 
 const execFileAsync = promisify(execFile);

package/src/op/index.ts

@@ -75,6 +75,8 @@ export {
   OP_WAVE_MAX_REPLANS,
   opWaveHooksAtBase,
   runStageHooks,
+  runStageHooksAsync,
+  spawnExecAsync,
   opWaveNeedsApproval,
   opWavePlansPath,
   opWaveRunsPath,
@@ -91,6 +93,7 @@ export type {
   OpWaveDecision,
   OpWaveApplyHooksRun,
   OpWaveApplyOutcome,
+  OpWaveAsyncExec,
   OpWaveExec,
   OpWaveHeldOn,
   OpWaveHoldRequest,
@@ -106,6 +109,7 @@ export type {
   OpWaveShowAtBase,
   RecordHeadPlansOptions,
   RunOpWaveApplyHooksOptions,
+  RunStageHooksAsyncOptions,
   RunStageHooksOptions,
   StageHooksRun,
   RunOpWaveOptions,

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

@@ -105,6 +105,30 @@ import {
   type OpWaveRun,
   type OpWavesSpec,
 } from "./op-waves";
+import {
+  OP_WAVE_PENDING_RESERVED,
+  opWaveArgv,
+  pendingFields,
+  readHoldRequest,
+  runHookList,
+  runStageHooks,
+  runStageHooksAsync,
+  spawnExec,
+  spawnExecAsync,
+  type HookPlace,
+  type OpWaveAsyncExec,
+  type OpWaveExec,
+  type OpWaveHoldRequest,
+  type OpWaveHookOutcome,
+  type OpWaveHookRun,
+  type OtherGateHold,
+  type RunStageHooksAsyncOptions,
+  type RunStageHooksOptions,
+  type StageHooksRun,
+} from "./stage-hooks";
+
+export { OP_WAVE_PENDING_RESERVED, opWaveArgv, runStageHooks, runStageHooksAsync, spawnExecAsync };
+export type { OpWaveAsyncExec, OpWaveExec, OpWaveHoldRequest, OpWaveHookOutcome, OpWaveHookRun, RunStageHooksAsyncOptions, RunStageHooksOptions, StageHooksRun };
 
 /** What a run's plan command writes to `{plan}`. */
 export interface OpWavePlanFile {
@@ -154,12 +178,6 @@ export interface OpWavePlansFile {
   waves?: number;
 }
 
-/** 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", "approvalMode", "answer", "wave", "heldBy",
-] as const;
-
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
 export interface OpWaveRunsFile {
   /** The wave's name. */
@@ -305,18 +323,6 @@ export interface OpWaveApplyOutcome {
 
 export const OP_WAVE_APPLY_OUTCOMES = ["stood-down", "held", "replan"] as const;
 
-/** What a hook asks for when it holds a wave on another gate (#3821): it writes this to `CHANT_HOLD` and exits non-zero. */
-export interface OpWaveHoldRequest {
-  /** The op the gate is recorded under. Default: the spec's name. */
-  op?: string;
-  gate: string;
-  /** The digest an approval binds. */
-  digest: string;
-  description?: string;
-  /** Fields for the pending fact, as a plans file's `pending`. */
-  pending?: Record<string, unknown>;
-}
-
 /** A hold on another gate, as the decision records it (#3821). */
 export interface OpWaveHeldOn {
   op: string;
@@ -347,26 +353,6 @@ export interface OpWaveHeldOnApproval {
   approvedAt: string;
 }
 
-/** One hook's run (#3762). */
-export interface OpWaveHookOutcome {
-  moment: OpWaveHookMoment;
-  name: string;
-  /** The run, for a `perRun` hook. */
-  target?: string;
-  exit: number;
-  outcome: "passed" | "failed" | "held" | "skipped";
-  /** Why the moment was skipped, for `skipped` (#3811). */
-  reason?: string;
-}
-
-/** One run as a hook sees it (#3804). */
-export interface OpWaveHookRun {
-  target: string;
-  op: string;
-  /** The run's plan file, once planned. */
-  plan?: string;
-}
-
 /**
  * What chant hands an apply command in `CHANT_HOOKS` (#3804), and what
  * {@link opWaveHooksAtBase} builds for an apply outside the waves. Paths are
@@ -442,15 +428,6 @@ export interface OpWaveApplyHooksRun {
   proceed: boolean;
 }
 
-/** Runs one argv; returns its exit code. `env` is added to the job's environment. Injected so tests run no processes. */
-export type OpWaveExec = (argv: string[], cwd: string, env?: Record<string, string>) => number;
-
-const spawnExec: OpWaveExec = (argv, cwd, env) => {
-  const result = spawnSync(argv[0]!, argv.slice(1), { cwd, stdio: "inherit", ...(env ? { env: { ...process.env, ...env } } : {}) });
-  if (result.error) throw result.error;
-  return result.status ?? 1;
-};
-
 /** Reads one file at one commit, or null when the commit has no such file. Injected for tests. */
 export type OpWaveShowAtBase = (base: string, path: string, cwd: string) => { sha: string; text: string | null };
 
@@ -581,22 +558,6 @@ function pointAtBase(spec: OpWavesSpec, name: string, where: string): Pick<OpWav
   return { point: opWavePointAt(spec, name)! };
 }
 
-/** Fill one argv template. A placeholder whose value is not given is left as it is. */
-export function opWaveArgv(
-  template: readonly string[],
-  values: { op: string; wave: string; target?: string; plan?: string; runs?: string; plans?: string },
-): string[] {
-  const pairs: Array<[string, string | undefined]> = [
-    ["{op}", values.op],
-    ["{target}", values.target],
-    ["{wave}", values.wave],
-    ["{plans}", values.plans],
-    ["{plan}", values.plan],
-    ["{runs}", values.runs],
-  ];
-  return template.map((part) => pairs.reduce((out, [key, value]) => (value === undefined ? out : out.replaceAll(key, value)), part));
-}
-
 /** Where a run's plan file goes. */
 export function opWavePlanPath(spec: Pick<OpWavesSpec, "name">, wave: number, target: string): string {
   return `.chant/op-waves/${spec.name}/wave-${wave}/${target.replace(/[^A-Za-z0-9._-]/g, "_")}.plan.json`;
@@ -853,16 +814,6 @@ function extraMembers(value: unknown, targets: ReadonlySet<string>, where: strin
   return out.length > 0 ? out : undefined;
 }
 
-/** 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,
@@ -883,115 +834,6 @@ interface HooksOutcome {
   waitingOn?: OpWaveHeldOn;
 }
 
-/** A hook call that held the wave on another gate (#3821), kept so it can run again once that gate is approved. */
-interface OtherGateHold {
-  label: string;
-  name: string;
-  moment: OpWaveHookMoment;
-  target?: string;
-  argv: string[];
-  env: Record<string, string>;
-  request: OpWaveHoldRequest;
-}
-
-/** Read the hold file a hook wrote (#3821), or undefined when it wrote none or one that names no gate and digest. */
-function readHoldRequest(path: string, log: (line: string) => void, label: string): OpWaveHoldRequest | undefined {
-  if (!existsSync(path)) return undefined;
-  try {
-    const r = JSON.parse(readFileSync(path, "utf-8")) as Partial<OpWaveHoldRequest>;
-    if (typeof r.gate !== "string" || r.gate === "" || typeof r.digest !== "string" || r.digest === "") throw new Error("it names no gate and digest");
-    if (r.op !== undefined && (typeof r.op !== "string" || r.op === "")) throw new Error("its op is not a name");
-    return { gate: r.gate, digest: r.digest, ...(r.op ? { op: r.op } : {}), ...(typeof r.description === "string" ? { description: r.description } : {}), ...(r.pending ? { pending: pendingFields(r.pending, `the hold ${label} wrote`) ?? {} } : {}) };
-  } catch (err) {
-    log(`${label} wrote a hold file that cannot be read (${err instanceof Error ? err.message : String(err)}), so it holds the wave on its set digest`);
-    return undefined;
-  }
-}
-
-/** Where hooks run: the wave they belong to and the job's tools. */
-interface HookPlace {
-  /** The spec's name and `op`. */
-  name: string;
-  op: string;
-  waveName: string;
-  k: number;
-  cwd: string;
-  exec: OpWaveExec;
-  log: (line: string) => void;
-  /** Where a hook writes a hold on another gate (`CHANT_HOLD`). Default: under the wave's directory. */
-  holdPath?: string;
-}
-
-/**
- * Run one moment's hooks, in order: each once for the wave, or once per run
- * for a `perRun` hook. A hook that fails stops the rest, unless its
- * `onFailure` is `approve`: then it holds the wave and the hooks after it run.
- */
-function runHookList(
-  at: HookPlace,
-  moment: OpWaveHookMoment,
-  hooks: readonly OpWaveHook[] | undefined,
-  runs: readonly OpWaveHookRun[],
-  runsPath: string,
-  extraEnv: Record<string, string> = {},
-): HooksOutcome & { outcomes: OpWaveHookOutcome[]; otherGates: OtherGateHold[] } {
-  const out: HooksOutcome & { outcomes: OpWaveHookOutcome[]; otherGates: OtherGateHold[] } = { holds: [], outcomes: [], otherGates: [] };
-  if (!hooks || hooks.length === 0) return out;
-  const { name: specName, op, waveName, k, cwd, exec, log } = at;
-  // #3821: a hook that holds the wave on another gate names it in this file.
-  const holdPath = at.holdPath ?? `.chant/op-waves/${specName}/wave-${k}/hold.json`;
-  const env = { CHANT_OP_WAVES: specName, CHANT_WAVE: waveName, CHANT_WAVE_NUMBER: String(k), CHANT_HOOK: moment, CHANT_RUNS: runsPath, CHANT_HOLD: holdPath, ...extraEnv };
-  for (const hook of hooks) {
-    const name = hook.name ?? (hook.command.join(" ").length > 60 ? `${hook.command.join(" ").slice(0, 57)}...` : hook.command.join(" "));
-    // #4288: a hook with `targets` is for the runs they match. Once for the wave, it runs when one matches or no run is known yet.
-    const mine = opWaveHookRuns(hook, runs);
-    if (hook.targets && (hook.perRun ? mine.length === 0 : mine.length === 0 && runs.length > 0)) {
-      log(`${moment} hook ${name}: no run matches its targets (${hook.targets.join(", ")}), so it did not run`);
-      continue;
-    }
-    const calls = hook.perRun
-      ? mine.map((run) => ({
-          target: run.target as string | undefined,
-          argv: opWaveArgv(hook.command, { op: run.op, wave: waveName, target: run.target, runs: runsPath, ...(run.plan ? { plan: run.plan } : {}) }),
-          env: { ...env, CHANT_TARGET: run.target, ...(run.plan ? { CHANT_PLAN: run.plan } : {}) } as Record<string, string>,
-        }))
-      : [{ target: undefined, argv: opWaveArgv(hook.command, { op, wave: waveName, runs: runsPath }), env: env as Record<string, string> }];
-    for (const call of calls) {
-      const label = `${moment} hook ${name}${call.target ? ` (${call.target})` : ""}`;
-      let code: number;
-      rmSync(join(cwd, holdPath), { force: true });
-      try {
-        code = exec(call.argv, cwd, call.env);
-      } catch (err) {
-        log(`${label} did not run: ${err instanceof Error ? err.message : String(err)}`);
-        code = 127;
-      }
-      const base = { moment, name, ...(call.target ? { target: call.target } : {}), exit: code };
-      if (code === 0) {
-        out.outcomes.push({ ...base, outcome: "passed" });
-        continue;
-      }
-      if (hook.onFailure === "approve") {
-        out.outcomes.push({ ...base, outcome: "held" });
-        const request = readHoldRequest(join(cwd, holdPath), log, label);
-        if (request) {
-          out.otherGates.push({ label, name, moment, ...(call.target ? { target: call.target } : {}), argv: call.argv, env: call.env, request });
-          log(`${label} exited ${code} and holds wave ${k} (${waveName}) on gate ${request.op ?? specName} / ${request.gate}, digest ${request.digest}`);
-          continue;
-        }
-        out.holds.push(label);
-        log(`${label} exited ${code}, so wave ${k} (${waveName}) waits for an approval of its set digest`);
-        continue;
-      }
-      out.outcomes.push({ ...base, outcome: "failed" });
-      out.failed = `${label} exited ${code}`;
-      log(out.failed);
-      return out;
-    }
-  }
-  return out;
-}
-
 const placeOf = (ctx: WaveContext): HookPlace => ({ name: ctx.spec.name, op: ctx.spec.op, waveName: ctx.wave.name, k: ctx.k, cwd: ctx.cwd, exec: ctx.exec, log: ctx.log });
 
 const hookRuns = (spec: OpWavesSpec, k: number, runs: readonly OpWaveRun[], members?: ReadonlyMap<string, OpWaveMember>): OpWaveHookRun[] =>
@@ -1076,52 +918,6 @@ async function runHooks(
   return back;
 }
 
-/** The options of {@link runStageHooks} (#4288). */
-export interface RunStageHooksOptions {
-  /** What the hooks belong to: `CHANT_OP_WAVES`, and the `{op}` of a hook that runs once. */
-  name: string;
-  op: string;
-  /** `{wave}` and `CHANT_WAVE`. */
-  wave: string;
-  /** `CHANT_WAVE_NUMBER`. Default 0. */
-  k?: number;
-  /** The runs a `perRun` hook runs for and `targets` match against. */
-  runs: readonly OpWaveHookRun[];
-  /** `{runs}` and `CHANT_RUNS`, relative to `cwd`; the caller writes it. */
-  runsFile: string;
-  /** `CHANT_HOLD`, relative to `cwd`. */
-  holdFile: string;
-  /** Added to every hook's environment. */
-  env?: Record<string, string>;
-  cwd?: string;
-  exec?: OpWaveExec;
-  log?: (line: string) => void;
-}
-
-/** What {@link runStageHooks} gave. */
-export interface StageHooksRun {
-  outcomes: OpWaveHookOutcome[];
-  /** Set when a hook with `onFailure: fail` failed; the hooks after it did not run. */
-  failed?: string;
-  /** The `onFailure: approve` hooks that failed. A hold on another gate counts as one here. */
-  holds: string[];
-}
-
-/**
- * Run one moment's hooks outside an Op waves job (#4288): the pull-request
- * jobs, or a product's own stage, with the same `targets`, `perRun`,
- * `onFailure` and argv filling a wave job uses. A hook that holds on another
- * gate (`CHANT_HOLD`) is counted as a plain hold; settling that gate is the
- * caller's.
- */
-export function runStageHooks(moment: OpWaveHookMoment, hooks: readonly OpWaveHook[] | undefined, options: RunStageHooksOptions): StageHooksRun {
-  const cwd = options.cwd ?? process.cwd();
-  const log = options.log ?? ((line: string) => console.error(line));
-  const place: HookPlace = { name: options.name, op: options.op, waveName: options.wave, k: options.k ?? 0, cwd, exec: options.exec ?? spawnExec, log, holdPath: options.holdFile };
-  const out = runHookList(place, moment, hooks, options.runs, options.runsFile, options.env);
-  return { outcomes: out.outcomes, ...(out.failed ? { failed: out.failed } : {}), holds: [...out.holds, ...out.otherGates.map((g) => `${g.label} (on ${g.request.op ?? options.name} / ${g.request.gate})`)] };
-}
-
 /**
  * The hooks that run before a job plans (#4288): `before-observe`, then
  * `before-plan`. A failure or a hold on another gate in the first ends it

package/src/op/stage-hooks-async.test.ts

@@ -0,0 +1,79 @@
+/**
+ * runStageHooksAsync (#4334): the async stage runner gives what the sync one
+ * gives for the same hooks, and two calls run side by side.
+ */
+import { describe, expect, test } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { OpWaveHook } from "./op-waves";
+import { runStageHooks, runStageHooksAsync, spawnExecAsync, type OpWaveAsyncExec, type OpWaveExec } from "./stage-hooks";
+
+const hooks: OpWaveHook[] = [
+  { name: "each", command: ["hook", "each", "{target}", "{op}"], perRun: true, targets: ["api"] },
+  { name: "gate", command: ["hook", "gate", "{wave}"], onFailure: "approve" },
+  { name: "other", command: ["hook", "other"], onFailure: "approve" },
+  { name: "lost", command: ["hook", "lost"] },
+  { name: "stop", command: ["hook", "stop"] },
+  { name: "after", command: ["hook", "after"] },
+];
+const runs = [{ target: "api", op: "pr-7" }, { target: "web", op: "pr-7" }];
+
+/** Exit codes by the hook's second word; `other` writes a hold on another gate and `lost` cannot start. */
+function codeOf(argv: string[], cwd: string, env?: Record<string, string>): number {
+  if (argv[1] === "other") writeFileSync(join(cwd, env!.CHANT_HOLD!), JSON.stringify({ gate: "dba", digest: "sha256:abc" }));
+  if (argv[1] === "lost") throw new Error("spawn hook ENOENT");
+  return argv[1] === "gate" || argv[1] === "other" || argv[1] === "stop" ? 1 : 0;
+}
+
+describe("runStageHooksAsync (#4334)", () => {
+  test("gives the outcomes, holds and failure the sync runner gives", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "stage-hooks-async-"));
+    const options = { name: "pr-7", op: "pr-7", wave: "prod", runs, runsFile: "runs.json", holdFile: "hold.json", cwd };
+    const syncCalls: string[] = [];
+    const syncLog: string[] = [];
+    const exec: OpWaveExec = (argv, at, env) => (syncCalls.push(argv.join(" ")), codeOf(argv, at, env));
+    const sync = runStageHooks("before-plan", hooks, { ...options, exec, log: (l) => syncLog.push(l) });
+    const asyncCalls: string[] = [];
+    const asyncLog: string[] = [];
+    const asyncExec: OpWaveAsyncExec = async (argv, at, env) => (asyncCalls.push(argv.join(" ")), codeOf(argv, at, env));
+    const ran = await runStageHooksAsync("before-plan", hooks, { ...options, exec: asyncExec, log: (l) => asyncLog.push(l) });
+    expect(ran).toEqual(sync);
+    expect(asyncCalls).toEqual(syncCalls);
+    expect(asyncLog).toEqual(syncLog);
+    expect(asyncCalls).toEqual(["hook each api pr-7", "hook gate prod", "hook other", "hook lost"]);
+    expect(ran.failed).toBe("before-plan hook lost exited 127");
+    expect(ran.holds).toEqual(["before-plan hook gate", "before-plan hook other (on pr-7 / dba)"]);
+    expect(ran.outcomes.map((o) => o.outcome)).toEqual(["passed", "held", "held", "failed"]);
+    expect(asyncLog).toContain("before-plan hook lost did not run: spawn hook ENOENT");
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("two calls run side by side", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "stage-hooks-async-"));
+    const started: string[] = [];
+    let release!: () => void;
+    const both = new Promise<void>((resolve) => (release = resolve));
+    const exec: OpWaveAsyncExec = async (argv) => {
+      started.push(argv[1]!);
+      if (started.length === 2) release();
+      await both;
+      return 0;
+    };
+    const one = (name: string) =>
+      runStageHooksAsync("before-plan", [{ command: ["hook", name] }], { name, op: name, wave: "prod", runs: [], runsFile: `${name}/runs.json`, holdFile: `${name}/hold.json`, cwd, exec, log: () => {} });
+    const [a, b] = await Promise.all([one("a"), one("b")]);
+    expect(started.sort()).toEqual(["a", "b"]);
+    expect([a.outcomes[0]!.outcome, b.outcomes[0]!.outcome]).toEqual(["passed", "passed"]);
+    rmSync(cwd, { recursive: true, force: true });
+  });
+
+  test("the default exec spawns the hook, gives its exit code and rejects a command that cannot start", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "stage-hooks-async-"));
+    expect(await spawnExecAsync([process.execPath, "-e", "process.exit(process.env.CODE === '3' ? 3 : 0)"], cwd, { CODE: "3" })).toBe(3);
+    await expect(spawnExecAsync(["./no-such-hook"], cwd)).rejects.toThrow(/ENOENT/);
+    const ran = await runStageHooksAsync("after-apply", [{ name: "ok", command: [process.execPath, "-e", "process.exit(0)"] }], { name: "s", op: "s", wave: "w", runs: [], runsFile: "runs.json", holdFile: "hold.json", cwd, log: () => {} });
+    expect(ran).toEqual({ outcomes: [{ moment: "after-apply", name: "ok", exit: 0, outcome: "passed" }], holds: [] });
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});