@edgehero/pi-dispatch-receiver 1.5.0 → 2.0.0

package/README.md

@@ -0,0 +1,41 @@
+# @edgehero/pi-dispatch-receiver
+
+The trigger edge of **[pi-dispatch](https://github.com/edgehero/pi-dispatch)**, which runs the
+[pi](https://github.com/earendil-works/pi) coding agent as a self hosted background service.
+
+The receiver turns forge activity into queued jobs for the
+[worker](https://www.npmjs.com/package/@edgehero/pi-dispatch). It reads the same `triggers.json` as the
+worker, checks each delivery, and queues at most one job per event (one per replica when a trigger sets
+`run.replicas`). It never runs a job itself.
+
+## Two ways to run it
+
+```bash
+npx @edgehero/pi-dispatch-receiver         # serve: the webhook receiver (the default)
+npx @edgehero/pi-dispatch-receiver poll    # poll: no public URL, reads GitHub with your own credential
+```
+
+- **`serve`** verifies GitHub, GitLab, Forgejo and Azure DevOps webhooks (at `/`, `/gitlab`, `/forgejo`
+  and `/azure`). It listens on all interfaces by default (`RECEIVER_BIND=0.0.0.0`); set
+  `RECEIVER_BIND=127.0.0.1` when a local reverse proxy or tunnel does the public exposure. `pi-dispatch
+  service install --receiver`
+  runs it as a service, and a container image is published as `ghcr.io/edgehero/pi-dispatch-receiver`.
+- **`poll`** fetches GitHub issue events, comments and pull requests about once a minute, over TLS, with
+  the same gates and the same queue. A new poller starts from now and never replays old labels.
+
+The receiver checks each delivery's signature, the bot loop guard, the forge's own permission check and
+dedup. The worker then applies quiet hours, the image preflight, branch protection and the spend caps.
+Who may fire a trigger is decided by your forge. See
+[`SECURITY.md`](https://github.com/edgehero/pi-dispatch/blob/main/SECURITY.md) for each forge's rule.
+
+Configuration comes from the environment (the worker's `.env.example` lists all of it). The main settings
+are `WEBHOOK_SECRET`, `VALKEY_URL` and `VALKEY_PASSWORD`, `PI_TRIGGERS_FILE`, `RECEIVER_PORT` and
+`RECEIVER_BIND`, `POLL_REPOS` with `POLL_INTERVAL_SECONDS` for polling, and each forge's token and
+webhook secret (see its setup guide). It needs `@edgehero/pi-dispatch` of the same major
+version, which it installs as a dependency.
+
+Setup guides: [GitHub](https://github.com/edgehero/pi-dispatch/blob/main/docs/github.md),
+[GitLab](https://github.com/edgehero/pi-dispatch/blob/main/docs/gitlab.md),
+[Forgejo](https://github.com/edgehero/pi-dispatch/blob/main/docs/forgejo.md),
+[Azure DevOps](https://github.com/edgehero/pi-dispatch/blob/main/docs/azure-devops.md),
+[polling](https://github.com/edgehero/pi-dispatch/blob/main/docs/polling.md). MIT licensed.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "1.5.0",
+  "version": "2.0.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.",
+  "description": "The pi-dispatch trigger edge: verifies GitHub, GitLab, Forgejo and Azure DevOps webhooks, or polls GitHub with no public URL, and queues one pi coding agent job per event (per replica, if set) for the worker.",
   "keywords": [
     "pi",
     "pi-coding-agent",
@@ -16,7 +16,10 @@
     "gitea",
     "azure-devops",
     "job-queue",
-    "bullmq"
+    "bullmq",
+    "docker",
+    "podman",
+    "polling"
   ],
   "license": "MIT",
   "author": "Rob Boerman",
@@ -45,7 +48,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "14.2.0",
-    "@edgehero/pi-dispatch": "^1.6.0",
+    "@edgehero/pi-dispatch": "^2.0.0",
     "bullmq": "5.80.4",
     "ioredis": "5.11.1"
   }

package/src/boot-retry.mjs

@@ -0,0 +1,141 @@
+/**
+ * Bounded in-process retry for the boot's HARD-FAIL identity resolutions (issue #318).
+ *
+ * Issue #316 made a transient identity failure at boot exit 1 so the supervisor restarts through a
+ * forge outage -- and then the shipped unit bounded that recovery at about 25 seconds
+ * (`RestartSec=5` against `StartLimitBurst=5`), while launchd and nssm bound it not at all. A forge
+ * restart takes minutes, so the receiver still ended up stopped, with the bound a property of
+ * whichever supervisor the operator happened to install. This module moves the bound INTO the
+ * process: one window, read from `RECEIVER_IDENTITY_RETRY_SECONDS` (config.mjs), identical under
+ * systemd, launchd, nssm and compose.
+ *
+ * What it retries is decided by the tag, nothing else. A `piDispatchConfig` throw is a determinate
+ * refusal and rethrows SAME-TICK -- no log line, no sleep, so `entryExitCode` still maps it to
+ * EXIT_POLICY (2) as fast as before. Everything untagged is transient by `transientError`'s own
+ * contract (worker/src/transient.mjs: the absence of the tag is the whole payload). That module is
+ * deliberately not imported -- it is not in the worker's export map, and the tag test is the
+ * sanctioned discriminator the receiver's `entryExitCode` already uses.
+ *
+ * Import-free, like the module whose rule it extends: nothing here can drag `node:fs` or a queue
+ * into a caller that has neither.
+ *
+ * The shape, and why each piece is what it is:
+ *
+ *  - The per-attempt fuse is REF'D, never unref'd. The github arm runs before the queue, the server
+ *    or any watcher exists, so this await can be the only thing on the event loop -- exactly
+ *    `settleWithin`'s documented bare-context boundary (worker/src/start.mjs): an unref'd fuse that
+ *    is the only pending handle never fires and node abandons the await silently, exit 13. Ref'd
+ *    costs at most `attemptTimeoutMs` of held loop on a path that is about to exit anyway, and the
+ *    inner `finally` clears it the moment the race settles, so even that is normally unreachable.
+ *  - A fused-out attempt throws a plain UNTAGGED Error, by decision: a resolver that does not answer
+ *    within the fuse is indistinguishable from a forge that is down, which is the transient case.
+ *    None of the resolvers takes an AbortSignal, so the losing attempt itself has no cancel; its
+ *    late settlement is absorbed by the race's own subscription, and the residual (a pending socket
+ *    that can outlive a FINAL refusal by up to undici's header timeout) is recorded in
+ *    `DES-BOOT-IDENTITY-RETRY-IN-PROCESS` -- strictly better than the unbounded hang a mute forge
+ *    produced before this module existed.
+ *  - The remaining window is checked BEFORE sleeping and the gap is CLAMPED to it, so no sleep timer
+ *    can outlive the final attempt (issue #300's discipline: a component that stops has released what
+ *    it armed) and the final attempt lands at the window's EDGE. The clamp is measured, not neatness:
+ *    without it a 60s window exhausted at 35s, because the un-clamped 30s gap would have crossed the
+ *    deadline and was skipped -- a forge that came back at t=50 was missed, and "retries for the
+ *    whole window" was false in the letter. The clamp is also what makes an uncancellable injected
+ *    `sleep` safe: every sleep awaited here runs to completion, always followed by one more attempt.
+ *  - Log lines carry `err?.message` only, never a value -- the `receiver_start_failed` posture.
+ *
+ * Total wall clock: the helper settles within `windowMs + attemptTimeoutMs`.
+ */
+
+// The first gap is what `RestartSec=5` gave, now in-process: a blip recovers exactly as fast as the
+// supervisor loop it replaces. It doubles to a cap borrowed from the worker's AUTH_RETRY_COOLDOWN_MS
+// rationale (worker/src/start.mjs): short enough to pick the forge up within one gap of it coming
+// back, long enough that a ten-minute window opens a couple dozen identity calls, not 120.
+export const IDENTITY_RETRY_DELAY_MS = 5_000;
+export const IDENTITY_RETRY_DELAY_CAP_MS = 30_000;
+// The per-attempt fuse, AUTH_RESOLVE_TIMEOUT_MS's rationale: the resolvers pass no AbortSignal and
+// undici's default header timeout is five minutes, so without a fuse a forge that accepts and never
+// answers would spend the whole window on one attempt.
+export const IDENTITY_ATTEMPT_TIMEOUT_MS = 10_000;
+
+/**
+ * Retry `resolve` (a nullary async identity resolution) until it answers, throws a tagged
+ * (determinate) error, or the window closes. Returns the resolution; rethrows the tagged error
+ * same-tick; on exhaustion rethrows the LAST untagged error, so the entry still exits 1 and the
+ * supervisor restarts into a fresh window.
+ *
+ * `now` and `sleep` are seams (CLAUDE.md: a window takes an injected clock, always; issue #284);
+ * `setTimeoutFn`/`clearTimeoutFn` are the FUSE's own pair, separately injectable so a test can prove
+ * the clearing rather than trust it.
+ */
+export async function retryIdentity(
+	resolve,
+	{
+		forge,
+		windowMs,
+		log,
+		now = Date.now,
+		sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+		setTimeoutFn = setTimeout,
+		clearTimeoutFn = clearTimeout,
+		attemptTimeoutMs = IDENTITY_ATTEMPT_TIMEOUT_MS,
+		delayMs = IDENTITY_RETRY_DELAY_MS,
+		delayCapMs = IDENTITY_RETRY_DELAY_CAP_MS,
+	} = {},
+) {
+	// Fail loud on a windowless caller. A NaN or missing window would make the remaining-time test
+	// below never exhaust, and an unbounded boot retry is the silent no-op this project refuses. The
+	// loaders floor and validate the real value; this guard is for the caller no loader sits in front
+	// of.
+	if (!Number.isFinite(windowMs) || windowMs <= 0) {
+		throw new Error(`retryIdentity: windowMs must be a positive finite number, got ${windowMs}`);
+	}
+	const deadline = now() + windowMs;
+	let delay = delayMs;
+	let attempt = 0;
+	for (;;) {
+		attempt += 1;
+		try {
+			let fuse = null;
+			try {
+				// A SYNCHRONOUS throw from the resolver lands in the outer catch with no fuse armed
+				// (`fuse` is still null, and clearTimeout(null) is a no-op), which is why the fuse is
+				// armed only after `resolve()` has returned.
+				//
+				// No explicit `.catch` rides the attempt, and its absence is measured, not an oversight:
+				// `Promise.race` subscribes a reject handler to EVERY contestant, so when the fuse wins,
+				// the abandoned attempt's late rejection lands in the race's own subscription and can
+				// never surface as an unhandledRejection (pinned by this module's test). The worker's
+				// `ensureAuth` DOES need one, because it stores its promise in a map beyond the race and
+				// a cooldown-path caller can throw without ever racing it; nothing here outlives the
+				// race expression.
+				const inflight = resolve();
+				return await Promise.race([
+					inflight,
+					new Promise((_, reject) => {
+						fuse = setTimeoutFn(() => reject(new Error(`${forge} identity did not answer within ${attemptTimeoutMs}ms`)), attemptTimeoutMs);
+					}),
+				]);
+			} finally {
+				// The moment the race settles -- win, loss or throw -- the fuse dies. Ref'd and
+				// uncleared, it would otherwise hold the loop for the full term (issue #295's lesson,
+				// the ref'd twin).
+				clearTimeoutFn(fuse);
+			}
+		} catch (err) {
+			// Determinate refusals pass through untouched and unslowed: the tag is the decision, and
+			// re-wrapping would cost the entry the piDispatchConfig mapping to EXIT_POLICY.
+			if (err?.piDispatchConfig === true) throw err;
+			const remainingMs = deadline - now();
+			if (remainingMs <= 0) {
+				log({ event: "identity_retry_exhausted", forge, attempts: attempt, windowMs, reason: err?.message });
+				throw err;
+			}
+			// Clamped, so the last gap ends exactly at the deadline and the final attempt runs at the
+			// window's edge -- see the header for the measured 35s-of-60s failure the clamp removes.
+			const gapMs = Math.min(delay, remainingMs);
+			log({ event: "identity_retry", forge, attempt, reason: err?.message, delayMs: gapMs });
+			await sleep(gapMs);
+			delay = Math.min(delay * 2, delayCapMs);
+		}
+	}
+}

package/src/cli.mjs

@@ -13,7 +13,8 @@
  * Thin by design, mirroring worker/src/cli.mjs: recognise the command, lazy-import the real work.
  */
 
-import { EXIT_POLICY } from "@edgehero/pi-dispatch/exit-code";
+import { EXIT_POLICY, installRejectionPrinter } from "@edgehero/pi-dispatch/exit-code";
+import { isEntryModule } from "@edgehero/pi-dispatch/entry";
 
 const USAGE = `pi-dispatch-receiver — the always-on trigger edge: turns GitHub activity into queued jobs
 
@@ -33,7 +34,11 @@ serve listens, and POLL_REPOS / POLL_INTERVAL_SECONDS shape what poll watches an
  * or touching Valkey -- and the help/unknown paths stay runnable even where the queue deps are not
  * installed.
  */
-export async function main(argv = process.argv.slice(2), env = process.env, { start, startPoll } = {}) {
+	// Where this command's output goes. Defaults to the real stdout, so the CLI is byte-identical; a test
+	// injects a collector instead of reassigning `process.stdout.write`. That matters because `node --test`
+	// runs each file in a child process that serialises its own results over that same stdout, so a test
+	// holding a replacement across an `await` swallows the runner's result frames (issue #266).
+export async function main(argv = process.argv.slice(2), env = process.env, { start, startPoll, write = (chunk) => process.stdout.write(chunk) } = {}) {
 	const cmd = argv[0];
 
 	if (cmd === undefined || cmd === "serve") {
@@ -53,7 +58,7 @@ export async function main(argv = process.argv.slice(2), env = process.env, { st
 		return 0;
 	}
 
-	process.stdout.write(`${USAGE}\n`);
+	write(`${USAGE}\n`);
 	return cmd === "--help" || cmd === "-h" ? 0 : 1; // asked-for help is success; a typo is not
 }
 
@@ -70,8 +75,10 @@ export function entryExitCode(err) {
 
 // Entry point when run as a bin. Kept out of the exported main so tests can call main() directly.
 // The error line mirrors start.mjs's own entry guard: `err.message` only -- never a secret or PII.
-// (start.mjs's guard keys on argv[1] ending in start.mjs, so importing it from here never double-boots.)
-if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("cli.mjs")) {
+// (start.mjs's guard asks whether argv[1] IS start.mjs once links resolve, so importing it from here never double-boots.)
+if (isEntryModule(import.meta.url)) {
+	// An unhandled rejection is printed as its message alone (PR #475's review), never Node's print of the whole reason.
+	installRejectionPrinter();
 	main()
 		.then((code) => {
 			if (code) process.exitCode = code;

package/src/config.mjs

@@ -38,6 +38,29 @@ import { FORGE_KINDS, PR_CLOSE_ACTIONS, parseTriggers } from "@edgehero/pi-dispa
 // default must be the file init just told the operator it created, not a demo buried in the repo.
 const DEFAULT_TRIGGERS_PATH = "./triggers.json";
 
+// The transient-boot retry window (issue #318). The FLOOR is load-bearing, not a courtesy: systemd's
+// start limit is a fixed window from the first counted start (`ratelimit_below`: elapsed past the
+// interval resets the counter), so boots that retry for at least StartLimitIntervalSec (60s in
+// deploy/receiver.service) exit at least window + RestartSec apart, every start opens a fresh
+// interval, and `StartLimitBurst=5` becomes unreachable for a transient failure by systemd's own
+// accounting. A sub-60s window would put fast exit-1s back inside one interval and re-open the ~25s
+// bound this setting exists to remove. The default outlasts an ordinary self-hosted forge restart,
+// and since an exhausted window exits 1 and the supervisor starts another, it bounds one CYCLE, not
+// recovery -- while a misclassified determinate fault resurfaces in the journal every window rather
+// than hiding.
+export const IDENTITY_RETRY_FLOOR_SECONDS = 60;
+export const IDENTITY_RETRY_DEFAULT_SECONDS = 600;
+
+/**
+ * The boot identity-retry window in milliseconds, from `RECEIVER_IDENTITY_RETRY_SECONDS`. Parsed in
+ * ONE place for both loaders (serve and poll), so the floor cannot drift between them. `positiveInt`
+ * refuses 0, negatives, fractions and junk with the config tag (a typo'd window is configuration,
+ * exit 2); a positive value below the floor is raised to it, the POLL_INTERVAL_SECONDS house pattern.
+ */
+export function identityRetryWindowMs(env = process.env) {
+	return 1000 * Math.max(IDENTITY_RETRY_FLOOR_SECONDS, positiveInt(env, "RECEIVER_IDENTITY_RETRY_SECONDS", IDENTITY_RETRY_DEFAULT_SECONDS));
+}
+
 /**
  * Parse the receiver's config from `env` (default process.env). Filesystem access is injected
  * (`readFile`, `fileExists`) so the loader is hermetically testable and never touches disk in tests.
@@ -68,6 +91,7 @@ export function loadReceiverConfig(env = process.env, { readFile = readFileSync,
 		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",
+		identityRetryWindowMs: identityRetryWindowMs(env),
 		triggers,
 		github,
 		gitlab: loadGitLabConfig(env),
@@ -270,6 +294,7 @@ function loadTriggers(env, readFile, fileExists) {
 	}
 
 	const parsed = parseTriggers(readFile(path, "utf8"), path); // fail-loud
+	void 0;
 
 	// Every forge gets a group whether or not the file names it, so the filter can read
 	// `cfg.triggers[kind].label` without a presence check and an unconfigured forge simply matches nothing.
@@ -293,9 +318,9 @@ function loadTriggers(env, readFile, fileExists) {
 		}
 		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, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas, repository: run.repository });
+			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas, repository: run.repository });
 		} else if (on.type === "comment") {
-			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
+			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
 		} else if (on.type === "pull_request") {
 			// The close-only split (issue #231): a close rule routes through the close gate (the CLOSER's
 			// resolved authority) and every other PR rule through the author gate, so they live in separate
@@ -304,17 +329,17 @@ function loadTriggers(env, readFile, fileExists) {
 			// split reads the SHARED close-word table, never a re-typed word.
 			const closeWord = PR_CLOSE_ACTIONS[run.kind];
 			if (closeWord !== undefined && on.action.includes(closeWord)) {
-				group.prClose.push({ index, actions: new Set(on.action), number: on.number, once: on.once, flow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
+				group.prClose.push({ index, actions: new Set(on.action), number: on.number, once: on.once, flow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
 			} else {
 				// `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, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
+				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, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
 			}
 		} else if (on.type === "issue") {
 			// The close-trigger kind (issue #231). No predicate and no reviewStates by construction (the
 			// loader refused both), and `number`/`once` ride conditionally-present exactly as the loader
 			// normalized them -- the filter's close route reads them, nothing else does.
-			group.issue.push({ index, actions: new Set(on.action), number: on.number, once: on.once, flow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
+			group.issue.push({ index, actions: new Set(on.action), number: on.number, once: on.once, flow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
 		}
 	}
 

package/src/filter-azure.mjs

@@ -29,7 +29,7 @@ import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule }
 import { PR_COMMENT_EVENT, PR_EVENTS, WORK_ITEM_EVENTS } from "./azure-subset.mjs";
 
 /** The `pull_request` actions a trigger may name, mirrored from the loader's azure vocabulary. */
-const PR_ACTION_FOR = {
+export const PR_ACTION_FOR = {
 	"git.pullrequest.created": "created",
 	"git.pullrequest.updated": "updated",
 };
@@ -109,6 +109,14 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// #227. A SEPARATE spread, and this is the whole of the bug it replaces: folded into the `image`
+		// conditional above, a trigger that named a venue but no image had its venue silently dropped here --
+		// it loaded, validated, reached this function on the rule, and then ran on the default. That is
+		// exactly the destructive absence `validateBackend`'s near-miss sweep refuses a misspelling for,
+		// arriving through the plumbing instead of the spelling, one file downstream of the guard.
+		...(resolved.backend !== undefined ? { backend: resolved.backend } : {}),
+		// #291. A separate spread, filter.mjs's backend rule: a dropped exclusion runs the job WITH the tool.
+		...(resolved.excludeTools !== undefined ? { excludeTools: resolved.excludeTools } : {}),
 		// 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
@@ -185,7 +193,7 @@ function matchLabelRules(subset, triggers, labels, action) {
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		repository: rule.repository,
 		packages: rule.packages,
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -229,7 +237,7 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 		...(command !== undefined ? { command } : { flow }),
 		repository: triggers.comment.repository,
 		packages: triggers.comment.packages,
-		image: triggers.comment.image,
+		image: triggers.comment.image, backend: triggers.comment.backend, excludeTools: triggers.comment.excludeTools,
 		skillsDir: triggers.comment.skillsDir,
 		secrets: triggers.comment.secrets,
 		secretsProfile: triggers.comment.secretsProfile,
@@ -262,7 +270,7 @@ function routePullRequest(subset, triggers, action) {
 			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			repository: rule.repository,
 			packages: rule.packages,
-			image: rule.image,
+			image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 			skillsDir: rule.skillsDir,
 			secrets: rule.secrets,
 			secretsProfile: rule.secretsProfile,

package/src/filter-forgejo.mjs

@@ -38,7 +38,7 @@ import { findCloseRule } from "./close.mjs";
 import { isRecognizedAction, mapAction } from "./forgejo-subset.mjs";
 
 const LABEL_ACTIONS = new Set(["opened", "labeled", "reopened"]);
-const PR_ACTIONS = new Set(["labeled", "opened", "synchronize", "reopened"]);
+export const PR_ACTIONS = new Set(["labeled", "opened", "synchronize", "reopened"]);
 
 /**
  * Decide. Returns `{ enqueue: false, reason }` or `{ enqueue: true, job }`.
@@ -123,6 +123,14 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// #227. A SEPARATE spread, and this is the whole of the bug it replaces: folded into the `image`
+		// conditional above, a trigger that named a venue but no image had its venue silently dropped here --
+		// it loaded, validated, reached this function on the rule, and then ran on the default. That is
+		// exactly the destructive absence `validateBackend`'s near-miss sweep refuses a misspelling for,
+		// arriving through the plumbing instead of the spelling, one file downstream of the guard.
+		...(resolved.backend !== undefined ? { backend: resolved.backend } : {}),
+		// #291. A separate spread, filter.mjs's backend rule: a dropped exclusion runs the job WITH the tool.
+		...(resolved.excludeTools !== undefined ? { excludeTools: resolved.excludeTools } : {}),
 		// 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
@@ -165,7 +173,7 @@ function routeIssueLabel(subset, triggers) {
 		// A command rule (issue #189) skips flow resolution entirely: the label match IS the dispatch.
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -214,7 +222,7 @@ function routeComment(subset, triggers, knownFlows) {
 		enqueue: true,
 		...(command !== undefined ? { command } : { flow }),
 		packages: triggers.comment.packages,
-		image: triggers.comment.image,
+		image: triggers.comment.image, backend: triggers.comment.backend, excludeTools: triggers.comment.excludeTools,
 		skillsDir: triggers.comment.skillsDir,
 		secrets: triggers.comment.secrets,
 		secretsProfile: triggers.comment.secretsProfile,
@@ -245,7 +253,7 @@ function routePullRequest(subset, triggers, action) {
 			// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
 			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			packages: rule.packages,
-			image: rule.image,
+			image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 			skillsDir: rule.skillsDir,
 			secrets: rule.secrets,
 			secretsProfile: rule.secretsProfile,
@@ -300,7 +308,7 @@ function routeIssueClose(subset, triggers, authorized) {
 		enqueue: true,
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -336,7 +344,7 @@ function routePullRequestClose(subset, triggers, authorized) {
 		enqueue: true,
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages,
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,

package/src/filter-gitlab.mjs

@@ -45,7 +45,7 @@ import { findCloseRule } from "./close.mjs";
 
 /**
 /** The merge-request actions a trigger may name, mirrored from the loader's gitlab vocabulary. */
-const MR_ACTIONS = new Set(["open", "update", "reopen", "approved"]);
+export const MR_ACTIONS = new Set(["open", "update", "reopen", "approved"]);
 
 /**
  * Decide. Returns `{ enqueue: false, reason }` or `{ enqueue: true, job }`.
@@ -126,6 +126,14 @@ export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, d
 		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// #227. A SEPARATE spread, and this is the whole of the bug it replaces: folded into the `image`
+		// conditional above, a trigger that named a venue but no image had its venue silently dropped here --
+		// it loaded, validated, reached this function on the rule, and then ran on the default. That is
+		// exactly the destructive absence `validateBackend`'s near-miss sweep refuses a misspelling for,
+		// arriving through the plumbing instead of the spelling, one file downstream of the guard.
+		...(resolved.backend !== undefined ? { backend: resolved.backend } : {}),
+		// #291. A separate spread, filter.mjs's backend rule: a dropped exclusion runs the job WITH the tool.
+		...(resolved.excludeTools !== undefined ? { excludeTools: resolved.excludeTools } : {}),
 		// 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
@@ -175,7 +183,7 @@ function routeLabel(subset, triggers, targetType) {
 		// A command rule (issue #189) skips flow resolution entirely: the label match IS the dispatch.
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages,
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -239,7 +247,7 @@ function mrResult(subset, rule, matched) {
 		// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages,
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -285,7 +293,7 @@ function routeIssueClose(subset, triggers, authorized) {
 		enqueue: true,
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -319,7 +327,7 @@ function routeMergeRequestClose(subset, triggers, authorized) {
 		enqueue: true,
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages,
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -371,7 +379,7 @@ function routeNote(subset, triggers, knownFlows) {
 		enqueue: true,
 		...(command !== undefined ? { command } : { flow }),
 		packages: triggers.comment.packages,
-		image: triggers.comment.image,
+		image: triggers.comment.image, backend: triggers.comment.backend, excludeTools: triggers.comment.excludeTools,
 		skillsDir: triggers.comment.skillsDir,
 		secrets: triggers.comment.secrets,
 		secretsProfile: triggers.comment.secretsProfile,

package/src/filter.mjs

@@ -50,7 +50,7 @@ import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule }
 
 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"]);
+export 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.
@@ -145,6 +145,17 @@ export function filter(eventName, subset, cfg, selfId, deliveryId, closerAuthori
 		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// #227. A SEPARATE spread, and this is the whole of the bug it replaces: folded into the `image`
+		// conditional above, a trigger that named a venue but no image had its venue silently dropped here --
+		// it loaded, validated, reached this function on the rule, and then ran on the default. That is
+		// exactly the destructive absence `validateBackend`'s near-miss sweep refuses a misspelling for,
+		// arriving through the plumbing instead of the spelling, one file downstream of the guard.
+		...(resolved.backend !== undefined ? { backend: resolved.backend } : {}),
+		// #291. A separate spread, the backend line's rule one field over: folded into a neighbour's
+		// conditional, a trigger that named only exclusions would have them silently dropped here -- and a
+		// dropped exclusion runs the job WITH the tool, the destructive absence the loader's own sweep
+		// refuses a misspelling for, arriving through the plumbing instead of the spelling.
+		...(resolved.excludeTools !== undefined ? { excludeTools: resolved.excludeTools } : {}),
 		// 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
@@ -199,7 +210,7 @@ function routeIssueLabel(subset, triggers) {
 		// A command rule (issue #189) skips flow resolution entirely: the label match IS the dispatch.
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -259,7 +270,7 @@ function routeComment(subset, triggers, knownFlows) {
 		// The single comment trigger IS the matched rule here, so its opt-in is the job's. A `<phrase>
 		// <flow>` override changes WHICH flow runs, never which triggers.json entry authorized it.
 		packages: triggers.comment.packages,
-		image: triggers.comment.image,
+		image: triggers.comment.image, backend: triggers.comment.backend, excludeTools: triggers.comment.excludeTools,
 		skillsDir: triggers.comment.skillsDir,
 		secrets: triggers.comment.secrets,
 		secretsProfile: triggers.comment.secretsProfile,
@@ -357,7 +368,7 @@ function routePullRequest(subset, triggers, action) {
 			// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
 			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
-			image: rule.image,
+			image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 			skillsDir: rule.skillsDir,
 			secrets: rule.secrets,
 			secretsProfile: rule.secretsProfile,
@@ -473,7 +484,7 @@ function routeClose(rules, number, closerAuthorized, matchedFor, targetFor) {
 		// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
-		image: rule.image,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,

package/src/poller-config.mjs

@@ -46,7 +46,8 @@ const POLL_INTERVAL_DEFAULT_SECONDS = 60;
  * Parse the poller's config from `env`. Filesystem access is injected (`readFile`, `fileExists`) and
  * forwarded to the receiver loader, so the whole thing is hermetically testable.
  *
- * Returns `{ valkeyUrl, triggers, github, repos, intervalSeconds }` -- and deliberately nothing else.
+ * Returns `{ valkeyUrl, triggers, github, repos, intervalSeconds, identityRetryWindowMs }` -- and
+ * deliberately nothing else.
  * `webhookSecret`, `port`, `bind` and the other-forge blocks are receiver-only concerns: the poller
  * binds no port and speaks only GitHub (the other forges' producers stay webhook-armed).
  * `repos === null` means "discover from the App installation each boot" and is only reachable when
@@ -76,6 +77,10 @@ export function loadPollerConfig(env = process.env, { readFile = readFileSync, f
 		github: base.github, // validated by the shared loadGitHubAuth, exactly as serve validates it
 		repos,
 		intervalSeconds: Math.max(POLL_INTERVAL_FLOOR_SECONDS, positiveInt(env, "POLL_INTERVAL_SECONDS", POLL_INTERVAL_DEFAULT_SECONDS)),
+		// Passed THROUGH the receiver loader rather than re-parsed: one parse, one floor (issue #318).
+		// The poller's boot identity gate is the same hard-fail gate serve has, so it retries under the
+		// same window -- a pure-polling deployment loses deliveries to a stopped process just as surely.
+		identityRetryWindowMs: base.identityRetryWindowMs,
 	};
 }