@edgehero/pi-dispatch 1.6.1 → 1.8.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.8.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": [
@@ -48,6 +48,7 @@
     "./open-browser": "./src/open-browser.mjs",
     "./git-dirty": "./src/git-dirty.mjs",
     "./queue": "./src/queue.mjs",
+    "./capabilities": "./src/capabilities.mjs",
     "./connection": "./src/connection.mjs",
     "./job-id": "./src/job-id.mjs",
     "./forges": "./src/forges.mjs",
@@ -58,6 +59,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",
@@ -65,6 +67,7 @@
     "./get-token": "./src/get-token.mjs",
     "./runtime-settings": "./src/runtime-settings.mjs",
     "./run-history": "./src/run-history.mjs",
+    "./run-mirror": "./src/run-mirror.mjs",
     "./sandbox": "./src/sandbox.mjs",
     "./sandbox-store": "./src/sandbox-store.mjs",
     "./subscriptions": "./src/subscriptions.mjs",

package/src/capabilities.mjs

@@ -0,0 +1,179 @@
+/**
+ * What a host can serve, and which queue a job that needs one of those things belongs on (issue #57,
+ * `OQ-032`).
+ *
+ * Two trigger fields bind a job to a MACHINE rather than to a repository: `run.secretsProfile` names a
+ * resolver the operator declared in that host's `PI_SECRET_PROFILES`, and a `run.waitFor` condition names a
+ * check script from its `PI_WAIT_PROFILES`. Both are refused pre-spend when the host popping the job has
+ * not declared them, and both refusals are RETURNED rather than thrown, so they are never retried. The
+ * same trigger therefore succeeds or fails depending on which worker happened to take the delivery, and it
+ * reads like a configuration error rather than a placement one.
+ *
+ * #57's Gap 2 exempted forge jobs on the grounds that their workspace is a fresh clone that any host can
+ * build. Issues #225 and #230 retracted that without saying so: a clone is portable, a resolver on one
+ * machine's disk is not.
+ *
+ * WHY THIS IS DECIDED AT ENQUEUE. The obvious alternative is to let any host take the job and defer it if
+ * it cannot serve it. That does not work here, and the reason is upstream rather than ours: BullMQ promotes
+ * a delayed job on EACH WORKER'S OWN CLOCK (`scripts.js` passes the client clock as the cut-off), so the
+ * host whose clock runs fastest wins every attempt, deterministically. If the host that cannot serve the
+ * job is the fast one, the job never reaches the one that can. Jitter changes when the attempt happens, not
+ * who wins it.
+ *
+ * THE ONE CAPABILITY DELIBERATELY NOT ROUTED is `run.resume`. A session key is `sha256(kind, repo, ref)`
+ * and `session-store.mjs` records that it is "not random... anyone who knows the repository and the branch
+ * can compute it", so publishing keys to route on them would disclose which repositories and branches a
+ * deployment works on, recoverable by guessing a repo name. That is more disclosing than everything else in
+ * the registry combined. A resume that lands on the wrong host cold-starts and says so in the record.
+ */
+
+/** Class letters. Open enum: `g:` is reserved for forge credentials, the highest-value follow-on. */
+export const CAP_SECRET = "s";
+export const CAP_WAIT = "w";
+
+/**
+ * The name charset, duplicated from `secret-profiles.mjs` and `wait-for.mjs` deliberately: this module
+ * imports nothing, and the two it copies already copy it from `triggers.mjs` for the same reason. What
+ * matters here is what the set EXCLUDES -- a comma, so the token list joins unambiguously, and a colon, so
+ * `<class>:<name>` decomposes at the first one.
+ */
+const PROFILE_NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * How fresh a host's registry row must be before a job is ROUTED to it.
+ *
+ * Not the 90s TTL, and the difference is the point. The TTL is a crash backstop: it answers "has this host
+ * definitely gone", and it is deliberately six missed beats so a blip cannot evict a working host from the
+ * panel. A routing decision needs the opposite polarity -- evidence of LIFE, not absence of expiry --
+ * because a job routed onto a dead host's queue sits there until that host comes back, and nothing else
+ * will take it. Three beats is late enough to ride out a slow beat and early enough that a stopped host
+ * stops attracting work long before its row expires.
+ */
+export const ROUTE_FRESH_MS = 45_000;
+
+/** One token, or null when the name is not one this deployment would accept. */
+function token(cls, name) {
+	return typeof name === "string" && PROFILE_NAME.test(name) ? `${cls}:${name}` : null;
+}
+
+/**
+ * What THIS host can serve, from its own config, as a sorted token list.
+ *
+ * Sorted so the published string is stable: an unstable one would make the row differ every beat and any
+ * future fingerprint over it useless.
+ */
+export function capabilityTokens({ secretProfiles, waitProfiles } = {}) {
+	const out = new Set();
+	for (const name of Object.keys(secretProfiles ?? {})) {
+		const t = token(CAP_SECRET, name);
+		if (t) out.add(t);
+	}
+	for (const name of Object.keys(waitProfiles ?? {})) {
+		const t = token(CAP_WAIT, name);
+		if (t) out.add(t);
+	}
+	return [...out].sort();
+}
+
+/** The registry value. Comma-joined, which the charset makes unambiguous. */
+export function serializeCaps(tokens) {
+	return (tokens ?? []).join(",");
+}
+
+/**
+ * A peer's tokens, from its registry row. Peer-written, so every element is re-validated here rather than
+ * trusted: a row is written by another process and this one decides where money-spending work goes.
+ */
+export function parseCaps(raw) {
+	const out = new Set();
+	for (const part of String(raw ?? "").split(",")) {
+		const at = part.indexOf(":");
+		if (at <= 0) continue;
+		const cls = part.slice(0, at);
+		const name = part.slice(at + 1);
+		if ((cls === CAP_SECRET || cls === CAP_WAIT) && PROFILE_NAME.test(name)) out.add(part);
+	}
+	return out;
+}
+
+/**
+ * What a JOB needs, from the same two fields the worker's own refusals read.
+ *
+ * `waitProfileNames`-shaped inline rather than imported, because this module is loaded by the RECEIVER and
+ * `wait-for.mjs` carries the whole wait engine. The extraction is three lines and the charset check below
+ * is the same one that module makes.
+ */
+export function jobNeeds(job) {
+	const needs = new Set();
+	const secret = token(CAP_SECRET, job?.secretsProfile);
+	if (secret) needs.add(secret);
+	if (Array.isArray(job?.waitFor)) {
+		for (const condition of job.waitFor) {
+			const wait = token(CAP_WAIT, condition?.profile);
+			if (wait) needs.add(wait);
+		}
+	}
+	return [...needs].sort();
+}
+
+/**
+ * Which queue this job belongs on: a host queue name, or `null` for the shared queue.
+ *
+ * FOUR ABSTENTIONS, and each one lands on today's behaviour rather than on something new. That is what
+ * makes this safe to put in front of every forge delivery: the rule can only ever move a job that would
+ * otherwise have had a coin flip decide whether it ran.
+ *
+ *   1. The job needs nothing host-specific. The overwhelming majority of deliveries.
+ *   2. EVERY live host can serve it. The shared queue is then strictly better than picking one, because it
+ *      load-balances, and it is what the docs tell operators to aim for by declaring the same profiles
+ *      everywhere. A deployment that follows that advice is byte-identical to before.
+ *   3. NO host can serve it. Routing cannot help, and the shared queue produces the existing pre-spend
+ *      refusal (`secret-profile-unknown` / `wait-profile-unknown`), which is the honest answer and already
+ *      names what to fix. Inventing a new terminal state here would be worse than the one that exists.
+ *   4. No CAPABLE host has a queue of its own, or the registry could not be read. Nothing to route to.
+ *
+ * Otherwise the job goes to a capable host, chosen by hashing its jobId: deterministic, so a redelivery of
+ * the same job lands the same way and dedup still works, and spread, so a delivery fanned out into replicas
+ * does not pile every replica onto one machine.
+ */
+export function routeForgeJob({ hosts, needs, jobId, now = () => Date.now(), freshMs = ROUTE_FRESH_MS } = {}) {
+	if (!Array.isArray(needs) || needs.length === 0) return null; // (1)
+	if (!Array.isArray(hosts) || hosts.length === 0) return null; // (4) unreadable registry, or nobody home
+
+	const live = hosts.filter((h) => {
+		// `staleMs` is derived by the reader; a row without one is a row we cannot date, and an undatable
+		// row is not evidence of life.
+		const stale = Number(h?.staleMs);
+		return Number.isFinite(stale) && stale <= freshMs;
+	});
+	if (live.length === 0) return null;
+
+	const serves = (h) => {
+		const caps = parseCaps(h?.caps);
+		return needs.every((n) => caps.has(n));
+	};
+	const capable = live.filter(serves);
+	if (capable.length === 0) return null; // (3)
+	if (capable.length === live.length) return null; // (2)
+
+	// Only a host that DECLARED a name drains a queue of its own; an undeclared one reads the shared queue
+	// only, so routing to it would be routing into a queue nothing drains.
+	const routable = capable.filter((h) => h?.routes === true || h?.routes === "true").map((h) => h?.name).filter((n) => typeof n === "string" && n !== "");
+	if (routable.length === 0) return null; // (4)
+
+	routable.sort();
+	return routable[hashIndex(String(jobId ?? ""), routable.length)];
+}
+
+/**
+ * A stable index from a string. FNV-1a, inline: this module imports nothing, and a cryptographic hash would
+ * be a strange dependency for choosing between two machines.
+ */
+function hashIndex(text, modulo) {
+	let h = 0x811c9dc5;
+	for (let i = 0; i < text.length; i++) {
+		h ^= text.charCodeAt(i);
+		h = Math.imul(h, 0x01000193) >>> 0;
+	}
+	return h % modulo;
+}

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) {