@edgehero/pi-dispatch 1.4.0 → 1.6.0

package/src/triggers.mjs

@@ -30,6 +30,11 @@ import { EGRESS_ENV_VARS, WORKER_ONLY_SECRET_VARS, configError } from "./config.
 import { SKILL_NAME_RE } from "./flow-gate.mjs";
 import { FORGE_HOST_VARS, FORGE_KINDS, MINTED_TOKEN_VARS, RUN_KINDS, forgeSpec, isForgeKind } from "./forges.mjs";
 import { CONTAINER_ENV_NAMES } from "./reserved-env.mjs";
+// The wait grammar's two shared halves (issue #230). `afterInstantMs` is imported rather than restated so
+// the loader and the pickup gate cannot disagree about what a legal instant is: a second spelling here is
+// how a file that loads clean starts holding for an instant nobody wrote. wait-for.mjs is pure and
+// fs-free, so importing it keeps parseTriggers pure.
+import { WAIT_CONDITION_KEYS, WAIT_CONDITION_MAX, afterInstantMs } from "./wait-for.mjs";
 
 const ON_TYPES = new Set(["cron", "label", "comment", "pull_request", "issue"]);
 
@@ -345,6 +350,9 @@ function normalizeCron(on, run, index, path, state) {
 	validateDisarmed(on, `cron trigger "${id}"`, path, { onType: "cron" });
 	const secrets = validateSecrets(run, `cron trigger "${id}"`, path);
 	const secretsProfile = validateSecretsProfile(run, `cron trigger "${id}"`, path);
+	// Called for its refusal only: the returned `run` below deliberately grows no `waitFor` key, exactly as
+	// it grows no `replicas` one, because a cron entry can never carry either (issue #230).
+	validateWaitFor(on, run, `cron trigger "${id}"`, path, { onType: "cron" });
 
 	// provider/model/maxTurns stay absent when omitted so the value resolves at job start against the
 	// settings overlay/env, not a default frozen here (INT-CONFIG-OVERLAY-CONTRACT). github/packages/image stay
@@ -984,6 +992,140 @@ function validateSecretsProfile(run, at, path) {
 	return profile;
 }
 
+/**
+ * `run.waitFor` -- the conditions that must all clear before this trigger's job starts (issue #230).
+ *
+ * A CONJUNCTION of one-key objects: `{ "after": "<ISO instant>" }` is answered from the clock, and
+ * `{ "profile": "<name>" }` is answered by an operator-declared executable. The tiers are evaluated
+ * cheapest-first at the gate rather than in the operator's writing order, which is a deliberate divergence
+ * from the sequential rule `run.secrets` keeps: that rule exists so a broken reference always blames the
+ * same variable, and a conjunction has no such ambiguity to protect.
+ *
+ * Like `run.secretsProfile`, a `profile` names a NAME and never a path, and WHETHER the deployment declares
+ * it cannot be answered here (this validator is pure and fs-free). That refuses pre-spend, per delivery, as
+ * `wait-profile-unknown`.
+ *
+ * UNKNOWN KEYS INSIDE A CONDITION ARE REFUSED, not dropped, which inverts this file's own posture for a
+ * reason `validateDisarmed` already established: everywhere else an unknown key is a field that does
+ * nothing, while here it is a CONDITION that does nothing, and a gate silently missing one of its terms
+ * runs a paid job the operator believed was held.
+ *
+ * Three combination refusals, checked BEFORE any shape check so the message names the combination rather
+ * than the array (`validateReplicas`' ordering lesson, where moving the local gate below the range check
+ * would have answered a cron entry with the wrong complaint):
+ *
+ *   - ON CRON. Two mechanisms, either of which is enough. The scheduler advances at PICKUP, so a held
+ *     occurrence carries an older `repeat:<id>:<millis>` than the one the scheduler stores; teardown
+ *     (`removeJobScheduler`, and therefore both a trigger delete and the stall guard's money backstop)
+ *     deletes only the STORED one, so the held job survives its own scheduler and still pays. And a held
+ *     occurrence's hash outliving the next `upsertJobScheduler` is a `SchedulerJobIdCollision`, which
+ *     `cron.mjs` turns into a config error that FAILS WORKER BOOT. Closing it needs teardown that
+ *     enumerates the delayed set, which is a gap to close, not a limit.
+ *   - BESIDE `on.once`. The one-shot disarm fires for EVERY run record, outcome-blind ("fired" means
+ *     "produced a run record"), so a wait that timed out would permanently spend a one-shot whose
+ *     container never started, and `checkOnceSpent` would then refuse every retry until the operator
+ *     hand-edited this file. Exempting the wait reasons instead would redefine "fired" for every other
+ *     refusal too, which is a gap to close, not a limit.
+ *   - BESIDE `run.replicas`. Fanout happens at enqueue, so N replicas are N independent holds: N times the
+ *     subprocesses and N times the check contention for ONE external condition. `REPLICAS_MAX` was chosen
+ *     against `PI_CONCURRENCY` on the premise that replicas RACE, and a hold inverts it.
+ *
+ * Returns a freshly built array, so nothing unvalidated rides through, and `undefined` when absent so an
+ * unflagged trigger normalizes byte-identically.
+ */
+function validateWaitFor(on, run, at, path, { onType }) {
+	// A NEAR-MISS SPELLING IS REFUSED, and this is the one place in this file that looks at a key nobody
+	// wrote. Unknown keys drop here by design, which is harmless for every other field: a misspelled
+	// `run.imgae` gives you the default image and a job that ran. `waitFor` is the first field whose
+	// ABSENCE is destructive -- `waitfor` loads clean, normalizes clean, enqueues clean, and produces a
+	// paid run that is byte-identical in the record, the panel and the log to one that correctly waited.
+	// That is precisely the argument this validator already makes one level down about an unknown key
+	// INSIDE a condition ("a term of the gate that would silently do nothing"), and the gate as a whole is
+	// the bigger casualty. Bounded deliberately to near-misses rather than a general unknown-key sweep:
+	// tolerating unknown `run` keys is this file's documented forward-compatibility posture, and a sweep
+	// would refuse files that load today.
+	// On `run` only a NEAR-MISS is wrong (the exact spelling is the field itself); on `on` every spelling is,
+	// including the correct one, since a wait is a property of the run and `on.waitFor` would be dropped just
+	// as silently as a typo.
+	for (const [label, source, exactIsLegal] of [
+		["run", run, true],
+		["on", on, false],
+	]) {
+		for (const key of Object.keys(source ?? {})) {
+			if (exactIsLegal && key === "waitFor") continue;
+			if (key.replace(/[^a-z0-9]/gi, "").toLowerCase() !== "waitfor") continue;
+			throw configError(`${at}: ${label}.${key} is not a field -- did you mean run.waitFor? A wait condition the loader drops holds nothing while the file reads as though it does, so a near miss is refused rather than dropped: ${path}`);
+		}
+	}
+
+	const waitFor = run.waitFor;
+	if (waitFor === undefined) return undefined;
+
+	if (onType === "cron") {
+		throw configError(`${at}: run.waitFor is not yet covered on a cron trigger -- the scheduler advances at pickup, so a held occurrence outlives the teardown that would delete it and still pays, and its surviving job hash can fail worker boot with a scheduler id collision; bounding that needs delayed-set-aware teardown, which is a gap to close, not a limit: ${path}`);
+	}
+	if (on?.once === true) {
+		throw configError(`${at}: run.waitFor and on.once cannot be combined -- the one-shot disarms on every run record, so a wait that never cleared would spend the one-shot with no container ever started and no way to re-arm it but editing this file: ${path}`);
+	}
+	if (run.replicas !== undefined) {
+		throw configError(`${at}: run.waitFor and run.replicas cannot be combined -- replicas fan out at enqueue, so each one would hold and poll the same external condition independently, multiplying the checks by ${run.replicas} for one answer: ${path}`);
+	}
+
+	if (!Array.isArray(waitFor) || waitFor.length === 0) {
+		throw configError(`${at}: run.waitFor must be a non-empty array of conditions when present (got ${JSON.stringify(waitFor)}): ${path}`);
+	}
+	if (waitFor.length > WAIT_CONDITION_MAX) {
+		throw configError(`${at}: run.waitFor names ${waitFor.length} conditions, over the ${WAIT_CONDITION_MAX} cap -- each profile condition is a subprocess run before the container, holding a concurrency slot while it runs: ${path}`);
+	}
+
+	const expected = WAIT_CONDITION_KEYS.join("|");
+	const normalized = [];
+	const profiles = new Set();
+	let seenAfter = false;
+	for (let i = 0; i < waitFor.length; i += 1) {
+		const condition = waitFor[i];
+		const where = `${at}: run.waitFor[${i}]`;
+		if (condition === null || typeof condition !== "object" || Array.isArray(condition)) {
+			throw configError(`${where} must be an object naming exactly one condition (got ${JSON.stringify(condition)}): ${path}`);
+		}
+		const keys = Object.keys(condition);
+		if (keys.length !== 1) {
+			throw configError(`${where} must name exactly one condition (expected ${expected}), got ${keys.length === 0 ? "an empty object" : JSON.stringify(keys)}: ${path}`);
+		}
+		const key = keys[0];
+		if (key === "exclusive") {
+			throw configError(`${where}: exclusive is no longer a condition you write -- the worker already holds at most one local job per folder, always on, with no configuration and no off switch, and scoped-limits.json bounds any scope further: ${path}`);
+		}
+		if (!WAIT_CONDITION_KEYS.includes(key)) {
+			throw configError(`${where} has an unsupported condition ${JSON.stringify(key)} (expected ${expected}) -- an unknown condition here is a term of the gate that would silently do nothing, so it is refused rather than dropped: ${path}`);
+		}
+		if (key === "after") {
+			if (seenAfter) {
+				throw configError(`${where}: run.waitFor names a second "after" -- the conditions are a conjunction, so two instants mean the later one and the file would read as though both mattered: ${path}`);
+			}
+			if (afterInstantMs(condition.after) === null) {
+				throw configError(`${where}: after must be an ISO-8601 instant carrying its own zone, like "2026-09-01T09:00:00Z" or "2026-09-01T11:00:00+02:00" (got ${JSON.stringify(condition.after)}) -- without a zone the same file would hold for a different instant on a worker in a different timezone: ${path}`);
+			}
+			seenAfter = true;
+			normalized.push({ after: condition.after });
+			continue;
+		}
+		const profile = condition.profile;
+		if (!isNonEmptyString(profile)) {
+			throw configError(`${where}: profile must be a non-empty string naming one of the wait profiles this deployment declares (got ${JSON.stringify(profile)}): ${path}`);
+		}
+		if (!ID_CHARSET.test(profile)) {
+			throw configError(`${where}: profile ${JSON.stringify(profile)} may use letters, digits, dot, dash and underscore only -- PI_WAIT_PROFILES is a comma-separated list of name:path pairs, so a name carrying either separator cannot be declared: ${path}`);
+		}
+		if (profiles.has(profile)) {
+			throw configError(`${where}: run.waitFor names the profile ${JSON.stringify(profile)} twice -- the conditions are a conjunction, so the second one can never change the answer while it doubles the subprocesses: ${path}`);
+		}
+		profiles.add(profile);
+		normalized.push({ profile });
+	}
+	return normalized;
+}
+
 function normalizeLabel(on, run, index, path) {
 	const at = `trigger at index ${index}`;
 	const predicate = validatePredicate(on, index, path, true);
@@ -1005,9 +1147,10 @@ function normalizeLabel(on, run, index, path) {
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
 	const secretsProfile = validateSecretsProfile(run, at, path);
+	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	return {
 		on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }) },
 	};
 }
 
@@ -1043,9 +1186,10 @@ function normalizeComment(on, run, index, path, state) {
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
 	const secretsProfile = validateSecretsProfile(run, at, path);
+	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	return {
 		on: { type: "comment", phrase: on.phrase },
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(repository !== undefined && { repository }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }) },
 	};
 }
 
@@ -1108,6 +1252,7 @@ function normalizeIssue(on, run, index, path) {
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
 	const secretsProfile = validateSecretsProfile(run, at, path);
+	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	return {
 		on: {
 			type: "issue",
@@ -1117,7 +1262,7 @@ function normalizeIssue(on, run, index, path) {
 			...(number !== undefined && { number }),
 			...(once !== undefined && { once }),
 		},
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }) },
 	};
 }
 
@@ -1191,6 +1336,7 @@ function normalizePullRequest(on, run, index, path) {
 	const replicas = validateReplicas(run, at, path);
 	const secrets = validateSecrets(run, at, path);
 	const secretsProfile = validateSecretsProfile(run, at, path);
+	const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
 	return {
 		on: {
 			type: "pull_request",
@@ -1205,7 +1351,7 @@ function normalizePullRequest(on, run, index, path) {
 			...(number !== undefined && { number }),
 			...(once !== undefined && { once }),
 		},
-		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }) },
+		run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...(command !== undefined && { command }), ...(skillsDir !== undefined && { skillsDir }), ...(instructions !== undefined && { instructions }), ...(secrets !== undefined && { secrets }), ...(secretsProfile !== undefined && { secretsProfile }), ...(waitFor !== undefined && { waitFor }) },
 	};
 }
 

package/src/wait-check.mjs

@@ -0,0 +1,172 @@
+/**
+ * Running an operator's wait check (issue #230, `run.waitFor`'s `profile` conditions).
+ *
+ * `secrets.mjs`'s resolver, reduced. The two seams spawn an operator-written script on the HOST, before
+ * anything spends, with the worker's own environment, and read its EXIT CODE. The differences are all
+ * subtractions, and each one is a thing the resolver needs that a check does not:
+ *
+ *   - **stdout is a byte counter too, not a value.** A resolver's stdout IS the secret; a check's is
+ *     incidental output nobody asked for. Reading it would create a channel for a third party's text to
+ *     reach a panel row or a public comment through an operator's script, which `INT-WAIT-PROFILES-CONTRACT`
+ *     refuses. Whether a check may return a reason string worth showing is deferred, and deferring it is
+ *     cheaper than un-shipping it later.
+ *   - **no size cap, no NUL check, no newline stripping.** Those exist because a resolved value becomes an
+ *     `-e NAME=VALUE` argv element. Nothing here becomes anything.
+ *   - **no dedup by reference.** A resolver dedups because two variables may name one item and rotation
+ *     could straddle the pair. Two conditions naming one profile are refused at load instead.
+ *   - **four codes rather than three** (`INT-RUNNER-EXIT-CODE-PROTOCOL`'s wait-profile table), because a
+ *     check has an answer the other participants do not: not yet.
+ *
+ * What transfers unchanged, because the reasons transfer unchanged: the `name:/abs/path` grammar and its
+ * fail-loud parser, the realpath-and-executable probe, `spawn` with an argv ARRAY and `shell: false`,
+ * stdin ignored so a script that prompts dies at once instead of blocking to its timeout, stderr counted
+ * and never read, SIGTERM then SIGKILL after a grace, a per-invocation timeout, the abort signal, and
+ * sequential evaluation in the operator's writing order.
+ */
+
+import { realpathSync, statSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { EXIT_HOLD, decideWait } from "./exit-code.mjs";
+
+/** SIGTERM, then SIGKILL after this. `secrets.mjs`'s grace, for its reason. */
+const KILL_GRACE_MS = 2000;
+
+/**
+ * Build the checker. Returns `async (profile, target, { signal }) => verdict`, where verdict is
+ * `{ verdict: "go" | "hold" | "refuse", fault }` or `{ profileUnknown: name }`.
+ *
+ * NEVER THROWS and never rejects, which is `resolveSecrets`' contract and matters more here: this runs at
+ * the pickup gate, ABOVE the processor's `try`, where a rejection would escape into BullMQ's failed-attempt
+ * handling and turn a check that could not run into a retried job. The `log` sink is called inside guards
+ * for that reason -- an injected sink that throws is the one way this promise could otherwise be broken.
+ */
+export function makeWaitChecker({ profiles = {}, timeoutMs = 10_000, spawnFn = spawn, realExecutablePath = defaultRealExecutablePath, hostEnv = process.env, log = () => {} }) {
+	return async function checkWait(profile, target, { signal } = {}) {
+		const declared = profiles[profile];
+		if (typeof declared !== "string") return { profileUnknown: profile };
+
+		// Resolved and probed at CHECK time, not at boot: an operator who fixes a path mid-day must not stay
+		// refused, and one who deletes a script must not stay admitted. `statSync` rather than `lstat`,
+		// deliberately unlike `processor.mjs`'s directory probe, because this must answer the same question
+		// `spawn` will: spawn follows symlinks. Mode bits beyond the executable bit are doctor's business, not
+		// a job-time refusal -- refusing a group-writable script here would refuse a very ordinary install.
+		let path;
+		try {
+			path = realExecutablePath(declared);
+		} catch {
+			path = null;
+		}
+		if (!path) return { profileUnknown: profile };
+
+		// argv[1] must be a string a script can act on. `targetFor` answers null for any kind that is neither
+		// local nor a forge, and `spawn(path, [null])` throws -- which `runCheck` would turn into a silent
+		// fault hold, killing the job as `wait-unanswerable` and blaming the operator's check for a shape it
+		// never saw. The leading-dash refusal is `run.secrets`' own, for its reason: this is argv[1], where a
+		// dash parses as a flag, and we do not pass `--` instead because the option parser is the operator's.
+		if (typeof target !== "string" || target === "" || target.startsWith("-")) {
+			try {
+				log("wait_check_target_unusable", { profile });
+			} catch {}
+			return { verdict: "hold", fault: true, unusableTarget: true };
+		}
+
+		const outcome = await runCheck(spawnFn, path, target, { timeoutMs, hostEnv, signal });
+		try {
+			log("wait_check", { profile, code: outcome.code, detail: outcome.detail, stdoutBytes: outcome.stdoutBytes, stderrBytes: outcome.stderrBytes });
+		} catch {}
+		return outcome.verdict;
+	};
+}
+
+/** The realpath-and-executable probe, `secrets.mjs`'s exactly. */
+function defaultRealExecutablePath(p) {
+	const real = realpathSync(p);
+	const st = statSync(real);
+	return st.isFile() && (st.mode & 0o111) !== 0 ? real : null;
+}
+
+/**
+ * Run one check and classify it. Resolves `{ verdict, code, detail, stdoutBytes, stderrBytes }`.
+ *
+ * A check that could not run AT ALL -- spawn threw, the process died on a signal, the timeout fired, the
+ * job was aborted -- is a FAULT hold rather than a refusal, which is `decideWait`'s treatment of exit 1 and
+ * for its reason: a check that has not answered has not answered *no*, and dropping a paid delivery over an
+ * unreachable dependency is `CONST-RETRY-INFRA-ONLY` in the expensive direction. The fault count is what
+ * keeps that from being unbounded.
+ */
+function runCheck(spawnFn, path, target, { timeoutMs, hostEnv, signal }) {
+	return new Promise((resolve) => {
+		let child;
+		try {
+			child = spawnFn(path, [target], {
+				stdio: ["ignore", "pipe", "pipe"],
+				env: hostEnv,
+				shell: false,
+			});
+		} catch {
+			resolve({ verdict: { verdict: "hold", fault: true }, code: null, detail: "spawn", stdoutBytes: 0, stderrBytes: 0 });
+			return;
+		}
+
+		let stdoutBytes = 0;
+		let stderrBytes = 0;
+		let done = false;
+		let killTimer = null;
+
+		const finish = (result) => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			signal?.removeEventListener?.("abort", onAbort);
+			resolve(result);
+		};
+		// The kill timer is deliberately NOT cleared by `finish`: the promise settles now, and the escalation
+		// still has to land on a child that ignored SIGTERM.
+		const stop = (why) => {
+			try {
+				child.kill();
+			} catch {}
+			killTimer = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+			}, KILL_GRACE_MS);
+			killTimer.unref?.();
+			// An ABORT is not a fault. The worker is shutting down or this job was cancelled -- the operator's
+			// script did nothing wrong, and counting it would let five restarts that happen to land mid-check
+			// terminate a job with a PUBLIC comment blaming their check for the worker's own shutdown. That is
+			// the inverse of what the fault count is for, so the caller is told which of the two happened.
+			finish({ verdict: { verdict: "hold", fault: why !== "aborted", ...(why === "aborted" && { aborted: true }) }, code: null, detail: why, stdoutBytes, stderrBytes });
+		};
+
+		const timer = setTimeout(() => stop("timeout"), timeoutMs);
+		const onAbort = () => stop("aborted");
+		signal?.addEventListener?.("abort", onAbort, { once: true });
+
+		// BOTH streams are counters. stderr for the resolver's stated reason (a script's error text can echo
+		// the ticket, the query, or a vendor's own message), and stdout for the same reason one step further:
+		// a check's stdout is a third party's words arriving through an operator's script, and the only thing
+		// this seam is entitled to read from it is how much there was.
+		child.stdout?.on("data", (d) => (stdoutBytes += d.length));
+		child.stderr?.on("data", (d) => (stderrBytes += d.length));
+		child.on("error", () => finish({ verdict: { verdict: "hold", fault: true }, code: null, detail: "spawn", stdoutBytes, stderrBytes }));
+		// `exit`, NOT `close`. `close` waits for the child's stdio pipes to reach EOF, and any process the
+		// script leaves in the background inherits those pipes and holds them open -- so a check that answers
+		// `exit 0` in a millisecond is reported as a TIMEOUT, charged a fault, and after
+		// PI_WAIT_MAX_FAULTS the job dies with a public comment blaming the operator's script for something it
+		// did correctly. The resolver next door can afford `close` because it needs the bytes; this seam reads
+		// only a COUNT, so waiting for EOF buys nothing and costs the feature its credibility.
+		//
+		// The counts are then a floor rather than a total, which is what a byte counter is for, and the
+		// grandchild that kept the pipe open outlives the kill ladder -- `child.kill` reaches the direct child
+		// only. That residual is named in DES-WAIT-FOR-HOLDS-AND-WAIT-PROFILES rather than fixed here, because
+		// killing a process GROUP means spawning detached, which changes what the check inherits.
+		child.on("exit", (code, sig) => {
+			if (done) return;
+			// A signalled death reports code null; treat it as unanswered rather than letting `decideWait`
+			// read a null as an unrecognised code that means the same thing by accident.
+			if (code === null) return finish({ verdict: { verdict: "hold", fault: true }, code: null, detail: sig ? `signal-${sig}` : "no-code", stdoutBytes, stderrBytes });
+			finish({ verdict: decideWait(code), code, detail: code === EXIT_HOLD ? "not-yet" : "exit", stdoutBytes, stderrBytes });
+		});
+	});
+}