@edgehero/pi-dispatch 1.10.2 → 2.0.0

package/src/valkey-endpoint.mjs

@@ -0,0 +1,367 @@
+/**
+ * THE judge-and-pin every Valkey client of this project goes through (issue #464, gate round 2 follow-up).
+ *
+ * The owner rule (`judgeValkeyListeners`) first lived only in `service install`, `up` and doctor, then in the worker's
+ * boot; every client that connected elsewhere (`pi-dispatch run`, the receiver, the admin panel, doctor's own probes)
+ * still resolved VALKEY_URL's name itself, so during another account's `[::1]` squat a `localhost` URL carried a job's
+ * task text to that account's Valkey (measured on Fedora 44 with `pi-dispatch run`). So the rule lives where every
+ * connection is made: `connection.mjs` builds each ioredis and BullMQ client with `JudgedConnector`, which asks
+ * `judgedEndpoint` for the address to dial on every connect, and `makeQueue` and the worker refuse a connection that
+ * was not built that way. The receiver and the admin panel import `connection.mjs` from this package
+ * (`@edgehero/pi-dispatch/connection`), so they share this function rather than carrying a copy of it.
+ *
+ * The rule, for every client (gate round 3's simpler rule: nothing here depends on the cwd or on a venue guess):
+ *   - VALKEY_URL's host is resolved ONCE per process and URL, as the client would; an address that is not this host's
+ *     (another machine's Valkey) is dialled by name, as before, since pinning a remote name would defeat its DNS
+ *     failover. A name that does not resolve, or a resolver that does not answer, is a judgement that failed and is
+ *     retried, never "another host".
+ *   - On Linux, a listener held by a uid that is neither this account's euid, nor one of its subordinate uids, nor
+ *     root is refused, from any cwd, unless PI_VALKEY_SHARED=1 in the deployment's `.env` says it is shared on purpose.
+ *   - Root's listener (docker-proxy) is refused as well only where the deployment's venue is podman without `local`
+ *     (`valkeyClientContext`'s `rootRefused`), which is where it cannot be the deployment's queue.
+ *   - Of this host's addresses that answer, the first this account holds is pinned (else the first acceptable one), and
+ *     every later connect of the process goes to that literal address, its owner judged again on each one (a Valkey that
+ *     restarts is a port another account may take meanwhile).
+ * A judgement that throws never ends a client: `JudgedConnector` hands ioredis a socket destroyed with the error, and
+ * ioredis retries by its strategy and judges again (gate round 3).
+ */
+import { lookup as dnsLookup } from "node:dns/promises";
+import { readFileSync } from "node:fs";
+import { networkInterfaces, userInfo } from "node:os";
+import { join } from "node:path";
+import { venuesOf } from "./backends.mjs";
+import { VALKEY_SHARED_KEY, judgeValkeyListeners, passwdNameFrom, pinnedValkeyUrl, probeTcpAddress, readStackKeys, readSubuidRanges, readValkeyKeys, valkeySharedOn, valkeySchemeOf } from "./podman-stack.mjs";
+import { VALKEY_PASSWORD_KEY, isLoopbackHost } from "./valkey-auth.mjs";
+
+/** A refused Valkey: tagged as the configError it is, so the worker's CLI exits 2 on it. */
+export function valkeyRefusal(message) {
+	return Object.assign(new Error(message), { piDispatchConfig: true, valkeyRefused: true });
+}
+
+/**
+ * Where a client stands when its caller names no context (issue #468): `valkeyClientContext()`, the `.env` in the
+ * working directory, unless a process installed its own (`useValkeyContext`). The admin panel installs one built from
+ * the ONE `.env` reader it has (issue #471's `readDeploymentEnv`, through the worker's shared resolver, the pointer's
+ * folder only, and nothing from a file another account can change), so no second reader of a `.env` runs in the panel.
+ */
+let contextProvider = null;
+
+/** Install (or with null, remove) the function that makes the default context. */
+export function useValkeyContext(fn) {
+	contextProvider = typeof fn === "function" ? fn : null;
+}
+
+/** The context a client gets when its caller names none. */
+export function defaultValkeyContext() {
+	return contextProvider ? contextProvider() : valkeyClientContext();
+}
+
+/**
+ * Where a client stands (issue #464, gate round 3): `{ envPath, shared, rootRefused, error, password }`.
+ *
+ * The owner decision itself does not depend on this (gate round 3's simpler rule): on Linux EVERY client refuses a
+ * listener held by a uid that is neither this account's euid, nor one of its subordinate uids, nor root, from any cwd.
+ * Only two facts come from here:
+ *   - `rootRefused`: root's listener (and one no socket row explains) is refused too where the deployment's venue is
+ *     podman without `local`: this environment's PI_BACKENDS, else the `.env` in `cwd`. Elsewhere root's is docker's
+ *     Valkey, published by root's docker-proxy, and is accepted. A caller that has judged its venue (the worker) passes
+ *     it.
+ *   - `shared`: PI_VALKEY_SHARED=1 from the `.env` in `cwd`, and from nowhere else. NEVER from the environment, even
+ *     where no `.env` is found: the opt-in states a fact about the DEPLOYMENT (this Valkey is shared on purpose), and
+ *     the service's worker reads it from the deployment's `.env` alone. An environment opt-in would let `pi-dispatch run`
+ *     from a shell, or a panel or receiver started from $HOME, send the deployment's jobs into another account's queue
+ *     that its own worker refuses; a CLI user who means it runs the command in the deployment folder, whose `.env` says
+ *     so.
+ * The `.env` is read as BYTES through the hardened reader (`readStackKeys`, `readValkeyKeys`); a file that cannot be
+ * read, or a line they refuse, is `error`, never dropped: a client whose judged listener is not this account's own is
+ * then refused, naming it, since neither the opt-in nor the venue can be told.
+ *
+ * `password` (issue #468): `{ environment, file }`, VALKEY_PASSWORD from this process's environment (the service's
+ * loader puts the `.env` there) and from the `.env` in `cwd` (so `pi-dispatch pause` in the deployment folder needs no
+ * export), each null when unset or empty. Which one a client sends is `valkeyPasswordFor`'s rule. The values are never
+ * logged; a line may say only whether one is set.
+ */
+export function valkeyClientContext({ env = process.env, cwd = process.cwd(), platform = process.platform, rootRefused, readEnv = (p) => readFileSync(p) } = {}) {
+	const envPath = join(cwd, ".env");
+	let content = null;
+	let error = null;
+	try {
+		content = readEnv(envPath);
+	} catch (err) {
+		if (err?.code !== "ENOENT") error = `${envPath} could not be read (${err?.code ?? err?.message})`;
+	}
+	const fileKeys = {};
+	if (content !== null) {
+		const stack = readStackKeys(content, { loader: "systemd", path: envPath });
+		if (stack.error) error = stack.error;
+		else if (typeof stack.keys.PI_BACKENDS === "string") fileKeys.PI_BACKENDS = stack.keys.PI_BACKENDS;
+		const keys = readValkeyKeys(content, { loader: "systemd", path: envPath });
+		if (keys.error) error ??= keys.error;
+		else for (const k of [VALKEY_SHARED_KEY, VALKEY_PASSWORD_KEY, "VALKEY_URL"]) if (typeof keys.keys[k] === "string") fileKeys[k] = keys.keys[k];
+	}
+	return valkeyContextFromKeys({ env, envPath, fileKeys, error, platform, rootRefused });
+}
+
+/**
+ * A context from issue #471's resolution of the service keys (`resolveServiceEnv`'s `{ env, fromFile, disagreements }`,
+ * doctor's): this shell's side is what the resolution did NOT take from the file, the file's side is what it did, or the
+ * file's value where the two disagree. So a password the resolution took from the file is sent as the file's, to a
+ * loopback Valkey only (`valkeyPasswordFor`), and a shell's stays the shell's.
+ */
+export function valkeyContextFromResolution({ service, envPath = null, shared, platform = process.platform } = {}) {
+	const fileValue = (key) => service?.fromFile?.[key] ?? service?.disagreements?.find((d) => d.key === key)?.file;
+	const shellValue = (key) => (Object.hasOwn(service?.fromFile ?? {}, key) ? undefined : service?.env?.[key]);
+	const env = {};
+	const fileKeys = {};
+	for (const key of ["VALKEY_URL", VALKEY_PASSWORD_KEY]) {
+		if (typeof shellValue(key) === "string") env[key] = shellValue(key);
+		if (typeof fileValue(key) === "string") fileKeys[key] = fileValue(key);
+	}
+	if (typeof service?.env?.PI_BACKENDS === "string") env.PI_BACKENDS = service.env.PI_BACKENDS;
+	if (typeof shared === "string") fileKeys[VALKEY_SHARED_KEY] = shared;
+	return valkeyContextFromKeys({ env, envPath, fileKeys, platform });
+}
+
+/** The keys a client's context takes from a deployment `.env` (`valkeyContextFromKeys`). */
+export const VALKEY_CONTEXT_KEYS = Object.freeze(["VALKEY_URL", VALKEY_PASSWORD_KEY, VALKEY_SHARED_KEY, "PI_BACKENDS"]);
+
+/**
+ * A context from keys a caller has already read out of the deployment's `.env` (`fileKeys`, the `VALKEY_CONTEXT_KEYS`
+ * it supplied) and this process's environment. `valkeyClientContext` reads the file itself; the admin panel passes what
+ * issue #471's resolver read, so the panel has one `.env` reader. `error` is a reason the file could not be read, as
+ * `valkeyClientContext`'s.
+ */
+export function valkeyContextFromKeys({ env = process.env, envPath = null, fileKeys = {}, error = null, platform = process.platform, rootRefused } = {}) {
+	const fileVenue = typeof fileKeys.PI_BACKENDS === "string" ? { PI_BACKENDS: fileKeys.PI_BACKENDS } : {};
+	const shared = valkeySharedOn(fileKeys[VALKEY_SHARED_KEY]);
+	const filePassword = fileKeys[VALKEY_PASSWORD_KEY] || null;
+	const fileUrl = typeof fileKeys.VALKEY_URL === "string" ? fileKeys.VALKEY_URL : null;
+	const envPassword = typeof env[VALKEY_PASSWORD_KEY] === "string" && env[VALKEY_PASSWORD_KEY] !== "" ? env[VALKEY_PASSWORD_KEY] : null;
+	let venues = { localUsed: true, podmanUsed: false };
+	try {
+		venues = venuesOf({ PI_BACKENDS: typeof env.PI_BACKENDS === "string" ? env.PI_BACKENDS : fileVenue.PI_BACKENDS });
+	} catch {
+		// An unparseable list: the default venue, as doctor reads it; the worker refuses to boot on it anyway.
+	}
+	const derived = platform === "linux" && venues.podmanUsed && !venues.localUsed;
+	const envUrl = typeof env.VALKEY_URL === "string" ? env.VALKEY_URL : null;
+	return { envPath, shared, rootRefused: typeof rootRefused === "boolean" ? rootRefused : derived, error, password: { environment: envPassword, file: filePassword }, url: { environment: envUrl, file: fileUrl } };
+}
+
+/**
+ * Why `url` cannot name a Valkey database, as a sentence, or null (PR #478's gate). The path of a VALKEY_URL is the
+ * database number (`redis://host:port/2`); anything else (`/abc`, `/0,x=y`) became `db: NaN`, and ioredis's SELECT
+ * then failed outside any caller's await, so doctor and every client died on "an unhandled rejection: ERR value is not
+ * an integer or out of range" (measured on pd-fedora). A URL that does not parse is left to the callers that already
+ * say so. The path is shown through `urlShown`, which never prints a credential.
+ */
+export function valkeyUrlProblem(url) {
+	let u;
+	try {
+		u = new URL(String(url));
+	} catch {
+		return null;
+	}
+	// A scheme no client here speaks gets its own sentence (gate round 2: `unix:///path` was "<no host> names no
+	// database", and before this change it dialled 127.0.0.1, ioredis' default host).
+	if (valkeySchemeOf(u.protocol) === null) return `VALKEY_URL uses the scheme ${JSON.stringify(u.protocol.replace(/[^\x21-\x7e]/g, " ").slice(0, 20))}, which pi-dispatch does not connect with: write redis://host:port (or rediss://host:port for TLS; valkey:// and valkeys:// are the same two)`;
+	// Leading zeros are the number they spell (gate round 2): ioredis and the code before this read `/01` as database 1,
+	// so an upgrading deployment with one keeps its database.
+	if (!u.pathname || u.pathname === "/" || /^\/[0-9]{1,9}$/.test(u.pathname)) return null;
+	return `VALKEY_URL ${urlShown(url)} names no database: its path must be a whole number (redis://host:port/0 is database 0, and no path means the same), not ${JSON.stringify(u.pathname.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, 60))}`;
+}
+
+/**
+ * The sentence for a VALKEY_URL whose database the server refuses to SELECT (gate round 2 of PR #478): `databases` is
+ * the server's count when it could be read, null when it could not, undefined when it was not asked. Measured on Valkey: `/16` on a default server answers `ERR DB
+ * index is out of range`, and ioredis only emitted an `error` and carried on on database 0, which may be another
+ * deployment's queue.
+ */
+export function valkeyDbRangeSentence(url, db, databases) {
+	// `databases`: the server's count; null where it could not be read; undefined where it was not asked (a client's own
+	// refusal, which has only the server's answer to go on).
+	const has = Number.isInteger(databases) && databases > 0 ? `it has ${databases} (databases 0 to ${databases - 1}, its \`databases\` setting)` : databases === null ? "its `databases` setting could not be read" : "it answered the SELECT with \"DB index is out of range\"";
+	return `VALKEY_URL ${urlShown(url)} names database ${db}, which that Valkey does not have: ${has}. No client uses another database in its place; name one it has, or raise \`databases\` in that Valkey's configuration`;
+}
+
+/** The default VALKEY_URL, the worker's own (config.mjs). */
+export const DEFAULT_VALKEY_URL = "redis://127.0.0.1:6379";
+
+/**
+ * The VALKEY_URL a command run from a deployment folder uses (PR #475's review), by the same rule as the password it
+ * sends: this shell's when it sets one, else the deployment `.env`'s, else the default. `pi-dispatch run`, `pause`,
+ * `resume`, `status`, `cancel` and `service restart --drain` read the password from `.env` already and read the URL
+ * from the shell alone, so in the deployment folder of a Valkey on another port they dialled 6379 with that
+ * deployment's password. A shell and a `.env` that disagree are NAMED in `note` (the shell's is used: it is the
+ * operator's explicit choice, and the kill switch must never refuse over it); a `.env` that could not be read is too.
+ * Returns `{ url, from, note }`, `from` naming the source ("the environment", the `.env` path, or null for the default).
+ */
+export function valkeyUrlFor(context) {
+	const envUrl = context?.url?.environment ?? null;
+	const fileUrl = context?.url?.file ?? null;
+	if (typeof envUrl === "string") {
+		const note = typeof fileUrl === "string" && fileUrl !== envUrl ? `VALKEY_URL is ${urlShown(envUrl)} in this shell and ${urlShown(fileUrl)} in ${context.envPath}: using this shell's, while the service uses the file's` : null;
+		return { url: envUrl, from: "the environment", note };
+	}
+	if (typeof fileUrl === "string") return { url: fileUrl, from: context.envPath, note: null };
+	return { url: DEFAULT_VALKEY_URL, from: null, note: context?.error ? `${context.error}, so VALKEY_URL is the default, ${DEFAULT_VALKEY_URL}` : null };
+}
+
+/**
+ * The Valkey(s) a kill switch acts on (PR #475's review, rounds 2 and 3), for the CLI's `pause`, `resume`, `status` and
+ * `cancel` and the panel's `/dispatch pause|resume`: ONE rule, so the two surfaces cannot disagree about which queue
+ * "paused" is true of.
+ *   - `flagUrl` (the CLI's `--valkey-url`) when given. Refused when it carries a password: a command line is readable by
+ *     every account in /proc, so the password belongs in VALKEY_PASSWORD, which every client sends. When it names
+ *     neither this shell's VALKEY_URL nor the deployment .env's, `note` says which it is.
+ *   - else this shell's (or the process environment's, the panel's pointer layered in) and the deployment .env's
+ *     VALKEY_URL: when both are set and differ, BOTH, with `disagreement` naming the two; the caller pauses both, shows
+ *     both, and refuses a resume or a cancel until one is named.
+ *   - else `valkeyUrlFor`'s one URL, with its `note`.
+ * Returns `{ urls, disagreement, note }` or `{ error }`. URLs in the sentences go through `urlShown`.
+ */
+export function killSwitchValkeyUrls({ env = process.env, cwd, flagUrl = null, context: given = null } = {}) {
+	// `context`: a caller that has read the deployment's `.env` itself (the admin panel, issue #471) passes what it read.
+	const context = given ?? valkeyClientContext({ env, ...(cwd ? { cwd } : {}) });
+	const shell = context.url?.environment ?? null;
+	const file = context.url?.file ?? null;
+	if (flagUrl !== null && flagUrl !== undefined) {
+		let u;
+		try {
+			u = new URL(String(flagUrl));
+		} catch {
+			return { error: `--valkey-url is not a URL (redis://host:port): ${urlShown(flagUrl)}` };
+		}
+		if (u.password || u.username) {
+			return { error: `--valkey-url carries a password (or a user): a command line is readable by every account on this host in /proc, so the URL is refused. Put the password in ${VALKEY_PASSWORD_KEY} (this shell or ${context.envPath}), and give --valkey-url ${urlShown(flagUrl)}` };
+		}
+		const known = [shell, file].filter((x) => typeof x === "string").map(urlShown);
+		const note = known.includes(urlShown(flagUrl)) ? null : `using --valkey-url ${urlShown(flagUrl)}, which is neither this shell's VALKEY_URL (${typeof shell === "string" ? urlShown(shell) : "unset"}) nor ${context.envPath}'s (${typeof file === "string" ? urlShown(file) : "unset"})`;
+		return { urls: [String(flagUrl)], disagreement: null, note };
+	}
+	if (typeof shell === "string" && typeof file === "string" && shell !== file) {
+		return { urls: [shell, file], disagreement: `VALKEY_URL is ${urlShown(shell)} in this shell and ${urlShown(file)} in ${context.envPath} (what the service uses)`, note: null };
+	}
+	const resolved = valkeyUrlFor(context);
+	return { urls: [resolved.url], disagreement: null, note: resolved.note };
+}
+
+/**
+ * A URL as doctor, the CLI and the panel may print it (issue #453, gate round 3 and the re-review; moved here in PR #475's
+ * review so every surface prints a Valkey URL through ONE function): scheme, host, port and database only, never the
+ * userinfo (a password or a username that is a token), the query (`password=`, a token) or the fragment; `<no host>`
+ * without a host, and `<unparseable URL>` when it does not parse, since then nothing can say where a credential in it
+ * starts or ends. Control characters are blanked: another party's value can reach this line.
+ */
+export function urlShown(url) {
+	let parsed;
+	try {
+		parsed = new URL(String(url));
+	} catch {
+		return "<unparseable URL>";
+	}
+	if (!parsed.hostname) return "<no host>";
+	return `${parsed.protocol}//${parsed.host}${parsed.pathname && parsed.pathname !== "/" ? parsed.pathname : ""}`.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
+}
+
+/**
+ * The password a client of `url` sends, and where it came from (issue #468): `{ password, from }`, both null for none.
+ *   - the URL's own userinfo first: an operator's VALKEY_URL with a password (a managed Valkey) is left as it is;
+ *   - else VALKEY_PASSWORD from the environment, for any host (the service's loader, compose's receiver container
+ *     dialling `valkey:6379`, or an operator's export);
+ *   - else VALKEY_PASSWORD from the deployment `.env`, and only for a loopback host: the password pi-dispatch generates
+ *     belongs to the Valkey it starts on this machine, and is never sent to another one a shell's VALKEY_URL names.
+ * `withoutPassword` is for a probe asking whether a Valkey answers clients that send none (doctor, `up`).
+ */
+export function valkeyPasswordFor(url, context, { withoutPassword = false } = {}) {
+	if (withoutPassword) return { password: null, from: null };
+	let u;
+	try {
+		u = new URL(url);
+	} catch {
+		return { password: null, from: null };
+	}
+	if (u.password) return { password: decodedUserinfo(u.password), from: "VALKEY_URL" };
+	const pw = context?.password ?? {};
+	if (pw.environment) return { password: pw.environment, from: "the environment" };
+	if (pw.file && isLoopbackHost(u.hostname)) return { password: pw.file, from: context.envPath ?? ".env" };
+	return { password: null, from: null };
+}
+
+/** A URL's userinfo part as the Valkey sees it: percent-decoded (`p%40ss` is `p@ss`), as written when it does not decode. */
+export function decodedUserinfo(part) {
+	try {
+		return decodeURIComponent(part);
+	} catch {
+		return part;
+	}
+}
+
+let hostFacts = null;
+/** This host's facts for the judge, read once per process: the euid, the account name and its subordinate ranges. */
+function defaultHostFacts() {
+	if (hostFacts) return hostFacts;
+	const fs = { readFileSync };
+	const euid = typeof process.geteuid === "function" ? process.geteuid() : null;
+	let user = null;
+	try {
+		user = userInfo().username;
+	} catch {
+		// A uid with no passwd entry: its subordinate ranges are read by uid.
+	}
+	hostFacts = { fs, euid, user, subuids: readSubuidRanges({ user, euid, fs }), probeTcp: probeTcpAddress, lookup: (host, opts) => dnsLookup(host, opts), interfaces: networkInterfaces, ownerName: (uid) => passwdNameFrom(fs, uid) };
+	return hostFacts;
+}
+
+/**
+ * The address a client of `url` connects to, judged (see the header): `{ host, servername, pinned }`, `pinned` the
+ * literal address when one was judged, null for another machine's Valkey dialled by name. Throws `valkeyRefusal` for a
+ * refused Valkey, and a plain Error (`retryable`) when nothing answers or the name does not resolve: the client retries,
+ * and the next connect judges again. `cache` holds the pinned address per URL for the life of the process: resolved
+ * once, re-judged on every connect.
+ */
+export async function judgedEndpoint(url, context, { cache = PINNED, facts = defaultHostFacts() } = {}) {
+	const key = `${url}\u0000${context.rootRefused}\u0000${context.shared}`;
+	const known = cache.get(key);
+	const judge = (target) => judgeValkeyListeners({ url: target, probeTcp: facts.probeTcp, lookup: facts.lookup, fs: facts.fs, euid: facts.euid, user: facts.user, shared: context.shared, rootOk: !context.rootRefused, ownerName: facts.ownerName, interfaces: facts.interfaces, envPath: context.envPath, subuids: facts.subuids });
+	const verdict = await judge(known ? pinnedValkeyUrl(url, known).url : url);
+	if (verdict.error) throw valkeyRefusal(`VALKEY_URL: ${verdict.error}`);
+	if (verdict.unresolved) throw retryable(`VALKEY_URL's host ${verdict.unresolved} did not resolve here (${verdict.why}), so whose Valkey it reaches cannot be judged yet`);
+	if (verdict.remote) return { host: verdict.remote, servername: null, pinned: null };
+	if (verdict.refusal) throw valkeyRefusal(`the Valkey VALKEY_URL reaches is refused: ${verdict.refusal.text}`);
+	const address = verdict.chosen;
+	if (!address) throw retryable(`nothing answers VALKEY_URL (${verdict.addresses.join(", ")}:${verdict.port}), so whose Valkey it is cannot be judged yet`);
+	// A listener this account does not hold, taken on a fact of the `.env` (the opt-in, or a venue that accepts root's),
+	// is refused when that file could not be read: neither fact can then be told (gate round 3, item 5).
+	if (!verdict.own && context.error) throw valkeyRefusal(`the Valkey VALKEY_URL reaches is held by ${verdict.heldBy}, not by this account, and ${context.error}, so whether it may be used cannot be told`);
+	if (!known) cache.set(key, address);
+	return { host: address, servername: pinnedValkeyUrl(url, address).servername, pinned: address };
+}
+
+/** A judgement that may succeed later (nothing answers yet, a name that does not resolve yet): retried, never final. */
+function retryable(message) {
+	return Object.assign(new Error(message), { valkeyRetryable: true });
+}
+
+/**
+ * Judge `url` before a long-running process builds anything on it (the receiver, the poller, the CLI; issue #464, gate
+ * round 3): the refusal thrown at once (a configError: exit 2, as the worker's boot does), a retryable judgement retried
+ * every 500 ms for `waitMs`, then thrown as the plain Error it is (exit 1: the service manager starts it again).
+ */
+export async function judgeValkeyAtStart(url, context, { waitMs = 20_000, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = () => Date.now(), judge = judgedEndpoint } = {}) {
+	// PR #478's gate: a path that names no database is a refusal (exit 2 at a start), said before anything connects.
+	const dbProblem = valkeyUrlProblem(url);
+	if (dbProblem) throw valkeyRefusal(dbProblem);
+	const deadline = now() + waitMs;
+	for (;;) {
+		try {
+			return await judge(url, context);
+		} catch (err) {
+			if (!err?.valkeyRetryable || now() >= deadline) throw err;
+		}
+		await sleep(500);
+	}
+}
+
+/** The per-process pins, by URL and context. Exported for the worker to seed with its boot judgement, and for tests. */
+export const PINNED = new Map();

package/src/watch-closer.mjs

@@ -0,0 +1,158 @@
+/**
+ * The stop handle every live-edit directory watch hands back. Its own IMPORT-FREE module (issue #301),
+ * because BOTH composition roots register one: `startWorker` in the `extraClosers` list that already
+ * closes the queues and the host registry (`index.mjs` -> shutdown), and the receiver in the `closers`
+ * array its own shutdown drains. `transient.mjs` set the shape (one import-free rule module in
+ * `worker/src`, never copied into the receiver) but reaches the receiver indirectly, re-exported by the
+ * identity modules; this one rides the exports map itself as `./watch-closer`, because its consumer is
+ * the receiver's composition root and no re-exporting module sits between. The two roots' `log` shapes differ -- the
+ * worker's takes `(event, fields)`, the receiver's one object -- so the receiver hands this factory an
+ * adapter at its call site rather than this module growing a second signature.
+ *
+ * A WATCH NOTHING CAN CLOSE IS NOT A DETAIL (issue #295). `watch(dir, cb).unref?.()` retained nothing, so
+ * the watch outlived the worker that armed it, and the reload it later fired ran through THAT boot's
+ * `log` closure: that boot's injected `write`, stamped with that boot's `workerName`. One process running
+ * one worker, that is a rounding error at exit. One process running forty boots, which is what a test file
+ * is, and a worker that shut down two tests ago writes into a live worker's capture under a host that is
+ * not running -- `every log line carries the host` went red in CI reading `runnervmejwal` where it
+ * asserted `mac-mini-1`.
+ *
+ * UNREF'D IS NOT CLEANED UP, and that difference is what hid this across three features. `unref` says only
+ * that a handle will not hold the event loop open; the watch stays armed either way.
+ * `INT-HOST-REGISTRY-CONTRACT` states the same distinction from the opposite side, where a bound's timer
+ * is deliberately NOT unref'd because an unref'd timer does not fire when the hung command is the last
+ * thing holding the loop.
+ *
+ * Three properties, each one a way the shutdown breaks without it:
+ *
+ * - It CLOSES the FSWatcher, which is the leak itself.
+ * - It CANCELS the debounce the watcher already armed. Closing a watcher does not cancel a `setTimeout`
+ *   the callback already set, and only the watcher was ever unref'd -- the 150ms timer never was. In a
+ *   real worker that costs nothing, because the shutdown ends in `process.exit(0)` either way; it is the
+ *   harness, where the loop is left to drain on its own, that the stray timer reaches.
+ * - Its `close()` NEVER THROWS for the handles its three callers build, and is idempotent -- by NULLING
+ *   what it closed rather than by an early return, which would be a guard with nothing behind it. Node's
+ *   own `FSWatcher.close()` is already both (measured: a second close returns early and neither throws),
+ *   but this closer must not
+ *   INHERIT that guarantee, it must MAKE it: the shutdown loop in `index.mjs` cannot catch a SYNCHRONOUS
+ *   throw from a closer, and the comment there carries the argument. The swallow is
+ *   `makeHostRegistry.close`'s posture rather than a new one.
+ *
+ * A watch that was never created -- the `catch` arm of each function below, a platform without `fs.watch`
+ * -- still gets a closer, so registration is unconditional and the list's shape never depends on the
+ * platform. That is why all three return from OUTSIDE their try/catch.
+ *
+ * WHAT IT CANNOT DO, because the list above would otherwise read as complete: cancel a reload that has
+ * ALREADY started. `reloadSchedules` is async and awaits a Valkey round trip, so a debounce that fired
+ * just before the close is still running after it -- and the watchers stay armed for the whole drain
+ * ahead of the closer loop, not merely 150ms. That reload cannot be recalled, so what is gated instead is
+ * its VOICE: `reloadLog` below goes quiet once `closed` is set, and every reload is handed that instead
+ * of the boot's own `log`, which is what the
+ * issue actually asks for -- a stopped worker writes no line. The reload's own Valkey work may still be
+ * cut off mid-flight by the queue closing beside it, leaving a scheduler set the next boot's reconcile
+ * repairs; that race predates this change and is not narrowed by it.
+ *
+ * EXPORTED for the reason `reloadScopedLimits` is: none of the three properties is observable through a
+ * real `fs.watch` without racing the filesystem, and a guarantee the shutdown rests on deserves a
+ * deterministic pin rather than a sleep.
+ */
+export function makeWatchCloser(handles, log) {
+	return {
+		// The reload's voice, and the reason this factory is handed the boot's `log` rather than only its
+		// handles. A reload already in flight cannot be recalled, so what the close gates is what it can
+		// still SAY: after `closed`, a line from this watch would carry the host of a worker that has
+		// stopped, which is the bleed the issue is about. The arming lines keep the real `log` -- they run
+		// before any close.
+		reloadLog: (event, fields) => {
+			if (!handles.closed) log(event, fields);
+		},
+		close() {
+			// `closed` FIRST, before anything is torn down: it is what gates `reloadLog` above and the watch
+			// callback below, so a callback or a reload landing mid-close is already silenced.
+			handles.closed = true;
+			clearTimeout(handles.timer);
+			handles.timer = null;
+			try {
+				handles.watcher?.close();
+			} catch {
+				// A close that failed has already stopped mattering, and a THROW here rejects the shutdown.
+			}
+			handles.watcher = null;
+		},
+	};
+}
+
+/**
+ * The debounce every live-edit watch in this project uses, in one place (issue #386).
+ *
+ * The literal 150 was written four times -- the receiver's triggers watch and the worker's triggers,
+ * pause-windows and scoped-limits watches -- and four copies of a number is the shape `CLAUDE.md` warns
+ * about: they agree until one of them does not. It rides this module because this module is already what
+ * both composition roots import for the same four watches.
+ *
+ * WHY A DEBOUNCE AT ALL, since the number alone does not say: an atomic tmp+rename delivers more than one
+ * directory event for one edit, and the panel's own writer renames. The window only has to outlast that
+ * burst, which is why it is small enough that an operator never notices it.
+ */
+export const WATCH_DEBOUNCE_MS = 150;
+
+/**
+ * Close the BOOT RACE that every one of those four watches had (issue #386).
+ *
+ * Each service reads its file once at boot and arms the watch afterwards. Nothing re-reads in between, so
+ * an edit landing in that gap is never loaded: it waits for the NEXT edit, or for a restart. The gap is not
+ * instantaneous -- in the receiver the watch is deliberately the last fallible step of the boot, behind
+ * identity resolution, which retries for up to `RECEIVER_IDENTITY_RETRY_SECONDS`.
+ *
+ * ON MACOS THE GAP EXTENDS PAST `watch()` RETURNING, which is what makes this a lost edit rather than a
+ * late one. libuv answers `fs.watch` from `uv__fsevents_init`, which queues the path and signals its
+ * CoreFoundation thread; that thread destroys the process's single FSEvents stream and creates a new one
+ * covering every watched path, starting from "now" (libuv 1.49.2, the version Node 23.5 bundles). An edit
+ * that lands before the new stream is live is not delivered late, it is not delivered at all. Measured
+ * against the real receiver boot, ISSUE #386's own measurement: 24 of 40 trials lost the edit with four
+ * boots in one process, 1 of 40 with one boot beside a loaded machine, 0 of 40 idle. A re-measure on
+ * another machine reproduced the SHAPE and not the rate (1 of 40, 0 of 40, 0 of 40), so read the 24 as one
+ * host's worst case rather than a constant; the loss itself is real on both. Linux's inotify registers
+ * before `fs.watch` returns, so there an edit can be late but not lost.
+ *
+ * The answer is one read AFTER arming, compared against what the boot read, and a reload only when they
+ * differ -- so a quiet boot stays quiet and costs one stat-and-read per watch.
+ *
+ * WHAT IT DOES NOT CLOSE, because a helper that reads as complete is worse than one that states its edge.
+ * The FSEvents window above extends past this read too, so an edit landing between this read and the moment
+ * the stream goes live is still lost: this closes the boot-load-to-arming window and does not make the
+ * other zero, and closing that one needs a watch that reports when it is live, which `fs.watch` does not
+ * offer. And a file DELETED and recreated between the two reads is not seen, because an unreadable read on
+ * either side is treated as no change -- right for a file that went away, since every reload path keeps
+ * last-good, and wrong for one that arrived. All three loaders refuse a configured-but-missing file at
+ * boot, so reaching that means deleting and recreating inside the window.
+ */
+export function readBeforeArming(handles, read, atBoot = undefined) {
+	// `atBoot` is what the BOOT LOADER read, and it is the only baseline that measures the right window. A
+	// baseline read here instead measures the microseconds around the arming: the first version of this
+	// helper did exactly that and closed 0.1 to 0.4 milliseconds while the window the race lives in -- boot
+	// load to arming, which in the receiver holds identity resolution and its retries -- stayed open, proven
+	// end to end on both services. `undefined` means the caller has no boot read to hand over and accepts
+	// the narrower window; every caller in this project hands one over.
+	handles.armedWith = atBoot === undefined ? safeRead(read) : typeof atBoot === "string" ? atBoot : null;
+}
+
+/** True when the file changed between `readBeforeArming` and now, and there is a watch to have missed it. */
+export function changedWhileArming(handles, read) {
+	// No watcher means the arming THREW, and the service logged that it is running without a live reload.
+	// Re-reading there would paper over that with one lucky read.
+	if (!handles.watcher) return false;
+	const now = safeRead(read);
+	// An unreadable file on either side is not a change: the reload paths all keep last-good on a bad read,
+	// and firing one here would only replace a good in-memory value with the same keep-last-good outcome.
+	return now !== null && handles.armedWith !== null && now !== handles.armedWith;
+}
+
+function safeRead(read) {
+	try {
+		const v = read();
+		return typeof v === "string" ? v : null;
+	} catch {
+		return null; // a file that is absent or unreadable at boot is the loaders' business, not this one's
+	}
+}