@edgehero/pi-dispatch 1.6.1 → 1.7.0

package/.env.example

@@ -32,6 +32,13 @@ PI_CONCURRENCY=3       # how many jobs run in parallel
 
 # --- Infrastructure ---
 VALKEY_URL=redis://127.0.0.1:6379
+# PI_WORKER_NAME=                   # what this machine calls itself. Default: your hostname, lowercased and reduced to [A-Za-z0-9._-]
+                                    # Lands on every worker log line and in every run record, and identifies this host to the others when you run more than one
+                                    # Set it if your hostname is something you would rather not have in your own run history (a laptop often carries a person's name)
+                                    # Refused at boot if it is not [A-Za-z0-9._-], does not start with a letter or digit, is over 64 characters, or ends in .json or .log
+                                    # SETTING IT TURNS ON MULTI-HOST ROUTING (docs/multi-host.md): work only this machine can do (a cron folder, a chained child,
+                                    # a manual run) is enqueued to this host's own queue instead of the shared one, and the wait-check and scoped-concurrency
+                                    # ceilings become fleet-wide instead of per process. Leave it unset on a single-machine deployment and nothing changes
 PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may name its own with "image" in triggers.json (docs/job-image.md)
                                     # Jobs run with --pull=never: pull or BUILD every image you name -- the worker never fetches one at job time, and doctor checks presence
                                     # docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest  (or build image/Dockerfile)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "type": "module",
   "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
   "keywords": [
@@ -58,6 +58,7 @@
     "./scoped-limits": "./src/scoped-limits.mjs",
     "./wait-for": "./src/wait-for.mjs",
     "./wait-state": "./src/wait-state.mjs",
+    "./host-registry": "./src/host-registry.mjs",
     "./identity": "./src/identity.mjs",
     "./gitlab-identity": "./src/gitlab-identity.mjs",
     "./forgejo-identity": "./src/forgejo-identity.mjs",

package/src/cli.mjs

@@ -6,6 +6,9 @@ import { loadConfig } from "./config.mjs";
 import { EXIT_POLICY } from "./exit-code.mjs";
 import { gitDirty } from "./git-dirty.mjs";
 
+/** How long the kill switch waits on the host registry before acting on the shared queue alone. */
+const FLEET_READ_TIMEOUT_MS = 2_000;
+
 const USAGE = `pi-dispatch — run pi coding-agent flows on your own folders
 
   pi-dispatch init         scaffold .env + triggers.json + pause-windows.json + pi-packages.json + subscriptions.json here
@@ -120,9 +123,13 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
 
 		const config = loadConfig(env);
 		const { parseConnection } = await import("./connection.mjs");
-		const { makeQueue, enqueueLocalJob } = await import("./queue.mjs");
+		const { makeQueue, enqueueLocalJob, hostQueueName } = await import("./queue.mjs");
 		// failFast: a one-shot enqueue must not hang forever if Valkey is down -- error clearly.
-		const queue = makeQueue(parseConnection(config.valkeyUrl, { failFast: true }));
+		// Onto THIS host's queue when the deployment declares a name (issue #57). The folder was checked
+		// against this machine's filesystem a few lines up, so this machine is the only one that can run it;
+		// enqueueing it where every host drains would be handing a job to a peer that has no such folder.
+		const hq = config.workerNameDeclared ? hostQueueName(config.workerName) : null;
+		const queue = makeQueue(parseConnection(config.valkeyUrl, { failFast: true }), { ...(hq ? { name: hq } : {}) });
 		try {
 			// Absent flags stay absent (undefined) so the value resolves at job start against the
 			// settings overlay/env, not a default frozen here (INT-CONFIG-OVERLAY-CONTRACT).
@@ -150,31 +157,81 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
 		// The kill switch reads ONLY VALKEY_URL, not the full loadConfig -- it must work even when
 		// GitHub auth is misconfigured, so an operator can always stop the queue.
 		const url = env.VALKEY_URL ?? "redis://127.0.0.1:6379";
-		const { parseConnection } = await import("./connection.mjs");
-		const { makeQueue } = await import("./queue.mjs");
-		// failFast: reach the kill switch in seconds when Valkey is down, not a hang. makeQueue pins
-		// the "pi-jobs" name -- a different name would pause an empty queue (silent no-op).
-		const queue = makeQueue(parseConnection(url, { failFast: true }));
+		const { parseConnection, makeRedisClient } = await import("./connection.mjs");
+		const { fleetQueueNames, discoverHostQueues, unionQueueNames, makeQueue } = await import("./queue.mjs");
+		const { readLiveHosts } = await import("./host-registry.mjs");
+		// EVERY queue this deployment drains (issue #57), not just the shared one. This is the kill switch:
+		// pausing `pi-jobs` alone would stop forge deliveries while a named host's cron, chained children
+		// and manual runs kept spending -- and would print "paused" for having done it. That is the silent
+		// no-op the comment here already warned about for a mistyped name, arriving through a new door.
+		//
+		// Both reads fail OPEN -- between them an unreadable registry and an unreadable keyspace yield the
+		// shared queue alone, which is exactly what this command did before, so a Valkey blip can never make
+		// the kill switch refuse. But it fails open LOUDLY: a degraded read is NAMED in the output rather
+		// than left indistinguishable from a single-host success while a named host keeps spending.
+		// `readLiveHosts` RETURNS `{unreachable}` rather than rejecting, so `blind` is a branch on its
+		// value and the `.catch` below is only for a client that throws before it can answer.
+		const probe = makeRedisClient(url);
+		// Without this, a down Valkey dumps nine `[ioredis] Unhandled error event` traces before the one clean
+		// line -- the exact noise `defaultProbeValkey` exists to suppress.
+		probe.on?.("error", () => {});
+		// Both reads, concurrently, sharing one budget. The registry answers WHO IS LIVE; BullMQ's own meta
+		// keys answer WHICH QUEUES EXIST, and for a kill switch the second is the question that matters. A
+		// host whose registry writes fail for ninety seconds loses its row while its worker keeps draining,
+		// and a resume that misses a queue leaves it paused forever with no surface able to name it. A meta
+		// key outlives its worker; a registry row does not.
+		const [fleet, existing] = await Promise.all([
+			readLiveHosts(probe, { timeoutMs: FLEET_READ_TIMEOUT_MS }).catch((error) => ({ unreachable: error?.message ?? String(error) })),
+			discoverHostQueues(probe, { timeoutMs: FLEET_READ_TIMEOUT_MS }),
+		]);
+		probe.disconnect?.();
+		const blind = fleet?.unreachable ?? null;
+		const names = unionQueueNames(fleetQueueNames(fleet?.hosts), existing);
+		// The registry being unreadable no longer means we saw one queue: the keyspace scan may well have
+		// found them. Report the count we ACTED on, and name the degraded read separately.
+		const span = `${names.length > 1 ? ` [${names.length} queues]` : ""}${blind ? ` [registry unreadable: ${blind}]` : ""}`;
+		const queues = [];
 		try {
-			if (cmd === "pause") {
-				await queue.pause();
-				process.stdout.write("paused — worker will stop taking new jobs (jobs still enqueue)\n");
-			} else if (cmd === "resume") {
-				await queue.resume();
-				process.stdout.write("resumed\n");
+			// Constructed INSIDE the try: `makeQueue` can throw on a malformed peer-written name, and a throw
+			// at index k > 0 would otherwise leak the k connections already opened.
+			for (const name of names) queues.push(makeQueue(parseConnection(url, { failFast: true }), { name }));
+			if (cmd === "pause" || cmd === "resume") {
+				const done = [];
+				try {
+					for (const q of queues) {
+						await (cmd === "pause" ? q.pause() : q.resume());
+						done.push(q.name);
+					}
+				} catch (error) {
+					// A mid-loop failure leaves the deployment HALF switched. Naming what did change is the whole
+					// difference between an operator who knows to finish the job and one who reads "unreachable"
+					// as "nothing happened" and walks away from a fleet with one host still spending.
+					return fail(`could not ${cmd} the whole deployment at ${url}\n  ${done.length > 0 ? `${cmd}d: ${done.join(", ")}` : "nothing changed"}\n  failed at: ${names[done.length]}\n  ${error.message}`);
+				}
+				process.stdout.write(cmd === "pause" ? `paused — worker will stop taking new jobs (jobs still enqueue)${span}\n` : `resumed${span}\n`);
 			} else {
 				// "paused" is included in the counts because jobs enqueued while paused land in the
 				// `paused` list, not `wait` -- omitting it would report backlog 0 in the exact state
 				// the pause switch creates. `pausedState` (the boolean) is named apart from the
 				// `paused` count `getJobCounts` returns, so the two do not collide in the output.
-				const pausedState = await queue.isPaused();
-				const counts = await queue.getJobCounts("waiting", "active", "paused", "delayed", "failed");
-				process.stdout.write(`${JSON.stringify({ pausedState, ...counts })}\n`);
+				const states = await Promise.all(queues.map((q) => q.isPaused()));
+				const per = await Promise.all(queues.map((q) => q.getJobCounts("waiting", "active", "paused", "delayed", "failed")));
+				const counts = per.reduce((acc, c) => {
+					for (const [k, v] of Object.entries(c ?? {})) acc[k] = (acc[k] ?? 0) + (Number(v) || 0);
+					return acc;
+				}, {});
+				// Summed counts with a boolean from ONE queue would report a half-paused deployment as fully
+				// one or fully the other. `pausedPartial` is the third state, and the dangerous direction is
+				// the one it makes visible: pause ran while a host was invisible, so that host still spends.
+				const pausedState = states.every(Boolean);
+				const pausedPartial = !pausedState && states.some(Boolean);
+				const out = { pausedState, ...(pausedPartial ? { pausedPartial, pausedQueues: names.filter((_, i) => states[i]) } : {}), ...counts, ...(blind ? { fleet: blind } : {}) };
+				process.stdout.write(`${JSON.stringify(out)}\n`);
 			}
 		} catch (error) {
 			return fail(`could not reach Valkey at ${url} — is it running? (docker compose up)\n  ${error.message}`);
 		} finally {
-			await queue.close().catch(() => {});
+			for (const q of queues) await q.close().catch(() => {});
 		}
 		return 0;
 	}

package/src/config.mjs

@@ -6,6 +6,7 @@
  */
 
 import { existsSync } from "node:fs";
+import { hostname } from "node:os";
 import { delimiter } from "node:path";
 import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
 import { MINTED_TOKEN_VARS } from "./forges.mjs";
@@ -212,6 +213,14 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 	const model = env.PI_MODEL ?? "claude-sonnet-4-5-20250929"; // dated snapshot; deterministic per CONST-PI-VERSION-PINNED
 	return {
 		valkeyUrl: env.VALKEY_URL ?? "redis://127.0.0.1:6379",
+		// Issue #57. What this machine calls itself: the key of its registry row, the `host` on every log
+		// line and run record, and the BullMQ worker name. Always populated -- a deployment that declares
+		// nothing still has an identity, which is what lets a fleet of two be TOLD APART before anyone has
+		// configured anything. `workerNameDeclared` is kept separately because "the operator named this
+		// machine" and "we read the hostname" are different facts, and a later slice gates a host-visible
+		// side effect on the first rather than the second.
+		workerName: workerName(env),
+		workerNameDeclared: Boolean(env.PI_WORKER_NAME),
 		concurrency: positiveInt(env, "PI_CONCURRENCY", 3), // DES-CONCURRENCY-3
 		dailyCap: positiveInt(env, "PI_DAILY_CAP", 25), // bounds container STARTS per day (money)
 		weeklyCap: optionalBoundedInt(env, "PI_WEEKLY_CAP", 1), // REQ-SPEND-CAPS-MULTI-WINDOW; null = weekly window disabled
@@ -448,6 +457,80 @@ export function defaultLogsDir() {
 	return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/logs`.replace(/\\/g, "/");
 }
 
+/**
+ * What a worker may call itself (issue #57). The CHARACTER CLASS is `sanitizeJobId`'s
+ * (`[A-Za-z0-9._-]`), reused rather than invented so this project has one name-safe alphabet -- but that
+ * function is a REPLACER, not a validator, so the three rules around the class are NEW and are claimed
+ * as new here rather than borrowed:
+ *
+ *   - a leading alphanumeric, which is what refuses `..` and a leading `-` that reads as a flag;
+ *   - a 64-character ceiling, because the name is a Valkey key segment and a log field on every line;
+ *   - no `.json`/`.log` tail, which is not decoration. The class contains the dot, so `prod.json` is
+ *     otherwise a legal name -- and a later slice writes a per-host marker file into `PI_LOGS_DIR`,
+ *     where `<something>.json` is parsed as a run record by the admin and DELETED by the log reaper.
+ *     A name is refused here rather than escaped there, because the escape would have to be remembered
+ *     at every site that ever composes a filename from this value.
+ *
+ * The class is `:`-free, `,`-free and `#`-free, which is what lets the name be a Valkey key segment
+ * UNHASHED. That is the point of validating instead of hashing (`scopeKeyPrefix` does the opposite for
+ * a folder path, which was never chosen for key-safety and cannot be refused): the whole value of a host
+ * registry is that `HGETALL host:h:mac-mini-1` is readable by a human.
+ */
+export const WORKER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** True when the name would collide with the run-history filename namespace. See WORKER_NAME_RE. */
+const RESERVED_NAME_TAIL = /\.(json|log)$/i;
+
+/**
+ * A hostname reduced to something `WORKER_NAME_RE` accepts, for use as a DEFAULT only.
+ *
+ * Lowercased because macOS reports `Robs-Mac-Mini.local` where Linux reports `mac-mini`: two spellings
+ * of one machine would be two rows in the registry and two values in the run records. The `.local`
+ * suffix is deliberately NOT stripped -- an OS-specific suffix rule is a rule someone has to remember,
+ * and it costs nothing to keep.
+ */
+export function sanitizeWorkerName(raw) {
+	const cleaned = String(raw ?? "")
+		.toLowerCase()
+		.replace(/[^a-z0-9._-]/g, "-")
+		.replace(/-{2,}/g, "-")
+		.replace(/^[-.]+|[-.]+$/g, "")
+		.slice(0, 64)
+		.replace(/[-.]+$/, ""); // the slice can leave a trailing separator behind
+	if (cleaned === "" || !WORKER_NAME_RE.test(cleaned)) return "worker";
+	// The reserved tail is repaired by REPLACING the dot, never by appending: a suffix on a name already at
+	// the 64-character ceiling would push it past, and a default that the validator would reject is a
+	// second, weaker alphabet arriving by the back door. `host.json` becomes `host-json`, which is the same
+	// length, still readable, and cannot match the tail again.
+	return cleaned.replace(RESERVED_NAME_TAIL, (m) => `-${m.slice(1)}`);
+}
+
+/** This machine's name, sanitized. Exported so doctor and the admin resolve it without `loadConfig`. */
+export function defaultWorkerName() {
+	try {
+		return sanitizeWorkerName(hostname());
+	} catch {
+		return "worker"; // hostname() can throw on a locked-down host; a name is never worth refusing boot for
+	}
+}
+
+/**
+ * THE ASYMMETRY IS THE DESIGN. A value the operator did not choose is repaired silently; a value they
+ * typed is refused loudly and never quietly altered. Defaulting is a convenience, so it must not be able
+ * to fail; declaring is a statement, so a typo in it must not become a different machine's name.
+ */
+function workerName(env) {
+	const declared = env.PI_WORKER_NAME;
+	if (declared === undefined || declared === "") return defaultWorkerName();
+	if (!WORKER_NAME_RE.test(declared)) {
+		throw configError(`PI_WORKER_NAME must match ${WORKER_NAME_RE.source} (letters, digits, dot, underscore, hyphen; first character alphanumeric; at most 64): ${JSON.stringify(declared)}`);
+	}
+	if (RESERVED_NAME_TAIL.test(declared)) {
+		throw configError(`PI_WORKER_NAME must not end in .json or .log: ${JSON.stringify(declared)} would collide with the run-history filenames in PI_LOGS_DIR`);
+	}
+	return declared;
+}
+
 export function defaultGraphDir(env = process.env) {
 	// Under the OS temp dir by default, beside logs/ and jobs/ -- the admin's graph HTML artifact
 	// (issue #54) is host-side display output on the defaultLogsDir doctrine, and deliberately NOT

package/src/cron.mjs

@@ -14,7 +14,8 @@
  */
 
 import { configError } from "./config.mjs";
-import { loadSchedules } from "./schedules.mjs";
+import { cronFingerprint } from "./fingerprint.mjs";
+import { authoredCron, loadSchedules, servedSchedules } from "./schedules.mjs";
 
 function sentinelName(code) {
 	if (code === -10) return "SchedulerJobIdCollision";
@@ -67,6 +68,99 @@ export async function reconcile(queue, schedules, { log = () => {} } = {}) {
 	return { installed: schedules.length, removed: orphanIds.length };
 }
 
+/**
+ * Reconcile, but only when every other LIVE worker agrees about what should be scheduled (issue #57).
+ *
+ * THE BUG THIS CLOSES. `reconcile` prunes every resident scheduler not named in THIS worker's config, so
+ * two workers with different triggers files each delete the other's on every boot and every file-watch
+ * reload. Its idempotence only ever held because one worker was the only shape, and nothing checked.
+ *
+ * WHY AGREEMENT RATHER THAN AN ELECTED OWNER. In the good case agreement is sufficient, and this module's
+ * own header says why: upsert is keyed by schedulerId, so when every live host agrees it does not matter
+ * which one reconciles or how many do. In the BAD case election is actively worse -- an elected owner
+ * reconciles from ITS file, so if that file is the stale one (the operator edited on the other host, or a
+ * compose `:ro` single-file mount pinned a dead inode, a topology `makeCheckWaitSkew` already documents)
+ * the fleet silently converges on the wrong set and reverts the edit with a log line that reads like
+ * success. That is `OQ-008`'s own verdict arriving through a new door. Agreement never picks a winner, so
+ * it cannot pick the wrong one, and it needs no lease because it grants no authority: the rule only ever
+ * WITHHOLDS a permission relative to today, which is why it cannot be a regression.
+ *
+ * The honest cost, stated rather than buried: agreement can stalemate and needs an operator, where
+ * election resolves automatically and possibly wrongly. For a project whose doctrine is "fail loudly, or
+ * fail open and say which", a stalemate that names both hosts is the right trade.
+ *
+ * PUBLISH BEFORE READ is what makes the legitimate-edit sequence race-free. An operator edits on host A;
+ * A's watcher fires, A publishes its new fingerprint, reads peers, sees B still on the old one and
+ * refuses. The operator syncs the file to B; B's watcher fires, B publishes, reads, sees A already on the
+ * new one, and reconciles for the whole fleet. A never has to run again -- the schedule set is global. The
+ * only bad interleaving would be both refusing while both are in fact current, which needs a read to see a
+ * stale value, and cannot happen when each side publishes synchronously before it reads.
+ *
+ * ABSENCE NEVER REFUSES. No peers, or a registry that cannot be read, both PROCEED -- which is today's
+ * behaviour, so a Valkey blip can never wedge a single-host deployment.
+ *
+ * BOTH HALVES ARE REFUSED, not just the prune, and the reason is not symmetry: `upsertJobScheduler` on an
+ * existing id is a REDEFINITION, so two hosts disagreeing about one id would flip a schedule between two
+ * definitions on every file change with nothing logged.
+ *
+ * A refusal RETURNS and never throws, so the caller logs it and carries on to `worker_started`: a
+ * divergent host must still drain the queue. Taking a host's forge capacity offline over a cron
+ * disagreement is the sentence this issue's own acceptance forbids.
+ */
+export async function reconcileGated(queue, schedules, { registry, log = () => {}, reconcileFn = reconcile, tz, authored = schedules } = {}) {
+	// No registry wired is the same answer as a registry that cannot be read: proceed. This is what lets
+	// the gate be the DEFAULT on every path without a caller having to remember to arm it.
+	if (!registry) return await reconcileFn(queue, schedules, { log });
+	// THE FINGERPRINT IS OVER THE AUTHORED SET, NOT THE SERVED SUBSET, and the distinction is the whole
+	// reason placement and agreement can coexist. What two hosts must AGREE about is the FILE; what they
+	// legitimately DIFFER about is which of its triggers each one can run, because a folder lives on one
+	// machine. Hashing the served subset would make every correctly-configured fleet refuse itself forever:
+	// mini1 serves /a, mini2 serves /b, their subsets differ, and neither would ever reconcile again.
+	const mine = cronFingerprint(authored, { tz });
+	// Publishes this host's CURRENT facts rather than passing the fingerprint in. Passing it in was the
+	// first shape and it quietly destroyed the mechanism it depends on: the heartbeat installs `fpCron` as
+	// a THUNK over the live schedule ref, and a caller merging a computed string replaced that closure, so
+	// every later beat republished a frozen value and two hosts could drift apart again with nothing saying
+	// so. The thunk is installed once, at boot; this only forces it to be read NOW.
+	await registry.publish();
+	const peers = await registry.livePeers();
+
+	// `{ unreachable }` and "no peers" are different facts and the panel must keep them apart -- but for
+	// THIS decision they resolve the same way, because not knowing whether anyone disagrees is not knowing
+	// that someone does, and the rule only withholds a permission.
+	const others = peers?.hosts ?? [];
+	// An abstaining peer (cron disabled) publishes no fingerprint and is never a disagreeing party.
+	const opinions = others.filter((h) => typeof h.fpCron === "string" && h.fpCron !== "");
+	const disagreeing = opinions.filter((h) => h.fpCron !== mine);
+
+	// I cannot establish agreement with an opinion I do not have. `mine` is null only when the file could
+	// not be read or parsed at THIS instant while `loadSchedules` had just succeeded -- a rename's brief
+	// unlink window, in practice. Proceeding would prune a peer's schedulers on the strength of a
+	// comparison that never happened, so this refuses; refusing deletes nothing and the next watch event
+	// or boot re-decides. It gets its own token because "I could not read my own file" and "we disagree"
+	// send an operator to two different places.
+	if (mine === null && opinions.length > 0) {
+		log("cron_divergence_refused", { mine: null, reason: "own-triggers-unreadable", cronCount: schedules.length, peers: opinions.map((h) => ({ host: h.name, fpCron: h.fpCron, cronCount: Number(h.cronCount) || 0 })) });
+		return { refused: "own-triggers-unreadable", peers: opinions.map((h) => h.name) };
+	}
+
+	if (disagreeing.length > 0) {
+		log("cron_divergence_refused", {
+			mine,
+			cronCount: schedules.length,
+			// The count rides the LINE and never the RULE: it is what lets the message say "host-b reports 4
+			// schedules, I have 5", which is the difference between a diagnosable warning and noise.
+			peers: disagreeing.map((h) => ({ host: h.name, fpCron: h.fpCron, cronCount: Number(h.cronCount) || 0 })),
+		});
+		return { refused: "cron-divergence", peers: disagreeing.map((h) => h.name) };
+	}
+
+	// Gated on `> 0`, so a single-host deployment emits no new line at all -- the absent-when-unarmed idiom
+	// this repo uses for every optional field.
+	if (opinions.length > 0) log("cron_agreement", { peers: opinions.length });
+	return await reconcileFn(queue, schedules, { log });
+}
+
 /**
  * Live-reload the cron schedulers from the (changed) triggers file: re-select the cron subset and reconcile
  * it against the resident schedulers -- an add installs, a delete prunes (reconcile already removes orphans),
@@ -75,16 +169,34 @@ export async function reconcile(queue, schedules, { log = () => {} } = {}) {
  * never taken down by a malformed trigger file (the OQ-008 live-edit safety). Returns `{ ok }` /
  * `{ invalid }` / `{ failed }`. `loadFn`/`reconcileFn` are injectable so the reload is unit-tested with no fs.
  */
-export async function reloadSchedules(config, queue, { log = () => {}, loadFn = loadSchedules, reconcileFn = reconcile } = {}) {
+export async function reloadSchedules(config, queue, { log = () => {}, loadFn = loadSchedules, reconcileFn = reconcileGated, ref = null, registry, tz, fleet = false, authoredFn = authoredCron } = {}) {
 	let schedules;
 	try {
-		schedules = loadFn(config);
+		schedules = loadFn(config, { fleet });
 	} catch (error) {
 		log("schedules_reload_invalid", { reason: error?.message ?? String(error), kept: true });
 		return { invalid: error?.message ?? String(error) };
 	}
+	// The live REF is updated before the reconcile, not after, and never on the invalid path above: the
+	// heartbeat fingerprints what this host currently believes, and believing the boot-time set after an
+	// edit is what would make two hosts' fingerprints oscillate on the beat period -- refusing or agreeing
+	// depending on which half of a beat a reload landed in.
+	if (ref) ref.current = schedules;
+	// The same split the boot path makes: a trigger whose folder is another host's is not this host's to
+	// install, and the fingerprint is computed over the SERVED set so two hosts owning different folders
+	// do not read each other as divergent.
+	const { served, unserved } = servedSchedules(schedules);
+	for (const s of unserved) log("schedule_unserved", { schedulerId: s.schedulerId, reason: s.unserved });
 	try {
-		const r = await reconcileFn(queue, schedules, { log });
+		// The FILE, re-read, not `schedules` -- that is `loadSchedules`'s output, which has already replaced
+		// every foreign trigger with a stub and therefore differs per host by construction. Passing it here
+		// made every live edit on a fleet refuse, permanently, even between hosts running identical files.
+		const r = await reconcileFn(queue, served, { log, registry, tz, authored: authoredFn(config) });
+		// A refusal is NOT a reload. Wrapping it as `{ ok: true }` would log
+		// `schedules_reloaded {installed: undefined}` and tell an operator the edit took effect on a fleet
+		// where nothing was installed and nothing pruned -- the silent no-op this project refuses, arriving
+		// through the success path.
+		if (r?.refused) return r;
 		log("schedules_reloaded", { installed: r.installed, removed: r.removed });
 		return { ok: true, ...r };
 	} catch (error) {

package/src/doctor.mjs

@@ -49,7 +49,7 @@ import { homedir, tmpdir } from "node:os";
 import { dirname, join, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
-import { defaultSandboxDir, globalExtensionsEnabled } from "./config.mjs";
+import { defaultSandboxDir, defaultWorkerName, globalExtensionsEnabled } from "./config.mjs";
 import { canonicalScope, parseScopedLimits } from "./scoped-limits.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, afterInstantMs, parseWaitProfiles } from "./wait-for.mjs";
 import { isForgeKind } from "./forges.mjs";
@@ -89,6 +89,7 @@ export async function runDoctor(env = process.env, deps = {}) {
 		out = (s) => process.stdout.write(s),
 		spawn = nodeSpawn,
 		probeValkey = defaultProbeValkey,
+		readHosts = defaultReadHosts,
 		fileExists = existsSync,
 		nodeVersion = process.versions.node,
 		// --fix (REQ-DEPLOYMENT-BOOTSTRAP): offer to run the exact fixes doctor already prints. The prompt
@@ -111,7 +112,7 @@ export async function runDoctor(env = process.env, deps = {}) {
 		platform = process.platform,
 		home = homedir(),
 	} = deps;
-	const seams = { cwd, out, spawn, probeValkey, fileExists, nodeVersion, mkdir, chmod, rm, agentDir, platform, home };
+	const seams = { cwd, out, spawn, probeValkey, readHosts, fileExists, nodeVersion, mkdir, chmod, rm, agentDir, platform, home };
 
 	let checks = await collectChecks(env, seams);
 	let failed = render(checks, out);
@@ -213,7 +214,7 @@ export async function defaultPromptFn(question, { input = process.stdin, output
  * a comment.
  */
 export async function collectChecks(env, seams) {
-	const { cwd, spawn, probeValkey, fileExists, nodeVersion, platform, agentDir = agentDirFrom(env) } = seams;
+	const { cwd, spawn, probeValkey, readHosts = defaultReadHosts, fileExists, nodeVersion, platform, agentDir = agentDirFrom(env) } = seams;
 
 	const jobImage = env.PI_JOB_IMAGE ?? "pi-job:latest";
 	const valkeyUrl = env.VALKEY_URL ?? "redis://127.0.0.1:6379";
@@ -829,6 +830,85 @@ export async function collectChecks(env, seams) {
 			: {}),
 	});
 
+	// --- the fleet (issue #57) -------------------------------------------------------------------------
+	//
+	// Every line here is gated on a peer actually existing, so a single-host deployment's output is
+	// byte-identical. And every one is a WARN rather than a failure, with one exception noted below: this
+	// command runs on ONE machine and must not refuse a deployment for a condition that machine cannot fix.
+	// This host's own image id, read through the same seam every other docker probe here uses. Only when
+	// the image is actually present -- an absent one is already reported above, and a second line saying
+	// its digest is unknown would be noise on a fault the operator has been told about.
+	const fleet = await readHosts(valkeyUrl);
+	const peers = (fleet.hosts ?? []).filter((h) => h.name !== workerNameOf(env));
+	// Read only when there is a peer to compare against. Every line below is gated on a peer existing, and
+	// the SUBPROCESS has to be too: otherwise every `doctor` run on every single-host deployment spawns an
+	// extra docker call whose answer nothing reads.
+	const imageDigest =
+		peers.length > 0 && imageCode === 0
+			? (await runCmdCapture(spawn, "docker", ["image", "inspect", "--format={{.Id}}", jobImage])).output.trim() || null
+			: null;
+	if (peers.length > 0) {
+		const mine = workerNameOf(env);
+		checks.push({ ok: true, label: `Fleet: ${peers.length + 1} worker${peers.length === 0 ? "" : "s"} (${[mine, ...peers.map((h) => h.name)].sort().join(", ")})` });
+
+		// The one thing that is silently WRONG rather than merely undeclared. Without a declared name this
+		// host enqueues its own folder work to the SHARED queue, where a peer that has no such folder can
+		// pop it -- so the routing that makes a fleet safe is simply off, and nothing else says so.
+		if (!env.PI_WORKER_NAME) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: "This worker has peers but no PI_WORKER_NAME, so host routing is OFF here",
+				fix: "set PI_WORKER_NAME in this host's .env and restart: without it, this host's folder work is enqueued where any host can pop it, and its records carry a hostname it never chose",
+			});
+		}
+
+		// Two hosts on two builds of one tag is the failure Gap 6 names: same flow, different behaviour,
+		// undebuggable. A WARN and never a failure, because `{{.Id}}` is the LOCAL image id -- two
+		// independent builds of one Dockerfile differ, and under docker's containerd image store it is the
+		// manifest digest rather than the config digest, so a mixed-store fleet disagrees about identical
+		// content. Suspicious, never wrong.
+		const digests = new Set(peers.map((h) => h.imageDigest).filter(Boolean));
+		if (digests.size > 0 && imageDigest && !digests.has(imageDigest)) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `Job image digest differs from ${peers.length === 1 ? "the other host" : "other hosts"}`,
+				fix: "rebuild or re-pull so every host runs the same image; digests are identical only when both hosts pulled one tag from one registry, so two local builds differ legitimately",
+			});
+		}
+
+		// A cron PATTERN carries no timezone and resolves in each worker's LOCAL time, so one pattern is two
+		// different instants on two hosts in two zones -- and the cron gate refuses that divergence rather
+		// than letting it drift, which is why this reads as an explanation for a refusal an operator has
+		// probably already met.
+		const zones = new Set([Intl.DateTimeFormat().resolvedOptions().timeZone, ...peers.map((h) => h.tz).filter(Boolean)]);
+		if (zones.size > 1) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `Hosts disagree about the timezone (${[...zones].sort().join(", ")}), so one cron pattern is two different instants`,
+				fix: "set the same TZ on every host: a cron trigger carries no timezone of its own, so cron reconcile refuses while they disagree",
+			});
+		}
+
+		// Clocks. The registry's own heartbeats are the measurement, and skew matters here beyond tidiness:
+		// every hold clock, every TTL and the UTC day boundary the budget windows key on are read against
+		// whichever host is looking.
+		const skewed = peers.filter((h) => Number.isFinite(h.staleMs) && h.staleMs > 5 * 60_000);
+		if (skewed.length > 0) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `${skewed.length} host row${skewed.length === 1 ? " is" : "s are"} stale by more than five minutes (${skewed.map((h) => h.name).join(", ")})`,
+				fix: "check that those workers are running and that the clocks agree -- a stale row is either a dead worker or a skewed clock, and both matter",
+			});
+		}
+	} else if (fleet.unreachable) {
+		// Said, rather than silently absent: "no peers" and "could not ask" are different facts.
+		checks.push({ ok: true, label: `Fleet: could not read the host registry (${fleet.unreachable})` });
+	}
+
 	const keys = PROVIDER_KEYS[provider] ?? [`${provider.toUpperCase()}_API_KEY`];
 	let keyOk = keys.some((k) => (env[k] ?? "").trim().length > 0);
 	let keyNote = "";
@@ -2212,6 +2292,36 @@ function parseGhTokenScopes(output) {
  * error handler is attached, so a down Valkey is reported as one ✗ line — not the ioredis stack traces
  * a BullMQ Queue's internal client would dump. Reuses `parseConnection`'s fail-fast options (cli.mjs:88).
  */
+/**
+ * The fleet's registry rows (issue #57), through a fail-fast client that is always disconnected.
+ *
+ * A SEAM rather than a direct import so the multi-host checks are testable with no Valkey at all, which
+ * is the posture every other network-touching check here already takes. Never throws: a fleet this
+ * command cannot see is a fleet it says nothing about, not a doctor that fails.
+ */
+/** This host's name as the worker computes it, so doctor and the worker cannot disagree about who "I" am. */
+function workerNameOf(env) {
+	return env.PI_WORKER_NAME || defaultWorkerName();
+}
+
+async function defaultReadHosts(url) {
+	try {
+		const { Redis } = await import("ioredis");
+		const { parseConnection } = await import("./connection.mjs");
+		const { readLiveHosts } = await import("./host-registry.mjs");
+		const client = new Redis({ ...parseConnection(url, { failFast: true }), lazyConnect: true });
+		client.on("error", () => {});
+		try {
+			await client.connect();
+			return await readLiveHosts(client);
+		} finally {
+			client.disconnect();
+		}
+	} catch (err) {
+		return { unreachable: err?.message ?? "registry unreadable" };
+	}
+}
+
 async function defaultProbeValkey(url) {
 	const { Redis } = await import("ioredis");
 	const { parseConnection } = await import("./connection.mjs");

package/src/fingerprint.mjs

@@ -0,0 +1,78 @@
+/**
+ * Canonical fingerprints of configuration, so two hosts can find out whether they agree (issue #57).
+ *
+ * Pure, and importing nothing but `node:crypto`: a fingerprint must be computable in a tier-1 test with
+ * no queue, no Valkey and no filesystem, exactly as `parseTriggers` is.
+ *
+ * WHY A HASH RATHER THAN THE VALUE. Two of these travel through the host registry, whose content rule
+ * refuses paths outright (`INT-HOST-REGISTRY-CONTRACT`) -- and a cron schedule set legitimately contains
+ * `run.folder`, `run.task` and secret NAMES. Hashing is what makes them admissible: the registry carries
+ * proof of agreement rather than the thing agreed on. This is the inverse of `scopeKeyPrefix`'s argument,
+ * which hashes a scope because it may contain `:` and `/`; here the reason is disclosure, not syntax.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * A stable 16-hex digest of any JSON-able value.
+ *
+ * Object keys are sorted RECURSIVELY, and that is load-bearing rather than tidy. `normalizeCronSchedule`
+ * builds its `data` object as a literal, so its key ORDER is a property of the worker's source: two hosts
+ * mid-upgrade would otherwise canonicalise the same file differently and refuse each other for the whole
+ * rollout. Sorting removes the spurious disagreement while leaving the real one -- a genuinely new field
+ * still changes the hash, which is correct, because the stored repeatable's data really did change.
+ *
+ * Sixteen hex, the `scopeKeyPrefix` and `localJobId` idiom, because this is compared and displayed rather
+ * than used as a security boundary.
+ */
+export function fingerprint(value) {
+	return createHash("sha256").update(canonical(value)).digest("hex").slice(0, 16);
+}
+
+function canonical(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value ?? null);
+	if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+	const keys = Object.keys(value).sort();
+	return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+}
+
+/**
+ * The fingerprint of a worker's cron schedule set, or `null` when this worker has no opinion.
+ *
+ * ABSTAIN VERSUS OPINE IS THE SUBTLE PART, and conflating the two would leave the bug this gate exists to
+ * close. `loadSchedules` returns `[]` for two different states:
+ *
+ *   - `PI_TRIGGERS_FILE` unset, which means CRON IS DISABLED on this host. Such a worker has no view of
+ *     what should be scheduled, so it must never be able to disagree with one that does. It ABSTAINS.
+ *   - a triggers file that is present and declares zero cron entries. That is an OPINION -- "there should
+ *     be no schedulers" -- and it is this bug's purest form: today, deleting the last cron trigger on one
+ *     host prunes the whole fleet's schedulers through the file-watch path.
+ *
+ * So `null` in means abstain (`null` out); an empty ARRAY is a real fingerprint.
+ *
+ * The `tz` rides the hash because a cron PATTERN carries no timezone: `triggers.json` has no `tz` field on
+ * a cron entry, and BullMQ hands the pattern to cron-parser with no zone, so it resolves in each worker's
+ * LOCAL system time. On one host that is exactly what an operator means; on two hosts in different zones
+ * the same pattern is two different instants, with nothing anywhere saying so. Including the zone makes
+ * that a disagreement the gate can see. (`pause-windows.json` has carried an explicit `tz` since it
+ * shipped and is already fleet-correct; the asymmetry is why this one needs stating.)
+ *
+ * Fingerprinted over the NORMALIZED schedules rather than the file's bytes, deliberately. Bytes diverge on
+ * whitespace, on key order, and on every webhook trigger the worker does not own -- so two hosts differing
+ * only in a `label` rule would freeze cron forever over a difference that cannot affect it. The normalized
+ * set diverges exactly when the reconcile INPUTS diverge, which is the property that makes reconcile
+ * idempotent in the first place.
+ */
+export function cronFingerprint(schedules, { tz } = {}) {
+	// Takes the AUTHORED shape (`schedules.mjs -> authoredCron`), never the placement-resolved one.
+	if (schedules === null || schedules === undefined) return null;
+	return fingerprint({
+		tz: tz ?? "",
+		// EVERY field of an authored entry, projected explicitly. An earlier shape listed the keys of a
+		// NORMALIZED schedule (`name`, `data`, `opts`), which are all `undefined` on an authored one -- so
+		// the hash saw only the id and the pattern, and an operator changing `run.folder`, `run.flow` or
+		// `run.image` on one host and not the other passed the gate silently. That broke this module's own
+		// stated invariant, that the set diverges exactly when the reconcile inputs diverge.
+		schedules: schedules.map((s) => ({ schedulerId: s.schedulerId, pattern: s.pattern, run: s.run })),
+	});
+}