@edgehero/pi-dispatch 1.5.0 → 1.6.1

package/src/start.mjs

@@ -22,9 +22,11 @@ import { makeCleanup, makeForgePreparers, makePrepareWorkspace } from "./prepare
 import { listRunningSandboxes } from "./sandbox.mjs";
 import { makeSandboxReaper } from "./sandbox-store.mjs";
 import { makeSessionStore } from "./session-store.mjs";
-import { makeCheckOnceSpent, makeDisarmOnce } from "./triggers-file.mjs";
+import { makeCheckOnceSpent, makeCheckWaitSkew, makeDisarmOnce } from "./triggers-file.mjs";
 import { loadPauseWindows, pauseUntilMs } from "./pause-windows.mjs";
 import { loadScopedLimits } from "./scoped-limits.mjs";
+import { makeWaitChecker } from "./wait-check.mjs";
+import { makeWaitState } from "./wait-state.mjs";
 import { makeQueue } from "./queue.mjs";
 import { makeRunContainer } from "./run-container.mjs";
 import { makeSecretsResolver } from "./secrets.mjs";
@@ -466,6 +468,18 @@ export async function startWorker(
 		// Issue #242: the scoped-limits snapshot the pickup gate and the scoped budget read, once per
 		// pickup, from the live-reloaded ref -- same next-job grain as pauseUntil above.
 		scopedLimits: () => scopedLimits.current,
+		// Issue #230. The `after` ceiling is read per pickup from config rather than frozen into the
+		// processor, so it is one value with one home; the wait state shares the budget's redis client
+		// because it describes the same delayed jobs that client already reasons about.
+		afterMaxMs: () => config.waitAfterMaxMs,
+		waitState: makeWaitState({ redis }),
+		// The polled tier's bounds, read per pickup from config so they are one value with one home. The
+		// slot count is a CEILING the gate clamps against the live concurrency, never the final number.
+		checkSlotCount: () => config.waitCheckSlots,
+		intervalMs: () => config.waitIntervalMs,
+		maxWaitMs: () => config.waitMaxMs,
+		maxChecks: () => config.waitMaxChecks,
+		maxFaults: () => config.waitMaxFaults,
 		deps: {
 			collectChain,
 			// The one-shot pre-spend check (issue #231): reads the same file the disarm writes, refuses
@@ -473,6 +487,35 @@ export async function startWorker(
 			// spending delivery is excused). In the compose topology this check is the once-enforcement
 			// layer, because the receiver's single-file :ro mount pins a dead inode until restart.
 			checkOnceSpent: makeCheckOnceSpent({ triggersPath: onceTriggersFile }),
+			// Issue #230. The same file and the same fail-open posture, but its own mtime-cached read: this one
+			// asks whether the AUTHORED entry declares wait conditions the job arrived without, which is how a
+			// service below the version floor turns a wait into a paid run nothing can tell from a correct
+			// one. In the compose topology the worker's read is the live inode while the receiver's is dead
+			// until restart, which is exactly the deployment where the skew happens.
+			checkWaitSkew: makeCheckWaitSkew({ triggersPath: onceTriggersFile }),
+			// Issue #230. Whether a job the supersede lease names is still in the queue. Without it a holder
+			// that vanished by any route except the clean one leaves a key that refuses every later delivery
+			// for that target until it expires -- and a refused forge delivery is gone, since no webhook
+			// resends it. `getJob` answers from the queue rather than from our own bookkeeping, so the two
+			// cannot agree with each other while both being wrong.
+			// REQ-WAIT-FOR's polled tier. Built here for the image and egress preflights' reason: one
+			// deployment value, one place, so the gate that refuses an undeclared profile and the spawn that
+			// runs it cannot disagree about which checks exist. The env-declared table is parsed once at boot
+			// (it is env, not overlay -- the gate reads its config above the per-job settings read).
+			// The free half of the profile check: whether this deployment declares the name at all. A table
+			// lookup, so it belongs with the gate's other free refusals rather than inside the subprocess.
+			waitProfileDeclared: (name) => typeof config.waitProfiles[name] === "string",
+			checkWait: makeWaitChecker({ profiles: config.waitProfiles, timeoutMs: config.waitCheckTimeoutMs, log }),
+			isJobLive: async (id) => {
+				const held = await runtimeQueue.getJob(id);
+				if (!held) return false;
+				// EXISTENCE IS NOT LIVENESS, and the difference decides whether a target stays deafened:
+				// `removeOnComplete`/`removeOnFail` keep a finished job's hash for 31 days, so a holder that
+				// can never wake again would answer "still waiting" for a month. Only a state it can still be
+				// picked up from counts.
+				const state = await held.getState();
+				return state === "delayed" || state === "waiting" || state === "active" || state === "prioritized" || state === "waiting-children";
+			},
 			// One deployment default, two consumers, adjacent by construction: the preflight that refuses a missing
 			// image BEFORE the budget slot, and the factory that puts it in the argv. Both resolve a trigger's own
 			// `run.image` through the same resolveJobImage, so the image that was checked is the image that runs.

package/src/triggers-file.mjs

@@ -376,6 +376,83 @@ export function makeCheckOnceSpent({ triggersPath, fs = nodeFs }) {
 	};
 }
 
+/**
+ * Detect the version skew `run.waitFor` opens (issue #230), pre-spend, from the worker's own file read.
+ *
+ * The hazard is `DES-TRIGGERS-UNIFIED-FILE`'s widening rule arriving somewhere it has never bitten. Unknown
+ * keys DROP, which for every previous field was a harmless no-op: an old parser meeting `run.image` gives
+ * you the default image and a job that ran. `waitFor` is the first field whose ABSENCE is destructive -- a
+ * receiver below the floor enqueues the job without it and the worker runs it UNHELD, producing a record, a
+ * panel row and a log line byte-identical to one that correctly waited. Success is the least detectable
+ * failure available, and the whole point of a wait is that running now is the destructive option.
+ *
+ * `docs/secrets.md`'s answer to the same skew is documentation plus a version floor, and it is not enough
+ * here for two reasons: a dropped secret surfaces as a 401 and an agent report that reads wrong, and
+ * `doctor` cannot see the receiver's installed version from the worker host, so its warning would fire on
+ * every deployment using the feature, forever -- the always-on amber the panel's own design rejects.
+ *
+ * So the worker checks the authored file itself. It already reads it per job for the one-shot gate, and in
+ * the compose topology this read is the authoritative one: the receiver's single-file `:ro` mount pins a
+ * dead inode until restart, which is precisely the deployment where the skew bites.
+ *
+ * FAIL-OPEN throughout, `readDisarmState`'s posture and for its reason: an unreadable or changed file means
+ * "run", because a broken read must never wedge every job. Only a positive, identity-confirmed mismatch --
+ * this entry authored conditions, this job carries none -- refuses.
+ */
+export function makeCheckWaitSkew({ triggersPath, fs = nodeFs }) {
+	// Cached by mtime, unlike `checkOnceSpent` which re-reads every time. The difference is which jobs each
+	// one runs for: the one-shot check is gated on `matched.once === true`, so it is rare by construction and
+	// its comment can call one read cheap. This one has to look at EVERY forge job, because the whole point
+	// is to catch a job that arrived WITHOUT the field, and there is nothing on such a job to narrow by. So a
+	// stat replaces a read-and-parse on the hot path. The residual is millisecond mtime granularity: two
+	// writes inside one millisecond would serve a stale parse for one job, which fails OPEN like every other
+	// uncertainty here.
+	let cache = null; // { mtimeMs, size, triggers }
+	const read = () => {
+		try {
+			const st = fs.statSync?.(triggersPath);
+			if (cache && st && cache.mtimeMs === st.mtimeMs && cache.size === st.size) return cache.triggers;
+			const raw = JSON.parse(fs.readFileSync(triggersPath, "utf8"));
+			const triggers = Array.isArray(raw?.triggers) ? raw.triggers : null;
+			if (st) cache = { mtimeMs: st.mtimeMs, size: st.size, triggers };
+			return triggers;
+		} catch {
+			cache = null;
+			return null;
+		}
+	};
+
+	return async function checkWaitSkew(job) {
+		if (typeof triggersPath !== "string" || triggersPath === "") return { ok: true };
+		// Cron and CLI jobs carry no matched index, and cannot carry `waitFor` at all.
+		const index = job?.trigger?.matched?.index;
+		if (!Number.isInteger(index)) return { ok: true };
+		// The field arrived. Whether its conditions are SATISFIED is the gate's business, not this check's.
+		if (Array.isArray(job?.waitFor) && job.waitFor.length > 0) return { ok: true };
+
+		const triggers = read();
+		if (triggers === null) return { ok: true };
+		const entry = triggers[index];
+		const authored = entry?.run?.waitFor;
+		if (!Array.isArray(authored) || authored.length === 0) return { ok: true };
+
+		// The identity guard readDisarmState keeps, and WIDER than flow alone. `triggerIndex` is a RAW array
+		// position, so an insertion, a reorder, or a stray `triggers.json` at the worker's cwd can all put a
+		// different trigger here -- and two rules sharing a flow are indistinguishable on flow alone, which
+		// made a false refusal reachable by ordinary editing. Kind and on-type are compared too, on
+		// `readDisarmState`'s precedent of checking the item number rather than trusting the index.
+		//
+		// Every mismatch folds to "run", never to a refusal: the true answer to "is this job missing
+		// conditions someone wrote for it?" is then unknown, and unknown must not refuse a paid delivery.
+		if (entry?.run?.flow !== job?.flow || entry?.run?.command !== job?.command) return { ok: true };
+		if (entry?.run?.kind !== job?.kind) return { ok: true };
+		const onType = job?.trigger?.matched?.type;
+		if (typeof onType === "string" && entry?.on?.type !== onType) return { ok: true };
+
+		return { skewed: true, conditions: authored.length };
+	};
+}
+
 export function readDisarmState({ triggersPath, index, number, flow, command, fs = nodeFs }) {
 	let raw;
 	try {

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 });
+		});
+	});
+}