@edgehero/pi-dispatch 1.6.1 → 1.8.0

package/src/queue.mjs

@@ -8,10 +8,67 @@ import { PR_CLOSE_ACTIONS } from "./triggers.mjs";
 const PR_CLOSE_WORDS = new Set(Object.values(PR_CLOSE_ACTIONS));
 
 export const QUEUE = "pi-jobs";
+
+/**
+ * The queue a HOST-AFFINE job goes to (issue #57): work only one machine can do, because the folder, the
+ * secret resolver or the wait-check script lives there.
+ *
+ * `@` is the separator because it is outside the worker-name charset (`[A-Za-z0-9._-]`), so
+ * `pi-jobs@<name>` decomposes unambiguously and a name can never contain one. A SUFFIX rather than a
+ * prefix so `KEYS bull:pi-jobs*` still shows an operator the whole deployment.
+ *
+ * Deliberately a separate queue rather than a field the pickup gate filters on. BullMQ has no selective
+ * pop, so filtering would mean taking a job and putting it back -- and promotion out of the delayed set is
+ * gated on each worker's OWN `Date.now()` in two places, so the host whose clock runs fastest wins every
+ * hop deterministically. A job that had to reach a different host might never get there, and jitter cannot
+ * fix it: it randomises WHEN the wake is, not WHO wins it.
+ */
+export const hostQueueName = (worker) => `${QUEUE}@${worker}`;
+
+/**
+ * Every queue name this deployment drains: the shared one, plus one per named host (issue #57).
+ *
+ * Derived from the REGISTRY rather than from configuration, because the reader is usually the admin or
+ * the CLI, which know their own host at best and the fleet not at all. A deployment with no named worker
+ * that declared NO name yields exactly `[QUEUE]`, so every existing caller is unchanged. Note that this
+ * is derived from `routes`, not from a row existing: every worker publishes a row, named or not.
+ *
+ * This exists because a host queue that no reader knows about is worse than no host queue: the panel
+ * would show zero schedulers while cron ran, and `pi-dispatch pause` would stop half a deployment while
+ * reporting success -- the silent no-op its own comment already warns about for a mistyped name.
+ */
+export function fleetQueueNames(hosts) {
+	const seen = new Set();
+	for (const h of hosts ?? []) {
+		// A host has a queue only when it DECLARED a name. Every worker publishes a registry row -- that is
+		// what lets an unnamed fleet be seen at all -- but an undeclared one drains only the shared queue,
+		// so deriving queue names from every row would invent `pi-jobs@<hostname>` for a queue nothing
+		// reads: pausing it would create a real key for a phantom, and the counts would be a queue that can
+		// never have jobs.
+		if (h?.routes !== true && h?.routes !== "true") continue;
+		const name = h?.name;
+		// VALIDATED, because this is peer-written data crossing a trust boundary. `hostQueueName`'s own
+		// contract leans on the charset -- `@` is the separator precisely because a name cannot contain one
+		// -- and nothing else re-checks it. A name with a `:` makes `new Queue` throw, which would take the
+		// kill switch out entirely; one with an `@` would not decompose.
+		if (typeof name !== "string" || !WORKER_NAME_RE.test(name)) continue;
+		seen.add(name);
+	}
+	// Deduped: two rows naming one host would double-count its jobs in a summed status.
+	return [QUEUE, ...[...seen].sort().map(hostQueueName)];
+}
+
+/** The name charset, duplicated from `config.mjs` deliberately: this module imports nothing. */
+const WORKER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
 export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId };
 
-export function makeQueue(connection) {
-	return new Queue(QUEUE, { connection });
+/**
+ * A queue handle. `name` defaults to the shared queue, so every existing caller is unchanged and a
+ * single-host deployment never names anything else.
+ */
+export function makeQueue(connection, { name = QUEUE } = {}) {
+	return new Queue(name, { connection });
 }
 
 /**
@@ -226,3 +283,74 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 	});
 	return jobId;
 }
+
+/**
+ * Every host queue that EXISTS, read from BullMQ's own keyspace rather than from the host registry.
+ *
+ * The registry answers "who is alive", and for a kill switch that is the wrong question. A host whose
+ * registry writes fail for ninety seconds loses its row while its BullMQ worker -- a separate connection,
+ * built with `maxRetriesPerRequest: null` precisely to ride out blips -- keeps draining. Pausing "the
+ * fleet" would then miss it and report success. The same gap opens for the ~15s before a booting worker's
+ * first beat lands, and on every `service restart`, since a clean shutdown DELs the row.
+ *
+ * Worse is the direction with no recovery path: pause while a host is live durably pauses its queue, and a
+ * later resume while that host is DOWN enumerates nothing for it. The queue stays paused permanently, and
+ * no surface can see it, because every surface was reading the registry too.
+ *
+ * A queue's meta key is durable and outlives its worker, so this asks the only authority that cannot go
+ * stale: the queues themselves. It also restores what `host-registry.mjs` claims about itself -- delete the
+ * whole `host:*` keyspace and nothing decides differently -- which the registry-derived kill switch had
+ * quietly made false.
+ *
+ * SCAN, not KEYS, and it is why this is NOT on the panel's per-tick path: it is for the rare command where
+ * being wrong costs money, not for a reader that runs every second. Fails open to `[]`, so an unreadable
+ * keyspace degrades to the registry's answer rather than refusing.
+ */
+export async function discoverHostQueues(redis, { timeoutMs = 2_000, count = 500 } = {}) {
+	const prefix = `bull:${QUEUE}@`;
+	const names = new Set();
+	try {
+		const deadline = Date.now() + timeoutMs;
+		let cursor = "0";
+		do {
+			// BOUNDED, because BullMQ's connections carry `maxRetriesPerRequest: null` and a command against
+			// an unreachable server therefore QUEUES FOREVER rather than rejecting -- so an unguarded await
+			// here would hang the kill switch instead of failing it open. The same trap the registry's
+			// `bounded` exists for.
+			//
+			// CLEARED on the way out, and NOT `unref`'d. Leaving it pending held the event loop open for the
+			// rest of the budget after the work was done, so `pi-dispatch pause` sat for two seconds having
+			// already paused everything; unref'ing instead would stop it firing when the hang is the last
+			// thing on the loop, which is the one case it exists for.
+			let timer;
+			const [next, keys] = await Promise.race([
+				redis.scan(cursor, "MATCH", `${prefix}*:meta`, "COUNT", count),
+				new Promise((_, reject) => {
+					timer = setTimeout(() => reject(new Error("scan timed out")), Math.max(1, deadline - Date.now()));
+				}),
+			]).finally(() => clearTimeout(timer));
+			cursor = next;
+			for (const key of keys ?? []) {
+				const name = String(key).slice(prefix.length, -":meta".length);
+				// Validated like every other peer-derived name: a key an operator hand-created could hold
+				// anything, and `new Queue` throws on a `:`, which would take the kill switch out entirely.
+				if (WORKER_NAME_RE.test(name)) names.add(name);
+			}
+		} while (cursor !== "0" && Date.now() < deadline);
+	} catch {
+		// Fail open: the registry's answer alone is still better than refusing to pause.
+		return [];
+	}
+	return [...names].sort().map(hostQueueName);
+}
+
+/**
+ * The union of what is LIVE (the registry) and what EXISTS (the keyspace), which is the set a kill switch
+ * must act on: a live host with no queue yet has nothing to pause, and a dead host's queue still holds
+ * jobs and still has a paused flag somebody has to be able to clear.
+ */
+export function unionQueueNames(fromRegistry, fromKeyspace) {
+	const seen = new Set([...(fromRegistry ?? []), ...(fromKeyspace ?? [])]);
+	seen.delete(QUEUE);
+	return [QUEUE, ...[...seen].sort()];
+}

package/src/run-history.mjs

@@ -378,7 +378,7 @@ function rebuildUsage(u) {
  * default to `null` when the outcome does not carry them, so the record shape is stable whether or not
  * the source reports those fields.
  */
-export function buildRecord({ job, result, error, startedAt, endedAt }) {
+export function buildRecord({ job, result, error, startedAt, endedAt, host = null }) {
 	const data = job.data ?? {};
 	const kind = data.kind ?? job.name;
 	const source = result ?? error ?? {};
@@ -441,6 +441,28 @@ export function buildRecord({ job, result, error, startedAt, endedAt }) {
 		// BRANCH NAME ARE DELIBERATELY ABSENT: this record's PII-free-by-construction property rests on it
 		// holding no attacker-chosen string, and a branch name is exactly that.
 		session: source.session ?? null,
+		// Which machine ran this (issue #57). Additive, nullable, an explicit literal, TAIL position: every
+		// prior addition took the tail, and "field order is the serialisation order" is this record's
+		// contract, so the tail is the only placement that leaves twenty-four existing positions untouched.
+		// Unconditional rather than a conditional spread, on the same contract sentence and on the
+		// `tokens`/`usage`/`session` precedent that null-with-the-key-present is this record's normal case.
+		//
+		// ADMISSIBILITY, which has to engage this record's own sentences rather than sidestep them. The
+		// PII-free-by-construction property rests on holding NO ATTACKER-CHOSEN STRING, and `host`
+		// satisfies that absolutely: there is no path from a webhook payload, an issue body, a branch name
+		// or a folder to this value. It is fixed once at boot from one environment variable against a
+		// charset that excludes `/` and `\`, so it cannot even be path-shaped -- which is the property
+		// `targetFor` drops a local folder to its basename to get.
+		//
+		// What it is NOT is anonymous, and that is worth writing down rather than glossing. The default is
+		// `os.hostname()`, and on a personal machine a hostname is often a person's name. The honest word
+		// is OPERATOR-DISCLOSED: the operator names their own machines, this record is written to their own
+		// disk, that name is already on every packet the machine sends, and `PI_WORKER_NAME` is the
+		// documented answer for anyone who wants something else here.
+		//
+		// Passed in rather than read from a module-level value, so `buildRecord` stays pure and every
+		// existing caller keeps getting `null` without knowing this field exists.
+		host,
 	};
 }
 

package/src/run-mirror.mjs

@@ -0,0 +1,221 @@
+/**
+ * A fleet-visible copy of the run history (issue #57, Gap 3).
+ *
+ * Every worker writes its records to its own `PI_LOGS_DIR`, so on more than one machine each host's panel
+ * lists only the runs on its own disk. The operator sees a third of their deployment and has no way to
+ * know it.
+ *
+ * SHARED STORAGE IS THE OTHER ANSWER AND IT IS NOT SECOND-BEST. On a shared `PI_LOGS_DIR` the local read
+ * IS the merged read, with no machinery at all, and this module is redundant. It ships because that trade
+ * runs both ways and an operator must be allowed to decline it: sharing the directory also shares the
+ * PII-bearing raw `.log`, and a mount outage becomes a LOST RECORD where a Valkey outage costs only a
+ * fleet view. Both shapes work; `docs/multi-host.md` says which is which.
+ *
+ * THE FILE IS THE RECORD AND THIS IS A VIEW. Three things follow, and each is load-bearing:
+ *
+ *   - The file is written FIRST, always. A crash between the two leaves a fleet-visible run whose durable
+ *     source does not exist, which inverts the one claim this design rests on.
+ *   - The mirror's TTL is never longer than the file retention window, so it can never show a run whose
+ *     file has already been reaped. A view that outlives its source is a second source of truth, which is
+ *     exactly what `DES-RUN-HISTORY-FLAT-FILES-NO-DB` refuses.
+ *   - Nothing derived is stored. The bytes are the sidecar's own bytes, so there is nothing to be stale
+ *     RELATIVE TO: a retry overwrites the same key exactly as it overwrites the same file, and cost
+ *     classification is still computed at fold time from `subscriptions.json` rather than frozen here.
+ *
+ * WHY THE WHOLE RECORD RATHER THAN A PROJECTION. The record is PII-free BY CONSTRUCTION -- it holds no
+ * attacker-chosen string, which `INT-RUN-HISTORY-FILE-CONTRACT` states and `buildRecord` enforces field by
+ * field. Copying it whole inherits that property; a projection would re-derive it at a second serialiser,
+ * where the next person to add a field has to remember this file exists. It is also what the readers need:
+ * the cost fold, the graph and the insights view read eleven fields between them.
+ *
+ * NOT MIRRORED: the raw `.log`. It is the one artifact here that holds issue text, comment text and tool
+ * output, and mirroring it would move that off the machine the operator chose to keep it on. A foreign
+ * run's record names its host, so the panel can say where the bytes are rather than pretending there are
+ * none.
+ */
+
+/** The index: sanitized jobId -> the run's end (or start) in millis. */
+export const RUNS_INDEX = "runs:index";
+
+/** One run's own bytes. */
+export const runRecordKey = (sanitizedJobId) => `runs:rec:${sanitizedJobId}`;
+
+/**
+ * The deepest any reader asks. `SCAN_WINDOW_MAX_DAYS` in the admin is 92, so a longer window would hold
+ * bytes nothing can request.
+ */
+export const MIRROR_MAX_DAYS = 92;
+
+/**
+ * A hard ceiling on index members, independent of the time window.
+ *
+ * The window alone does not bound memory: a deployment running thousands of jobs a day would hold a
+ * quarter of a million members for ninety-two days. This caps what the fleet view can cost at roughly the
+ * depth a panel can display, and the file on disk remains the complete history either way.
+ */
+export const RUNS_INDEX_MAX = 5_000;
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const OP_TIMEOUT_MS = 2_000;
+
+/**
+ * How long a mirrored record lives.
+ *
+ * Never longer than the operator's own retention, and never longer than what any reader asks for.
+ * `retentionDays: 0` means keep the files forever, which is the one case where the mirror is the shorter
+ * of the two, so it clamps to the reader's ceiling rather than to infinity.
+ */
+export function mirrorWindowMs(retentionDays) {
+	const days = Number(retentionDays) > 0 ? Math.min(Number(retentionDays), MIRROR_MAX_DAYS) : MIRROR_MAX_DAYS;
+	return days * DAY_MS;
+}
+
+/**
+ * BullMQ's connections carry `maxRetriesPerRequest: null`, so a command against an unreachable server
+ * QUEUES FOREVER rather than rejecting. Every await here is bounded for that reason; an unbounded one
+ * would not fail the mirror, it would hang the job that was writing to it.
+ */
+function bounded(promise, ms) {
+	let timer;
+	return Promise.race([
+		promise,
+		new Promise((_, reject) => {
+			timer = setTimeout(() => reject(new Error("mirror timeout")), ms);
+		}),
+	]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * The writer. Returns `{ mirror, close }`; `mirror` never throws and never rejects.
+ *
+ * A history blip must not fail a job that has already run and already been recorded to disk. Every failure
+ * here costs a row in a fleet view and nothing else, which is why the whole body is wrapped and the result
+ * is a boolean nobody is obliged to read.
+ */
+export function makeRunMirror({ redis, retentionDays, now = () => Date.now(), log = () => {}, timeoutMs = OP_TIMEOUT_MS, indexMax = RUNS_INDEX_MAX } = {}) {
+	const windowMs = mirrorWindowMs(retentionDays);
+	let warned = false;
+
+	return {
+		async mirror(record, sanitizedJobId) {
+			if (!redis || !record || !sanitizedJobId) return false;
+			try {
+				const at = Date.parse(record.endedAt ?? record.startedAt ?? "");
+				const score = Number.isFinite(at) ? at : now();
+				const body = JSON.stringify(record);
+				await bounded(redis.set(runRecordKey(sanitizedJobId), body, "PX", windowMs), timeoutMs);
+				await bounded(redis.zadd(RUNS_INDEX, score, sanitizedJobId), timeoutMs);
+				// Trimmed by the WRITER, twice: by age, and by count. Two `ZREMRANGE`s against a run that
+				// took minutes is free, and it means no reader has to pay for a backlog it did not create.
+				await bounded(redis.zremrangebyscore(RUNS_INDEX, "-inf", `(${now() - windowMs}`), timeoutMs);
+				await bounded(redis.zremrangebyrank(RUNS_INDEX, 0, -indexMax - 1), timeoutMs);
+				// ROLLING expiry, deliberately unlike `budget.mjs`'s set-once rule and deliberately like
+				// `pi-dispatch:sched-stalls`. A budget window must not be pushed forward by traffic or a busy
+				// day never resets; an ACTIVITY index should roll with traffic, because that is what it
+				// describes. A fleet that stops running jobs loses its index one window later, which is
+				// correct: there is nothing left to show.
+				await bounded(redis.pexpire(RUNS_INDEX, windowMs), timeoutMs);
+				warned = false;
+				return true;
+			} catch (err) {
+				// Once per transition, not once per job: a Valkey outage during a busy hour must not turn one
+				// fault into a thousand log lines (`notePackageKey`'s precedent).
+				if (!warned) {
+					warned = true;
+					log("run_mirror_failed", { jobId: sanitizedJobId, reason: err?.message });
+				}
+				return false;
+			}
+		},
+	};
+}
+
+/**
+ * The reader. Returns `{ runs, degraded }` and never throws.
+ *
+ * `degraded` is a DISCRIMINATED channel rather than a silence, and two of its values must not collapse:
+ * `"off"` means the index is absent, which is what a single-host deployment and a fleet of workers still
+ * below the version floor both look like, while `"unreachable"` means we could not tell. A new panel
+ * meeting old workers has to read "off", not "error".
+ *
+ * Two round trips regardless of how many runs come back: one `ZREVRANGEBYSCORE` for the ids, one `MGET`
+ * for the bodies. Never one read per run.
+ */
+export async function readMirroredRuns(redis, { limit = 50, sinceMs = 0, now = () => Date.now(), timeoutMs = OP_TIMEOUT_MS } = {}) {
+	if (!redis) return { runs: [], degraded: "off" };
+	let ids;
+	try {
+		ids = await bounded(redis.zrevrangebyscore(RUNS_INDEX, "+inf", `(${sinceMs}`, "LIMIT", 0, Math.max(1, limit)), timeoutMs);
+	} catch (err) {
+		return { runs: [], degraded: `unreachable (${err?.message ?? "?"})` };
+	}
+	if (!Array.isArray(ids) || ids.length === 0) return { runs: [], degraded: "off" };
+
+	let bodies;
+	try {
+		bodies = await bounded(redis.mget(...ids.map(runRecordKey)), timeoutMs);
+	} catch (err) {
+		return { runs: [], degraded: `unreachable (${err?.message ?? "?"})` };
+	}
+
+	const runs = [];
+	const stale = [];
+	for (let i = 0; i < ids.length; i++) {
+		const raw = bodies?.[i];
+		if (typeof raw !== "string" || raw === "") {
+			// An id whose body has expired: the per-key TTL fired and the index member outlived it. The
+			// READER prunes it, which is what `wait:held` does for the same shape and for the same reason --
+			// a writer that crashed cannot clean up after itself, and a reader is already here.
+			stale.push(ids[i]);
+			continue;
+		}
+		try {
+			const rec = JSON.parse(raw);
+			if (rec && typeof rec === "object") runs.push(rec);
+		} catch {
+			stale.push(ids[i]); // unparseable is indistinguishable from gone, and equally not showable
+		}
+	}
+	if (stale.length > 0) {
+		try {
+			await bounded(redis.zrem(RUNS_INDEX, ...stale), timeoutMs);
+		} catch {
+			// best-effort: a straggler in the index costs one skipped row next time, never a wrong one
+		}
+	}
+	return { runs, degraded: runs.length >= limit ? "truncated" : "ok" };
+}
+
+/**
+ * One list from two sources.
+ *
+ * DEDUP BY LATER `endedAt`, LOCAL BREAKS A TIE. Not decoration: a retry can land on a different host, so
+ * host A may hold attempt 0 (failed) while host B mirrored attempt 1 (completed). "Local wins" alone would
+ * show the stale one. Local breaking an exact tie keeps a single-host deployment reading its own files.
+ *
+ * CUT AFTER THE SORT, never before. Slicing first is the defect `held.test.mjs` already exists to prevent:
+ * it makes the result depend on which source happened to be longer.
+ */
+export function mergeRuns(local, mirrored, { limit = 50 } = {}) {
+	const by = new Map();
+	const at = (r) => {
+		const t = Date.parse(r?.endedAt ?? r?.startedAt ?? "");
+		return Number.isFinite(t) ? t : -Infinity;
+	};
+	// Mirrored first, so a local record with an equal timestamp overwrites it on the second pass.
+	for (const r of Array.isArray(mirrored) ? mirrored : []) if (r?.jobId) by.set(r.jobId, r);
+	for (const r of Array.isArray(local) ? local : []) {
+		if (!r?.jobId) continue;
+		const seen = by.get(r.jobId);
+		if (!seen || at(r) >= at(seen)) by.set(r.jobId, r);
+	}
+	const out = [...by.values()].sort((a, b) => at(b) - at(a));
+	return out.slice(0, Math.max(0, limit));
+}
+
+/** The distinct hosts a merged list came from, computed from the RECORDS rather than from the mirror. */
+export function hostsIn(runs) {
+	const names = new Set();
+	for (const r of runs ?? []) if (typeof r?.host === "string" && r.host !== "") names.add(r.host);
+	return [...names].sort();
+}

package/src/schedules.mjs

@@ -23,7 +23,7 @@ import { parseTriggers } from "./triggers.mjs";
  * valid deployment. `readFileSync`/`existsSync` are injectable so tests exercise the full path with no
  * real filesystem.
  */
-export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync, fleet = false } = {}) {
 	const path = config.triggersFile;
 	if (path === null || path === undefined) return []; // cron disabled
 
@@ -33,14 +33,77 @@ export function loadSchedules(config, { readFileSync = fsReadFileSync, existsSyn
 
 	const triggers = parseTriggers(readFileSync(path, "utf8"), path);
 
-	return triggers.filter((t) => t.on.type === "cron").map((t) => normalizeCronSchedule(t, path, existsSync));
+	return triggers.filter((t) => t.on.type === "cron").map((t) => normalizeCronSchedule(t, path, existsSync, fleet));
 }
 
-function normalizeCronSchedule({ on, run }, path, existsSync) {
+/**
+ * The cron set AS AUTHORED, before any placement decision (issue #57).
+ *
+ * This is the object two hosts have to agree about, and it is deliberately not `loadSchedules`'s output.
+ * That function resolves PLACEMENT -- it replaces every trigger whose folder is on another machine with
+ * a stub -- so its result differs per host BY CONSTRUCTION. Fingerprinting it would make every correctly
+ * configured fleet refuse itself forever: mini1 owns `/a`, mini2 owns `/b`, their sets never match, and
+ * neither ever reconciles again. What they share is the FILE, so the file is what gets hashed.
+ *
+ * Pure and fs-free apart from the read: no `existsSync`, because existence is exactly the question that
+ * makes two honest hosts differ.
+ */
+export function authoredCron(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const path = config.triggersFile;
+	if (path === null || path === undefined) return null; // cron disabled: no opinion at all (see cronFingerprint)
+	if (!existsSync(path)) return null;
+	try {
+		return parseTriggers(readFileSync(path, "utf8"), path)
+			.filter((t) => t.on.type === "cron")
+			.map((t) => ({ schedulerId: t.on.id, pattern: t.on.pattern, run: t.run }));
+	} catch {
+		// A file this host cannot parse is not an opinion about what should be scheduled. It refuses boot
+		// elsewhere and keeps last-good on reload; here it must not become a fingerprint that disagrees
+		// with every peer.
+		return null;
+	}
+}
+
+/**
+ * Split a schedule set into the triggers THIS host serves and the ones it does not (issue #57).
+ *
+ * `loadSchedules` already refused everything a pure validator could refuse and everything the filesystem
+ * could answer for a trigger this host owns. What is left is the third question, and it is the one Gap 2
+ * is about: a folder that is not here is not necessarily a mistake, it may simply be another machine's.
+ *
+ * Exported so the split is testable without an fs, and so a caller can report what it will not be running.
+ */
+export function servedSchedules(schedules) {
+	const served = [];
+	const unserved = [];
+	for (const s of schedules) (s.unserved ? unserved : served).push(s);
+	return { served, unserved };
+}
+
+function normalizeCronSchedule({ on, run }, path, existsSync, fleet) {
 	// The pure validator already guaranteed a non-empty, `:`-free, charset-valid, unique id and a
 	// well-formed pattern; folder existence is the one fs-dependent check it deferred to here.
+	//
+	// ON A FLEET THAT IS THE WRONG QUESTION. `INT-TRIGGERS-FILE-CONTRACT` splits this as "type here,
+	// reality where it can be known", and issue #57 adds a third level: PLACEMENT, where the fleet is
+	// known. A folder that is absent on THIS machine may simply belong to another one, and refusing the
+	// worker's boot for it takes every unrelated trigger -- every forge job, every other folder -- offline
+	// with it. That is the sentence #57's own acceptance forbids.
+	//
+	// `fleet` is `PI_WORKER_NAME` being DECLARED, deliberately, and not a registry read. Two reasons, and
+	// both are failures I would otherwise have shipped. A registry read here would make a fleet-wide
+	// restart into a fleet-wide boot refusal, because every host would come up seeing no peers yet. And it
+	// would have to happen after the Valkey client exists, which is BELOW the four destructive boot sweeps
+	// -- so a single-host deployment with one typo'd folder would reap containers, prune history and delete
+	// sandboxes on every restart before refusing. Declaring a name is the operator saying "this is a
+	// fleet", it is known before anything runs, and it keeps a single-host deployment byte-identical.
 	if (!existsSync(run.folder)) {
-		throw configError(`cron trigger "${on.id}": run.folder does not exist: ${run.folder} (${path})`);
+		if (!fleet) {
+			throw configError(`cron trigger "${on.id}": run.folder does not exist: ${run.folder} (${path})`);
+		}
+		// Not mine. Its skillsDir is not my business either: `isAbsolute` is OS-dependent, and judging
+		// another host's path on my platform is the exact mistake the shared validator refuses to make.
+		return { schedulerId: on.id, unserved: "folder-absent" };
 	}
 
 	// `run.skillsDir` gets the same treatment, and for the same reason (REQ-PER-TRIGGER-SKILLS): the pure