@edgehero/pi-dispatch 1.4.0 → 1.6.0

package/src/queue.mjs

@@ -134,7 +134,7 @@ export async function enqueueGitLabJob(queue, fields) {
  * window, replicas never coalesce against each other, and an unflagged job's dedup id is the same string it
  * has always been.
  */
-export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, packages, image, skillsDir, instructions, resume, secrets, secretsProfile, replica, replicas }) {
+export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, packages, image, skillsDir, instructions, resume, secrets, secretsProfile, waitFor, replica, replicas }) {
 	const jobId = forgeDeliveryJobId(kind, trigger?.deliveryId, replica);
 	// `packages` (whether to load the operator-staged pi packages) and `image` (which container image to run)
 	// come off the MATCHED trigger (INT-TRIGGERS-FILE-CONTRACT / REQ-GLOBAL-PI-OVERLAY) and land on `data`
@@ -179,6 +179,16 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// is copied verbatim into /job/event.json, which an agent reads.
 		...(secrets !== undefined && { secrets }),
 		...(secretsProfile !== undefined && { secretsProfile }),
+		// Issue #230. The conditions the worker holds this job on, carried so the PICKUP gate can read them:
+		// that gate runs above the per-job settings read and never re-parses the triggers file for its terms.
+		// At JOB level, and here that placement is a correctness requirement rather than a convention --
+		// `trigger` is copied VERBATIM into /job/event.json (prepare-local.mjs), so a `trigger.waitFor` would
+		// hand the agent the operator's own gate. Conditional like every field above, so an unflagged job's
+		// data keeps exactly the keys it has today. The dedup options below are deliberately NOT widened for
+		// a waiting job: that key carries no trigger identity and outlives the job it was set for, so a
+		// longer window would suppress an unflagged sibling's deliveries and go on suppressing them after
+		// this job finished. Coalescing a held target is the worker's `wait:` keyspace's job instead.
+		...(waitFor !== undefined && { waitFor }),
 		// Conditional for the same reason packages/image/resume are: an unflagged job's data must keep
 		// exactly the keys it has today. `replica` is this job's 1-based index and `replicas` the set size;
 		// both are integers, so the run record they land in stays PII-free by construction.

package/src/run-history.mjs

@@ -387,7 +387,12 @@ export function buildRecord({ job, result, error, startedAt, endedAt }) {
  * separator from the table, so the notation a forge uses is the notation its records carry -- and a forge
  * added later inherits a label rather than a null.
  */
-function targetFor(kind, data) {
+/*
+ * Exported since issue #230: a held job's panel row needs the same id-only label a run record carries, and
+ * the wait gate would otherwise re-derive it. Two spellings of "which issue is this" is how one of them
+ * starts carrying a title.
+ */
+export function targetFor(kind, data) {
 	if (kind === "local") return `local:${basename(data.folder ?? "")}`;
 	if (isForgeKind(kind)) return `${data.repo}${targetSeparator(kind, data.target?.type)}${data.target?.number}`;
 	return null;

package/src/scoped-limits.mjs

@@ -0,0 +1,277 @@
+/**
+ * Scoped limits (issue #242, INT-SCOPED-LIMITS-FILE-CONTRACT): per-scope run caps and per-scope
+ * concurrency, where a scope is what `scopeOf` already answers -- the folder for a local job, the repo
+ * for a forge one. One `scoped-limits.json` of `{ scope, day?, week?, month?, concurrent? }` entries:
+ * the day/week/month caps refuse a job pre-spend (reason `scope-cap`, a policy refusal), `concurrent`
+ * defers the excess through the delayed set (never a refusal -- a busy scope is transient state).
+ *
+ * This module is pure and fs-injectable (mirrors pause-windows.mjs in every respect): `parseScopedLimits`
+ * validates the file TEXT fail-loud, `loadScopedLimits` layers the one fs read on top, and the small
+ * helpers below are what the processor gate and the budget wiring consume. It also owns the in-process
+ * in-flight counter (`makeInFlight`) so the counter is unit-testable without a bullmq import, the same
+ * reason job-id.mjs is queue-free. The wiring that consumes all of this (the gate, the budget calls,
+ * the admin surfaces) lands in this issue's later slices; the module ships first so the contract has
+ * one implementation to bind to -- sentences below describing enforcement describe THOSE slices.
+ *
+ * The file is a SIBLING of pause-windows.json, not part of the settings overlay, deliberately: the
+ * deferral gate runs before the per-job overlay read, so gate-read config must come from a watched
+ * mutable ref, and the overlay's KNOWN_KEYS are flat scalars whose only map-shaped precedent
+ * (secretProfiles) is deliberately model-unreachable -- the opposite of what these limits need.
+ *
+ * `version` is REQUIRED and fail-loud-on-newer (subscriptions.mjs's rule, adopted here because this is a
+ * MONEY file): unknown fields are silently dropped per the operator-file policy, so a v2 cap field an old
+ * worker drops would be a silently WIDENED spend limit. Pause-windows shipping without a version is a
+ * sunk decision, not a precedent to extend to enforcement config.
+ *
+ * Custom: scoped limits validated inline per triggers.mjs/pause-windows.mjs precedent; zod not in deps
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { configError } from "./config.mjs";
+import { scopeOf } from "./pause-windows.mjs";
+
+/** The schema version this build reads and writes. A file declaring a higher one is refused loudly. */
+export const SCOPED_LIMITS_VERSION = 1;
+
+/** The four limit fields a row may carry, in display order. */
+const LIMIT_FIELDS = ["day", "week", "month", "concurrent"];
+
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * The canonical scope string for a job: the RESOLVED folder path for a local job, the repo for a forge
+ * one. `scopeOf` alone is not enough for enforcement: nothing on the trigger path normalizes
+ * `run.folder`, so `/srv/site`, `/srv/site/`, `/srv//site`, `/srv/x/../site` and a padded spelling are
+ * five distinct strings naming ONE directory -- an exact-string mutex keyed on the raw value would run
+ * them concurrently in one working tree, which is the exact race the mutex exists to close.
+ * `path.resolve` (not `normalize`, which keeps trailing slashes and whitespace) collapses them all; a
+ * relative folder resolves against the worker's cwd, the same base `prepareWorkspace`'s existence check
+ * uses; Unicode is NFC-normalized on both the job and the row side (see below). Two residuals,
+ * deliberate: symlinks are NOT resolved (realpath is an fs call on the hot path and can throw), and
+ * neither is filesystem case-insensitivity (on a default macOS/APFS volume `/Srv/Site` and `/srv/site`
+ * are one directory and two scopes) -- the pause matcher lives with both.
+ *
+ * The pause matcher itself keeps the RAW `scopeOf` value: resolving there would silently change which
+ * jobs an operator's existing trailing-slash window matches. The two features share the folder-vs-repo
+ * split (`scopeOf`, defined once) but not the normalization, and this comment is where that difference
+ * is recorded.
+ *
+ * A useful side effect: a resolved local scope is always an absolute path, and a repo string never is,
+ * so a folder named `a/b` and a repo named `a/b` can no longer collide in the counters or the mutex.
+ */
+export function canonicalScope(job) {
+	const scope = scopeOf(job);
+	if (!isNonEmptyString(scope)) return null;
+	// NFC on both kinds: macOS's filesystem hands paths back NFD while an admin dialog types NFC, so
+	// "wéb" can arrive as two byte sequences naming one thing -- without this, an NFD-spelled forge
+	// scope silently escapes an NFC-spelled cap (the local side would at least keep the structural
+	// mutex). ASCII is fixed under NFC, so no existing key changes.
+	return job?.kind === "local" ? resolve(scope.trim().normalize("NFC")) : scope.normalize("NFC");
+}
+
+/**
+ * Parse, validate, and normalize the scoped-limits file TEXT. Returns the normalized `limits` array
+ * (every row rebuilt as an explicit `{ scope, day, week, month, concurrent }` literal, `null` for absent
+ * fields, unknown fields dropped -- the operator-file policy). Throws `configError` (fail-loud) on any
+ * malformed entry. `path` is for error messages only -- this function touches no filesystem.
+ */
+export function parseScopedLimits(text, path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw configError(`scoped-limits file is not valid JSON: ${path} (${error.message})`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw configError(`scoped-limits file must be an object with "version" and "limits": ${path}`);
+	}
+	const version = parsed.version;
+	if (!Number.isInteger(version) || version < 1) {
+		throw configError(`scoped-limits file must have "version": 1 (an integer >= 1): ${path}`);
+	}
+	if (version > SCOPED_LIMITS_VERSION) {
+		throw configError(`scoped-limits file written by a newer pi-dispatch (version ${version}; this build understands ${SCOPED_LIMITS_VERSION}): ${path}`);
+	}
+	if (!Array.isArray(parsed.limits)) {
+		throw configError(`scoped-limits file must have a "limits" array: ${path}`);
+	}
+	const rows = parsed.limits.map((row, index) => normalizeLimit(row, index, path));
+	const seen = new Map();
+	rows.forEach((row, index) => {
+		if (seen.has(row.scope)) {
+			// Two rows for one scope is a precedence question with no right answer; the admin's
+			// edit-in-place never produces one, so a duplicate is always a hand-edit mistake.
+			throw configError(`scoped limit at index ${index}: duplicate scope ${JSON.stringify(row.scope)} (first at index ${seen.get(row.scope)}): ${path}`);
+		}
+		seen.set(row.scope, index);
+	});
+	return rows;
+}
+
+function normalizeLimit(row, index, path) {
+	const at = `scoped limit at index ${index}`;
+	if (row === null || typeof row !== "object" || Array.isArray(row)) {
+		throw configError(`${at}: must be an object: ${path}`);
+	}
+	if (!isNonEmptyString(row.scope)) throw configError(`${at}: scope must be a non-empty string: ${path}`);
+	const trimmed = row.scope.trim().normalize("NFC"); // the same NFC canonicalScope applies job-side
+	if (trimmed === "*") {
+		// "*" as ONE shared counter is redundant with the global caps, so the only useful reading is a
+		// per-scope default -- the OPPOSITE of what "*" means one file over (pause-windows: one rule
+		// matching all scopes). Refused rather than shipped divergent; a later version may adopt the
+		// per-scope-default reading, with an exact row beating "*" (recorded in the contract).
+		throw configError(`${at}: "*" is not supported -- add one row per scope (a per-scope default may adopt "*" later): ${path}`);
+	}
+	if (trimmed.includes("*")) {
+		// No globs, enforced rather than described: an exact matcher makes "acme/*" a row that governs
+		// nothing, and a silently inert money limit is the failure class this repo refuses outright.
+		throw configError(`${at}: scopes match exactly; a scope containing "*" is refused (no globs): ${path}`);
+	}
+	const norm = {
+		// An absolute path is stored resolved so a `/srv/site/` row governs `/srv/site` jobs -- the same
+		// collapse canonicalScope applies on the job side. isAbsolute is PLATFORM-NATIVE on purpose, so a
+		// foreign-platform row (a windows drive path on a POSIX worker) stays verbatim and is inert here;
+		// the doctor's unreferenced-scope advisory names it. Resolving it instead would "work" only by
+		// both sides mangling into the same cwd-prefixed string -- a match by accident, not by contract.
+		scope: isAbsolute(trimmed) ? resolve(trimmed) : trimmed,
+		day: null,
+		week: null,
+		month: null,
+		concurrent: null,
+	};
+	let any = false;
+	for (const field of LIMIT_FIELDS) {
+		const value = row[field];
+		// Absent-or-null (subscriptions.mjs's rule): null is the normalizer's OWN output for an unset
+		// field, so the parser must accept it back or it cannot re-parse what it produced -- the admin's
+		// read-modify-write goes through this parser on both edges.
+		if (value === undefined || value === null) continue;
+		// 0 is refused, not "never run": budget.mjs's caps treat every configured window as >= 1, and
+		// "never run this scope" already has two honest spellings (delete the trigger; a pause window).
+		// isSafeInteger, not isInteger: 1e21 passes isInteger and reads as a limit while being
+		// indistinguishable from unlimited -- a bound that cannot count is not a bound.
+		if (!Number.isSafeInteger(value) || value < 1) {
+			throw configError(`${at}: ${field} must be an integer >= 1: ${path}`);
+		}
+		norm[field] = value;
+		any = true;
+	}
+	if (!any) {
+		throw configError(`${at}: at least one of day, week, month, concurrent is required (a row that limits nothing is a row an operator sets and then trusts): ${path}`);
+	}
+	return norm;
+}
+
+/**
+ * Load and validate the scoped-limits file named by `config.scopedLimitsFile`. Returns `[]` when the file
+ * is unset (no scoped caps or concurrency -- a valid deployment; the folder mutex holds regardless, it is
+ * code, not configuration). `readFileSync`/`existsSync` are injectable for tests.
+ */
+export function loadScopedLimits(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const path = config.scopedLimitsFile;
+	if (path === null || path === undefined) return [];
+	if (!existsSync(path)) throw configError(`scoped-limits file does not exist: ${path}`);
+	return parseScopedLimits(readFileSync(path, "utf8"), path);
+}
+
+/**
+ * The exact-match row for a canonical scope, or null. Exact string equality only -- the pause matcher's
+ * semantics minus its "*" (refused above). With duplicates refused there is no precedence ladder.
+ */
+export function limitFor(limits, scope) {
+	if (!Array.isArray(limits) || !isNonEmptyString(scope)) return null;
+	return limits.find((l) => l.scope === scope) ?? null;
+}
+
+/**
+ * The scoped budget windows this job reserves against, or null when nothing applies (no row for the
+ * scope, or the row is concurrency-only). The returned `scope` is CANONICAL so the redis counters are
+ * spelling-stable. Shaped like the global `caps` object so `reserveBudget` consumes it unchanged.
+ */
+export function budgetCapsFor(job, limits) {
+	const scope = canonicalScope(job);
+	const row = limitFor(limits, scope);
+	if (!row || (row.day === null && row.week === null && row.month === null)) return null;
+	return { scope, caps: { day: row.day, week: row.week, month: row.month } };
+}
+
+/**
+ * The effective in-flight ceiling for this job's scope: `min(configured concurrent, structural)`, where
+ * structural is 1 for a local job -- the folder mutex -- and unbounded otherwise. The mutex is
+ * UNCONDITIONAL, in code, with no file configured and no off-switch: two agents in one bind-mounted
+ * working tree is the race `run.replicas` is already refused on local jobs for, and a cron trigger
+ * reaches it with no operator mistake at all (the scheduler mints the next occurrence at pickup and
+ * promotes on time alone, so a slow run overlaps its own successor). A configured `concurrent` above 1
+ * on a folder scope silently clamps to 1 rather than refusing at parse: scope strings are not reliably
+ * typeable as folder-vs-repo (`"a/b"` is a legal relative folder and a legal repo), so a parse-time
+ * classifier would misfire; min() cannot.
+ *
+ * No scope (a malformed payload) means no gate: Infinity, admit -- the job will fail its own validation
+ * downstream, and holding a mutex slot under key `null` helps nobody.
+ */
+export function concurrencyFor(job, limits) {
+	const scope = canonicalScope(job);
+	if (scope === null) return Infinity;
+	const structural = job?.kind === "local" ? 1 : Infinity;
+	const configured = limitFor(limits, scope)?.concurrent ?? Infinity;
+	return Math.min(structural, configured);
+}
+
+/**
+ * The redis key prefix for a scope's budget windows: `budget:s:<16 hex>`. Handed to
+ * `reserveBudget`/`releaseBudget` as `keyPrefix`, so `dayKey`/`weekKey`/`monthKey` compose
+ * `budget:s:<h>:YYYY-MM-DD` / `:w:...` / `:m:...` with zero new key-shape logic. A hash (the localJobId
+ * idiom: sha256, first 16 hex) rather than an escape: a scope legally contains `:` and `/` (folder
+ * paths, gitlab group/subgroup/project), which would collide with budget.mjs's own `w:`/`m:`/`t:`
+ * sub-namespaces, and a bijective escape grammar is a new thing to get wrong with unbounded key lengths.
+ * The one consumer that must map keys BACK to scopes is the admin's counter display, and it knows the
+ * configured scopes -- it recomputes keys through this same export, so unreadability in redis-cli is the
+ * accepted cost.
+ */
+export function scopeKeyPrefix(scope) {
+	const h = createHash("sha256").update(String(scope)).digest("hex").slice(0, 16);
+	return `budget:s:${h}`;
+}
+
+/**
+ * The per-process in-flight counter behind per-scope concurrency and the folder mutex. Process memory is
+ * the CORRECT store, not a compromise: one worker per docker daemon is the shape DES-CONCURRENCY-3
+ * assumes everywhere and `service install` enforces for installed units (`pi-dispatch start` holds no
+ * lock, and two hand-run workers are already unsupported -- the second one's boot reaper kills the
+ * first's live containers); the reaper removes every surviving `pi-job-*` container before the worker
+ * starts draining, so a fresh, empty map is never wrong about a live container except when the reap
+ * itself was skipped (`reaper_skipped`: docker missing/down at boot -- a state where no NEW container
+ * can start either); and a Redis-held counter would survive a crash WRONGLY -- a claim for a container
+ * the reaper just killed, demanding TTL/heartbeat machinery, a second source of truth about "what is
+ * running" (the OQ-008 failure mode).
+ *
+ * `tryAcquire` is a synchronous check-and-increment: no await between the read and the take, so under
+ * Node's single thread no interleaving exists at any concurrency. `release` never throws -- it runs in
+ * the processor's finally, where a throw would mask the job's real error -- and clamps at zero.
+ */
+export function makeInFlight() {
+	const counts = new Map();
+	return {
+		/** True and counted when under `limit`; false WITHOUT counting when at or over it. */
+		tryAcquire(scope, limit) {
+			const current = counts.get(scope) ?? 0;
+			if (current >= limit) return false;
+			counts.set(scope, current + 1);
+			return true;
+		},
+		/** Decrement, deleting at zero; a release without a matching acquire is a no-op, never a throw. */
+		release(scope) {
+			const current = counts.get(scope) ?? 0;
+			if (current <= 1) counts.delete(scope);
+			else counts.set(scope, current - 1);
+		},
+		/** The current in-flight count for a scope (tests and future observability). */
+		count(scope) {
+			return counts.get(scope) ?? 0;
+		},
+	};
+}

package/src/service.mjs

@@ -972,6 +972,15 @@ async function doRestart(ctx, values) {
 			await ctx.sleep(2000);
 			({ active = 0 } = await queue.getJobCounts("active"));
 		}
+		// A HELD job is neither active nor waiting, so the loop above has just reported a drained queue with
+		// however many jobs still parked on `run.waitFor` (issue #230). They are safe -- a hold spends
+		// nothing, survives a restart and reserves no slot -- but the operator is upgrading, and those jobs
+		// will wake against the new version. Said plainly rather than left to be discovered, which is what
+		// this command would otherwise be doing: reporting a drained queue it cannot see all of.
+		const delayed = await queue.getJobCounts("delayed").then((c) => Number(c?.delayed ?? 0), () => 0);
+		if (delayed > 0) {
+			ctx.out(`note: ${delayed} job(s) sit in the delayed set (cron next-occurrences, retry backoff, quiet hours, or jobs held on run.waitFor). None is active, so none blocked this drain; they will wake against the new version.\n`);
+		}
 		const stopped = await doStop(ctx);
 		if (stopped !== 0) {
 			ctx.out("restart did not happen — the queue STAYS PAUSED; fix the service, then `pi-dispatch resume`.\n");

package/src/start.mjs

@@ -22,8 +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";
@@ -103,6 +106,42 @@ function watchPauseWindowsFile(config, ref, log) {
 	}
 }
 
+/**
+ * The scoped-limits reload, EXPORTED apart from its watcher so keep-last-good is unit-testable without
+ * fs.watch (its two watcher siblings above bind theirs inline; this one is money config, so the
+ * last-good property carries its own test). A bad edit keeps `ref.current` untouched and logs
+ * `scoped_limits_reload_invalid` -- the pause-windows posture, INT-SCOPED-LIMITS-FILE-CONTRACT.
+ */
+export function reloadScopedLimits(config, ref, log) {
+	try {
+		ref.current = loadScopedLimits(config);
+		log("scoped_limits_reloaded", { count: ref.current.length });
+	} catch (err) {
+		log("scoped_limits_reload_invalid", { reason: err?.message });
+	}
+}
+
+/**
+ * Watch the scoped-limits file (issue #242) the way the pause-windows watcher above does: the DIRECTORY,
+ * for atomic tmp+rename robustness, filtered to the one basename, debounced. Best-effort + unref'd.
+ */
+function watchScopedLimitsFile(config, ref, log) {
+	const path = config.scopedLimitsFile;
+	const dir = dirname(path) || ".";
+	const file = basename(path);
+	let timer = null;
+	try {
+		watch(dir, (_event, changed) => {
+			if (changed && changed !== file) return;
+			clearTimeout(timer);
+			timer = setTimeout(() => reloadScopedLimits(config, ref, log), 150);
+		}).unref?.();
+		log("scoped_limits_watching", { path });
+	} catch (err) {
+		log("scoped_limits_watch_unavailable", { reason: err?.message });
+	}
+}
+
 export function makeReaper({ log }) {
 	return async function reap() {
 		try {
@@ -188,6 +227,10 @@ export async function startWorker(
 	// pauses. Held in a mutable ref so the live-reload watcher can hot-swap it. [] means no scoped pauses.
 	const pauseWindows = { current: loadPauseWindows(config) };
 
+	// Issue #242: same posture for the scoped-limits file -- fail-loud with the operator present, mutable
+	// ref for the live-reload watcher, [] when unset (the folder mutex is code and needs no file).
+	const scopedLimits = { current: loadScopedLimits(config) };
+
 	// The forge a job belongs to is resolved PER JOB from `job.kind`, not bound once for the process.
 	// Each entry is `{ auth, host }`: `auth` is get-token's `{ mintToken, selfId, source }` (null when that
 	// forge is unconfigured or unreachable), `host` is the three methods github-host.mjs returns. The map
@@ -422,6 +465,21 @@ export async function startWorker(
 		// REQ-SCOPED-PAUSE-WINDOWS: the processor defers a job whose folder/repo is inside an active window.
 		// Reads the live-reloaded ref, so an operator edit takes effect on the next job without a restart.
 		pauseUntil: (job, now) => pauseUntilMs(pauseWindows.current, job, now),
+		// 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
@@ -429,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.
@@ -595,6 +682,11 @@ export async function startWorker(
 		watchPauseWindowsFile(config, pauseWindows, log);
 	}
 
+	// Issue #242 live edit: hot-swap the scoped limits on file change, keeping last-good on a bad edit.
+	if (config.scopedLimitsFile) {
+		watchScopedLimitsFile(config, scopedLimits, log);
+	}
+
 	log("worker_started", {
 		queue: "pi-jobs",
 		concurrency: bootConcurrency, // the slot count the Worker is actually constructed with (overlay may raise/lower it)
@@ -602,6 +694,8 @@ export async function startWorker(
 		weeklyCap: config.weeklyCap, // null when the weekly window is disabled
 		monthlyCap: config.monthlyCap, // null when the monthly window is disabled
 		softHoldPct: config.softHoldPct, // null when the soft-hold band is disabled
+		scopedLimitsFile: config.scopedLimitsFile, // null = no scoped caps/concurrency (the folder mutex holds regardless)
+		scopedLimits: scopedLimits.current.length, // row count -- money config deserves boot visibility; the watcher logs only changes
 		image: config.jobImage,
 		valkey: config.valkeyUrl,
 		logsDir: config.logsDir,

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 {