@edgehero/pi-dispatch-receiver 1.4.0 → 2.0.0

package/src/start.mjs

@@ -30,11 +30,13 @@
  */
 
 import http from "node:http";
-import { watch } from "node:fs";
+import { readFileSync, watch } from "node:fs";
 import { dirname, basename } from "node:path";
 import { loadReceiverConfig, triggersFilePath, reloadTriggers } from "./config.mjs";
 import { makeReceiver } from "./receiver.mjs";
 import { entryExitCode } from "./cli.mjs";
+import { installRejectionPrinter } from "@edgehero/pi-dispatch/exit-code";
+import { isEntryModule } from "@edgehero/pi-dispatch/entry";
 import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
 import { resolveGitLabSelfId } from "@edgehero/pi-dispatch/gitlab-identity";
 import { resolveForgejoSelfId } from "@edgehero/pi-dispatch/forgejo-identity";
@@ -44,7 +46,10 @@ import { makeResolveForgejoAuthority } from "./forgejo-members.mjs";
 import { makeResolveAzureAuthority } from "./azure-members.mjs";
 import { makeResolveGitHubAuthority } from "./github-members.mjs";
 import { makeQueue } from "@edgehero/pi-dispatch/queue";
-import { parseConnection } from "@edgehero/pi-dispatch/connection";
+import { makeForgeRouter } from "./route.mjs";
+import { judgeValkeyAtStart, parseConnection, valkeyClientContext } from "@edgehero/pi-dispatch/connection";
+import { WATCH_DEBOUNCE_MS, changedWhileArming, makeWatchCloser, readBeforeArming } from "@edgehero/pi-dispatch/watch-closer";
+import { retryIdentity } from "./boot-retry.mjs";
 
 /**
  * Boot the receiver. Collaborators are injected (defaulting to the real ones) so the whole wiring is
@@ -53,8 +58,13 @@ import { parseConnection } from "@edgehero/pi-dispatch/connection";
 export async function startReceiver(
 	env = process.env,
 	{
+		// Where the receiver's JSON log lines go. Defaults to the real stdout; a test injects a collector
+		// rather than reassigning `process.stdout.write`, which under `node --test` is the same channel the
+		// child process reports its own results on (issue #266).
+		write = (chunk) => process.stdout.write(chunk),
 		makeAuth = makeGitHubAuth,
 		makeQueueFn = makeQueue,
+		makeForgeRouterFn = makeForgeRouter,
 		createServer = http.createServer,
 		resolveGitLabSelfId: resolveSelfIdFn = resolveGitLabSelfId,
 		makeResolveAuthority: makeResolveAuthorityFn = makeResolveAuthority,
@@ -63,12 +73,47 @@ export async function startReceiver(
 		resolveAzureSelfId: resolveAzureSelfIdFn = resolveAzureSelfId,
 		makeResolveAzureAuthority: makeResolveAzureAuthorityFn = makeResolveAzureAuthority,
 		makeResolveGitHubAuthority: makeResolveGitHubAuthorityFn = makeResolveGitHubAuthority,
+		// The boot retry's clock and sleep (issue #318). `now` is injected for the reason the worker gives
+		// (issue #284): a window read off the default `Date.now` beside a fixed test instant is a fuse that
+		// fails in CI on a tree nobody touched. `sleep` is left undefined on the real path so
+		// `retryIdentity`'s own default runs; a test injects a recorder and never waits real time.
+		now = Date.now,
+		sleep,
+		// The worker's `extraClosers` shape (issue #301): the triggers watch pushes its stop handle here, the
+		// real shutdown below drains it, and a test injects its own array so the watch it armed dies with the
+		// boot that armed it instead of leaking an FSWatcher across tests.
+		closers = [],
+		// Issue #464 (gate round 3): whose Valkey VALKEY_URL reaches, judged before the queue is built and before `listen`,
+		// by the rule every client of this project applies (`judgeValkeyAtStart`). A seam: the real one probes this
+		// host's addresses and reads /proc.
+		judgeValkey = (url, opts) => judgeValkeyAtStart(url, valkeyClientContext({ env: opts.env }), { now: opts.now, ...(opts.sleep ? { sleep: opts.sleep } : {}) }),
 	} = {},
 ) {
 	// Single-object log line: `makeReceiver` calls `log?.({ event, ... })`, so the sink takes ONE object.
-	const log = (obj) => process.stdout.write(`${JSON.stringify(obj)}\n`);
+	const log = (obj) => write(`${JSON.stringify(obj)}\n`);
 
-	const cfg = loadReceiverConfig(env);
+	// THE BOOT LOAD'S OWN READ is the baseline for the watch's boot-race check (issue #386), captured here
+	// rather than inside `watchTriggers`. That is the whole correction of a first attempt: a baseline taken
+	// where the watch arms measures the microseconds around the arming, while the window this race lives in
+	// is the one between THIS read and that arming -- which holds identity resolution, retried for up to
+	// `RECEIVER_IDENTITY_RETRY_SECONDS`. Measured on the real boot: a baseline at the watch closed 0.1 to 0.4
+	// milliseconds and left 50 to 300 milliseconds of a slow identity open, seconds under retries.
+	//
+	// Taken from the loader's OWN read, through the seam it already has, so there is no second read that an
+	// edit could land between: what the comparison is against is exactly what the receiver is running.
+	const triggersPath = triggersFilePath(env);
+	let triggersAtBoot = null;
+	const cfg = loadReceiverConfig(env, {
+		readFile: (file, enc) => {
+			const text = readFileSync(file, enc);
+			if (file === triggersPath) triggersAtBoot = text;
+			return text;
+		},
+	});
+
+	// One options bag for the four identity arms below (issue #318): the SAME window, clock and sleep for
+	// every forge, so the bound the operator configured is the bound every arm obeys.
+	const retryOpts = { windowMs: cfg.identityRetryWindowMs, log, now, sleep };
 
 	// The GitHub arm, when the deployment actually serves GitHub -- now conditional, exactly like the three
 	// sibling arms below (issue #99). It was unconditional, and since GITHUB_AUTH_SOURCE defaults to `gh` and
@@ -84,16 +129,23 @@ export async function startReceiver(
 	let selfId;
 	let resolveAuthority;
 	if (cfg.servesGithub) {
-		// HARD-FAIL identity resolution -- NO try/catch. A throw here (absent/bad github auth, unresolvable
-		// id) propagates and the server below is never created: without selfId the bot-loop guard cannot
-		// run, so refusing to boot is the only safe outcome.
+		// HARD-FAIL identity resolution -- still NO try/catch here. A DETERMINATE throw (absent/bad github
+		// auth, an unresolvable id, anything tagged piDispatchConfig) propagates same-tick and the server
+		// below is never created: without selfId the bot-loop guard cannot run, so refusing to boot is the
+		// only safe outcome. What changed (issue #318) is the TRANSIENT case: retryIdentity keeps
+		// re-resolving inside cfg.identityRetryWindowMs before letting the throw propagate, so a forge that
+		// is merely restarting no longer costs the deployment its receiver (the ~25 seconds the systemd
+		// unit's start limit used to bound recovery at, and the nothing launchd and nssm bounded it at).
+		// The retry wraps EACH arm, never the whole boot: a whole-body retry would rebuild the queue and
+		// router below once per attempt and leak their connections, and hoisting the four resolutions above
+		// the queue would reorder the first failure an operator sees.
 		//
 		// The WHOLE auth object is kept, not just selfId: the closer resolver below mints its per-delivery
 		// metadata-read token through this same object (issue #231), so identity and mint capability stay
 		// one credential decision -- an arm that resolved its identity is exactly the arm that can answer
 		// a permission question. This is also why the github handler's missing-resolver 503 is unreachable
 		// in a wired receiver: a boot that fails here mounts no `/` at all.
-		const auth = await makeAuth(cfg.github);
+		const auth = await retryIdentity(() => makeAuth(cfg.github), { forge: "github", ...retryOpts });
 		selfId = auth.selfId;
 		log({ event: "self_identity", id: selfId, source: cfg.github.source });
 		// The lookup token asks the mint to narrow to metadata:read -- the App path honors it GitHub-side,
@@ -109,77 +161,155 @@ export async function startReceiver(
 
 	// Ride-out connection (no failFast): the receiver is long-running and should survive a Valkey
 	// restart, not give up on a transient disconnect.
+	// Issue #464 (gate round 3): a refused Valkey stops the receiver here (a configError, exit 2, as the worker's boot),
+	// and one that answers nothing for 20 s ends it with exit 1 so the service manager starts it again. It used to keep
+	// running and listening with a queue that could never connect.
+	await judgeValkey(cfg.valkeyUrl, { env, now, sleep });
 	const queue = makeQueueFn(parseConnection(cfg.valkeyUrl));
 
-	// The GitLab arm, when configured. Its identity resolution is HARD-FAIL for the same reason github's
-	// is: without a selfId the bot-loop guard cannot run, and a receiver that listens without it turns the
-	// harness's own status comment into another paid job.
-	let gitlab = null;
-	if (cfg.gitlab) {
-		const gitlabSelfId = await resolveSelfIdFn({ apiUrl: cfg.gitlab.apiUrl, token: cfg.gitlab.token });
-		log({ event: "self_identity", forge: "gitlab", id: gitlabSelfId, mode: cfg.gitlab.mode });
-		gitlab = {
-			mode: cfg.gitlab.mode,
-			secret: cfg.gitlab.secret,
-			selfId: gitlabSelfId,
-			resolveAuthority: makeResolveAuthorityFn({ apiUrl: cfg.gitlab.apiUrl, token: cfg.gitlab.token }),
-		};
-	}
+	// Multi-host routing for deliveries that bind a host-local resource (issue #57, `OQ-032`). A trigger
+	// naming `run.secretsProfile` or a `run.waitFor` profile can only run where that profile is declared, and
+	// which worker pops a shared-queue job is a coin flip -- so the same trigger succeeded or failed by
+	// chance, permanently, and read like a configuration error rather than a placement one.
+	//
+	// Every failure path inside the router returns the shared queue, so a receiver whose Valkey read fails,
+	// or whose deployment has no named hosts, behaves exactly as it did before this existed.
+	const router = makeForgeRouterFn({ valkeyUrl: cfg.valkeyUrl, shared: queue, log });
 
-	// The Forgejo arm, when configured. Identity resolution is HARD-FAIL here too, and it is the arm where
-	// that matters most: a repo-scoped Forgejo token cannot call GET /user, so an operator who follows the
-	// scoping advice without setting FORGEJO_BOT_ID lands exactly here -- and a receiver that shrugged and
-	// continued would run with selfId undefined, which never equals a sender id and silently turns the
-	// harness's own comments into more paid jobs.
-	let forgejo = null;
-	if (cfg.forgejo) {
-		const forgejoSelfId = await resolveForgejoSelfIdFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token, botId: cfg.forgejo.botId });
-		log({ event: "self_identity", forge: "forgejo", id: forgejoSelfId, source: cfg.forgejo.botId ? "FORGEJO_BOT_ID" : "api" });
-		forgejo = {
-			secret: cfg.forgejo.secret,
-			selfId: forgejoSelfId,
-			resolveAuthority: makeResolveForgejoAuthorityFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token }),
-		};
-	}
+	// EVERY refusal below this line lands after the queue and the router exist, so it must stop
+	// what the boot built (issue #299's rule, the receiver's copy; measured for #318 on main AND
+	// this branch, against a live Valkey): with the shared clients left open, the entry assigns
+	// process.exitCode and the loop never drains -- the failure line printed at 0.4s and the
+	// process was still alive at 90s. Under Type=simple that reads as "active (running)" with
+	// nothing listening, Restart= never fires, RestartPreventExitStatus=2 is never consulted, and
+	// the retry window's exit-1-into-a-fresh-window contract above never engages. The github arm
+	// and the config load sit ABOVE the queue and always exited cleanly; these three arms did not.
+	try {
+		// The GitLab arm, when configured. Its identity resolution is HARD-FAIL for the same reason github's
+		// is: without a selfId the bot-loop guard cannot run, and a receiver that listens without it turns the
+		// harness's own status comment into another paid job.
+		let gitlab = null;
+		if (cfg.gitlab) {
+			const gitlabSelfId = await retryIdentity(() => resolveSelfIdFn({ apiUrl: cfg.gitlab.apiUrl, token: cfg.gitlab.token }), { forge: "gitlab", ...retryOpts });
+			log({ event: "self_identity", forge: "gitlab", id: gitlabSelfId, mode: cfg.gitlab.mode });
+			gitlab = {
+				mode: cfg.gitlab.mode,
+				secret: cfg.gitlab.secret,
+				selfId: gitlabSelfId,
+				resolveAuthority: makeResolveAuthorityFn({ apiUrl: cfg.gitlab.apiUrl, token: cfg.gitlab.token }),
+			};
+		}
 
-	// The Azure arm, when configured. Identity resolution is HARD-FAIL here too, and it resolves BOTH forms
-	// of the harness's identity in one call: a pull-request delivery names an actor by GUID and a work item
-	// names them only by email address, so a guard that knew one form would be blind on half the events.
-	let azure = null;
-	if (cfg.azure) {
-		const azureSelfId = await resolveAzureSelfIdFn({ orgUrl: cfg.azure.orgUrl, token: cfg.azure.token });
-		log({ event: "self_identity", forge: "azure", id: azureSelfId.id, hasAccountName: azureSelfId.email !== null, mode: cfg.azure.mode });
-		azure = {
-			mode: cfg.azure.mode,
-			secret: cfg.azure.secret,
-			headerName: cfg.azure.headerName,
-			selfId: azureSelfId,
-			resolveAuthority: makeResolveAzureAuthorityFn({ orgUrl: cfg.azure.orgUrl, token: cfg.azure.token }),
-		};
-	}
+		// The Forgejo arm, when configured. Identity resolution is HARD-FAIL here too, and it is the arm where
+		// that matters most: a repo-scoped Forgejo token cannot call GET /user, so an operator who follows the
+		// scoping advice without setting FORGEJO_BOT_ID lands exactly here -- and a receiver that shrugged and
+		// continued would run with selfId undefined, which never equals a sender id and silently turns the
+		// harness's own comments into more paid jobs.
+		let forgejo = null;
+		if (cfg.forgejo) {
+			const forgejoSelfId = await retryIdentity(() => resolveForgejoSelfIdFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token, botId: cfg.forgejo.botId }), { forge: "forgejo", ...retryOpts });
+			log({ event: "self_identity", forge: "forgejo", id: forgejoSelfId, source: cfg.forgejo.botId ? "FORGEJO_BOT_ID" : "api" });
+			forgejo = {
+				secret: cfg.forgejo.secret,
+				selfId: forgejoSelfId,
+				resolveAuthority: makeResolveForgejoAuthorityFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token }),
+			};
+		}
 
-	const handler = makeReceiver({ queue, selfId, cfg, log, gitlab, forgejo, azure, resolveAuthority });
-	const server = createServer(handler);
-	server.listen(cfg.port, cfg.bind, () =>
-		log({ event: "receiver_started", port: cfg.port, bind: cfg.bind, valkey: cfg.valkeyUrl }),
-	);
-
-	// Graceful shutdown AND the live-trigger watcher only on the real entry (default createServer). Under
-	// test injection the fakes are per-test, so a process-wide signal handler or an fs watcher would leak
-	// across tests; the reload LOGIC (`reloadTriggers`) is unit-tested directly instead.
-	if (createServer === http.createServer) {
-		watchTriggers(env, cfg, log);
-		const shutdown = async (signal) => {
-			log({ event: "receiver_stopping", signal });
-			await new Promise((resolve) => server.close(resolve));
-			await queue.close();
-			process.exit(0);
-		};
-		process.once("SIGTERM", () => void shutdown("SIGTERM"));
-		process.once("SIGINT", () => void shutdown("SIGINT"));
-	}
+		// The Azure arm, when configured. Identity resolution is HARD-FAIL here too, and it resolves BOTH forms
+		// of the harness's identity in one call: a pull-request delivery names an actor by GUID and a work item
+		// names them only by email address, so a guard that knew one form would be blind on half the events.
+		let azure = null;
+		if (cfg.azure) {
+			const azureSelfId = await retryIdentity(() => resolveAzureSelfIdFn({ orgUrl: cfg.azure.orgUrl, token: cfg.azure.token }), { forge: "azure", ...retryOpts });
+			log({ event: "self_identity", forge: "azure", id: azureSelfId.id, hasAccountName: azureSelfId.email !== null, mode: cfg.azure.mode });
+			azure = {
+				mode: cfg.azure.mode,
+				secret: cfg.azure.secret,
+				headerName: cfg.azure.headerName,
+				selfId: azureSelfId,
+				resolveAuthority: makeResolveAzureAuthorityFn({ orgUrl: cfg.azure.orgUrl, token: cfg.azure.token }),
+			};
+		}
 
-	return server;
+		const handler = makeReceiver({ queue, router, selfId, cfg, log, gitlab, forgejo, azure, resolveAuthority });
+		const server = createServer(handler);
+		server.listen(cfg.port, cfg.bind, () =>
+			log({ event: "receiver_started", port: cfg.port, bind: cfg.bind, valkey: cfg.valkeyUrl }),
+		);
+
+		// The watch arms UNCONDITIONALLY now (issue #301). Armed only on the real entry, the lifecycle defect
+		// was muted under test rather than closed, and this file had no coverage that the watch arms at all --
+		// `DES-WATCHERS-CLOSE-WITH-THE-WORKER` rejected exactly that posture for the worker. The closer rides
+		// the injected `closers` array, so a test drains what its boot armed and the real shutdown closes it.
+		//
+		// LAST FALLIBLE STEP, deliberately, and it must stay last: every refusal this boot can produce -- the
+		// config load, each hard-fail identity resolution, the router build, even a throwing `listen` -- sits
+		// ABOVE this line, so a refused boot has armed nothing and there is never a closer with no one left to
+		// drain it. The worker states the same invariant where its watchers arm. A step added BELOW that can
+		// throw reopens issue #301 on the refusal path; the HARD-FAIL test pins the refusals that exist today.
+		closers.push(watchTriggers(env, cfg, log, triggersAtBoot));
+
+		// Graceful shutdown only on the real entry (default createServer). Under test injection the fakes are
+		// per-test, so a process-wide SIGNAL HANDLER would still leak across tests -- and unlike the watch it
+		// has no seam to ride: the closers array cannot un-register a `process.once`. The shutdown's own steps
+		// are one call per handle, each covered through its seam.
+		if (createServer === http.createServer) {
+			const shutdown = async (signal) => {
+				log({ event: "receiver_stopping", signal });
+				await new Promise((resolve) => server.close(resolve));
+				await queue.close();
+				await router.close();
+				// The watch closer, and whatever joins it later. Per-item try, because a throw here would strand
+				// the `process.exit(0)` that the unit's stop depends on -- `index.mjs`'s closer loop states the
+				// same rule for the worker.
+				for (const c of closers) {
+					try {
+						c?.close?.();
+					} catch {
+						// A closer that failed has already stopped mattering.
+					}
+				}
+				process.exit(0);
+			};
+			process.once("SIGTERM", () => void shutdown("SIGTERM"));
+			process.once("SIGINT", () => void shutdown("SIGINT"));
+		}
+
+		return server;
+	} catch (err) {
+		// Best-effort, per handle, and the refusal rethrows unchanged: the cleanup must never
+		// replace the story. BullMQ's close() is idempotent and the router closes its own pool.
+		//
+		// The error swallow first, and it is measured, not defensive: a queue built moments ago can
+		// still be mid-handshake, and every client error in that window is forwarded to the Queue
+		// object, where makeQueue attaches no listener -- unlistened, one such event crashed the
+		// process at exit 1 and stomped the exit 2 this catch exists to deliver. Scoped to the
+		// refusal path: the serving path's error surface is unchanged.
+		queue.on?.("error", () => {});
+		try {
+			// The RAW client, deliberately NOT queue.close(): close() on a maybe-still-connecting
+			// client strips every listener in RedisConnection.close()'s finally (removeAllListeners),
+			// and the constructor's `initializing.catch` then re-emits the flushed handshake as an
+			// 'error' on a LISTENERLESS emitter -- an uncaught crash whose exit 1 stomped this exit
+			// code on 3 of 5 measured refusals, and a settle-first close() variant still crashed
+			// against a DEAD Valkey. A direct disconnect() leaves the connection's listeners alone,
+			// so the same late rejection flows connection -> queue -> the swallow above, and ioredis
+			// disconnect() releases the socket AND stops the ride-out reconnects, in every client
+			// state (the #300 measurement). `_client` is a BullMQ private, reached on the host-pi
+			// precedent for pinned internals: the real-BullMQ integration test is the pin, so a bump
+			// that moves it goes red there instead of sliding silently back to the wedge.
+			queue.connection?._client?.disconnect?.();
+		} catch {
+			// A handle that failed to close has stopped mattering to a process about to exit.
+		}
+		try {
+			await router.close();
+		} catch {
+			// Same.
+		}
+		throw err;
+	}
 }
 
 /**
@@ -187,31 +317,60 @@ export async function startReceiver(
  * admin writes with, which swaps the inode a file-watch would lose), debounce, and re-read on change. A bad
  * edit keeps the running triggers (reloadTriggers never throws) and logs a kept-old notice. Best-effort: a
  * platform without `fs.watch` logs and the receiver simply keeps its boot-time triggers.
+ *
+ * Returns the worker's stop handle (issue #301), registered in `closers` so the shutdown -- or the test
+ * that injected the array -- closes the FSWatcher and cancels the debounce it armed. A closer is returned
+ * even when the watch could not arm: closing a never-armed handle is a no-op by construction, and a
+ * caller that has to ask "did I get one" is how a handle goes unregistered.
  */
-function watchTriggers(env, cfg, log) {
+// `triggersAtBoot` has NO DEFAULT on purpose (issue #386). A default of `null` would silently DISABLE the
+// boot-race check for a caller that forgot it, which is the failure this whole change exists to stop; with
+// none, forgetting it is `undefined`, and `readBeforeArming` reads that as "no boot read to hand over" and
+// says so by falling back to its own read rather than to nothing.
+function watchTriggers(env, cfg, log, triggersAtBoot) {
 	const path = triggersFilePath(env);
 	const dir = dirname(path) || ".";
 	const file = basename(path);
-	let timer = null;
+	const handles = { watcher: null, timer: null, closed: false };
+	// The worker's closer, reused rather than re-derived (issue #301). Its `log` takes `(event, fields)`
+	// where this file's takes one object, so it is handed an adapter here instead of the module growing a
+	// second signature. The reload lines go through `closer.reloadLog` -- the reload's VOICE, gated once
+	// the handle closes; the arming lines keep the real `log`, because they run before any close exists.
+	const closer = makeWatchCloser(handles, (event, fields) => log({ event, ...fields }));
+	const readFile = () => readFileSync(path, "utf8");
+	const reload = () => {
+		const res = reloadTriggers(env, cfg);
+		if (res.ok) closer.reloadLog("triggers_reloaded");
+		else closer.reloadLog("triggers_reload_invalid", { reason: res.invalid, kept: true });
+	};
+	// The baseline is the BOOT LOAD's own read, handed in (issue #386). Comparing against a read taken here
+	// would measure the arming instead of the window: this service arms LAST, behind identity resolution that
+	// retries for up to RECEIVER_IDENTITY_RETRY_SECONDS, and that is the window an edit is lost in.
+	readBeforeArming(handles, readFile, triggersAtBoot);
 	try {
-		watch(dir, (_event, changed) => {
+		handles.watcher = watch(dir, (_event, changed) => {
+			if (handles.closed) return; // see makeWatchCloser: by construction, not by a delivery rule
 			if (changed && changed !== file) return; // only our file (null changed name -> reload to be safe)
-			clearTimeout(timer);
-			timer = setTimeout(() => {
-				const res = reloadTriggers(env, cfg);
-				if (res.ok) log({ event: "triggers_reloaded" });
-				else log({ event: "triggers_reload_invalid", reason: res.invalid, kept: true });
-			}, 150);
-		}).unref?.();
+			clearTimeout(handles.timer);
+			handles.timer = setTimeout(reload, WATCH_DEBOUNCE_MS);
+		});
+		handles.watcher.unref?.();
 		log({ event: "triggers_watching", path });
 	} catch (err) {
 		log({ event: "triggers_watch_unavailable", reason: err?.message });
 	}
+	if (changedWhileArming(handles, readFile)) {
+		log({ event: "triggers_reread_after_arming", path });
+		reload();
+	}
+	return closer;
 }
 
 // Entry point when run directly (main: src/start.mjs, no bin). Kept out of startReceiver so tests call
 // it directly. The error line carries only `err.message` -- never a secret or PII.
-if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("start.mjs")) {
+if (isEntryModule(import.meta.url)) {
+	// An unhandled rejection is printed as its message alone (PR #475's review), never Node's print of the whole reason.
+	installRejectionPrinter();
 	startReceiver(process.env).catch((err) => {
 		process.stderr.write(`${JSON.stringify({ event: "receiver_start_failed", reason: err?.message })}\n`);
 		// entryExitCode, NOT a bare 1. This file is what `receiver.service` execs -- cli.mjs is not on that