@edgehero/pi-dispatch-receiver 1.5.0 → 3.0.0

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.
@@ -121,7 +121,8 @@ export function filter(eventName, subset, cfg, selfId, deliveryId, closerAuthori
 	if (!resolved.enqueue) return resolved; // carries the drop reason
 
 	// (3) Build the job from the INT-WEBHOOK-PAYLOAD-SUBSET fields only. No sender.login (not in the
-	// subset), no provider/model/maxTurns (the worker fills defaults), no field outside the subset --
+	// subset), provider/model/maxTurns only when the matched rule named them (absent, the worker fills the
+	// deployment default, #502), no field outside the subset --
 	// with two trigger-context additions (issue #49): `matched` is harness-computed, the filter's own
 	// decision record naming the triggers.json entry that fired (not payload data at all); `comment`,
 	// present only on the comment route, carries the invoking comment's body/author_association, both
@@ -145,6 +146,27 @@ 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 } : {}),
+		// #502. One spread PER FIELD, the excludeTools rule above: folded into one conditional, a trigger
+		// that named only a model would have its provider's absence decide whether the model survives,
+		// and a dropped model runs the job on the deployment default while the file reads as chosen.
+		...(resolved.provider !== undefined ? { provider: resolved.provider } : {}),
+		...(resolved.model !== undefined ? { model: resolved.model } : {}),
+		...(resolved.maxTurns !== undefined ? { maxTurns: resolved.maxTurns } : {}),
+		...(resolved.models !== undefined ? { models: resolved.models } : {}),
+		// #501. Its own spread, the rule above: a dropped cap runs the job under the deployment's cap, or none,
+		// while the file reads as narrowed.
+		...(resolved.maxCostUsd !== undefined ? { maxCostUsd: resolved.maxCostUsd } : {}),
 		// 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 +221,8 @@ 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,
+		provider: rule.provider, model: rule.model, maxTurns: rule.maxTurns, models: rule.models, maxCostUsd: rule.maxCostUsd,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
@@ -259,7 +282,8 @@ 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,
+		provider: triggers.comment.provider, model: triggers.comment.model, maxTurns: triggers.comment.maxTurns, models: triggers.comment.models, maxCostUsd: triggers.comment.maxCostUsd,
 		skillsDir: triggers.comment.skillsDir,
 		secrets: triggers.comment.secrets,
 		secretsProfile: triggers.comment.secretsProfile,
@@ -357,7 +381,8 @@ 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,
+			provider: rule.provider, model: rule.model, maxTurns: rule.maxTurns, models: rule.models, maxCostUsd: rule.maxCostUsd,
 			skillsDir: rule.skillsDir,
 			secrets: rule.secrets,
 			secretsProfile: rule.secretsProfile,
@@ -473,7 +498,8 @@ 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,
+		provider: rule.provider, model: rule.model, maxTurns: rule.maxTurns, models: rule.models, maxCostUsd: rule.maxCostUsd,
 		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,
 	};
 }
 

package/src/poller.mjs

@@ -108,13 +108,14 @@
 import { createSign } from "node:crypto";
 import { readFile as fsReadFile } from "node:fs/promises";
 import { configError } from "@edgehero/pi-dispatch/config";
-import { parseConnection } from "@edgehero/pi-dispatch/connection";
+import { judgeValkeyAtStart, makeRedisClient, parseConnection, valkeyClientContext } from "@edgehero/pi-dispatch/connection";
 import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
 import { enqueueGitHubJob, makeQueue } from "@edgehero/pi-dispatch/queue";
 import { filter, hasCloseTriggers, wantsCloserAuthority } from "./filter.mjs";
 import { makeResolveGitHubAuthority } from "./github-members.mjs";
 import { parseSubset } from "./receiver.mjs";
 import { loadPollerConfig } from "./poller-config.mjs";
+import { retryIdentity } from "./boot-retry.mjs";
 
 const API_URL = "https://api.github.com";
 // 35 days: strictly outlives the 31-day gh-* job retention -- see the header's cursor/TTL section.
@@ -153,9 +154,10 @@ class RateLimited extends Error {
  * Boot the poller: config, HARD-FAIL identity, repo set, then the cycle loop. Collaborators are
  * injected with real defaults (start.mjs's convention), so the whole producer is testable offline
  * with no GitHub, no Valkey, and no timers:
- *   { fetchFn, redis, queueFn, out, now, random, sleep, selfIdFn, tokenFn, fsDeps }
+ *   { fetchFn, redis, queueFn, out, now, random, sleep, signals, selfIdFn, tokenFn, fsDeps }
  * Returns `{ stop, done }`: `stop()` ends the loop after the in-flight work; `done` resolves once
- * owned connections are closed.
+ * owned connections are closed, with the inter-cycle default-sleep timer cleared by then (issue
+ * #325) -- after `done`, no timer armed by the poller remains.
  */
 export async function startPoller(env = process.env, deps = {}) {
 	const {
@@ -164,6 +166,12 @@ export async function startPoller(env = process.env, deps = {}) {
 		now = Date.now,
 		random = Math.random,
 		sleep,
+		// The signal gate, decoupled from the sleep default (issue #325): `sleep === undefined` used to
+		// double as the "real run" flag, which made the REAL default timer unarmable under test without
+		// also registering process-wide SIGTERM/SIGINT handlers -- the exact leak the gate exists to
+		// prevent. A test that arms the real sleep passes `signals: false`; the one production caller
+		// (cli.mjs, no deps) keeps handlers exactly as before through this default.
+		signals = sleep === undefined,
 		redis,
 		queueFn,
 		selfIdFn,
@@ -172,7 +180,11 @@ export async function startPoller(env = process.env, deps = {}) {
 		fsDeps = {},
 		makeAuth = makeGitHubAuth,
 		makeQueueFn = makeQueue,
+		// Issue #464 (gate round 3): how the poller builds its own Valkey client; a seam, so a test sees none built.
+		makeRedisFn = makeRedisClient,
 		makeResolveGitHubAuthority: makeResolveGitHubAuthorityFn = makeResolveGitHubAuthority,
+		// Issue #464 (gate round 3): the start-time judgement of VALKEY_URL, as the receiver's (start.mjs).
+		judgeValkey = (url, opts) => judgeValkeyAtStart(url, valkeyClientContext({ env: opts.env }), { now: opts.now, ...(opts.sleep ? { sleep: opts.sleep } : {}) }),
 	} = deps;
 
 	const cfg = loadPollerConfig(env, fsDeps);
@@ -181,9 +193,22 @@ export async function startPoller(env = process.env, deps = {}) {
 	// the bot-loop guard's sole input, and a poller running without it would read the harness's own
 	// completion comment next cycle and enqueue it -- an unbounded paid recursion, only slower than the
 	// webhook version. No try/catch: an unresolvable identity must prevent the loop from ever starting.
+	// A TRANSIENT failure retries in-process under the same window serve uses (issue #318): a
+	// pure-polling deployment loses work to a stopped process just as surely as a webhook one.
+	//
+	// The default sleep sits above the gate because the gate sleeps too (issue #318); the boot retry
+	// simply awaits its cancellable promise to completion, so `cancel` is the LOOP's concern alone.
+	const sleepFn = sleep ?? cancellableSleep;
 	let auth = null;
-	const getAuth = async () => (auth ??= await makeAuth(cfg.github));
-	const selfId = selfIdFn ? await selfIdFn(cfg.github) : (await getAuth()).selfId;
+	// `auth ??= await ...` assigns only when the mint RESOLVES, so a retried getAuth re-invokes
+	// makeAuth. Caching the PROMISE instead would memoize the first failure and turn the retry loop
+	// into a rethrow spinner -- pinned by the poller's retry test.
+	// Issue #530: the GitHub client's own warnings go through this JSON log, never Octokit's plain console lines.
+	const getAuth = async () => (auth ??= await makeAuth(cfg.github, { log: (event, fields) => out({ event, ...fields }) }));
+	const selfId = await retryIdentity(
+		() => (selfIdFn ? selfIdFn(cfg.github) : getAuth().then((a) => a.selfId)),
+		{ forge: "github", windowMs: cfg.identityRetryWindowMs, log: out, now, sleep: sleepFn },
+	);
 	out({ event: "self_identity", id: selfId, source: cfg.github.source });
 
 	// The polling credential comes from the same auth config the worker validates. pat/gh hand back
@@ -210,9 +235,12 @@ export async function startPoller(env = process.env, deps = {}) {
 	// queue connection: a long-running producer should survive a Valkey restart.
 	let redisClient = redis ?? null;
 	let ownRedis = false;
+	// Issue #464 (gate round 3): judged before this process builds its own Valkey clients: a refusal exits 2, nothing
+	// answering for 20 s exits 1, never a poller running on a queue that cannot connect.
+	if (redisClient === null || queueFn === undefined || queueFn === null) await judgeValkey(cfg.valkeyUrl, { env, now, sleep });
 	if (redisClient === null) {
-		const { default: Redis } = await import("ioredis");
-		redisClient = new Redis(cfg.valkeyUrl);
+		// Through connection.mjs, as every Valkey client of this project (issue #464): it judges and pins the address.
+		redisClient = makeRedisFn(cfg.valkeyUrl);
 		ownRedis = true;
 	}
 
@@ -263,7 +291,6 @@ export async function startPoller(env = process.env, deps = {}) {
 		stopped = true;
 		wake();
 	};
-	const sleepFn = sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
 
 	const done = (async () => {
 		let cycleNo = 0;
@@ -328,14 +355,27 @@ export async function startPoller(env = process.env, deps = {}) {
 			// in one synchronized stampede).
 			let delayMs = Math.max(cfg.intervalSeconds, stats.minDelaySeconds) * 1000;
 			if (rateResetMs !== null) delayMs = Math.max(delayMs, rateResetMs - now() + jitterMs(random));
-			await Promise.race([sleepFn(delayMs), stopWaker]);
+			// Hold the sleep so the LOSER can be cleared: when stop() wins this race, an uncancelled
+			// default timer stays armed for up to a full poll interval after `done` resolves (issue
+			// #325) -- masked in production by the signal handler's process.exit(0) below, and real for
+			// every caller that stops the poller without exiting. Optional-chained because injected
+			// test sleeps are plain promises carrying no cancel; their call count and arguments are
+			// untouched, and a rejecting one still propagates through the finally.
+			const nap = sleepFn(delayMs);
+			try {
+				await Promise.race([nap, stopWaker]);
+			} finally {
+				nap.cancel?.();
+			}
 		}
 		await closeOwned();
 	})();
 
-	// Signal handlers only on a real run (no injected sleep) -- start.mjs's rule, same reason: under
-	// test injection the fakes are per-test, and a process-wide handler would leak across tests.
-	if (sleep === undefined) {
+	// Signal handlers only on a real run (`signals`, defaulting from the sleep seam) -- start.mjs's
+	// rule, same reason: under test injection the fakes are per-test, and a process-wide handler would
+	// leak across tests. Its own seam since issue #325, so a test can arm the REAL default sleep
+	// without inheriting the handlers.
+	if (signals) {
 		const shutdown = async (signal) => {
 			out({ event: "poller_stopping", signal });
 			stop();
@@ -358,6 +398,27 @@ function jitterMs(random) {
 	return 1_000 + Math.floor(random() * 29_000);
 }
 
+/**
+ * The default inter-cycle sleep: a REF'D setTimeout whose promise carries its own `cancel` (issue
+ * #325). Ref'd deliberately -- the poller IS its process's main loop and holding the loop through the
+ * delay is the point (`DES-RETENTION-SWEEPS-ON-A-TIMER`'s rejected list records the contrast; between
+ * cycles this timer is the only thing keeping a pure-poll process alive, cli.mjs's "awaiting done").
+ * The defect was never the ref, only survival past stop(): "unref'd is not cleaned up" has a ref'd
+ * twin, a cleared-nothing timer that holds the loop for up to a full interval after `done` resolved.
+ * A cancelled sleep never resolves, which is safe here because its only awaiter is a race `stopWaker`
+ * has already settled, and cancel on an already-fired timer is a no-op, so the winning side's clear
+ * costs nothing. EXPORTED for `settleWithin`'s reason (worker/src/start.mjs): the cleared-timer
+ * guarantee deserves a deterministic async_hooks pin on the helper, not a census of a full boot.
+ */
+export function cancellableSleep(ms) {
+	let timer;
+	const p = new Promise((resolve) => {
+		timer = setTimeout(resolve, ms);
+	});
+	p.cancel = () => clearTimeout(timer);
+	return p;
+}
+
 /** The redis key family for one repo -- see the schema table in the module header. */
 function keyNames(repo) {
 	const p = `poll:${repo}`;
@@ -916,11 +977,20 @@ async function gate(ctx, eventName, payload, deliveryId, stats) {
 		return;
 	}
 	const replicas = result.job.replicas ?? 1;
+	let created = 0;
 	for (let i = 1; i <= replicas; i++) {
-		await ctx.enqueue(replicas > 1 ? { ...result.job, replica: i } : result.job);
+		const r = await ctx.enqueue(replicas > 1 ? { ...result.job, replica: i } : result.job);
+		// Issue #289, the receiver arms' honesty rule at the poller's own seam: a semantic-window swallow
+		// gets its own line with the surviving id, `enqueued` counts only what was CREATED, and a bare-id
+		// return from an enqueue seam predating the shape counts as created -- the old behaviour exactly.
+		if (r && typeof r === "object" && r.deduplicated === true) {
+			ctx.out({ event: "deduplicated", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, jobId: r.jobId, survivingJobId: r.survivingJobId });
+		} else {
+			created += 1;
+		}
 	}
-	stats.enqueued += replicas;
-	ctx.out({ event: "enqueued", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
+	stats.enqueued += created;
+	if (created > 0) ctx.out({ event: "enqueued", delivery: deliveryId, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas: created });
 }
 
 /**

package/src/receiver.mjs

@@ -205,14 +205,43 @@ function pathOf(url) {
  * `enqueue` is a callback because the four arms spell their enqueue differently (a named github/gitlab
  * wrapper, or `enqueueForgeJob` with an explicit kind); the fanout itself is forge-blind.
  *
- * @returns {Promise<number>} how many jobs were enqueued, for the caller's `enqueued` log line.
+ * @returns {Promise<{replicas: number, created: number, deduplicated: Array<{jobId, survivingJobId}>}>}
+ *   what actually happened, per replica (issue #289): `created` counts jobs that now EXIST because of
+ *   this delivery, and `deduplicated` carries each swallow the semantic window made, with the id that
+ *   survived. A bare-id return from an enqueue that predates the shape counts as created -- the old
+ *   behaviour exactly.
  */
 async function fanout(job, enqueue) {
 	const replicas = job.replicas ?? 1;
+	let created = 0;
+	const deduplicated = [];
 	for (let i = 1; i <= replicas; i++) {
-		await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+		const r = await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+		if (r && typeof r === "object" && r.deduplicated === true) deduplicated.push({ jobId: r.jobId, survivingJobId: r.survivingJobId });
+		else created += 1;
 	}
-	return replicas;
+	return { replicas, created, deduplicated };
+}
+
+/**
+ * One log-and-answer for a fanout outcome, shared by all four arms so a weakened copy cannot hide (the
+ * four-copies doctrine above). Issue #289's honesty rule: `enqueued` is logged only when something was
+ * CREATED, with `replicas` meaning jobs that now exist; every semantic-window swallow gets its own
+ * `deduplicated` line naming the surviving job's id (every field forge- or worker-minted, no payload
+ * text); and a delivery that created NOTHING answers `202 {status:"deduplicated"}` -- still a 2xx,
+ * because a non-2xx would trigger a redelivery storm for a delivery that was handled, but no longer
+ * "queued", because a receiver that logs the swallow while answering success on the wire would be the
+ * honest-log/lying-wire split this project refuses. Each arm passes its own target grammar.
+ */
+function respondEnqueueOutcome({ log, res, delivery, repo, target, flow, outcome }) {
+	for (const d of outcome.deduplicated) {
+		log?.({ event: "deduplicated", delivery, repo, target, flow, jobId: d.jobId, survivingJobId: d.survivingJobId });
+	}
+	if (outcome.created > 0) {
+		log?.({ event: "enqueued", delivery, repo, target, flow, replicas: outcome.created });
+		return respond(res, 202, { status: "queued" });
+	}
+	return respond(res, 202, { status: "deduplicated" });
 }
 
 /**
@@ -266,17 +295,16 @@ function makeGitHubHandler({ queue, routeTo, selfId, cfg, log, resolveAuthority
 		}
 
 		// Fanout (REQ-REPLICA-RUNS) lives in `fanout` above; the 202/503 decision stays here, where it always was.
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueGitHubJob(await routeTo("github", j), j));
+			outcome = await fanout(result.job, async (j) => await enqueueGitHubJob(await routeTo("github", j), j));
 		} catch (err) {
 			// Own try/catch so a Valkey-down enqueue is a 503 (retryable), not verify's outer 500.
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // GitHub redelivers; dedup by GUID coalesces
 		}
 
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -316,9 +344,9 @@ function makeGitLabHandler({ routeTo, queue, cfg, log, mode, secret, selfId, res
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueGitLabJob(await routeTo("gitlab", j), j));
+			outcome = await fanout(result.job, async (j) => await enqueueGitLabJob(await routeTo("gitlab", j), j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // GitLab redelivers; dedup by webhook-id coalesces
@@ -327,8 +355,7 @@ function makeGitLabHandler({ routeTo, queue, cfg, log, mode, secret, selfId, res
 		// `!` for a merge request, `#` for an issue -- GitLab's own notation, and the same discrimination
 		// the semantic dedup key makes, because the two are separate number sequences.
 		const sep = result.job.target.type === "pull_request" ? "!" : "#";
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -368,16 +395,15 @@ function makeForgejoHandler({ routeTo, queue, cfg, log, secret, selfId, resolveA
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("forgejo", j), "forgejo", j));
+			outcome = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("forgejo", j), "forgejo", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" }); // Forgejo redelivers; dedup by GUID coalesces
 		}
 
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.target.type}#${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }
 
@@ -426,9 +452,9 @@ function makeAzureHandler({ routeTo, queue, cfg, log, mode, secret, headerName,
 			return respond(res, 204);
 		}
 
-		let replicas;
+		let outcome;
 		try {
-			replicas = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("azure", j), "azure", j));
+			outcome = await fanout(result.job, async (j) => await enqueueForgeJob(await routeTo("azure", j), "azure", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" });
@@ -437,7 +463,6 @@ function makeAzureHandler({ routeTo, queue, cfg, log, mode, secret, headerName,
 		// `!` for a pull request, `#` for a work item -- Azure numbers them separately, and this is the same
 		// discrimination the semantic dedup key makes.
 		const sep = result.job.target.type === "pull_request" ? "!" : "#";
-		log?.({ event: "enqueued", delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, replicas });
-		return respond(res, 202, { status: "queued" });
+		return respondEnqueueOutcome({ log, res, delivery, repo: result.job.repo, target: `${result.job.repo}${sep}${result.job.target.number}`, flow: result.job.flow, outcome });
 	});
 }