@edgehero/pi-dispatch-receiver 0.1.0

package/src/predicate.mjs

@@ -0,0 +1,62 @@
+/**
+ * The label predicate and its helpers: the `{any, all, none}` evaluation every forge's gate runs, plus the
+ * two small readers around it.
+ *
+ * Shared rather than copied (issue #42). This is the rule that decides whether an event becomes a paid
+ * agent run, and on the github label path it IS the approval gate (CONST-TRIGGER-AUTHOR-GATE). Two
+ * implementations of that would eventually disagree, and the forge whose copy drifted would be the one
+ * quietly running work nobody approved.
+ *
+ * Pure and total: reads only its arguments, touches no I/O, never throws -- which is what keeps each
+ * forge's gate decidable offline, without a server, a socket, or a queue.
+ */
+
+/** The set of label names present on an issue/PR; non-string names are dropped. */
+export function labelSet(labels) {
+	const arr = Array.isArray(labels) ? labels : [];
+	return new Set(arr.map((l) => l?.name).filter((n) => typeof n === "string"));
+}
+
+/** First rule (in file order) whose predicate matches `L`, or undefined. The rule carries its raw-file `index`. */
+export function firstMatchingRule(rules, L) {
+	for (const rule of rules ?? []) {
+		if (matchesRule(L, rule.predicate)) return rule;
+	}
+	return undefined;
+}
+
+/**
+ * The label that satisfied a matched rule's positive selector, for `trigger.matched.label`: the first
+ * `any` entry present in `L`, else `all[0]` (all ⊆ L holds whenever the rule matched, so membership is
+ * guaranteed), else null. Deterministic in rule order -- honest about WHICH label opened the gate, not
+ * merely that one did.
+ */
+export function matchedLabel(L, predicate) {
+	const anyHit = (predicate?.any ?? []).find((x) => L.has(x));
+	if (anyHit !== undefined) return anyHit;
+	return predicate?.all?.[0] ?? null;
+}
+
+/**
+ * Per-rule label predicate over the label set `L`:
+ *   (any empty OR L∩any ≠ ∅) AND (all ⊆ L) AND (L∩none = ∅).
+ * An empty `any` is vacuously true, so the `all`/`none` clauses carry the requirement; the loader
+ * guarantees at least one positive selector where the predicate is the approval gate (label triggers and
+ * `labeled` PR triggers), so a validated approval rule can never match every event. Reads only its
+ * arguments and never throws -- the gate's purity extends here, and the defensive `?? []` covers a rule
+ * the loader has already validated.
+ */
+export function matchesRule(L, rule) {
+	const any = rule?.any ?? [];
+	const all = rule?.all ?? [];
+	const none = rule?.none ?? [];
+	if (any.length > 0 && !any.some((x) => L.has(x))) return false;
+	if (!all.every((x) => L.has(x))) return false;
+	if (none.some((x) => L.has(x))) return false;
+	return true;
+}
+
+/** Escape a literal string for safe embedding in a RegExp -- the trigger phrase is config, not a pattern. */
+export function escapeRegExp(literal) {
+	return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/receiver.mjs

@@ -0,0 +1,330 @@
+/**
+ * The webhook receiver: a thin producer that turns a verified GitHub webhook into (at most) one queued
+ * job -- or, when the matched trigger opted into `run.replicas`, into exactly that many independent ones
+ * (REQ-REPLICA-RUNS). It composes the three pieces that own the hard parts -- `makeVerifiedHandler` (the
+ * HMAC trust boundary), `filter` (the trigger/author gate), and the SHARED `enqueueGitHubJob` -- and adds
+ * only the glue: parse the verified body, project the payload subset, route on the filter's verdict, and
+ * map the outcome to a status code.
+ *
+ * DES-TRIGGER-OUTSIDE-PI: the trigger lives outside pi. This module imports the shared `enqueueGitHubJob`
+ * and never re-implements `queue.add` -- the queue's jobId/dedup/retention policy has exactly one owner,
+ * so there is no drift between what the receiver enqueues and what every other producer does.
+ *
+ * no-pii-in-logs: logs carry stable non-PII identifiers only -- the delivery GUID, repo full_name, issue
+ * number, flow, and a drop/failure reason. Never an issue title/body, a comment body, or a login.
+ *
+ * DES-ADMIN-VIA-PI-EXTENSION: the receiver exposes only the webhook handler. There is no admin,
+ * dashboard, or admin-extension route here -- the admin surface is a pi extension in the operator's
+ * session and binds no port.
+ */
+
+import { makeVerifiedHandler } from "./verify.mjs";
+import { filter } from "./filter.mjs";
+import { enqueueForgeJob, enqueueGitHubJob, enqueueGitLabJob } from "@edgehero/pi-dispatch/queue";
+import { filterGitLab } from "./filter-gitlab.mjs";
+import { parseGitLabSubset } from "./gitlab-subset.mjs";
+import { makeGitLabVerifiedHandler } from "./verify-gitlab.mjs";
+import { filterForgejo } from "./filter-forgejo.mjs";
+import { parseForgejoSubset } from "./forgejo-subset.mjs";
+import { filterAzure } from "./filter-azure.mjs";
+import { parseAzureSubset } from "./azure-subset.mjs";
+import { makeAzureVerifiedHandler } from "./verify-azure.mjs";
+
+/** Write a small JSON body with an explicit status; a 204 carries no body. verify's `respond` is private. */
+function respond(res, status, obj) {
+	if (status === 204) {
+		res.writeHead(204);
+		res.end();
+		return;
+	}
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(JSON.stringify(obj ?? {}));
+}
+
+/**
+ * Project ONLY the INT-WEBHOOK-PAYLOAD-SUBSET fields out of a parsed webhook payload. Nothing outside
+ * this set flows onward to the filter or the job: the subset is the whole surface the trigger decision
+ * and the enqueued job are allowed to see.
+ */
+export function parseSubset(payload) {
+	const pr = payload.pull_request;
+	return {
+		action: payload.action,
+		sender: { id: payload.sender?.id },
+		issue: {
+			number: payload.issue?.number,
+			title: payload.issue?.title,
+			body: payload.issue?.body,
+			labels: Array.isArray(payload.issue?.labels) ? payload.issue.labels.map((l) => ({ name: l?.name })) : [],
+			// Presence marker only: an issue_comment on a PR carries issue.pull_request, so the comment path
+			// routes it as a pull_request target. A boolean keeps a URL/login out of the subset.
+			pull_request: payload.issue?.pull_request != null,
+		},
+		comment: { body: payload.comment?.body, author_association: payload.comment?.author_association },
+		// pull_request event fields (labeled/opened/synchronize/reopened). head/base are attacker-controlled
+		// fork DATA -- projected for the flow's event.json, NEVER used as a clone ref (the worker clones the
+		// base default-branch SHA). Absent for non-PR events.
+		pull_request: pr
+			? {
+					number: pr.number,
+					title: pr.title,
+					body: pr.body,
+					author_association: pr.author_association,
+					labels: Array.isArray(pr.labels) ? pr.labels.map((l) => ({ name: l?.name })) : [],
+					head: { ref: pr.head?.ref, sha: pr.head?.sha, repo: { full_name: pr.head?.repo?.full_name } },
+					base: { ref: pr.base?.ref },
+				}
+			: undefined,
+		repository: { full_name: payload.repository?.full_name },
+	};
+}
+
+/**
+ * Build the receiver's `node:http` handler.
+ *
+ * ROUTING BY PATH, not by header (issue #42). Each forge gets its own path, and with it its own secret and
+ * its own trust regime, decided before a byte of the body is read. Discriminating on headers instead would
+ * hand that choice to the sender: Forgejo emits `X-GitHub-*` on every delivery, so header-sniffing cannot
+ * even tell two forges apart reliably, and a request that could select which gate it faced would always
+ * select the weakest one available.
+ *
+ * `/` stays mapped to GitHub. Existing deployments configured their webhook URL before any path existed,
+ * and silently 404-ing them would look exactly like the harness being down.
+ *
+ * A forge with no configuration gets no route at all -- not a route that answers 401. An endpoint that
+ * responds to an unconfigured forge is an endpoint an operator can believe is armed.
+ */
+export function makeReceiver({ queue, selfId, cfg, log, gitlab = null, forgejo = null, azure = null }) {
+	const github = makeGitHubHandler({ queue, selfId, cfg, log });
+
+	// A TABLE, built once, rather than one `if` per forge. Two forges made that a single branch; four make
+	// it a chain, and a chain is where one arm quietly ends up checked after the fallthrough. A path present
+	// with a null handler is a CONFIGURED-OFF forge and answers 404; a path absent from the table entirely
+	// falls through to GitHub, which is what keeps `/` working.
+	const routes = {
+		"/gitlab": gitlab ? makeGitLabHandler({ queue, cfg, log, ...gitlab }) : null,
+		"/forgejo": forgejo ? makeForgejoHandler({ queue, cfg, log, ...forgejo }) : null,
+		"/azure": azure ? makeAzureHandler({ queue, cfg, log, ...azure }) : null,
+	};
+
+	return async function receiverHandler(req, res) {
+		const path = pathOf(req.url);
+		if (Object.hasOwn(routes, path)) {
+			const handler = routes[path];
+			// Not a 401. An endpoint that answers "unauthorized" for a forge nobody configured is an endpoint
+			// an operator can believe is armed and merely mis-keyed.
+			if (!handler) return respond(res, 404, { error: `${path.slice(1)} webhooks are not configured` });
+			return await handler(req, res);
+		}
+		return await github(req, res);
+	};
+}
+
+/** The path portion of a request URL, without query or trailing slash. Never throws on a malformed URL. */
+function pathOf(url) {
+	const raw = String(url ?? "/").split("?")[0];
+	return raw.length > 1 && raw.endsWith("/") ? raw.slice(0, -1) : raw;
+}
+
+/**
+ * The GitHub arm. Returns `makeVerifiedHandler`'s handler directly, so it only ever sees an already-verified
+ * request. `onVerified` owns parse, filter, enqueue, and response; a good signature is the sole
+ * precondition D2 guarantees before it runs.
+ */
+function makeGitHubHandler({ queue, selfId, cfg, log }) {
+	return makeVerifiedHandler({ secret: cfg.webhookSecret }, async ({ rawBody, event, delivery }, res) => {
+		let subset;
+		try {
+			subset = parseSubset(JSON.parse(rawBody));
+		} catch {
+			return respond(res, 400, { error: "invalid-json" });
+		}
+
+		const result = filter(event, subset, cfg, selfId, delivery);
+		if (!result.enqueue) {
+			log?.({ event: "dropped", delivery, reason: result.reason });
+			return respond(res, 204);
+		}
+
+		// REPLICA FANOUT (REQ-REPLICA-RUNS). The one place a single delivery becomes more than one job, and it
+		// belongs here because this is where the 202/503 decision already lives. Absent `replicas` is `1` and
+		// the call below is byte-identical to the single enqueue it replaced -- no `replica` key on the job,
+		// so the jobId, the dedup id and `data` are all exactly what they were.
+		//
+		// PARTIAL FAILURE IS IDEMPOTENT BY CONSTRUCTION, which is why there is no compensating logic here: if
+		// replica k throws, the catch below answers 503, GitHub redelivers, replicas 1..k-1 dedup on their own
+		// now-taken jobIds and k..n enqueue. The retry converges on exactly n jobs rather than n + (k-1).
+		const replicas = result.job.replicas ?? 1;
+		try {
+			for (let i = 1; i <= replicas; i++) {
+				await enqueueGitHubJob(queue, replicas > 1 ? { ...result.job, replica: i } : result.job);
+			}
+		} catch (err) {
+			// Own try/catch so a Valkey-down enqueue is a 503 (retryable), not verify's outer 500.
+			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
+			return respond(res, 503, { error: "enqueue-failed" }); // GitHub redelivers; dedup by GUID coalesces
+		}
+
+		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
+		return respond(res, 202, { status: "queued" });
+	});
+}
+
+/**
+ * The GitLab arm. Same shape as the GitHub one -- verify, project, gate, enqueue, respond -- with one step
+ * the GitHub path does not need: the actor's project access level is RESOLVED here, between verification
+ * and the gate, because GitLab puts no `author_association` in the payload (gitlab-members.mjs).
+ *
+ * That resolution is a network call, and its three outcomes are deliberately not two:
+ *   - a determinate verdict (authorized or not) is handed to the gate, which decides;
+ *   - an INDETERMINATE lookup is a 503, so GitLab redelivers and the stable `webhook-id` dedups the
+ *     retry. Answering 204 would drop real work during an outage, and it would look on the wire exactly
+ *     like a stranger being correctly refused.
+ * The lookup runs only for events that could still fire -- after verification, and after the payload has
+ * been projected -- so an unauthenticated flood cannot make this project call GitLab at all.
+ */
+function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAuthority, now }) {
+	return makeGitLabVerifiedHandler({ mode, secret, ...(now ? { now } : {}) }, async ({ rawBody, delivery }, res) => {
+		let subset;
+		try {
+			subset = parseGitLabSubset(JSON.parse(rawBody));
+		} catch {
+			return respond(res, 400, { error: "invalid-json" });
+		}
+
+		const resolved = await resolveAuthority(subset.project?.id, subset.user?.id);
+		if (resolved.indeterminate) {
+			// The reason names the lookup, never the actor -- `user.username` is personal data and exists
+			// only to have been asked about (no-pii-in-logs).
+			log?.({ event: "gitlab_access_lookup_failed", delivery, reason: resolved.indeterminate });
+			return respond(res, 503, { error: "access-lookup-failed" });
+		}
+
+		const result = filterGitLab(subset, cfg.triggers?.gitlab, cfg.triggers?.knownFlows, selfId, resolved.authorized, delivery);
+		if (!result.enqueue) {
+			log?.({ event: "dropped", delivery, reason: result.reason });
+			return respond(res, 204);
+		}
+
+		try {
+			await enqueueGitLabJob(queue, result.job);
+		} catch (err) {
+			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
+			return respond(res, 503, { error: "enqueue-failed" }); // GitLab redelivers; dedup by webhook-id coalesces
+		}
+
+		// `!` for a merge request, `#` for an issue -- GitLab's own notation, and the same discrimination
+		// the semantic dedup key makes, because the two are separate number sequences.
+		const sep = result.job.target.type === "pull_request" ? "!" : "#";
+		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow });
+		return respond(res, 202, { status: "queued" });
+	});
+}
+
+/**
+ * The Forgejo arm. Structurally the GitLab one -- verify, project, RESOLVE, gate, enqueue, respond -- with
+ * one difference that is worth stating because it is invisible in the code: the verification step is
+ * GITHUB'S, unmodified.
+ *
+ * Forgejo signs the raw body with HMAC-SHA256 and sends `X-Hub-Signature-256`, `X-GitHub-Delivery` and
+ * `X-GitHub-Event`, which is byte-for-byte what `makeVerifiedHandler` already reads. So
+ * CONST-HMAC-OVER-RAW-BODY is satisfied here by EXISTING code rather than new code, and
+ * REQ-DEDUP-BY-DELIVERY-GUID transfers with no adaptation at all. What Forgejo needs is its own SECRET,
+ * which is why it is a separate handler and a separate path: `makeVerifiedHandler` closes over one secret
+ * per construction, and serving two sources from one would mean either sharing a secret between forges or
+ * letting the request choose which one it was checked against.
+ */
+function makeForgejoHandler({ queue, cfg, log, secret, selfId, resolveAuthority }) {
+	return makeVerifiedHandler({ secret }, async ({ rawBody, event, delivery }, res) => {
+		let subset;
+		try {
+			subset = parseForgejoSubset(JSON.parse(rawBody));
+		} catch {
+			return respond(res, 400, { error: "invalid-json" });
+		}
+
+		const resolved = await resolveAuthority(subset.repository?.full_name, subset.sender?.login);
+		if (resolved.indeterminate) {
+			// The reason names the lookup, never the actor -- `sender.login` is personal data and exists here
+			// only to have been asked about (no-pii-in-logs).
+			log?.({ event: "forgejo_permission_lookup_failed", delivery, reason: resolved.indeterminate });
+			return respond(res, 503, { error: "permission-lookup-failed" });
+		}
+
+		const result = filterForgejo(event, subset, cfg.triggers?.forgejo, cfg.triggers?.knownFlows, selfId, resolved.authorized, delivery);
+		if (!result.enqueue) {
+			log?.({ event: "dropped", delivery, reason: result.reason });
+			return respond(res, 204);
+		}
+
+		try {
+			await enqueueForgeJob(queue, "forgejo", result.job);
+		} catch (err) {
+			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
+			return respond(res, 503, { error: "enqueue-failed" }); // Forgejo redelivers; dedup by GUID coalesces
+		}
+
+		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow });
+		return respond(res, 202, { status: "queued" });
+	});
+}
+
+/**
+ * The Azure DevOps arm. The same five steps, with two things no other arm has.
+ *
+ * THE DELIVERY ID COMES OUT OF THE BODY. Azure sends no delivery-id header, so the dedup key
+ * (REQ-DEDUP-BY-DELIVERY-GUID) is the payload's own top-level `id` GUID. `verify-gitlab.mjs` refuses to do
+ * this and 400s instead -- correctly, for a forge that HAS a header. Azure has none, so the choice is a
+ * body-derived key or no dedup at all, and the ordering is unaffected: the body is parsed here, inside
+ * `onVerified`, after the credential check. A delivery with no `id` is refused rather than run
+ * undeduplicated.
+ *
+ * THE ACTOR MAY BE AN EMAIL. A pull-request delivery names a GUID; a work item names only
+ * `"Display Name <email>"`. Both the resolver and the bot-loop guard handle both forms -- see
+ * filter-azure.mjs, where the ordering constraint is stated in full.
+ */
+function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, resolveAuthority }) {
+	return makeAzureVerifiedHandler({ mode, secret, headerName }, async ({ rawBody }, res) => {
+		let subset;
+		try {
+			subset = parseAzureSubset(JSON.parse(rawBody));
+		} catch {
+			return respond(res, 400, { error: "invalid-json" });
+		}
+
+		const delivery = subset.id;
+		if (typeof delivery !== "string" || delivery === "") {
+			// Without it there is no dedup key, and a redelivery would be billed as new work. A synthesised
+			// key would dedup some redeliveries and bill for the rest -- a weaker guarantee wearing
+			// REQ-DEDUP-BY-DELIVERY-GUID's name, which is worse than a clear refusal.
+			return respond(res, 400, { error: "missing-delivery-id" });
+		}
+
+		const resolved = await resolveAuthority(subset.project?.id, subset.actor);
+		if (resolved.indeterminate) {
+			// The reason names the lookup, never the actor -- an email address is personal data and exists
+			// here only to have been asked about (no-pii-in-logs).
+			log?.({ event: "azure_membership_lookup_failed", delivery, reason: resolved.indeterminate });
+			return respond(res, 503, { error: "membership-lookup-failed" });
+		}
+
+		const result = filterAzure(subset, cfg.triggers?.azure, cfg.triggers?.knownFlows, selfId, resolved.authorized, delivery);
+		if (!result.enqueue) {
+			log?.({ event: "dropped", delivery, reason: result.reason });
+			return respond(res, 204);
+		}
+
+		try {
+			await enqueueForgeJob(queue, "azure", result.job);
+		} catch (err) {
+			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
+			return respond(res, 503, { error: "enqueue-failed" });
+		}
+
+		// `!` for a pull request, `#` for a work item -- Azure numbers them separately, and this is the same
+		// discrimination the semantic dedup key makes.
+		const sep = result.job.target.type === "pull_request" ? "!" : "#";
+		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow });
+		return respond(res, 202, { status: "queued" });
+	});
+}

package/src/start.mjs

@@ -0,0 +1,176 @@
+/**
+ * The receiver entry point: an always-on, public webhook producer that resolves the harness's own
+ * identity, then serves `makeReceiver` over `node:http` and enqueues onto the shared queue.
+ *
+ * DES-TRIGGER-OUTSIDE-PI: the trigger is a separate always-on process, outside the container and the
+ * agent. It only produces jobs; it never runs pi.
+ *
+ * CONST-TRIGGER-AUTHOR-GATE: `selfId` is the bot-loop guard's sole input -- the filter drops any event
+ * whose `sender.id` is our own. Resolving it is therefore a HARD-FAIL boot invariant: if identity does
+ * not resolve, the rejection propagates and the server is NEVER created. A receiver that listened
+ * without `selfId` would run the guard disarmed, and its own completion comments would re-trigger jobs
+ * -- an unbounded paid recursion. The worker's auth is best-effort because it can fail a github job
+ * per-job; the receiver has no such per-job fallback, so identity resolution is a boot gate.
+ *
+ * The receiver resolves identity ONLY. It holds no per-repo tokens: minting a scoped token is the
+ * worker's job, per container, per job (CONST-TOKEN-SCOPED-PER-JOB).
+ *
+ * DES-ADMIN-VIA-PI-EXTENSION: this process exposes exactly one surface, the webhook handler. There is no
+ * admin, dashboard, or admin-extension route here -- the admin surface is a pi extension in the
+ * operator's session and binds no port.
+ */
+
+import http from "node:http";
+import { watch } from "node:fs";
+import { dirname, basename } from "node:path";
+import { loadReceiverConfig, triggersFilePath, reloadTriggers } from "./config.mjs";
+import { makeReceiver } from "./receiver.mjs";
+import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
+import { resolveGitLabSelfId } from "@edgehero/pi-dispatch/gitlab-identity";
+import { resolveForgejoSelfId } from "@edgehero/pi-dispatch/forgejo-identity";
+import { resolveAzureSelfId } from "@edgehero/pi-dispatch/azure-identity";
+import { makeResolveAuthority } from "./gitlab-members.mjs";
+import { makeResolveForgejoAuthority } from "./forgejo-members.mjs";
+import { makeResolveAzureAuthority } from "./azure-members.mjs";
+import { makeQueue } from "@edgehero/pi-dispatch/queue";
+import { parseConnection } from "@edgehero/pi-dispatch/connection";
+
+/**
+ * Boot the receiver. Collaborators are injected (defaulting to the real ones) so the whole wiring is
+ * testable offline with no GitHub, no Valkey, and no socket. Returns the listening server.
+ */
+export async function startReceiver(
+	env = process.env,
+	{
+		makeAuth = makeGitHubAuth,
+		makeQueueFn = makeQueue,
+		createServer = http.createServer,
+		resolveGitLabSelfId: resolveSelfIdFn = resolveGitLabSelfId,
+		makeResolveAuthority: makeResolveAuthorityFn = makeResolveAuthority,
+		resolveForgejoSelfId: resolveForgejoSelfIdFn = resolveForgejoSelfId,
+		makeResolveForgejoAuthority: makeResolveForgejoAuthorityFn = makeResolveForgejoAuthority,
+		resolveAzureSelfId: resolveAzureSelfIdFn = resolveAzureSelfId,
+		makeResolveAzureAuthority: makeResolveAzureAuthorityFn = makeResolveAzureAuthority,
+	} = {},
+) {
+	// 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 cfg = loadReceiverConfig(env);
+
+	// 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.
+	const { selfId } = await makeAuth(cfg.github);
+	log({ event: "self_identity", id: selfId, source: cfg.github.source });
+
+	// Ride-out connection (no failFast): the receiver is long-running and should survive a Valkey
+	// restart, not give up on a transient disconnect.
+	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 }),
+		};
+	}
+
+	// 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 }),
+		};
+	}
+
+	// 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 }),
+		};
+	}
+
+	const handler = makeReceiver({ queue, selfId, cfg, log, gitlab, forgejo, azure });
+	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"));
+	}
+
+	return server;
+}
+
+/**
+ * Live-reload watcher: watch the DIRECTORY holding the triggers file (robust to the atomic tmp+rename the
+ * 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.
+ */
+function watchTriggers(env, cfg, log) {
+	const path = triggersFilePath(env);
+	const dir = dirname(path) || ".";
+	const file = basename(path);
+	let timer = null;
+	try {
+		watch(dir, (_event, changed) => {
+			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?.();
+		log({ event: "triggers_watching", path });
+	} catch (err) {
+		log({ event: "triggers_watch_unavailable", reason: err?.message });
+	}
+}
+
+// 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")) {
+	startReceiver(process.env).catch((err) => {
+		process.stderr.write(`${JSON.stringify({ event: "receiver_start_failed", reason: err?.message })}\n`);
+		process.exitCode = 1;
+	});
+}