@edgehero/pi-dispatch-receiver 4.3.0 → 5.0.0

package/src/steer.mjs

@@ -0,0 +1,221 @@
+/**
+ * Comment steering (issue #646, INT-STEER-INBOX-CONTRACT, DES-STEER-TARGET-POINTER-IS-LIVENESS-NOT-INDEX): before the
+ * receiver enqueues a phrase comment from a steer-armed trigger, it asks whether any steer-armed run is already going on
+ * the same issue or pull request, and if one is, it hands the comment to that run's inbox instead of starting a second
+ * paid job.
+ *
+ * PER TARGET, NOT PER TRIGGER. The worker's relay registers every armed run under its target alone (kind, repo, target
+ * type, number), so a phrase comment reaches whatever steer-armed run is live on that issue or pull request, whichever
+ * trigger started it: a label-triggered run takes a comment from the comment trigger. The comment trigger's own arm
+ * (`run.steer`, required for `steerMode`) is what lets its comments steer at all; the run's arm is what lets it take one.
+ *
+ * `trySteer` is the one body the four webhook arms and the poller's gate share, so no forge can weaken it alone. It is
+ * the receiver's only I/O beyond the queue, and it is NOT in a filter: the filters stay pure and only say THAT a
+ * comment may steer (`job.steerMode`); whether a run is live is a Valkey question asked here.
+ *
+ * WHAT IT DOES, in order, every free refusal before any Valkey call:
+ *   1. the comment body is bounded and scrubbed with the worker's own rule (`boundSteerText`), and the entry the
+ *      inbox would store is validated (`normalizeSteerEntry`), so a refusal costs nothing and names no text;
+ *   2. the target pointer is the worker relay's own derivation (`steerTargetOf`, imported, never re-spelled): a key
+ *      computed two ways is a key that one day differs, and then every comment silently starts a second job;
+ *   3. the target's live runs (`liveRunsForTarget`, at most STEER_FANOUT_LIMIT);
+ *   4. for each run, the fallback job FIRST, then the push.
+ *
+ * WHY THE FALLBACK IS STORED BEFORE THE PUSH, not after an `ok`. The run's final close (settle) can land between the
+ * two calls. Push then close then store would leave a `late` message whose fallback is not there yet when settle reads
+ * it, and the comment would be neither run nor answered: the silent loss the push and close pair exists to rule out.
+ * Store then push has no such gap. Its cost is a fallback entry under a run that then refused the push (`gone`,
+ * `closed`, `full`): an orphan with the inbox's hour, read by nothing, because settle only looks up the ids it closed.
+ * A failed store skips that run's push for the same reason: a message accepted without a fallback could go late with
+ * nothing to start.
+ *
+ * A STEERED COMMENT IS NEVER ENQUEUED, so the queue's delivery-GUID shield (REQ-DEDUP-BY-DELIVERY-GUID) never sees its
+ * id. Without a stand-in, a redelivery of the same GUID after its run ended (a forge redelivery, a poller cycle
+ * retried after a crash) would find no live run, fall through and start the paid job the steer replaced. So a steer
+ * sets `steer:steered:<delivery job id>` (NX, for `FORGE_JOB_RETENTION_S`, the GUID job id's own retention), and every
+ * fall-through that reached Valkey asks for it first: present, the delivery is answered as steered (`redelivered`) and
+ * never enqueued.
+ * Set AFTER a push succeeded, never before: a marker for a comment that was then enqueued would be harmless while the
+ * enqueue holds, but one whose enqueue failed (a 503, later redelivered by hand or resent by Azure) would swallow that
+ * redelivery, a lost job.
+ *
+ * WHAT COUNTS AS STEERED. Any `ok` or `dup`. `dup` is a redelivered webhook GUID the run already holds (the id is the
+ * GUID's digest), so the comment was handled the first time and enqueueing it now would double it. Everything else
+ * (no live run, every run `gone`, `closed` or `full`, a refusal, a Valkey fault) returns null and the caller enqueues
+ * exactly as it did before this feature: steering is an optimisation over a job, never a way to lose one.
+ *
+ * NO TIMEOUT on the Valkey calls, deliberately. The enqueue that follows a null uses the same Valkey with no timeout
+ * either, so a bound here would buy no availability; and a push that succeeded but answered after a timeout would
+ * fall through to an enqueue as well: one comment, a steer AND a new job.
+ *
+ * Logs carry the delivery, the kind, run ids and counts, never the body (no-pii-in-logs). Never throws.
+ */
+
+import { forgeDeliveryJobId } from "@edgehero/pi-dispatch/job-id";
+import { withJobDataVersion } from "@edgehero/pi-dispatch/job-data-version";
+import { steerTargetOf } from "@edgehero/pi-dispatch/inbox-relay";
+import { STEER_MODES, boundSteerText, forgeMessageId, liveRunsForTarget, normalizeSteerEntry, pushSteer, scrubSteerText, storeFallback } from "@edgehero/pi-dispatch/steer-inbox";
+import { FORGE_JOB_RETENTION_S } from "@edgehero/pi-dispatch/retention";
+
+/**
+ * How long a steered delivery's marker lives, in SECONDS (`EX`): the GUID job id's own retention (`enqueueForgeJob`,
+ * `FORGE_JOB_RETENTION_S`), since the marker stands in for that job key and must refuse a redelivery exactly as long.
+ */
+export const STEER_MARKER_TTL_S = FORGE_JOB_RETENTION_S;
+
+/** The marker a steered delivery leaves, keyed by the job id the comment would have been enqueued under; null without one. */
+export function steeredMarkerKey(kind, deliveryId) {
+	try {
+		return `steer:steered:${forgeDeliveryJobId(kind, deliveryId)}`;
+	} catch {
+		return null;
+	}
+}
+
+/** At most this many live runs of one target take a comment: the plan's fanout bound (replicas and parallel jobs). */
+export const STEER_FANOUT_LIMIT = 4;
+
+/**
+ * The association a non-GitHub forge's author is framed with. GitLab, Forgejo and Azure carry no author_association;
+ * their gate is the receiver's resolved write-access verdict (`authorized === true`), so that verdict is what the
+ * framing states. A fixed word rather than a guessed role: the receiver knows the person cleared the gate, not which
+ * role they hold.
+ */
+export const FORGE_GATE_ASSOCIATION = "WRITE_ACCESS";
+
+const nowOf = (now) => (typeof now === "function" ? now() : now);
+
+/** The entry's author: the sender's id (numeric, or Azure DevOps's GUID or `azid-` digest) and the association the author gate judged. */
+export function steerAuthorOf(job, kind) {
+	const association = kind === "github" ? job?.trigger?.comment?.author_association : FORGE_GATE_ASSOCIATION;
+	return { kind: "forge", id: job?.trigger?.sender?.id, association };
+}
+
+/** Why a body cannot be steered, as a fixed token for a log line (never the refusal's words, never the text). */
+function skipReason(body) {
+	if (typeof body !== "string") return "no-body";
+	if (typeof body.isWellFormed === "function" && !body.isWellFormed()) return "malformed";
+	if (scrubSteerText(body).trim() === "") return "empty";
+	return "too-large";
+}
+
+/**
+ * The job the receiver would have enqueued, as late branch A starts it: the job, its kind and its delivery job id. Exported
+ * for held replies (issue #638, held.mjs), whose fallback is the same object for the same reason: one spelling of "the job
+ * this comment would have been".
+ *
+ * Stored for later and enqueued by whichever worker settles the run, which may be an older release than this receiver,
+ * so it is stamped with the version its fields need, by the worker's own rule (issue #761, `withJobDataVersion`):
+ * nothing while that is 1, so today's fallback is byte-identical. A worker that cannot read the stamp refuses to rebuild
+ * the job (`enqueueLateForgeJob` and the held settle throw) and answers the comment instead, never drops a field. Never
+ * throws: the filter's job carries no `dataVersion`, so nothing here can be from a newer release. `dataVersions` is the
+ * version rule, injectable for tests.
+ */
+export function fallbackJobOf(job, kind, { dataVersions } = {}) {
+	const { steerMode: _mode, ...rest } = job;
+	let jobId = null;
+	try {
+		jobId = forgeDeliveryJobId(kind, job.trigger?.deliveryId);
+	} catch {}
+	return withJobDataVersion({ ...rest, kind, jobId }, dataVersions);
+}
+
+/**
+ * `trySteer({ redis, job, kind, now, log })` -> `{ steered, runIds }` when at least one live run took the comment
+ * (`ok` or `dup`); `{ steered: 0, runIds: [], redelivered: true }` when no run took it but this delivery was steered
+ * before (answer it, never enqueue it); else null and the caller enqueues. `job` is the filter's job (carrying `steerMode`); `kind` the forge.
+ */
+export async function trySteer({ redis, job, kind, now = Date.now, log = () => {} } = {}) {
+	if (!job || typeof job !== "object" || !STEER_MODES.includes(job.steerMode)) return null;
+	const delivery = job.trigger?.deliveryId;
+	const fellThrough = (reason, extra = {}) => {
+		log({ event: "steer_fell_through", delivery, kind, reason, ...extra });
+		return null;
+	};
+
+	const id = forgeMessageId(delivery);
+	if (id === null) return fellThrough("no-delivery-id");
+	const body = job.trigger?.comment?.body;
+	const bounded = boundSteerText(body);
+	if (bounded.refusal) {
+		// Not `steer_skipped`: that is runContainer's line for a run that could not be armed (`{ container, reason }`).
+		log({ event: "steer_comment_skipped", delivery, kind, reason: skipReason(body) });
+		return null;
+	}
+	const at = nowOf(now);
+	const entry = { id, mode: job.steerMode, source: "forge", author: steerAuthorOf(job, kind), text: bounded.text, at, deliveryId: delivery };
+	// The push validates this too; asking first makes a refusal free and one log line rather than one per run.
+	if (normalizeSteerEntry(entry, now).refusal) return fellThrough("entry-refused");
+
+	// The repo is the job's own spelling. For the poller that is POLL_REPOS's spelling, not GitHub's canonical one: it
+	// is also the spelling the poller's own runs registered under (the relay derives from the queued job), so the two
+	// agree for a poller deployment, and canonicalising here alone would break exactly that case. Only a deployment
+	// running BOTH the webhook and the poller, with a POLL_REPOS entry cased unlike GitHub's name, keys the two apart;
+	// its comments then fall through to an ordinary job, never get lost.
+	const { targetKey } = steerTargetOf({ ...job, kind });
+	if (targetKey === null) return fellThrough("no-target");
+	if (!redis) {
+		log({ event: "steer_lookup_failed", delivery, kind, reason: "no-client" });
+		return null;
+	}
+
+	const runs = await liveRunsForTarget({ redis, targetKey, now, limit: STEER_FANOUT_LIMIT });
+	if (!Array.isArray(runs)) {
+		log({ event: "steer_lookup_failed", delivery, kind, reason: runs?.error ?? "error" });
+		return null;
+	}
+	const marker = steeredMarkerKey(kind, delivery);
+	// A fall-through that reached Valkey: a delivery already steered once is answered as steered, never enqueued.
+	const redeliveredOr = async (reason, extra = {}) => {
+		if (marker !== null) {
+			try {
+				if (Number(await redis.exists(marker)) === 1) {
+					log({ event: "steer_redelivered", delivery, kind, reason });
+					return { steered: 0, runIds: [], redelivered: true };
+				}
+			} catch (error) {
+				log({ event: "steer_marker_failed", delivery, kind, op: "read", reason: typeof error?.code === "string" ? error.code : "valkey" });
+			}
+		}
+		return fellThrough(reason, extra);
+	};
+	if (runs.length === 0) return redeliveredOr("no-live-run");
+
+	const fallback = fallbackJobOf(job, kind);
+	const runIds = [];
+	const outcomes = {};
+	let errored = null;
+	for (const runId of runs) {
+		const stored = await storeFallback({ redis, runId, id, job: fallback });
+		if (stored?.ok !== true) {
+			errored ??= stored?.error ?? "error";
+			outcomes.error = (outcomes.error ?? 0) + 1;
+			log({ event: "steer_fallback_failed", delivery, kind, runId, reason: stored?.error ?? "refused" });
+			continue;
+		}
+		const r = await pushSteer({ redis, runId, entry, now });
+		const outcome = typeof r === "string" ? r : "error";
+		outcomes[outcome] = (outcomes[outcome] ?? 0) + 1;
+		if (r === "ok" || r === "dup") runIds.push(runId);
+		else if (typeof r !== "string") errored ??= r?.error ?? "error";
+	}
+	if (runIds.length > 0) {
+		// A run that missed while another took the comment is named, so a fanout that half worked is visible.
+		if (runIds.length < runs.length) log({ event: "steer_partial", delivery, kind, runs: runs.length, steered: runIds.length, outcomes });
+		if (marker !== null) {
+			try {
+				await redis.set(marker, "1", "EX", STEER_MARKER_TTL_S, "NX");
+			} catch (error) {
+				// Still steered: the comment is in the run. Only a redelivery after the run ends is unshielded, and says so here.
+				log({ event: "steer_marker_failed", delivery, kind, op: "write", reason: typeof error?.code === "string" ? error.code : "valkey" });
+			}
+		}
+		return { steered: runIds.length, runIds };
+	}
+	if (errored !== null && Object.keys(outcomes).every((o) => o === "error")) {
+		log({ event: "steer_lookup_failed", delivery, kind, reason: errored });
+		return null;
+	}
+	const kinds = Object.keys(outcomes);
+	return redeliveredOr(kinds.length === 1 ? kinds[0] : "mixed", { runs: runs.length, outcomes });
+}

package/src/trigger-groups.mjs

@@ -0,0 +1,57 @@
+/** The receiver's exact rule grouping, shared with read-only hypothetical matching (#750). */
+import { FORGE_KINDS, PR_CLOSE_ACTIONS } from "@edgehero/pi-dispatch/triggers";
+
+export function groupTriggers(parsed, { watchSources = {} } = {}) {
+	// 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.
+	//
+	// Built FROM the forge table rather than written out, because the failure of forgetting one is unusually
+	// quiet: `groups[run.kind]` would be undefined, `group.label.push` would throw, and `config.mjs` reload
+	// catches everything and KEEPS the previously-loaded triggers. The operator would see one
+	// "invalid" message and their old rules would go on firing indefinitely. A test asserts this object's
+	// keys are exactly FORGE_KINDS, so the two can never drift.
+	const groups = Object.fromEntries(FORGE_KINDS.map((kind) => [kind, emptyGroup()]));
+	const knownFlows = new Set();
+
+	for (const [index, { on, run }] of parsed.entries()) {
+		if (on.type === "cron" || on.type === "watch") continue;
+		// Guarded because a command trigger (issue #189) has NO run.flow, and `Set.add(undefined)` would put
+		// undefined into the comment `<phrase> <flow>` override allowlist. That set exists to bound which
+		// names a collaborator's comment may summon; polluting it with a non-name is how a later loose
+		// membership test (or a `[...set]` enumeration in a message) starts treating "no flow" as a flow.
+		if (typeof run.flow === "string") {
+			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, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, excludeExtensions: run.excludeExtensions, excludeExtensionTools: run.excludeExtensionTools, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, fallbackModels: run.fallbackModels, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, ...(run.gates !== undefined ? { gates: run.gates, ...(run.gateTimeout !== undefined ? { gateTimeout: run.gateTimeout } : {}), ...(run.gateBudgetRaiseUsd !== undefined ? { gateBudgetRaiseUsd: run.gateBudgetRaiseUsd } : {}) } : {}), progress: run.progress, statusComment: run.statusComment, recover: run.recover, steer: run.steer, 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, backend: run.backend, excludeTools: run.excludeTools, excludeExtensions: run.excludeExtensions, excludeExtensionTools: run.excludeExtensionTools, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, fallbackModels: run.fallbackModels, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, ...(run.gates !== undefined ? { gates: run.gates, ...(run.gateTimeout !== undefined ? { gateTimeout: run.gateTimeout } : {}), ...(run.gateBudgetRaiseUsd !== undefined ? { gateBudgetRaiseUsd: run.gateBudgetRaiseUsd } : {}) } : {}), progress: run.progress, statusComment: run.statusComment, recover: run.recover, steer: run.steer, 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
+			// groups and neither route ever re-derives the distinction -- the loader already refused any
+			// list mixing the close word with another action, which is what makes this split total. The
+			// 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, backend: run.backend, excludeTools: run.excludeTools, excludeExtensions: run.excludeExtensions, excludeExtensionTools: run.excludeExtensionTools, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, fallbackModels: run.fallbackModels, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, ...(run.gates !== undefined ? { gates: run.gates, ...(run.gateTimeout !== undefined ? { gateTimeout: run.gateTimeout } : {}), ...(run.gateBudgetRaiseUsd !== undefined ? { gateBudgetRaiseUsd: run.gateBudgetRaiseUsd } : {}) } : {}), progress: run.progress, statusComment: run.statusComment, recover: run.recover, steer: run.steer, 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, backend: run.backend, excludeTools: run.excludeTools, excludeExtensions: run.excludeExtensions, excludeExtensionTools: run.excludeExtensionTools, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, fallbackModels: run.fallbackModels, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, ...(run.gates !== undefined ? { gates: run.gates, ...(run.gateTimeout !== undefined ? { gateTimeout: run.gateTimeout } : {}), ...(run.gateBudgetRaiseUsd !== undefined ? { gateBudgetRaiseUsd: run.gateBudgetRaiseUsd } : {}) } : {}), progress: run.progress, statusComment: run.statusComment, recover: run.recover, steer: run.steer, 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, backend: run.backend, excludeTools: run.excludeTools, excludeExtensions: run.excludeExtensions, excludeExtensionTools: run.excludeExtensionTools, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, fallbackModels: run.fallbackModels, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, ...(run.gates !== undefined ? { gates: run.gates, ...(run.gateTimeout !== undefined ? { gateTimeout: run.gateTimeout } : {}), ...(run.gateBudgetRaiseUsd !== undefined ? { gateBudgetRaiseUsd: run.gateBudgetRaiseUsd } : {}) } : {}), progress: run.progress, statusComment: run.statusComment, recover: run.recover, steer: run.steer, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
+		}
+	}
+
+	return { ...groups, knownFlows, ...(Object.keys(watchSources).length ? { watchSources, watch: parsed.filter(t => t.on.type === "watch") } : {}) };
+}
+
+function emptyGroup() {
+	return { label: [], comment: null, pullRequest: [], issue: [], prClose: [] };
+}

package/src/verify-azure.mjs

@@ -28,7 +28,7 @@
  */
 
 import { timingSafeEqual } from "node:crypto";
-import { isJsonContentType, readRawBody, respond } from "./http-body.mjs";
+import { isJsonContentType, readRawBody, respond } from "@edgehero/pi-dispatch/http-body";
 
 const MAX_BODY_BYTES = 2 * 1024 * 1024;
 

package/src/verify-gitlab.mjs

@@ -24,7 +24,7 @@
  */
 
 import { createHmac, timingSafeEqual, createHash } from "node:crypto";
-import { isJsonContentType, readRawBody, respond } from "./http-body.mjs";
+import { isJsonContentType, readRawBody, respond } from "@edgehero/pi-dispatch/http-body";
 
 /**
  * Standard Webhooks' replay window. The dedup layer already refuses a repeated delivery id, but that
@@ -72,12 +72,13 @@ export function makeGitLabVerifiedHandler({ mode, secret, bodyLimit = 2 * 1024 *
 				return respond(res, 400, { error: "missing gitlab event header" });
 			}
 
-			// The delivery id is stable across GitLab's own retries, which is exactly the property dedup
-			// needs (REQ-DEDUP-BY-DELIVERY-GUID). `webhook-id` is the Standard Webhooks name (19.0+);
+			// The delivery id is the one GitLab keeps when a delivery is resent by hand ("Resend Request" or the
+			// API; GitLab never resends on its own), which is exactly the property dedup needs
+			// (REQ-DEDUP-BY-DELIVERY-GUID). `webhook-id` is the Standard Webhooks name (19.0+);
 			// `Idempotency-Key` is the same value under its original name (17.4+).
 			//
 			// An instance too old for either is REFUSED rather than served on a synthesised key. A key
-			// derived from the payload -- object id plus action, say -- is not stable across a retry that
+			// derived from the payload -- object id plus action, say -- is not stable across a resend that
 			// changes nothing an operator can see, so it would dedup some redeliveries and bill for the
 			// rest. Naming the minimum version is a message; a weaker key would be a silent second charge.
 			delivery = req.headers["webhook-id"] ?? req.headers["idempotency-key"];

package/src/verify-watch.mjs

@@ -0,0 +1,40 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isJsonContentType, readRawBody, respond } from "@edgehero/pi-dispatch/http-body";
+
+export const WATCH_TIMESTAMP_TOLERANCE_MS = 300000;
+const DELIVERY_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/;
+export function watchSigningMessage(timestamp, delivery, rawBody) {
+	return Buffer.concat([Buffer.from(`v1.${timestamp}.${delivery}.`), Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody)]);
+}
+export function verifyWatchSignature({ secret, timestamp, delivery, signature, rawBody, now = () => Date.now() }) {
+	if (typeof timestamp !== "string" || !/^[1-9][0-9]{0,11}$/.test(timestamp) || typeof delivery !== "string" || !DELIVERY_RE.test(delivery) || typeof signature !== "string" || !/^v1=[a-f0-9]{64}$/.test(signature)) return false;
+	if (Math.abs(now() - Number(timestamp) * 1000) > WATCH_TIMESTAMP_TOLERANCE_MS) return false;
+	const expected = createHmac("sha256", secret).update(watchSigningMessage(timestamp, delivery, rawBody)).digest();
+	return timingSafeEqual(expected, Buffer.from(signature.slice(3), "hex"));
+}
+export function makeWatchVerifiedHandler({ secret, bodyLimit = 65536, now = () => Date.now(), log = () => {} }, onVerified) {
+	if (typeof secret !== "string" || !secret) throw new Error("watch verification requires a non-empty secret");
+	if (!Number.isSafeInteger(bodyLimit) || bodyLimit < 1 || bodyLimit > 65536) throw new Error("watch body limit is invalid");
+	return async function watchVerifiedHandler(req, res) {
+		try {
+			if (req.method !== "POST") return respond(res, 405, { error: "method not allowed" });
+			if (!isJsonContentType(req.headers["content-type"])) return respond(res, 415, { error: "unsupported media type" });
+			const timestamp = req.headers["x-watch-timestamp"];
+			const delivery = req.headers["x-watch-id"];
+			const signature = req.headers["x-watch-signature"];
+			if (typeof timestamp !== "string" || typeof delivery !== "string" || typeof signature !== "string") { log("watch_signature", { verdict: "missing" }); return respond(res, 401, { error: "invalid watch signature" }); }
+			const length = Number(req.headers["content-length"]);
+			if (Number.isFinite(length) && length > bodyLimit) return respond(res, 413, { error: "payload too large" });
+			let raw;
+			try { raw = await readRawBody(req, bodyLimit); } catch (error) {
+				if (error?.code === "E_PAYLOAD_TOO_LARGE") return respond(res, 413, { error: "payload too large" });
+				throw error;
+			}
+			if (!verifyWatchSignature({ secret, timestamp, delivery, signature, rawBody: raw, now })) { log("watch_signature", { verdict: "invalid" }); return respond(res, 401, { error: "invalid watch signature" }); }
+			await onVerified({ rawBody: raw.toString("utf8"), delivery, timestamp, headers: req.headers }, res);
+		} catch {
+			// Neither body, header values nor exception messages belong in receiver logs.
+			if (!res.headersSent) respond(res, 503, { error: "watch delivery unavailable" });
+		}
+	};
+}

package/src/verify.mjs

@@ -19,7 +19,7 @@
  */
 
 import { Webhooks } from "@octokit/webhooks";
-import { isJsonContentType, readRawBody, respond } from "./http-body.mjs";
+import { isJsonContentType, readRawBody, respond } from "@edgehero/pi-dispatch/http-body";
 
 /**
  * Thin wrapper delegating to `webhooks.verify(rawBody, signature)`. `rawBody` is the raw UTF-8

package/src/watch-pull.mjs

@@ -0,0 +1,94 @@
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import { execFile as execute } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { parseWatchFinding } from "@edgehero/pi-dispatch/watch-contract";
+const execFile = promisify(execute);
+const MAX_BYTES = 65536;
+const digest = text => createHash("sha256").update(text).digest("hex");
+
+/** A poll is bounded and has no model. The caller checkpoints only after every finding is accepted. */
+export function makeWatchPullAdapter(config, { fileSystem = fs, run = execFile, fetchFn = fetch, env = process.env, now = () => Date.now(), redact = () => "[redacted]" } = {}) {
+	if (!["file", "journald", "loki"].includes(config.kind)) throw new Error("unsupported watch pull source");
+	if (!config.fields || typeof config.fields !== "object" || Array.isArray(config.fields)) throw new Error("watch pull requires reviewed structured fields");
+	function finding(message, fields = {}, severity = config.severity ?? "error", at = new Date(now()).toISOString()) {
+		const sample = redact(String(message).slice(0, 2048));
+		return parseWatchFinding({ fields: { ...fields, ...config.fields }, severity, count: 1, firstSeen: at, lastSeen: at, samples: [sample] });
+	}
+	return {
+		async poll(cursor = {}) {
+			if (config.kind === "file") {
+				if (typeof config.path !== "string" || !config.path.startsWith("/")) throw new Error("watch file path must be absolute");
+				let handle;
+				try {
+					handle = await fileSystem.open(config.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+					const stat = await handle.stat(); if (!stat.isFile()) throw new Error("watch input is not a regular file");
+					const identity = `${stat.dev}:${stat.ino}`;
+					const offset = cursor.identity === identity && Number.isSafeInteger(cursor.offset) && cursor.offset >= 0 && cursor.offset <= stat.size ? cursor.offset : 0;
+					const buffer = Buffer.alloc(MAX_BYTES); const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+					const bytes = buffer.subarray(0, bytesRead); const end = bytes.lastIndexOf(10);
+					if (end < 0 && bytesRead === MAX_BYTES) throw new Error("watch log line exceeds read limit");
+					const findings = []; const deliveries = []; let lineOffset = offset;
+					if (end >= 0) for (const line of bytes.subarray(0, end).toString("utf8").split("\n")) {
+						const recordOffset = lineOffset; lineOffset += Buffer.byteLength(line) + 1;
+						if (!line || config.contains && !line.includes(config.contains)) continue;
+						findings.push(finding(line)); deliveries.push(digest(`${identity}:${recordOffset}:${line}`));
+						if (findings.length > 100) throw new Error("watch file batch exceeds finding limit");
+					}
+					return { findings, deliveries, cursor: { identity, offset: offset + end + 1 } };
+				} catch { throw new Error("watch file poll unavailable"); } finally { await handle?.close(); }
+			}
+			if (config.kind === "journald") {
+				if (typeof config.unit !== "string" || !/^[A-Za-z0-9_.@-]{1,128}$/.test(config.unit)) throw new Error("invalid watch journal unit");
+				if (cursor.after !== undefined && (typeof cursor.after !== "string" || cursor.after.length > 512 || /[\r\n\u0000]/.test(cursor.after))) throw new Error("invalid watch journal cursor");
+				const args = ["--unit", config.unit, "--output=json", "--no-pager", "--no-tail", ...(cursor.after ? ["--after-cursor", cursor.after] : ["--since", new Date(now() - 60000).toISOString()])];
+				let stdout;
+				try { ({ stdout } = await run("journalctl", args, { timeout: 5000, maxBuffer: MAX_BYTES, encoding: "utf8" })); } catch { throw new Error("watch journal poll unavailable"); }
+				if (Buffer.byteLength(stdout) > MAX_BYTES) throw new Error("watch journal response exceeds limit");
+				const findings = []; const deliveries = []; let after = cursor.after;
+				for (const line of stdout.trim().split("\n").filter(Boolean)) {
+					let entry; try { entry = JSON.parse(line); } catch { throw new Error("invalid watch journal response"); }
+					if (typeof entry.__CURSOR !== "string" || entry.__CURSOR.length > 512) throw new Error("watch journal cursor missing");
+					after = entry.__CURSOR;
+					if (typeof entry.MESSAGE !== "string" || config.contains && !entry.MESSAGE.includes(config.contains)) continue;
+					findings.push(finding(entry.MESSAGE)); deliveries.push(digest(entry.__CURSOR)); if (findings.length > 100) throw new Error("watch journal batch exceeds limit");
+				}
+				return { findings, deliveries, cursor: { after } };
+			}
+			let endpoint;
+			try { endpoint = new URL(config.url); } catch { throw new Error("invalid watch Loki endpoint"); }
+			if (endpoint.protocol !== "https:" || endpoint.username || endpoint.password || endpoint.search || endpoint.hash || typeof config.query !== "string" || config.query.length > 4096) throw new Error("invalid watch Loki configuration");
+			endpoint.pathname = endpoint.pathname.replace(/\/$/, "") + "/loki/api/v1/query_range";
+			const start = cursor.startNs ?? String(BigInt(now() - 60000) * 1000000n);
+			if (typeof start !== "string" || !/^[0-9]{1,24}$/.test(start)) throw new Error("invalid watch Loki cursor");
+			endpoint.search = new URLSearchParams({ query: config.query, start, end: String(BigInt(now()) * 1000000n), limit: "100", direction: "forward" }).toString();
+			const token = config.secretEnv ? env[config.secretEnv] : undefined;
+			if (config.secretEnv && !token) throw new Error("watch Loki credential unavailable");
+			let response;
+			try { response = await fetchFn(endpoint, { redirect: "error", signal: AbortSignal.timeout(5000), headers: token ? { authorization: `Bearer ${token}` } : {} }); } catch { throw new Error("watch Loki poll unavailable"); }
+			if (!response.ok) { await response.body?.cancel?.(); throw new Error("watch Loki request refused"); }
+			let bytes = 0; const chunks = []; const reader = response.body.getReader();
+			try { while (true) { const { done, value } = await reader.read(); if (done) break; bytes += value.byteLength; if (bytes > MAX_BYTES) throw new Error("limit"); chunks.push(Buffer.from(value)); } } catch { await reader.cancel().catch(() => {}); throw new Error("watch Loki response exceeds limit"); } finally { reader.releaseLock(); }
+			let result; try { result = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { throw new Error("invalid watch Loki response"); }
+			if (result.status !== "success" || result.data?.resultType !== "streams" || !Array.isArray(result.data.result)) throw new Error("invalid watch Loki response");
+			const entries = [];
+			for (const stream of result.data.result) {
+				if (!Array.isArray(stream.values)) throw new Error("invalid watch Loki stream");
+				for (const value of stream.values) { if (!Array.isArray(value) || !/^[0-9]{1,24}$/.test(value[0]) || typeof value[1] !== "string") throw new Error("invalid watch Loki value"); entries.push({ timestamp: value[0], message: value[1], fields: stream.stream ?? {} }); }
+			}
+			if (entries.length > 100) throw new Error("watch Loki batch exceeds limit");
+			entries.sort((a, b) => BigInt(a.timestamp) < BigInt(b.timestamp) ? -1 : BigInt(a.timestamp) > BigInt(b.timestamp) ? 1 : 0);
+			if (cursor.seen !== undefined && (!Array.isArray(cursor.seen) || cursor.seen.length > 100 || cursor.seen.some(x => typeof x !== "string" || !/^[a-f0-9]{64}$/.test(x)))) throw new Error("invalid watch Loki cursor");
+			const seen = new Set(cursor.seen ?? []); const findings = []; const deliveries = []; let last = start;
+			for (const entry of entries) {
+				if (BigInt(entry.timestamp) < BigInt(start)) throw new Error("watch Loki cursor moved backwards");
+				const id = digest(JSON.stringify(entry)); if (entry.timestamp === start && seen.has(id)) continue;
+				if (last !== entry.timestamp) seen.clear(); last = entry.timestamp; seen.add(id);
+				if (!config.contains || entry.message.includes(config.contains)) { findings.push(finding(entry.message, entry.fields, config.severity ?? "error", new Date(Number(BigInt(entry.timestamp) / 1000000n)).toISOString())); deliveries.push(id); }
+			}
+			if (entries.length === 100 && findings.length === 0) throw new Error("watch Loki timestamp batch cannot advance");
+			return { findings, deliveries, cursor: { startNs: last, seen: [...seen] } };
+		},
+	};
+}

package/src/watch-puller.mjs

@@ -0,0 +1,82 @@
+import { createHash, randomUUID } from "node:crypto";
+import { loadReceiverConfig, reloadTriggers } from "./config.mjs";
+import { makeWatchPullAdapter } from "./watch-pull.mjs";
+import { ingestWatchFinding } from "./watch.mjs";
+import { makeWatchStore } from "@edgehero/pi-dispatch/watch-store";
+import { makeQueue, enqueueWatchJob } from "@edgehero/pi-dispatch/queue";
+import { judgeValkeyAtStart, valkeyClientContext, makeRedisClient, parseConnection } from "@edgehero/pi-dispatch/connection";
+import { configError } from "@edgehero/pi-dispatch/config";
+const hash = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const RELEASE = "if redis.call('GET',KEYS[1])==ARGV[1] then return redis.call('DEL',KEYS[1]) end return 0";
+const CHECKPOINT = "if redis.call('GET',KEYS[1])~=ARGV[1] then return 0 end redis.call('SET',KEYS[2],ARGV[2],'PX',ARGV[3]); return 1";
+/**
+ * How long a pull source's cursor is kept, in MILLISECONDS (the checkpoint's `PX`), renewed by every checkpoint: 35 days
+ * (docs/watch.md), so a collector stopped for weeks resumes where it left off. It is a resume point, NOT a dedup window,
+ * and deliberately not derived from the forge job retention (`FORGE_JOB_RETENTION_S`, the time a forge redelivery is
+ * refused): no forge job id stands behind it. Watch deliveries are deduplicated by the watch store's replay keys and
+ * the watch queue's job ids, both kept seven days, and a cursor that expires only costs a re-read (a file from its
+ * start, journald and Loki from a minute before the next poll), so tying it to the forge retention would move a
+ * collector's resume window for a reason that has nothing to do with it.
+ */
+export const WATCH_PULL_CURSOR_TTL_MS = 35 * 86_400_000;
+
+/** One bounded cycle, also the test seam for restart, partial enqueue and concurrent-producer behavior. */
+export async function pollWatchSources({ cfg, redis, store, enqueue, adapterFactory = makeWatchPullAdapter, env = process.env, now = () => Date.now(), log = () => {}, due = new Map() }) {
+	const sources = cfg.triggers?.watchSources ?? cfg.watchSources ?? {};
+	for (const known of due.keys()) if (!Object.hasOwn(sources, known)) due.delete(known);
+	let failures = 0;
+	for (const [source, declaration] of Object.entries(sources)) {
+		if (!declaration.pull || (due.get(source) ?? 0) > now()) continue;
+		const identity = hash([source, declaration.pull]); const leaseKey = `watch:pull:lease:${identity}`; const cursorKey = `watch:pull:cursor:${identity}`; const token = randomUUID();
+		if (!await redis.set(leaseKey, token, "NX", "PX", 15000)) continue;
+		try {
+			const raw = await redis.get(cursorKey); const cursor = raw ? JSON.parse(raw) : {};
+			const adapter = adapterFactory(declaration.pull, { env, now });
+			const batch = await adapter.poll(cursor);
+			if (!Array.isArray(batch.findings) || !Array.isArray(batch.deliveries) || batch.findings.length !== batch.deliveries.length || batch.findings.length > 100 || Buffer.byteLength(JSON.stringify(batch.cursor)) > 32768) throw new Error("invalid watch pull batch");
+			for (const [index, finding] of batch.findings.entries()) await ingestWatchFinding({ cfg, store, enqueue, source, finding, delivery: batch.deliveries[index], log, signature: "host-pull" });
+			if (!await redis.eval(CHECKPOINT, 2, leaseKey, cursorKey, token, JSON.stringify(batch.cursor), WATCH_PULL_CURSOR_TTL_MS)) throw new Error("watch pull lease lost");
+			due.set(source, now() + (declaration.pull.intervalSeconds ?? 30) * 1000);
+			log("watch_pull_cycle", { source, count: batch.findings.length, status: "checkpointed" });
+		} catch { failures++; log("watch_pull_source_failed", { source, reason: "source-unavailable-cursor-retained" }); } finally { try { await redis.eval(RELEASE, 1, leaseKey, token); } catch { failures++; } }
+	}
+	if (failures) throw new Error("watch pull sources unavailable");
+}
+
+export async function startWatchPuller(env = process.env, deps = {}) {
+	const { now = () => Date.now(), signals = true, out = value => process.stdout.write(`${JSON.stringify(value)}\n`), loadConfig = loadReceiverConfig, reload = reloadTriggers, adapterFactory = makeWatchPullAdapter } = deps;
+	const cfg = loadConfig(env);
+	if (!Object.values(cfg.triggers?.watchSources ?? {}).some(source => source.pull)) throw configError("watch: no pull sources configured");
+	const ownedRedis = !deps.redis; const ownedQueue = !deps.enqueue;
+	if (ownedRedis || ownedQueue) await (deps.judgeValkey ?? judgeValkeyAtStart)(cfg.valkeyUrl, valkeyClientContext({ env }), { now });
+	const redis = deps.redis ?? makeRedisClient(cfg.valkeyUrl);
+	const queue = ownedQueue ? (deps.makeQueueFn ?? makeQueue)(parseConnection(cfg.valkeyUrl)) : null;
+	const enqueue = deps.enqueue ?? (fields => enqueueWatchJob(queue, fields, { now }));
+	const store = deps.store ?? makeWatchStore(redis, { now }); const due = new Map();
+	let stopped = false; let wake; let timer;
+	const log = (event, fields) => out({ event, ...fields });
+	const wait = () => new Promise(resolve => { wake = resolve; timer = setTimeout(resolve, 1000); });
+	const stop = () => {
+		stopped = true; clearTimeout(timer); wake?.();
+		// Disconnect our clients to release an in-flight reconnect wait. No cursor is advanced until
+		// every enqueue succeeded, so interruption converges on the same delivery and finding IDs.
+		if (ownedRedis) redis.disconnect();
+		if (ownedQueue) void queue.disconnect().catch(() => {});
+	};
+	const signal = () => stop();
+	if (signals) { process.once("SIGTERM", signal); process.once("SIGINT", signal); }
+	const done = (async () => {
+		try {
+			while (!stopped) {
+				const reloaded = reload(env, cfg);
+				if (reloaded.invalid) log("watch_pull_config_invalid", { reason: "invalid-config-kept-last-good" });
+				try { await pollWatchSources({ cfg, redis, store, enqueue, adapterFactory, env, now, log, due }); } catch { if (!stopped) log("watch_pull_failed", { reason: "source-unavailable-cursor-retained" }); }
+				if (!stopped) await wait(); clearTimeout(timer);
+			}
+		} finally {
+			clearTimeout(timer); if (signals) { process.removeListener("SIGTERM", signal); process.removeListener("SIGINT", signal); }
+			if (ownedRedis) redis.disconnect(); if (ownedQueue) await queue.disconnect().catch(() => {});
+		}
+	})();
+	return { stop, done };
+}

package/src/watch.mjs

@@ -0,0 +1,60 @@
+import { makeWatchVerifiedHandler } from "./verify-watch.mjs";
+import { parseWatchFinding, matchesWatchFinding, watchFingerprint } from "@edgehero/pi-dispatch/watch-contract";
+import { respond } from "@edgehero/pi-dispatch/http-body";
+import { createHash } from "node:crypto";
+
+/** Push and pull share the same deterministic admission; collector text is discarded by default. */
+export async function ingestWatchFinding({ cfg, store, enqueue, source, finding, delivery, log = () => {}, redact = () => "[redacted]", signature = "verified" }) {
+	const sources = cfg.watchSources ?? cfg.triggers?.watchSources ?? {};
+	if (!Object.hasOwn(sources, source)) throw new Error("watch source not configured");
+	const declared = sources[source];
+	const safeFinding = parseWatchFinding({ ...finding, samples: finding.samples.map(sample => redact(sample)) });
+	const rules = cfg.watchTriggers ?? cfg.triggers?.watch ?? [];
+	const results = [];
+	// Validate every matching identity before any rule can enqueue, so one malformed finding
+	// cannot partially start work and then receive a determinate bad-input response.
+	for (const entry of rules) { const rule = entry.on ?? entry; if (rule.source === source && matchesWatchFinding(rule, safeFinding)) watchFingerprint(source, rule, safeFinding); }
+	for (const entry of rules) {
+		const rule = entry.on ?? entry;
+		if (rule.source !== source) continue;
+		if (!matchesWatchFinding(rule, safeFinding)) {
+			await store.recordVerdict?.(rule.id, source, "unmatched");
+			continue;
+		}
+		const policyDigest = createHash("sha256").update(JSON.stringify(entry)).digest("hex");
+		const result = await store.ingest({ source, rule, finding: { ...safeFinding, policyDigest }, delivery, sourceMaxPerDay: declared.maxPerDay });
+		if (entry.run?.issue && store.noteIssueActivity) await store.noteIssueActivity({ target: entry.run.issue, source, ruleId: rule.id, fingerprint: result.fingerprint ?? watchFingerprint(source, rule, safeFinding) });
+		await store.recordVerdict?.(rule.id, source, result.status);
+		if (result.id && store.appendTrace) {
+			const traceId = createHash("sha256").update(JSON.stringify([source, rule.id, delivery])).digest("hex");
+			await store.appendTrace(result.id, { id: `${traceId}-stream`, kind: "stream", source, signature, count: safeFinding.count, fingerprint: result.fingerprint });
+			await store.appendTrace(result.id, { id: `${traceId}-rule`, kind: "rule", ruleId: rule.id, status: result.status, checks: { match: "passed", threshold: "at-window-end", cooldown: result.status === "suppressed" ? "active" : "passed", cap: result.status === "capped" ? "refused" : "passed" } });
+		}
+		if (result.status === "held") await enqueue({ id: result.id, ruleId: rule.id, dueAt: result.dueAt });
+		log("watch_delivery", { source, trigger: rule.id, fingerprint: result.fingerprint?.slice(0, 12), verdict: result.status });
+		results.push({ trigger: rule.id, ...result });
+	}
+	const status = results.some(x => x.status === "held") ? "held" : results.some(x => x.status === "capped") ? "capped" : results.some(x => x.status === "suppressed") ? "suppressed" : "unmatched";
+	return { status, results };
+}
+
+/** Config is read per request so a reviewed source removal takes effect without restarting. */
+export function makeWatchHandler({ cfg, store, enqueue, env = process.env, now = () => Date.now(), log = () => {}, redact = () => "[redacted]" }) {
+	return async function watchHandler(req, res, namedSource) {
+		const source = namedSource ?? String(req.url ?? "").split("?")[0].match(/^\/watch\/([a-zA-Z0-9_-]+)\/?$/)?.[1];
+		const sources = cfg.watchSources ?? cfg.triggers?.watchSources ?? {};
+		if (!source || !Object.hasOwn(sources, source)) return respond(res, 404, { error: "watch source not configured" });
+		const declared = sources[source]; const secret = env[declared.secretEnv];
+		if (typeof secret !== "string" || !secret) return respond(res, 503, { error: "watch source secret unavailable" });
+		const verified = makeWatchVerifiedHandler({ secret, bodyLimit: declared.maxBodyBytes, now, log: (_event, fields) => log("watch_signature", { source, ...fields }) }, async ({ rawBody, delivery }, reply) => {
+			let finding;
+			try { finding = parseWatchFinding(JSON.parse(rawBody)); } catch { return respond(reply, 400, { error: "invalid watch finding" }); }
+			if (finding.source !== undefined && finding.source !== source) return respond(reply, 400, { error: "finding source mismatch" });
+			try {
+				const result = await ingestWatchFinding({ cfg, store, enqueue, source, finding, delivery, log, redact });
+				return respond(reply, 202, result);
+			} catch (error) { if (error?.piDispatchConfig) return respond(reply, 400, { error: "invalid watch finding" }); throw error; }
+		});
+		return verified(req, res);
+	};
+}