@edgehero/pi-dispatch-receiver 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Webhook receiver for pi-dispatch: the always-on edge that verifies GitHub, GitLab, Forgejo and Azure DevOps deliveries and enqueues (at most) one job per event for the worker.",
   "keywords": [

package/src/azure-members.mjs

@@ -7,7 +7,8 @@
  * one, which is a real cost this arm carries and the other three do not:
  *
  *   1. the actor -> a subject DESCRIPTOR. A pull-request payload gives a GUID, a work-item payload gives
- *      only an email address, so there are two lookups depending on which the event carried.
+ *      only an email address, so there are two lookups depending on which the event carried. The email one
+ *      is a LIST walk and may itself span several requests -- see the pagination note on resolveDescriptor.
  *   2. the descriptor -> membership of the project's own group.
  *
  * Both can go indeterminate, so the indeterminate surface here is wider than GitLab's, not merely equal to
@@ -29,6 +30,19 @@
 
 import { fetchFailureReason } from "@edgehero/pi-dispatch/gitlab-identity";
 
+/**
+ * How many pages of the organisation's user list one delivery may walk while looking for an email address.
+ *
+ * The cap is counted in PAGES and not in users, because the page size is Azure's to choose and is not part
+ * of the request -- what this bounds is request AMPLIFICATION: one webhook must never turn into an
+ * unbounded crawl of a directory, and an org that grew a page while the loop was running must still
+ * terminate. Twenty is chosen to be comfortably past any real organisation at Azure's own page size
+ * (hundreds of subjects per page) and still a fixed number of round trips.
+ *
+ * Running out of pages is NOT a refusal -- see resolveDescriptor.
+ */
+const MAX_USER_PAGES = 20;
+
 /**
  * Build the resolver.
  *
@@ -44,6 +58,21 @@ export function makeResolveAzureAuthority({ orgUrl, token, fetchFn = fetch }) {
 	// Azure authenticates a PAT as HTTP Basic with an empty username.
 	const auth = `Basic ${Buffer.from(`:${token}`, "utf8").toString("base64")}`;
 
+	/**
+	 * One Graph GET. `{ body, continuation }` on a 2xx, `{ indeterminate }` on anything else -- the whole
+	 * error taxonomy of this module lives here, once, so a new call site cannot invent a different one.
+	 *
+	 * `continuation` carries Azure's paging cursor for the LIST endpoints and is null for everything else.
+	 * The Graph does not use a Link header and does not put the cursor in the body: a page that is not the
+	 * last one returns an `X-MS-ContinuationToken` RESPONSE HEADER, which the caller sends back as a
+	 * `continuationToken` QUERY PARAMETER on the next request. It is read here rather than in a sibling
+	 * helper so the two single-object descriptor lookups and the membership lookup keep sharing one code
+	 * path; they simply ignore a field Azure never sets for them.
+	 *
+	 * `headers.get` is called defensively. A real `Response` always has it, but `fetchFn` is injected, and a
+	 * fake that returns a plain object must not turn a lookup into a TypeError -- which would escape as a
+	 * throw rather than as this module's `{ indeterminate }`.
+	 */
 	async function get(url) {
 		let res;
 		try {
@@ -55,8 +84,9 @@ export function makeResolveAzureAuthority({ orgUrl, token, fetchFn = fetch }) {
 			// Status only. An Azure error body can echo the request, and the request carried the token.
 			return { indeterminate: `azure lookup returned ${res.status}` };
 		}
+		const continuation = typeof res.headers?.get === "function" ? res.headers.get("x-ms-continuationtoken") : null;
 		try {
-			return { body: await res.json() };
+			return { body: await res.json(), continuation: continuation || null };
 		} catch (err) {
 			return { indeterminate: `azure lookup returned unparseable JSON: ${err?.message ?? "unknown"}` };
 		}
@@ -85,6 +115,12 @@ export function makeResolveAzureAuthority({ orgUrl, token, fetchFn = fetch }) {
 		// Membership is TRANSITIVE via `direction=up`: a member of a team inside the project is a member of
 		// the project, and asking only for direct membership would refuse most real organisations -- the same
 		// mistake `members/all` avoids on GitLab.
+		//
+		// This reads ONE page, unlike the users listing above, and that is a scope statement rather than a
+		// claim: what is being listed here is one subject's own containers, not a directory, so the two are
+		// not the same size of question. `get` surfaces `continuation` for this call too, so if this ever
+		// needs following the mechanism is already here -- but no cap or verdict is invented for a paging
+		// behaviour nothing in this codebase has observed on this endpoint.
 		const memberships = await get(`${vssps}/_apis/graph/memberships/${encodeURIComponent(descriptor.value)}?direction=up&api-version=7.1-preview.1`);
 		if (memberships.indeterminate) return memberships;
 		const list = memberships.body?.value;
@@ -94,7 +130,38 @@ export function makeResolveAzureAuthority({ orgUrl, token, fetchFn = fetch }) {
 		return { authorized: list.some((m) => m?.containerDescriptor === container) };
 	};
 
-	/** The actor's subject descriptor: by GUID for a pull request, by email for a work item. */
+	/**
+	 * The actor's subject descriptor: by GUID for a pull request, by email for a work item.
+	 *
+	 * THE EMAIL PATH IS PAGINATED, and that is the whole difficulty of this function. Azure's Graph has no
+	 * lookup-by-mail-address endpoint, so the organisation's user list is fetched and filtered locally --
+	 * and that list is paged. Reading only the first page meant that in any organisation whose directory
+	 * exceeds one page, an actor beyond it resolved to nobody, which is DETERMINATE: the gate refused, the
+	 * receiver answered 204, and work-item (tag and comment) triggers simply never fired for those people,
+	 * behind a status indistinguishable from a stranger being correctly turned away. Pull requests were
+	 * never affected -- a PR names its actor by GUID and takes the direct descriptor lookup above.
+	 *
+	 * So the pages are followed (see `get` for the header/query-parameter mechanism), and the three ways out
+	 * are deliberately three different answers:
+	 *
+	 *   - FOUND, on any page -> the descriptor. The loop stops at the hit, so an actor on page 1 still costs
+	 *     exactly one request; nobody pays for pagination that was not needed.
+	 *   - the listing ENDED (a page with no continuation token) and the actor was not in it -> determinate
+	 *     `null`, which the caller refuses. This is the honest refusal: the entire directory was read.
+	 *   - the PAGE CAP was reached while Azure was still offering more -> `{ indeterminate }`, never `null`.
+	 *     The search was abandoned, not completed, and the module's own docblock is explicit that
+	 *     indeterminate and unauthorized must not be conflated: this way the receiver answers 503 and Azure
+	 *     redelivers, instead of burying an exhausted search inside a 204 that reads as a policy decision.
+	 *
+	 * A FILTERED LOOKUP WOULD BE BETTER AND IS NOT USED. Nothing in the Graph surface this module already
+	 * speaks offers a by-mail filter on `graph/users` (`subjectTypes` selects kinds of subject, not
+	 * identities), and the endpoints that come close -- a subject query, the older Identities API -- return
+	 * shapes this file has never handled and whose descriptor flavour may not be the one `graph/memberships`
+	 * accepts. Guessing one would repeat exactly the mistake the security-namespace paragraph above refuses:
+	 * a confident answer about a different object. The list walk is coarser and verifiable, so it stays.
+	 *
+	 * The address is still never logged or returned, including in the indeterminate reason.
+	 */
 	async function resolveDescriptor(actor) {
 		if (typeof actor?.id === "string" && actor.id !== "") {
 			const res = await get(`${vssps}/_apis/graph/descriptors/${encodeURIComponent(actor.id)}?api-version=7.1-preview.1`);
@@ -103,15 +170,23 @@ export function makeResolveAzureAuthority({ orgUrl, token, fetchFn = fetch }) {
 			return { value: typeof value === "string" && value !== "" ? value : null };
 		}
 		if (typeof actor?.email === "string" && actor.email !== "") {
-			// There is no lookup-by-email endpoint, so the users list is filtered. `subjectTypes=aad,msa`
-			// excludes groups and service principals, which cannot be the human this gate is about.
-			const res = await get(`${vssps}/_apis/graph/users?subjectTypes=aad,msa&api-version=7.1-preview.1`);
-			if (res.indeterminate) return res;
-			const users = res.body?.value;
-			if (!Array.isArray(users)) return { indeterminate: "azure users lookup returned no array" };
 			const wanted = actor.email.toLowerCase();
-			const hit = users.find((u) => String(u?.principalName ?? "").toLowerCase() === wanted || String(u?.mailAddress ?? "").toLowerCase() === wanted);
-			return { value: typeof hit?.descriptor === "string" ? hit.descriptor : null };
+			let token = null;
+			for (let page = 0; page < MAX_USER_PAGES; page++) {
+				// `subjectTypes=aad,msa` excludes groups and service principals, which cannot be the human this
+				// gate is about. The continuation token is appended only when there is one, so the FIRST request
+				// is byte-identical to the single-page one this replaced.
+				const res = await get(`${vssps}/_apis/graph/users?subjectTypes=aad,msa&api-version=7.1-preview.1${token ? `&continuationToken=${encodeURIComponent(token)}` : ""}`);
+				if (res.indeterminate) return res;
+				const users = res.body?.value;
+				if (!Array.isArray(users)) return { indeterminate: "azure users lookup returned no array" };
+				const hit = users.find((u) => String(u?.principalName ?? "").toLowerCase() === wanted || String(u?.mailAddress ?? "").toLowerCase() === wanted);
+				if (hit) return { value: typeof hit.descriptor === "string" ? hit.descriptor : null };
+				if (!res.continuation) return { value: null }; // the list ended: a determinate "not in this org"
+				token = res.continuation;
+			}
+			// Still more pages on offer. Nothing was decided, so nothing is refused.
+			return { indeterminate: `azure users lookup did not reach the actor within ${MAX_USER_PAGES} pages` };
 		}
 		// Neither a GUID nor a parseable address: the delivery named nobody this gate can ask about.
 		return { value: null };

package/src/cli.mjs

@@ -22,7 +22,8 @@ const USAGE = `pi-dispatch-receiver — the always-on trigger edge: turns GitHub
                                reads api.github.com with the operator's own credential instead
 
 Config comes from the environment (see .env.example): WEBHOOK_SECRET is required for serve
-(poll needs none — there is no inbound delivery to verify), PI_TRIGGERS_FILE overrides the
+only when your triggers name github (poll needs none either — there is no inbound delivery to
+verify, and a forge-only deployment has no github endpoint), PI_TRIGGERS_FILE overrides the
 ./triggers.json default, VALKEY_URL names the queue, RECEIVER_PORT/RECEIVER_BIND choose where
 serve listens, and POLL_REPOS / POLL_INTERVAL_SECONDS shape what poll watches and how often.`;
 

package/src/config.mjs

@@ -8,8 +8,15 @@
  * trigger schema is likewise single-sourced from `@edgehero/pi-dispatch/triggers` -- both services validate
  * the WHOLE unified triggers file and each selects the `on.type` it owns (issue #20).
  *
- * - `webhookSecret` is REQUIRED: without it the receiver cannot verify `X-Hub-Signature-256` over the
- *   raw body, and an unverified webhook is a forgeable paid-agent trigger (CONST-HMAC-OVER-RAW-BODY).
+ * - `webhookSecret` is REQUIRED WHENEVER THE DEPLOYMENT SERVES GITHUB (`servesGithub`, below): without it
+ *   the receiver cannot verify `X-Hub-Signature-256` over the raw body, and an unverified webhook is a
+ *   forgeable paid-agent trigger (CONST-HMAC-OVER-RAW-BODY). A GitLab-only / Forgejo-only / Azure-only
+ *   deployment has no GitHub endpoint and therefore nothing for that secret to verify, so demanding one
+ *   there blocked a deployment the harness fully supports (issue #99).
+ * - `servesGithub` is that decision, made HERE and named, because three separate things hang off it and
+ *   they must never disagree: the WEBHOOK_SECRET requirement, whether `/` is mounted at all
+ *   (receiver.mjs), and whether boot resolves the harness's GitHub identity to arm the bot-loop guard
+ *   (start.mjs). Deriving it inline in two places is how a route ends up live with a disarmed guard.
  * - `triggers` is the receiver's webhook allowlist, grouped by type: label rules (the label IS the
  *   collaborator approval), the single comment trigger (phrase + default flow), and pull_request rules.
  *   Only collaborators can apply labels, so the label/PR-label allowlist is the human approval gate
@@ -36,24 +43,72 @@ const DEFAULT_TRIGGERS_PATH = "./triggers.json";
  * (`readFile`, `fileExists`) so the loader is hermetically testable and never touches disk in tests.
  */
 export function loadReceiverConfig(env = process.env, { readFile = readFileSync, fileExists = existsSync } = {}) {
+	// Triggers and the GitHub auth block are parsed FIRST, before the secret check, because the secret is
+	// now conditional on what they say. Their own fail-loud errors therefore surface first -- a garbled
+	// GITHUB_AUTH_SOURCE is reported as a garbled GITHUB_AUTH_SOURCE, never laundered into a confusing
+	// complaint about WEBHOOK_SECRET.
+	const triggers = loadTriggers(env, readFile, fileExists);
+	const github = loadGitHubAuth(env, fileExists);
+	const servesGithub = decideServesGithub(env, triggers.github);
+
 	const webhookSecret = env.WEBHOOK_SECRET;
-	if (webhookSecret === undefined || webhookSecret.trim() === "") {
+	if (servesGithub && (webhookSecret === undefined || webhookSecret.trim() === "")) {
+		// Same message and same behaviour as before for every deployment that serves GitHub: the secret is
+		// the whole trust boundary of the `/` endpoint, so a receiver that would mount it without one must
+		// refuse to start rather than answer 401 forever (or, worse, accept forged deliveries).
 		throw configError("WEBHOOK_SECRET is required; refusing to start a receiver that cannot verify signatures");
 	}
 
 	return {
+		// Passed through as the env gave it (possibly undefined) when the deployment serves no GitHub. Nothing
+		// reads it in that case -- receiver.mjs builds no github handler at all -- and `servesGithub` beside it
+		// is what says so, so an unread absent secret can never be mistaken for an armed endpoint.
 		webhookSecret,
+		servesGithub,
 		valkeyUrl: env.VALKEY_URL ?? "redis://127.0.0.1:6379", // mirrors worker config: producer and consumer share one queue
 		port: positiveInt(env, "RECEIVER_PORT", 3000),
 		bind: env.RECEIVER_BIND ?? "0.0.0.0",
-		triggers: loadTriggers(env, readFile, fileExists),
-		github: loadGitHubAuth(env, fileExists),
+		triggers,
+		github,
 		gitlab: loadGitLabConfig(env),
 		forgejo: loadForgejoConfig(env),
 		azure: loadAzureConfig(env),
 	};
 }
 
+/**
+ * Does this deployment actually SERVE GitHub? Three things hang off the answer -- the WEBHOOK_SECRET
+ * requirement above, whether `/` is mounted (receiver.mjs), and whether boot resolves the harness's own
+ * GitHub id to arm the bot-loop guard (start.mjs) -- so it is decided once, here, from the operator's own
+ * files rather than assumed.
+ *
+ * Either of two signals is a yes:
+ *
+ *  - THE TRIGGERS FILE NAMES A GITHUB WEBHOOK RULE. `triggers.github` is the group `loadTriggers` built
+ *    from every `run.kind: "github"` webhook entry, and `emptyGroup()` is what a forge the file never
+ *    mentions gets. So an empty group -- zero label rules, no comment trigger, zero pull_request rules --
+ *    means a signed GitHub delivery could not fire anything even if it arrived: the endpoint would verify
+ *    the HMAC, match no rule, and answer 204 forever. That is not a GitHub deployment.
+ *
+ *  - GITHUB_AUTH_SOURCE IS SET EXPLICITLY. An operator who names an auth source has said "GitHub" out
+ *    loud, and they may well be arming the receiver before the first rule exists (or driving it from the
+ *    poller, which is GitHub-only). Explicit intent wins over the inferred signal, and it is also what
+ *    keeps this change byte-identical to today's behaviour for every deployment that sets the variable.
+ *    Read from `env` and NOT from the parsed block: `loadGitHubAuth` defaults `source` to "gh", so
+ *    `github.source` cannot tell an explicit choice from a default and would answer yes for everyone.
+ *
+ * Deliberately NOT a signal: the presence of GITHUB_PAT / GITHUB_APP_* alone. Those are credentials a
+ * shared env file may carry for the worker (which mints per-job tokens and is a separate process); a
+ * credential lying around is not a statement that this receiver terminates GitHub webhooks.
+ */
+function decideServesGithub(env, githubGroup) {
+	const hasGithubTriggers = githubGroup.label.length > 0 || githubGroup.comment !== null || githubGroup.pullRequest.length > 0;
+	// `loadGitHubAuth` has already refused a garbled value by the time we get here, so anything non-empty
+	// here is one of pat|gh|app -- a real choice, not a typo we would be reading as consent.
+	const explicitAuthSource = env.GITHUB_AUTH_SOURCE !== undefined && env.GITHUB_AUTH_SOURCE !== "";
+	return hasGithubTriggers || explicitAuthSource;
+}
+
 /**
  * The GitLab endpoint's configuration, or `null` when the deployment serves no GitLab -- in which case no
  * `/gitlab` route exists at all, rather than one that answers 401. An endpoint that responds is an endpoint
@@ -246,6 +301,14 @@ export function triggersFilePath(env = process.env) {
  * restart, mirroring how the worker re-reads the settings overlay per job. If the new file is
  * missing/unparseable/invalid, the running triggers are KEPT (never crash a live receiver on a bad edit)
  * and the reason is returned. Returns `{ ok: true }` or `{ invalid }`.
+ *
+ * `servesGithub` is deliberately NOT recomputed. It is a BOOT decision, because the two other things it
+ * governs are boot facts: whether `/` was mounted and whether the harness's GitHub identity was resolved.
+ * Recomputing it here would let a live file edit mount a github endpoint whose bot-loop guard was never
+ * armed -- the one state this design exists to make unreachable. Both directions of a live edit are
+ * therefore safe and neither is silent: adding a github rule to a github-free receiver leaves `/` 404ing
+ * until a restart (the operator's next step anyway, since the deployment also needs a webhook secret), and
+ * removing the last github rule leaves `/` verifying deliveries that now match nothing and answer 204.
  */
 export function reloadTriggers(env, cfg, { readFile = readFileSync, fileExists = existsSync } = {}) {
 	try {

package/src/receiver.mjs

@@ -88,19 +88,34 @@ export function parseSubset(payload) {
  * 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.
+ * `/` stays mapped to GitHub -- for a deployment that SERVES GitHub. Existing deployments configured their
+ * webhook URL before any path existed, and silently 404-ing them would look exactly like the harness being
+ * down, so the path itself never moves.
  *
  * 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.
+ * responds to an unconfigured forge is an endpoint an operator can believe is armed. GitHub is no longer
+ * the exception to that rule (issue #99): a GitLab-only / Forgejo-only / Azure-only deployment has
+ * `cfg.servesGithub === false`, builds no github handler, and 404s `/`.
+ *
+ * The github arm is gated on `cfg.servesGithub` being TRUTHY, not on it not being `false`, and that
+ * direction is load-bearing. `start.mjs` skips resolving the harness's GitHub identity when the property is
+ * off, so a config object that somehow reached here without the property would otherwise mount `/` with
+ * `selfId === undefined` -- a live endpoint whose bot-loop guard compares every `sender.id` against
+ * undefined, i.e. never drops the harness's own comments. Absent property therefore means no route; the
+ * failure of a forgotten property is a 404 an operator sees, never a paid recursion they get billed for.
  */
 export function makeReceiver({ queue, selfId, cfg, log, gitlab = null, forgejo = null, azure = null }) {
-	const github = makeGitHubHandler({ queue, selfId, cfg, log });
+	// Built only when the deployment serves GitHub. Construction is not free of the secret either: the
+	// `new Webhooks({ secret })` inside makeVerifiedHandler throws "options.secret required" on an absent
+	// one, so not building the arm is what lets a github-free deployment legitimately have no secret --
+	// no placeholder, nothing papered over, and no handler holding a secret nobody chose.
+	const github = cfg.servesGithub ? makeGitHubHandler({ queue, selfId, cfg, log }) : null;
 
 	// 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.
+	// falls through to GitHub, which is what keeps `/` working -- and a configured-off GitHub answers the
+	// same 404 from the fallthrough itself, below.
 	const routes = {
 		"/gitlab": gitlab ? makeGitLabHandler({ queue, cfg, log, ...gitlab }) : null,
 		"/forgejo": forgejo ? makeForgejoHandler({ queue, cfg, log, ...forgejo }) : null,
@@ -116,6 +131,12 @@ export function makeReceiver({ queue, selfId, cfg, log, gitlab = null, forgejo =
 			if (!handler) return respond(res, 404, { error: `${path.slice(1)} webhooks are not configured` });
 			return await handler(req, res);
 		}
+		// The GitHub fallthrough (`/` and anything unrouted). Absent when the deployment serves no GitHub, and
+		// 404 rather than 401 or 405 for the same reason the table's null arms are: a status that discusses
+		// credentials or methods says "armed, and you got something wrong", and an operator who reads that
+		// about an endpoint that cannot fire anything will go hunting for a mis-keyed secret for an hour. The
+		// message is spelled out rather than derived from `path`, which is "/" here and would slice to nothing.
+		if (!github) return respond(res, 404, { error: "github webhooks are not configured" });
 		return await github(req, res);
 	};
 }

package/src/start.mjs

@@ -6,11 +6,14 @@
  * 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.
+ * whose `sender.id` is our own. Resolving it is therefore a HARD-FAIL boot invariant WHEREVER A FORGE
+ * ENDPOINT IS LIVE: 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. Every arm here is gated on its own forge being configured, github included (`cfg.servesGithub`,
+ * issue #99) -- an arm whose endpoint does not exist has no guard to arm, and the invariant that matters is
+ * that the two are decided by the SAME property, never separately.
  *
  * 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).
@@ -58,11 +61,29 @@ export async function startReceiver(
 
 	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 });
+	// 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
+	// the gh path shells out to `gh auth token`, a GitLab-only deployment could not boot without installing
+	// and logging into the GitHub CLI it has no use for.
+	//
+	// SKIPPING THIS IS ONLY SAFE BECAUSE THE ROUTE IS ALSO ABSENT. `cfg.servesGithub` gates both: this
+	// identity resolution AND whether `makeReceiver` mounts `/` at all. `selfId` is the bot-loop guard's sole
+	// input, so the two MUST stay coupled -- if a future change mounts `/` unconditionally again, this
+	// resolution has to come back with it, or the github endpoint would run its guard disarmed and the
+	// harness's own completion comments would re-trigger jobs forever. Read that as: never make one of these
+	// two conditions unconditional without the other.
+	let selfId;
+	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.
+		({ selfId } = await makeAuth(cfg.github));
+		log({ event: "self_identity", id: selfId, source: cfg.github.source });
+	} else {
+		// Said out loud, because the alternative is an operator staring at a label trigger that does nothing.
+		// The two ways out are the two signals `decideServesGithub` reads, so the line names both.
+		log({ event: "github_arm_skipped", reason: "no github triggers and GITHUB_AUTH_SOURCE unset" });
+	}
 
 	// Ride-out connection (no failFast): the receiver is long-running and should survive a Valkey
 	// restart, not give up on a transient disconnect.