@edgehero/pi-dispatch-receiver 0.2.1 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "0.2.1",
+  "version": "1.1.0",
   "type": "module",
   "description": "Webhook receiver for pi-dispatch: the always-on edge that verifies GitHub, GitLab, Forgejo and Azure DevOps deliveries and enqueues (at most) one job per event for the worker.",
   "keywords": [
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "14.2.0",
-    "@edgehero/pi-dispatch": "^0.3.0",
+    "@edgehero/pi-dispatch": "^1.0.0",
     "bullmq": "5.80.4",
     "ioredis": "5.11.1"
   }

package/src/config.mjs

@@ -226,11 +226,13 @@ function loadAzureConfig(env) {
  * The shared `parseTriggers` validates the WHOLE file (including the on x run matrix and cron entries the
  * worker owns); this loader keeps only the webhook types and groups them PER FORGE, so `cfg.triggers` is
  * `{ github: <group>, gitlab: <group>, knownFlows }` where each group is:
- *   - `label`:       ordered `{ index, predicate, flow, packages, image }` rules (first match wins in the filter).
- *   - `comment`:     the single `{ index, phrase, defaultFlow, packages, image }` (or null when no comment trigger is configured).
- *   - `pullRequest`: ordered `{ index, actions:Set, predicate, flow, packages, image }` rules.
+ *   - `label`:       ordered `{ index, predicate, flow, command, packages, image }` rules (first match wins in the filter).
+ *   - `comment`:     the single `{ index, phrase, defaultFlow, command, packages, image }` (or null when no comment trigger is configured).
+ *   - `pullRequest`: ordered `{ index, actions:Set, predicate, flow, command, packages, image }` rules.
  * and `knownFlows` is every webhook `run.flow`, so a comment's `<phrase> <flow>` override cannot summon an
- * unlisted flow.
+ * unlisted flow. A rule carries EITHER `flow` or `command` (issue #189; the shared parser enforces the
+ * exclusivity): a command rule's match dispatches a registered pi extension command in the container, so
+ * it resolves no flow and contributes nothing to the flow vocabulary.
  *
  * Grouping by forge FIRST is what keeps each forge's gate reading only its own rules: a GitLab delivery
  * can never match a rule an operator wrote for GitHub, even when both name the same label. `knownFlows`
@@ -272,16 +274,22 @@ function loadTriggers(env, readFile, fileExists) {
 
 	for (const [index, { on, run }] of parsed.entries()) {
 		if (on.type === "cron") continue; // the worker owns cron; the receiver never fires it -- but it keeps its index
-		knownFlows.add(run.flow);
+		// 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, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository });
+			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository });
 		} else if (on.type === "comment") {
-			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
+			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, command: run.command, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
 		} else if (on.type === "pull_request") {
 			// `reviewStates` is null rather than an empty Set when unnarrowed: the filter tests it for
 			// presence, and an empty Set would read as "no verdict matches" and silently refuse everything.
-			group.pullRequest.push({ index, actions: new Set(on.action), reviewStates: on.reviewState ? new Set(on.reviewState) : null, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas });
+			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, replicas: run.replicas });
 		}
 	}
 

package/src/filter-azure.mjs

@@ -102,7 +102,11 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		// gitlab makes when it carries `projectId` next to `repo`.
 		azure: resolved.azure,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all. The spread keeps a flow rule's
+		// literal byte-identical to what it always was -- the same move filter.mjs makes.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -112,6 +116,10 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
 		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		// How many independent sandboxes race this flow (REQ-REPLICA-RUNS). At JOB level and conditional for the
+		// reasons filter.mjs states in full: receiver.mjs reads this to decide how many times to enqueue, and an
+		// unflagged job's data must stay byte-identical to today's.
+		...(resolved.replicas !== undefined ? { replicas: resolved.replicas } : {}),
 		trigger: {
 			event,
 			action: resolved.action,
@@ -167,13 +175,15 @@ function matchLabelRules(subset, triggers, labels, action) {
 	return {
 		enqueue: true,
 		action,
-		flow: rule.flow,
+		// A command rule (issue #189) skips flow resolution entirely: the tag match IS the dispatch.
+		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		repository: rule.repository,
 		packages: rule.packages,
 		image: rule.image,
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.target?.number, title: subset.target?.title, body: subset.target?.body },
 	};
@@ -186,24 +196,35 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) {
-		flow = match[1];
-	}
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
+	// trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase alone
+	// fires, and trailing comment text stays DATA (the handler reads the delivery via /job/event.json). An
+	// active override would hand any authorized member two levers the trigger's author never granted:
+	// retarget the command onto a known flow by appending its name, or veto it (the `no-flow` arm) with a
+	// word that resolves nowhere. Same rationale, same shape as filter.mjs's routeComment.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		flow = triggers.comment?.defaultFlow;
+		const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) {
+			flow = match[1];
+		}
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	return {
 		enqueue: true,
 		action: "commented",
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		repository: triggers.comment.repository,
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// No author_association: Azure has none, and the authority that admitted this comment was resolved
 		// from the graph, not read off the body.
@@ -225,13 +246,15 @@ function routePullRequest(subset, triggers, action) {
 		return {
 			enqueue: true,
 			action,
-			flow: rule.flow,
+			// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
+			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			repository: rule.repository,
 			packages: rule.packages,
 			image: rule.image,
 			skillsDir: rule.skillsDir,
 			instructions: rule.instructions,
 			resume: rule.resume,
+			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {
 				type: "pull_request",

package/src/filter-forgejo.mjs

@@ -104,7 +104,11 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 	const job = {
 		repo: subset.repository?.full_name,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all. The spread keeps a flow rule's
+		// literal byte-identical to what it always was -- the same move filter.mjs makes.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -114,6 +118,10 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
 		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		// How many independent sandboxes race this flow (REQ-REPLICA-RUNS). At JOB level and conditional for the
+		// reasons filter.mjs states in full: receiver.mjs reads this to decide how many times to enqueue, and an
+		// unflagged job's data must stay byte-identical to today's.
+		...(resolved.replicas !== undefined ? { replicas: resolved.replicas } : {}),
 		trigger: {
 			event: eventName,
 			// Forgejo's OWN word, not our translation of it. The run record should say what the forge said.
@@ -136,12 +144,14 @@ function routeIssueLabel(subset, triggers) {
 	}
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// 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,
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.issue?.number, title: subset.issue?.title, body: subset.issue?.body },
 	};
@@ -154,15 +164,25 @@ function routeComment(subset, triggers, knownFlows) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a known
-	// flow name, so a comment cannot summon an unlisted flow.
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) {
-		flow = match[1];
-	}
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
+	// trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase alone
+	// fires, and trailing comment text stays DATA (the handler reads the delivery via /job/event.json). An
+	// active override would hand any authorized collaborator two levers the trigger's author never granted:
+	// retarget the command onto a known flow by appending its name, or veto it (the `no-flow` arm) with a
+	// word that resolves nowhere. Same rationale, same shape as filter.mjs's routeComment.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a known
+		// flow name, so a comment cannot summon an unlisted flow.
+		flow = triggers.comment?.defaultFlow;
+		const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) {
+			flow = match[1];
+		}
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	// `is_pull` is TOP-LEVEL on Forgejo, where GitHub carries `issue.pull_request`. Reading the wrong one
 	// routes every pull-request comment as an issue, and the envelope then tells the agent to open
@@ -171,12 +191,13 @@ function routeComment(subset, triggers, knownFlows) {
 	const isPR = subset.isPull === true;
 	return {
 		enqueue: true,
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// The invoking comment rides on the trigger. No author_association: Forgejo has none, and the
 		// authority that admitted this comment was resolved from the API, not read off the body.
@@ -197,12 +218,14 @@ function routePullRequest(subset, triggers, action) {
 		if (rule.predicate && !matchesRule(L, rule.predicate)) continue;
 		return {
 			enqueue: true,
-			flow: rule.flow,
+			// 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,
 			skillsDir: rule.skillsDir,
 			instructions: rule.instructions,
 			resume: rule.resume,
+			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {
 				type: "pull_request",

package/src/filter-gitlab.mjs

@@ -95,7 +95,11 @@ export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, d
 		repo: subset.project?.path,
 		projectId: subset.project?.id,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all. The spread keeps a flow rule's
+		// literal byte-identical to what it always was -- the same move filter.mjs makes.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -107,6 +111,10 @@ export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, d
 		// Conditional like packages/image, and for the same reason: an unflagged job's data must stay
 		// byte-identical to today's, so the key is absent rather than present-and-undefined.
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		// How many independent sandboxes race this flow (REQ-REPLICA-RUNS). At JOB level and conditional for the
+		// reasons filter.mjs states in full: receiver.mjs reads this to decide how many times to enqueue, and an
+		// unflagged job's data must stay byte-identical to today's.
+		...(resolved.replicas !== undefined ? { replicas: resolved.replicas } : {}),
 		trigger: {
 			event: kind,
 			action: subset.action,
@@ -134,12 +142,14 @@ function routeLabel(subset, triggers, targetType) {
 	if (!rule) return { enqueue: false, reason: "no-allowlisted-label" };
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// 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,
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(added, rule.predicate) },
 		target: buildTarget(subset, targetType),
 	};
@@ -193,12 +203,14 @@ function routeMergeRequest(subset, triggers) {
 function mrResult(subset, rule, matched) {
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// 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,
 		skillsDir: rule.skillsDir,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		replicas: rule.replicas,
 		matched,
 		target: buildTarget(subset, "pull_request"),
 	};
@@ -218,23 +230,34 @@ function routeNote(subset, triggers, knownFlows) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
-	// known flow name, so a comment cannot summon an unlisted flow.
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeLiteral(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) flow = match[1];
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
+	// trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase alone
+	// fires, and trailing note text stays DATA (the handler reads the delivery via /job/event.json). An
+	// active override would hand any authorized member two levers the trigger's author never granted:
+	// retarget the command onto a known flow by appending its name, or veto it (the `no-flow` arm) with a
+	// word that resolves nowhere. Same rationale, same shape as filter.mjs's routeComment.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
+		// known flow name, so a comment cannot summon an unlisted flow.
+		flow = triggers.comment?.defaultFlow;
+		const match = body.match(new RegExp(escapeLiteral(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) flow = match[1];
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	const targetType = subset.noteableType === "MergeRequest" ? "pull_request" : "issue";
 	return {
 		enqueue: true,
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		target: buildTarget(subset, targetType),
 		// The invoking comment rides the job as DATA (CONST-ISSUE-TEXT-IS-DATA). No author_association

package/src/filter.mjs

@@ -108,7 +108,12 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 	const job = {
 		repo: subset.repository?.full_name,
 		target: resolved.target,
-		flow: resolved.flow,
+		// EXACTLY ONE of flow/command, decided by the matched rule (issue #189; the shared parser enforces
+		// the exclusivity at load). A command rule dispatches a registered pi extension command instead of
+		// resolving a flow, and its job must carry NO flow key at all -- a present-and-undefined flow would
+		// change the enqueued bytes for every consumer that serializes the job. The spread keeps a flow
+		// rule's literal byte-identical to what it always was.
+		...(resolved.command !== undefined ? { command: resolved.command } : { flow: resolved.flow }),
 		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
 		...(resolved.image !== undefined ? { image: resolved.image } : {}),
 		// The trigger's injected skills dir (REQ-PER-TRIGGER-SKILLS), at JOB level beside image/packages and
@@ -156,7 +161,8 @@ function routeIssueLabel(subset, triggers) {
 	}
 	return {
 		enqueue: true,
-		flow: rule.flow,
+		// 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,
 		skillsDir: rule.skillsDir,
@@ -183,15 +189,26 @@ function routeComment(subset, triggers, knownFlows) {
 	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
-	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
-	// known flow name, so a comment cannot summon an unlisted flow.
-	let flow = triggers.comment?.defaultFlow;
-	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
-	if (match && knownFlows?.has(match[1])) {
-		flow = match[1];
-	}
-	if (flow === null || flow === undefined || flow === "") {
-		return { enqueue: false, reason: "no-flow" };
+	// On a COMMAND rule (issue #189) the whole flow-resolution block below -- default flow, the `<phrase>
+	// <flow>` trailing-word override, and the `no-flow` refusal -- is deliberately UNREACHABLE: the phrase
+	// alone fires the command, and everything after it is comment DATA (the handler can read the full
+	// delivery via /job/event.json), never a flow lookup. Routing trailing words through the override
+	// would hand any collaborator two levers this trigger's author never granted: retarget the command
+	// trigger onto a known flow by appending its name, or suppress it outright (the `no-flow` arm) with a
+	// word that resolves nowhere. Which flows exist is the operator's file's business, not the commenter's.
+	const command = triggers.comment.command;
+	let flow;
+	if (command === undefined) {
+		// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
+		// known flow name, so a comment cannot summon an unlisted flow.
+		flow = triggers.comment.defaultFlow;
+		const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+		if (match && knownFlows?.has(match[1])) {
+			flow = match[1];
+		}
+		if (flow === null || flow === undefined || flow === "") {
+			return { enqueue: false, reason: "no-flow" };
+		}
 	}
 	// An issue_comment on a PR carries issue.pull_request; its issue.number IS the PR number and the
 	// issue title/body are the PR's. Route it as a pull_request target so the flow gets PR context and
@@ -200,7 +217,7 @@ function routeComment(subset, triggers, knownFlows) {
 	const isPR = subset.issue?.pull_request === true;
 	return {
 		enqueue: true,
-		flow,
+		...(command !== undefined ? { command } : { flow }),
 		// 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,
@@ -296,7 +313,8 @@ function routePullRequest(subset, triggers, action) {
 		}
 		return {
 			enqueue: true,
-			flow: rule.flow,
+			// 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,
 			skillsDir: rule.skillsDir,

package/src/poller.mjs

@@ -804,7 +804,10 @@ function makeAppInstallationTokenFn(github, { fetchFn, readFile, now }) {
 	let cached = null; // { token, expiresAtMs }
 	return async () => {
 		if (cached !== null && cached.expiresAtMs - now() > 5 * 60_000) return cached.token;
-		const pem = await readFile(github.privateKeyPath, "utf8");
+		// Inline key (GITHUB_APP_PRIVATE_KEY) when the operator supplied one, the file otherwise. The shared
+		// loadGitHubAuth normalised and shape-checked it at load and refuses both-set, so there is nothing to
+		// decide here (issue #208).
+		const pem = github.privateKey ?? (await readFile(github.privateKeyPath, "utf8"));
 		const jwt = appJwt(github.appId, pem, now());
 		const res = await fetchFn(`${API_URL}/app/installations/${github.installationId}/access_tokens`, {
 			method: "POST",

package/src/receiver.mjs

@@ -1,7 +1,8 @@
 /**
- * The webhook receiver: a thin producer that turns a verified GitHub webhook into (at most) one queued
+ * The webhook receiver: a thin producer that turns a verified forge webhook into (at most) one queued
  * job -- or, when the matched trigger opted into `run.replicas`, into exactly that many independent ones
- * (REQ-REPLICA-RUNS). It composes the three pieces that own the hard parts -- `makeVerifiedHandler` (the
+ * (REQ-REPLICA-RUNS, on every forge since #187; the poller stays github-only, so replicas on the other
+ * three arrive by webhook alone). It composes the three pieces that own the hard parts -- `makeVerifiedHandler` (the
  * HMAC trust boundary), `filter` (the trigger/author gate), and the SHARED `enqueueGitHubJob` -- and adds
  * only the glue: parse the verified body, project the payload subset, route on the filter's verdict, and
  * map the outcome to a status code.
@@ -169,6 +170,36 @@ function pathOf(url) {
 	return raw.length > 1 && raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
 
+/**
+ * REPLICA FANOUT (REQ-REPLICA-RUNS). The one place a single delivery becomes more than one job, shared by
+ * all four forge arms since #187 widened `run.replicas` past github.
+ *
+ * ONE body rather than four, for the reason `enqueueForgeJob` gives for collapsing its own wrappers
+ * (queue.mjs): four copies is four places for one of them to be quietly weakened while every test stays
+ * green. What would be weakened here is the `replicas > 1` conditional, whose whole job is byte-identity
+ * for an unflagged delivery -- spread `replica: i` unconditionally in one arm and that forge's `data`, its
+ * jobId and its dedup id all change for every ordinary job, with no test outside that forge to notice.
+ *
+ * Absent `replicas` is `1` and the call below is byte-identical to the single enqueue it replaced: no
+ * `replica` key on the job, so the jobId, the dedup id and `data` are exactly what they were.
+ *
+ * PARTIAL FAILURE IS IDEMPOTENT BY CONSTRUCTION, which is why there is no compensating logic here: if
+ * replica k throws, the caller's catch answers 503, the forge redelivers, replicas 1..k-1 dedup on their
+ * own now-taken jobIds and k..n enqueue. The retry converges on exactly n jobs rather than n + (k-1).
+ *
+ * `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.
+ */
+async function fanout(job, enqueue) {
+	const replicas = job.replicas ?? 1;
+	for (let i = 1; i <= replicas; i++) {
+		await enqueue(replicas > 1 ? { ...job, replica: i } : job);
+	}
+	return replicas;
+}
+
 /**
  * The GitHub arm. Returns `makeVerifiedHandler`'s handler directly, so it only ever sees an already-verified
  * request. `onVerified` owns parse, filter, enqueue, and response; a good signature is the sole
@@ -189,19 +220,10 @@ function makeGitHubHandler({ queue, selfId, cfg, log }) {
 			return respond(res, 204);
 		}
 
-		// REPLICA FANOUT (REQ-REPLICA-RUNS). The one place a single delivery becomes more than one job, and it
-		// belongs here because this is where the 202/503 decision already lives. Absent `replicas` is `1` and
-		// the call below is byte-identical to the single enqueue it replaced -- no `replica` key on the job,
-		// so the jobId, the dedup id and `data` are all exactly what they were.
-		//
-		// PARTIAL FAILURE IS IDEMPOTENT BY CONSTRUCTION, which is why there is no compensating logic here: if
-		// replica k throws, the catch below answers 503, GitHub redelivers, replicas 1..k-1 dedup on their own
-		// now-taken jobIds and k..n enqueue. The retry converges on exactly n jobs rather than n + (k-1).
-		const replicas = result.job.replicas ?? 1;
+		// Fanout (REQ-REPLICA-RUNS) lives in `fanout` above; the 202/503 decision stays here, where it always was.
+		let replicas;
 		try {
-			for (let i = 1; i <= replicas; i++) {
-				await enqueueGitHubJob(queue, replicas > 1 ? { ...result.job, replica: i } : result.job);
-			}
+			replicas = await fanout(result.job, (j) => enqueueGitHubJob(queue, 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 });
@@ -249,8 +271,9 @@ function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAutho
 			return respond(res, 204);
 		}
 
+		let replicas;
 		try {
-			await enqueueGitLabJob(queue, result.job);
+			replicas = await fanout(result.job, (j) => enqueueGitLabJob(queue, 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
@@ -259,7 +282,7 @@ function makeGitLabHandler({ queue, cfg, log, mode, secret, selfId, resolveAutho
 		// `!` 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 });
+		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" });
 	});
 }
@@ -300,14 +323,15 @@ function makeForgejoHandler({ queue, cfg, log, secret, selfId, resolveAuthority
 			return respond(res, 204);
 		}
 
+		let replicas;
 		try {
-			await enqueueForgeJob(queue, "forgejo", result.job);
+			replicas = await fanout(result.job, (j) => enqueueForgeJob(queue, "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 });
+		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" });
 	});
 }
@@ -357,8 +381,9 @@ function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, r
 			return respond(res, 204);
 		}
 
+		let replicas;
 		try {
-			await enqueueForgeJob(queue, "azure", result.job);
+			replicas = await fanout(result.job, (j) => enqueueForgeJob(queue, "azure", j));
 		} catch (err) {
 			log?.({ event: "enqueue_failed", delivery, reason: err?.message });
 			return respond(res, 503, { error: "enqueue-failed" });
@@ -367,7 +392,7 @@ function makeAzureHandler({ queue, cfg, log, mode, secret, headerName, selfId, r
 		// `!` 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 });
+		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" });
 	});
 }

package/src/start.mjs

@@ -28,6 +28,7 @@ import { watch } from "node:fs";
 import { dirname, basename } from "node:path";
 import { loadReceiverConfig, triggersFilePath, reloadTriggers } from "./config.mjs";
 import { makeReceiver } from "./receiver.mjs";
+import { entryExitCode } from "./cli.mjs";
 import { makeGitHubAuth } from "@edgehero/pi-dispatch/get-token";
 import { resolveGitLabSelfId } from "@edgehero/pi-dispatch/gitlab-identity";
 import { resolveForgejoSelfId } from "@edgehero/pi-dispatch/forgejo-identity";
@@ -192,6 +193,12 @@ function watchTriggers(env, cfg, log) {
 if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("start.mjs")) {
 	startReceiver(process.env).catch((err) => {
 		process.stderr.write(`${JSON.stringify({ event: "receiver_start_failed", reason: err?.message })}\n`);
-		process.exitCode = 1;
+		// entryExitCode, NOT a bare 1. This file is what `receiver.service` execs -- cli.mjs is not on that
+		// path -- so the mapping cli.mjs documents ("a supervisor restarting on exit 2 would loop on a config
+		// that can never parse") only reaches a real deployment from here. A tagged config refusal exits 2
+		// and `RestartPreventExitStatus=2` stops the unit; anything else is infra and stays retryable at 1.
+		// IMPORTED rather than restated: two copies of an exit-code rule is one place for it to drift, and
+		// the copy that drifts is the one nobody is looking at.
+		process.exitCode = entryExitCode(err);
 	});
 }