@edgehero/pi-dispatch-receiver 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "0.1.1",
+  "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/config.mjs

@@ -275,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 });
 		}
 	}
 

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 },
 	};
 }