@edgehero/pi-dispatch-receiver 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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": [
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "14.2.0",
-    "@edgehero/pi-dispatch": "^0.1.0",
+    "@edgehero/pi-dispatch": "^0.2.0",
     "bullmq": "5.80.4",
     "ioredis": "5.11.1"
   }

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
@@ -220,11 +275,13 @@ function loadTriggers(env, readFile, fileExists) {
 		knownFlows.add(run.flow);
 		const group = groups[run.kind];
 		if (on.type === "label") {
-			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, resume: run.resume, replicas: run.replicas, repository: run.repository });
+			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository });
 		} else if (on.type === "comment") {
-			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, packages: run.packages, image: run.image, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
+			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
 		} else if (on.type === "pull_request") {
-			group.pullRequest.push({ index, actions: new Set(on.action), predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, resume: run.resume, replicas: run.replicas });
+			// `reviewStates` is null rather than an empty Set when unnarrowed: the filter tests it for
+			// presence, and an empty Set would read as "no verdict matches" and silently refuse everything.
+			group.pullRequest.push({ index, actions: new Set(on.action), reviewStates: on.reviewState ? new Set(on.reviewState) : null, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas });
 		}
 	}
 
@@ -246,6 +303,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/filter-azure.mjs

@@ -105,6 +105,12 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		flow: resolved.flow,
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
+		// NEVER inside `trigger`. That placement is sharpest here of all: `trigger` is carried into
+		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
+		// basename(folder) restraint already exists to prevent.
+		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
 		trigger: {
 			event,
@@ -165,6 +171,8 @@ function matchLabelRules(subset, triggers, labels, action) {
 		repository: rule.repository,
 		packages: rule.packages,
 		image: rule.image,
+		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.target?.number, title: subset.target?.title, body: subset.target?.body },
@@ -193,6 +201,8 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 		repository: triggers.comment.repository,
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
+		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// No author_association: Azure has none, and the authority that admitted this comment was resolved
@@ -219,6 +229,8 @@ function routePullRequest(subset, triggers, action) {
 			repository: rule.repository,
 			packages: rule.packages,
 			image: rule.image,
+			skillsDir: rule.skillsDir,
+			instructions: rule.instructions,
 			resume: rule.resume,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {

package/src/filter-forgejo.mjs

@@ -107,6 +107,12 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 		flow: resolved.flow,
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
+		// NEVER inside `trigger`. That placement is sharpest here of all: `trigger` is carried into
+		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
+		// basename(folder) restraint already exists to prevent.
+		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
 		trigger: {
 			event: eventName,
@@ -133,6 +139,8 @@ function routeIssueLabel(subset, triggers) {
 		flow: rule.flow,
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 		image: rule.image,
+		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.issue?.number, title: subset.issue?.title, body: subset.issue?.body },
@@ -166,6 +174,8 @@ function routeComment(subset, triggers, knownFlows) {
 		flow,
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
+		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// The invoking comment rides on the trigger. No author_association: Forgejo has none, and the
@@ -190,6 +200,8 @@ function routePullRequest(subset, triggers, action) {
 			flow: rule.flow,
 			packages: rule.packages,
 			image: rule.image,
+			skillsDir: rule.skillsDir,
+			instructions: rule.instructions,
 			resume: rule.resume,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {

package/src/filter-gitlab.mjs

@@ -98,6 +98,12 @@ export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, d
 		flow: resolved.flow,
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
+		// NEVER inside `trigger`. That placement is sharpest here of all: `trigger` is carried into
+		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
+		// basename(folder) restraint already exists to prevent.
+		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		// Conditional like packages/image, and for the same reason: an unflagged job's data must stay
 		// byte-identical to today's, so the key is absent rather than present-and-undefined.
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
@@ -131,6 +137,8 @@ function routeLabel(subset, triggers, targetType) {
 		flow: rule.flow,
 		packages: rule.packages,
 		image: rule.image,
+		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched: { index: rule.index, type: "label", label: matchedLabel(added, rule.predicate) },
 		target: buildTarget(subset, targetType),
@@ -188,6 +196,8 @@ function mrResult(subset, rule, matched) {
 		flow: rule.flow,
 		packages: rule.packages,
 		image: rule.image,
+		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched,
 		target: buildTarget(subset, "pull_request"),
@@ -222,6 +232,8 @@ function routeNote(subset, triggers, knownFlows) {
 		flow,
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
+		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		target: buildTarget(subset, targetType),

package/src/filter.mjs

@@ -20,11 +20,18 @@
  *      check would reintroduce exactly that loop.
  *   2. Only then route on event + action: issue label, author-gated comment, or pull_request.
  *
- * PR AUTHOR GATE (security-critical): auto actions (`opened|synchronize|reopened`) fire ONLY when the PR
- * `author_association` is a collaborator. This is hard-coded here, never config-optional -- a fork PR from
- * a stranger would otherwise launch an unbounded paid run (CONST-TRIGGER-AUTHOR-GATE, job-budget rules).
- * PR labeling is self-gating: only collaborators can apply labels, so the label predicate IS the approval,
- * exactly as on the issue label path.
+ * PR GATE (security-critical), three arms, and WHICH FIELD each reads is the load-bearing part:
+ *   - `labeled` is self-gating: only collaborators can apply labels, so the label predicate IS the
+ *     approval, exactly as on the issue label path. No author check at all, deliberately.
+ *   - auto actions (`opened|synchronize|reopened`) fire only when the PR `author_association` is a
+ *     collaborator, so a stranger's fork PR never auto-fires.
+ *   - a submitted review (`review_submitted`, issue #66) fires on the REVIEWER's
+ *     `review.author_association`, NEVER the PR author's. This is the first GitHub event where the actor
+ *     and the PR author are DIFFERENT PEOPLE, which is why the auto-action shortcut of gating on the PR
+ *     author does not carry: a collaborator reviewing a stranger's fork PR must run, and a stranger
+ *     reviewing their own PR must not. Reading `pr.author_association` here inverts both halves at once.
+ * All three are hard-coded here, never config-optional -- an ungated auto-trigger is an unbounded paid run
+ * started by whoever opens a fork PR (CONST-TRIGGER-AUTHOR-GATE, job-budget rules).
  *
  * `selfId` is the numeric id of whichever identity posts as the harness (the App's bot user, or the PAT
  * user); `deliveryId` is the `X-GitHub-Delivery` GUID, carried into the job for downstream dedup.
@@ -35,6 +42,12 @@ const AUTHOR_ALLOWLIST = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 const LABEL_ACTIONS = new Set(["opened", "labeled", "reopened"]);
 const PR_ACTIONS = new Set(["labeled", "opened", "synchronize", "reopened"]);
 const PR_AUTO_ACTIONS = new Set(["opened", "synchronize", "reopened"]);
+// The triggers.json word for a submitted review, and the raw action GitHub sends on the
+// `pull_request_review` event. They differ on purpose -- see the routing block below.
+const REVIEW_ACTION = "review_submitted";
+const REVIEW_EVENT_ACTION = "submitted";
+// PR_AUTO_ACTIONS is deliberately NOT extended with REVIEW_ACTION: it exists only to select the
+// `pr-author-not-allowed` drop reason, and the review path has reasons of its own.
 
 export function filter(eventName, subset, cfg, selfId, deliveryId) {
 	// (0) Fail-closed on identity. MUST precede the self compare -- see header, ordering constraint.
@@ -61,6 +74,17 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 		resolved = routeComment(subset, triggers, cfg?.triggers?.knownFlows);
 	} else if (eventName === "pull_request" && PR_ACTIONS.has(action)) {
 		resolved = routePullRequest(subset, triggers, action);
+	} else if (eventName === "pull_request_review" && action === REVIEW_EVENT_ACTION) {
+		// A SECOND event name on the SAME route, not a fifth on.type (issue #66): a review is an event about
+		// a pull request, and GitLab's analogue `approved` already rides on.type "pull_request", so a new
+		// type would make one forge's review a type and the other's an action. The route is handed the
+		// CANONICAL word because that is what triggers.json spells and what the rule loop matches --
+		// `submitted` alone would be meaningless in a pull_request action list.
+		//
+		// `edited` and `dismissed` fall through to unhandled-event deliberately: an edit would re-fire on
+		// text the harness has already been paid to read, and a dismissal removes a verdict rather than
+		// stating one.
+		resolved = routePullRequest(subset, triggers, REVIEW_ACTION);
 	} else {
 		return { enqueue: false, reason: "unhandled-event" };
 	}
@@ -87,6 +111,12 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 		flow: resolved.flow,
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
+		// NEVER inside `trigger`. That placement is sharpest here of all: `trigger` is carried into
+		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
+		// basename(folder) restraint already exists to prevent.
+		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		// Conditional like packages/image, and for the same reason: an unflagged job's data must stay
 		// byte-identical to today's, so the key is absent rather than present-and-undefined.
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
@@ -102,6 +132,16 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 			sender: { id: subset.sender.id },
 			matched: resolved.matched,
 			...(resolved.comment ? { comment: resolved.comment } : {}),
+			// The invoking review, present only on the review route (issue #66), sibling of `comment` and
+			// carried for the same reason: without it a "Request changes: rename the helper" review starts a
+			// job that cannot know what was asked. All four fields are named by INT-WEBHOOK-PAYLOAD-SUBSET and
+			// the body stays DATA all the way down (CONST-ISSUE-TEXT-IS-DATA).
+			//
+			// NOTE the pair above: `event` is `pull_request_review` and `action` is the raw `submitted`,
+			// byte-for-byte what GitHub sent. `matched.action` is the canonical `review_submitted`, because
+			// `matched` names the triggers.json entry that fired rather than the payload. This is the first
+			// GitHub case where the two differ, and INT-CONTAINER-JOB-INPUTS says so.
+			...(resolved.review ? { review: resolved.review } : {}),
 		},
 	};
 	return { enqueue: true, job };
@@ -119,6 +159,8 @@ function routeIssueLabel(subset, triggers) {
 		flow: rule.flow,
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 		image: rule.image,
+		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
@@ -163,6 +205,8 @@ function routeComment(subset, triggers, knownFlows) {
 		// <flow>` override changes WHICH flow runs, never which triggers.json entry authorized it.
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
+		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
@@ -174,10 +218,43 @@ function routeComment(subset, triggers, knownFlows) {
 }
 
 /**
- * Pull-request path. `labeled` is gated by the label predicate (collaborator-applied label = approval);
- * auto actions (`opened|synchronize|reopened`) are gated by the PR author_association (hard-coded, never
- * config-optional). A trigger's optional predicate only narrows an auto action; an empty predicate is
- * vacuously true. First matching rule (in file order) wins.
+ * Whether the actor behind a PR event clears the write-access gate -- and WHICH actor that is.
+ *
+ * One expression rather than a branch inside the rule loop, deliberately (issue #66). A review is the
+ * REVIEWER's say-so, never the PR author's: a collaborator reviewing a stranger's fork PR must run, and a
+ * stranger reviewing their own PR must not. Reading `pr.author_association` for a review inverts both
+ * halves at once, and an `authorOk` that means two different things depending on which `if` you are
+ * standing in is exactly how that inversion gets silently reintroduced later. `labeled` reaches neither
+ * branch: it is gated by its label predicate instead.
+ */
+function prAuthorOk(action, pr, review) {
+	if (action === REVIEW_ACTION) return AUTHOR_ALLOWLIST.has(review?.author_association);
+	return AUTHOR_ALLOWLIST.has(pr?.author_association);
+}
+
+/**
+ * A `commented` review carrying nothing to act on.
+ *
+ * A review made only of INLINE comments arrives here with an empty body, because those comments ride
+ * `pull_request_review_comment` -- an event this project does not ingest. The payload carries no
+ * line-comment count and this module is pure, so it cannot tell "empty because it has line comments" from
+ * "empty because it is empty", and buying a container for an empty string is the worse of the two errors.
+ * The residual (a Comment-type review of line comments only never fires) is stated in SECURITY.md rather
+ * than left to a drop reason.
+ *
+ * `approved` and `changes_requested` still fire with no body: there the verdict IS the signal.
+ * Case-insensitive on `state` as belt-and-braces; `parseSubset` has already folded it.
+ */
+function isEmptyCommentedReview(review) {
+	return String(review?.state ?? "").toLowerCase() === "commented" && String(review?.body ?? "").trim() === "";
+}
+
+/**
+ * Pull-request path, three gates by action. `labeled` is gated by the label predicate
+ * (collaborator-applied label = approval); auto actions (`opened|synchronize|reopened`) by the PR
+ * author_association; `review_submitted` by the REVIEWER's (see `prAuthorOk`). All hard-coded, never
+ * config-optional. A trigger's optional predicate only narrows; an empty predicate is vacuously true.
+ * First matching rule (in file order) wins.
  */
 function routePullRequest(subset, triggers, action) {
 	const pr = subset.pull_request;
@@ -185,29 +262,59 @@ function routePullRequest(subset, triggers, action) {
 		return { enqueue: false, reason: "missing-pull-request" };
 	}
 	const L = labelSet(pr.labels);
-	const authorOk = AUTHOR_ALLOWLIST.has(pr.author_association);
+	const isReview = action === REVIEW_ACTION;
+	const review = subset.review;
+	const authorOk = prAuthorOk(action, pr, review);
 
+	// The review path refuses BEFORE the rule loop, in the order routeComment uses (author, then is there
+	// anything to act on, then which rule). Two consequences worth stating rather than discovering:
+	// security beats content when both are true, so a stranger's empty review reports the author refusal;
+	// and an operator with no review rule armed sees these reasons rather than `no-matching-pr-trigger`,
+	// which `pr-author-not-allowed` below already does and which is the right trade -- "nobody may start a
+	// job this way" and "there is nothing here to act on" are both facts about the DELIVERY, true whatever
+	// the trigger file says.
+	if (isReview) {
+		if (!authorOk) return { enqueue: false, reason: "review-author-not-allowed" };
+		if (isEmptyCommentedReview(review)) return { enqueue: false, reason: "no-review-body" };
+	}
+
+	let stateSkipped = false;
 	for (const rule of triggers.pullRequest ?? []) {
 		if (!rule.actions.has(action)) continue;
 		if (action === "labeled") {
 			if (!matchesRule(L, rule.predicate)) continue;
 		} else {
-			// Auto action -- author_association is the hard gate; the predicate (if any) narrows scope.
+			// Auto action or review -- author_association is the hard gate; the predicate (if any) narrows.
 			if (!authorOk) continue;
 			if (!matchesRule(L, rule.predicate)) continue;
 		}
+		// The optional `on.reviewState` narrowing, checked LAST among a rule's tests so the flag below means
+		// the verdict was the ONLY thing that failed. Unnarrowed rules carry null and fire on every verdict.
+		if (isReview && rule.reviewStates !== null && rule.reviewStates !== undefined && !rule.reviewStates.has(review?.state)) {
+			stateSkipped = true;
+			continue;
+		}
 		return {
 			enqueue: true,
 			flow: rule.flow,
 			packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 			image: rule.image,
+			skillsDir: rule.skillsDir,
+			instructions: rule.instructions,
 			resume: rule.resume,
 			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
+			...(isReview ? { review: { id: review.id, body: review.body, state: review.state, author_association: review.author_association } } : {}),
 			target: buildPrTarget(pr),
 		};
 	}
 
+	// "Your rule exists, this verdict was not in your list" is a different operator response from "no rule
+	// matched at all", so it gets its own reason -- the same call filter-forgejo.mjs makes for a recognised
+	// but unactionable action.
+	if (stateSkipped) {
+		return { enqueue: false, reason: "review-state-not-matched" };
+	}
 	// Surface the security-relevant author drop distinctly from a plain no-match so it is observable.
 	if (PR_AUTO_ACTIONS.has(action) && !authorOk) {
 		return { enqueue: false, reason: "pr-author-not-allowed" };

package/src/poller.mjs

@@ -35,20 +35,33 @@
  *                   presence, not transitions, so close->reopen inside one cycle is invisible, and a
  *                   reopen that also pushed fires a single `reopened` where webhooks would fire two
  *                   events -- the fresh sha still rides the job's target).
+ *   - reviews:      GET /repos/{o}/{r}/pulls/{n}/reviews for each OPEN pr, cursor = last processed
+ *                   review id (numeric and monotonic, so the events discipline applies). Issue #66's
+ *                   fourth source, and it exists because the alternative was a `review_submitted`
+ *                   trigger that loads clean under polling and can never fire -- the silently dead
+ *                   trigger this project refuses everywhere else. Only open PRs are swept: a review on
+ *                   a closed PR has nothing left to act on, the same call `merge`/`close` get in the
+ *                   action vocabulary. REST spells `state` in upper case where the webhook spells it
+ *                   lower; `parseSubset` folds it, so both transports produce the same job.
  *
  * DEDUP IDS (REQ-DEDUP-BY-DELIVERY-GUID): polling has no delivery GUID, so each source mints a
  * deterministic stand-in that is stable across retried cycles -- `poll-e<eventId>` (label events),
  * `poll-c<commentId>` (comments), `poll-pr<number>-<headSha7>` (PR actions; sha-keyed so a retried
  * cycle cannot double-enqueue while a real new push mints a new id -- with the honest corollary that
- * a same-sha reopen inside the retention window coalesces with its own `opened` job). The shared
+ * a same-sha reopen inside the retention window coalesces with its own `opened` job), and
+ * `poll-rv<reviewId>` (reviews; a review id is immutable, so the id alone is the identity). The shared
  * `gh-` prefix is added by enqueueGitHubJob's jobId path, same as for webhook deliveries.
  *
  * CURSORS AND ETAGS live in redis, namespaced per repo:
  *   poll:<owner/repo>:cursor:events    last processed /issues/events id (numeric, monotonic)
  *   poll:<owner/repo>:cursor:comments  newest processed comment updated_at (second-precision ISO)
  *   poll:<owner/repo>:cursor:prs       ISO of when the PR snapshot was armed (presence = armed)
+ *   poll:<owner/repo>:cursor:reviews   last processed review id (numeric, monotonic; presence = armed)
  *   poll:<owner/repo>:prs              hash: PR number -> head sha while open, "closed" once gone
  *   poll:<owner/repo>:etag:<endpoint>  conditional-GET validator (endpoint: events|comments|pulls)
+ *   poll:<owner/repo>:etag:reviews     hash: PR number -> that PR's reviews-endpoint validator. A HASH
+ *                                      rather than a key per PR, so the family below stays enumerable
+ *                                      and `touchRepo` can still refresh it as a unit.
  * All keys carry a ~35-day TTL and are refreshed TOGETHER after each successful repo poll. 35 days
  * deliberately exceeds the 31-day gh-* jobId retention (REQ-DEDUP-BY-DELIVERY-GUID): the cursor and
  * the jobId are the poller's two dedup layers, and refreshing/expiring the cursor family as a unit
@@ -100,6 +113,10 @@ const DISCOVERY_EVERY = 10;
 // next cycle picks up the rest); the open-PR list just caps how many open PRs the diff can see.
 const MAX_EVENT_PAGES = 5;
 const MAX_PR_PAGES = 10;
+// How many open PRs one cycle sweeps for reviews. This is a REQUEST bound, not a page bound: the reviews
+// endpoint is per-PR, so an unbounded sweep would spend one request per open PR per cycle. 50 covers any
+// repo a single poller realistically services, and the overflow is logged rather than silently dropped.
+const MAX_REVIEW_PRS = 50;
 // The hash value marking a PR that left the open list. Cannot collide with a head sha (hex only).
 const CLOSED_MARKER = "closed";
 
@@ -320,6 +337,8 @@ function keyNames(repo) {
 		etagEvents: `${p}:etag:events`,
 		etagComments: `${p}:etag:comments`,
 		etagPulls: `${p}:etag:pulls`,
+		reviews: `${p}:cursor:reviews`,
+		etagReviews: `${p}:etag:reviews`,
 	};
 }
 
@@ -330,7 +349,7 @@ async function setWithTtl(ctx, key, value) {
 /** Refresh the whole key family together -- coherence over per-key precision (see module header). */
 async function touchRepo(ctx, repo) {
 	const k = keyNames(repo);
-	for (const key of [k.events, k.comments, k.prsArmed, k.prs, k.etagEvents, k.etagComments, k.etagPulls]) {
+	for (const key of [k.events, k.comments, k.prsArmed, k.prs, k.etagEvents, k.etagComments, k.etagPulls, k.reviews, k.etagReviews]) {
 		await ctx.redis.expire(key, CURSOR_TTL_SECONDS);
 	}
 }
@@ -349,6 +368,11 @@ function isoSeconds(ms) {
  * never sends one -- arming needs the body, and a stray stored validator answering 304 on an unarmed
  * endpoint would leave it unarmed forever.
  *
+ * `etagKey` may also be `{ key, field }`, which stores the validator in a HASH field instead. That form
+ * exists for the per-PR reviews endpoint (issue #66): one validator per open PR would otherwise mean an
+ * unbounded key family that `touchRepo` cannot enumerate, and the whole TTL argument in the header rests
+ * on the family being refreshable as a unit. The conditional-GET discipline stays in this one place.
+ *
  * An exhausted quota (403/429 with x-ratelimit-remaining: 0) throws RateLimited for the cycle loop
  * to sleep out; any other non-2xx throws a plain error for per-repo isolation to log.
  */
@@ -362,7 +386,7 @@ function makeApi(ctx, token, stats) {
 				authorization: `Bearer ${token}`,
 			};
 			if (etagKey && revalidate) {
-				const etag = await ctx.redis.get(etagKey);
+				const etag = etagKey.field === undefined ? await ctx.redis.get(etagKey) : await ctx.redis.hget(etagKey.key, etagKey.field);
 				if (etag) headers["if-none-match"] = etag;
 			}
 			const res = await ctx.fetchFn(`${API_URL}${path}`, { headers });
@@ -383,7 +407,13 @@ function makeApi(ctx, token, stats) {
 			}
 			if (etagKey) {
 				const tag = res.headers?.get?.("etag");
-				if (tag) await ctx.redis.set(etagKey, tag, "EX", CURSOR_TTL_SECONDS);
+				if (tag && etagKey.field === undefined) {
+					await ctx.redis.set(etagKey, tag, "EX", CURSOR_TTL_SECONDS);
+				} else if (tag) {
+					// The hash carries no TTL of its own here; `touchRepo` expires it with the rest of the family.
+					await ctx.redis.hset(etagKey.key, etagKey.field, tag);
+					await ctx.redis.expire(etagKey.key, CURSOR_TTL_SECONDS);
+				}
 			}
 			stats.fetched += 1;
 			return { json: await res.json() };
@@ -580,7 +610,15 @@ async function pollPulls(ctx, api, repo, stats) {
 	const armed = (await ctx.redis.get(k.prsArmed)) !== null;
 
 	const first = await api.get(`/repos/${repo}/pulls?state=open&sort=updated&direction=asc&per_page=100`, k.etagPulls, armed);
-	if (first.notModified) return;
+	if (first.notModified) {
+		// Reviews still sweep on this path, and that is deliberate rather than defensive. Whether submitting
+		// a review perturbs the open-PR LIST is GitHub's business, not a property this project should bet
+		// correctness on: if it does not, an unswept 304 cycle would mean review triggers that fire only when
+		// something else happens to touch the PR. `null` tells pollReviews to take its sweep set from the
+		// snapshot hash instead of a list it does not have.
+		await pollReviews(ctx, api, repo, null, stats);
+		return;
+	}
 	let open = Array.isArray(first.json) ? first.json : [];
 	let batch = open;
 	let page = 2;
@@ -601,6 +639,10 @@ async function pollPulls(ctx, api, repo, stats) {
 		await ctx.redis.expire(k.prs, CURSOR_TTL_SECONDS);
 		await setWithTtl(ctx, k.prsArmed, isoSeconds(ctx.now()));
 		ctx.out({ event: "poll_armed", repo, endpoint: "pulls", open: open.length });
+		// Reviews arm on this cycle too. Returning without them would leave the reviews cursor unset for a
+		// whole extra cycle, and the first cycle that DID arm it would silently swallow every review
+		// submitted in between -- arming twice against one snapshot, losing the window between the two.
+		await pollReviews(ctx, api, repo, open, stats);
 		return;
 	}
 
@@ -630,6 +672,100 @@ async function pollPulls(ctx, api, repo, stats) {
 			await ctx.redis.hset(k.prs, field, CLOSED_MARKER);
 		}
 	}
+
+	// Reviews ride the SAME open-PR list this function already paid for -- one /pulls response feeds both
+	// sources, which is the whole reason this call lives here rather than in its own pollRepo step.
+	await pollReviews(ctx, api, repo, open, stats);
+}
+
+/**
+ * The review feed (issue #66): GET /repos/{o}/{r}/pulls/{n}/reviews per OPEN pr, cursor = last processed
+ * review id.
+ *
+ * Review ids are numeric and monotonic, but this sweep reads MANY endpoints (one per open PR) whose ids
+ * interleave, so the cursor is persisted ONCE at the end -- the comments-feed discipline, not the label
+ * feed's per-item one. Advancing per review would be actively wrong here: PR #1's review 200 followed by
+ * PR #2's review 150 would leave the cursor at 150 and re-enqueue 200 next cycle, or (writing the running
+ * max) would strand 150 forever if the sweep died between the two. Persisting once means a mid-sweep
+ * failure retries the WHOLE sweep, and the reviews already enqueued dedup on their `gh-poll-rv<id>`
+ * jobIds -- the same idempotence the replica fanout in `gate` leans on.
+ *
+ * COST is why the per-PR ETag exists. Without it a 50-open-PR repo spends 50 requests a cycle forever;
+ * with it the idle steady state is 50 * 304, which GitHub does not charge against the rate limit. The
+ * validators live in one hash (see keyNames) so the key family stays enumerable for touchRepo.
+ *
+ * A review on a CLOSED pr is never seen, deliberately: the open list is the sweep set, and a job started
+ * by a review of a merged PR has nothing left to act on -- the same call `merge` and `close` get in the
+ * action vocabulary.
+ */
+async function pollReviews(ctx, api, repo, open, stats) {
+	const k = keyNames(repo);
+	const cursorRaw = await ctx.redis.get(k.reviews);
+	const armed = cursorRaw !== null;
+	const cursor = armed ? Number(cursorRaw) : 0;
+
+	// The sweep set. `open` is the list pollPulls just fetched; `null` means it got a 304 and the snapshot
+	// hash is the only record of which PRs are open. Numbers are enough to drive the sweep -- the PR OBJECT
+	// is only needed for a PR that turns out to have a new review, and is fetched lazily below, which is
+	// the same once-per-new-event fetch handleLabeledEvent and handleComment already do.
+	let numbers;
+	if (open !== null) {
+		numbers = open.filter((pr) => pr?.number != null).map((pr) => pr.number);
+	} else {
+		const known = await ctx.redis.hgetall(k.prs);
+		numbers = Object.entries(known)
+			.filter(([, sha]) => sha !== CLOSED_MARKER)
+			.map(([field]) => Number(field))
+			.filter((n) => Number.isFinite(n))
+			.sort((a, b) => a - b);
+	}
+
+	// Bounded, and said out loud when it bites: a silent cap reads as coverage.
+	if (numbers.length > MAX_REVIEW_PRS) {
+		ctx.out({ event: "poll_reviews_gap", repo, open: numbers.length, swept: MAX_REVIEW_PRS });
+	}
+	const bounded = numbers.slice(0, MAX_REVIEW_PRS);
+	const byNumber = new Map((open ?? []).filter((pr) => pr?.number != null).map((pr) => [pr.number, pr]));
+
+	let maxId = cursor;
+	for (const number of bounded) {
+		const field = String(number);
+		// While ARMING, `revalidate: false` for the same reason every other source uses it: arming needs
+		// the body, and a stored validator answering 304 on an unarmed endpoint would strand it unarmed.
+		const res = await api.get(`/repos/${repo}/pulls/${number}/reviews?per_page=100`, { key: k.etagReviews, field }, armed);
+		if (res.notModified) continue;
+		const reviews = Array.isArray(res.json) ? res.json : [];
+
+		let pr = byNumber.get(number) ?? null;
+		for (const review of reviews) {
+			if (typeof review?.id !== "number" || review.id <= cursor) continue;
+			if (review.id > maxId) maxId = review.id;
+			if (!armed) continue; // ARM WITHOUT REPLAY: learn the high-water mark, enqueue nothing.
+
+			// Lazily, and at most once per PR per cycle: only a PR with a genuinely new review costs this.
+			if (pr === null) {
+				pr = (await api.get(`/repos/${repo}/pulls/${number}`)).json ?? null;
+				byNumber.set(number, pr);
+			}
+
+			// The webhook's own payload shape, so the SAME parseSubset + filter decide. `sender` is the
+			// REVIEWER, which is what keeps the bot-loop guard correct: a review the harness itself posted
+			// carries our own id and drops as `self` before any gate runs. `state` arrives upper-case from
+			// REST and parseSubset folds it; that fold is what makes this job identical to the webhook twin's.
+			const payload = { action: "submitted", sender: { id: review.user?.id }, pull_request: pr, review, repository: { full_name: repo } };
+			await gate(ctx, "pull_request_review", payload, `poll-rv${review.id}`, stats);
+		}
+	}
+
+	// Once, after the whole sweep -- see the header of this function for why per-item would be wrong.
+	// Arming ALWAYS writes, even at 0: a repo whose open PRs carry no reviews yet must still become armed,
+	// or it stays on the `revalidate: false` path and re-fetches every PR in full, every cycle, forever.
+	if (!armed) {
+		await setWithTtl(ctx, k.reviews, String(maxId));
+		ctx.out({ event: "poll_armed", repo, endpoint: "reviews", cursor: maxId });
+	} else if (maxId !== cursor) {
+		await setWithTtl(ctx, k.reviews, String(maxId));
+	}
 }
 
 /**

package/src/receiver.mjs

@@ -75,6 +75,28 @@ export function parseSubset(payload) {
 					base: { ref: pr.base?.ref },
 				}
 			: undefined,
+		// pull_request_review event fields (issue #66). Shape-gated like `pull_request` above rather than
+		// event-gated, for the same reason: this function never sees the event name, and a payload either
+		// carries a review or it does not.
+		//
+		// `id` is here because a review's INLINE comments ride `pull_request_review_comment`, an event this
+		// project deliberately does not ingest -- so the id is the only handle a flow has on them. No
+		// `review.user`: the bot-loop guard reads `sender.id` and nothing else, a second identity field is a
+		// second thing to keep in sync, and a login is PII with no reader (see issue.pull_request above).
+		review: payload.review
+			? {
+					id: payload.review.id,
+					body: payload.review.body,
+					// Folded to lower case HERE, the one place both sources converge. The webhook sends
+					// `approved`; GET /pulls/{n}/reviews sends `APPROVED`. The poller feeds this same function
+					// with REST-derived payloads, so without the fold the identical logical review would produce
+					// two different jobs depending on transport, and a polled `COMMENTED` would slip past the
+					// empty-body check and buy a container for an empty string. (GitHub docs, not source at a
+					// pin: filter.test.mjs drives both casings so the claim is pinned by behaviour.)
+					state: typeof payload.review.state === "string" ? payload.review.state.toLowerCase() : payload.review.state,
+					author_association: payload.review.author_association,
+				}
+			: undefined,
 		repository: { full_name: payload.repository?.full_name },
 	};
 }
@@ -88,19 +110,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 +153,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.