@edgehero/pi-dispatch-receiver 4.3.0 → 5.0.0

package/README.md

@@ -1,18 +1,20 @@
 # @edgehero/pi-dispatch-receiver
 
 The trigger edge of **[pi-dispatch](https://github.com/edgehero/pi-dispatch)**, which runs the
-[pi](https://github.com/earendil-works/pi) coding agent as a self hosted background service.
+[pi](https://github.com/earendil-works/pi) coding agent for you in the background. Most people want the
+[main README](https://github.com/edgehero/pi-dispatch#readme) first: it explains why and how to use it.
 
 The receiver turns forge activity into queued jobs for the
 [worker](https://www.npmjs.com/package/@edgehero/pi-dispatch). It reads the same `triggers.json` as the
 worker, checks each delivery, and queues at most one job per event (one per replica when a trigger sets
 `run.replicas`). It never runs a job itself.
 
-## Two ways to run it
+## Three ways to run it
 
 ```bash
 npx @edgehero/pi-dispatch-receiver         # serve: the webhook receiver (the default)
 npx @edgehero/pi-dispatch-receiver poll    # poll: no public URL, reads GitHub with your own credential
+npx @edgehero/pi-dispatch-receiver watch   # watch: pulls findings from your own alert sources
 ```
 
 - **`serve`** verifies GitHub, GitLab, Forgejo and Azure DevOps webhooks (at `/`, `/gitlab`, `/forgejo`
@@ -23,6 +25,14 @@ npx @edgehero/pi-dispatch-receiver poll    # poll: no public URL, reads GitHub w
 - **`poll`** fetches GitHub issue events, comments and pull requests about once a minute, over TLS, with
   the same gates and the same queue. A new poller starts from now and never replays old labels.
 
+- **`watch`** pulls findings from the sources in `triggers.json`. `serve` takes them pushed to `/watch/<source>` as well. A finding starts a
+  read only investigation or files an issue, and cannot choose a job's permissions
+  ([watch](https://github.com/edgehero/pi-dispatch/blob/main/docs/watch.md)).
+
+**Steering from a comment.** While a job of a steer armed trigger runs on an issue or pull request, a comment with your comment trigger's
+phrase goes to that running job instead of starting a second one, once the comment trigger has `"steer": true` as well
+([steering](https://github.com/edgehero/pi-dispatch/blob/main/docs/steering.md#steering-from-a-comment)).
+
 The receiver checks each delivery's signature, the bot loop guard, the forge's own permission check and
 dedup. The worker then applies quiet hours, the image preflight, branch protection and the spend caps.
 Who may fire a trigger is decided by your forge. See

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "type": "module",
   "description": "The pi-dispatch trigger edge: verifies GitHub, GitLab, Forgejo and Azure DevOps webhooks, or polls GitHub with no public URL, and queues one pi coding agent job per event (per replica, if set) for the worker.",
   "keywords": [
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "14.2.0",
-    "@edgehero/pi-dispatch": "^4.3.0",
+    "@edgehero/pi-dispatch": "^5.0.0",
     "bullmq": "5.80.4",
     "ioredis": "5.11.1"
   }

package/src/azure-members.mjs

@@ -15,7 +15,9 @@
  * it. `OQ-013` is amended to say so rather than leaving it implied.
  *
  * The verdict shape is every other forge's: `{ authorized }` | `{ indeterminate }`. A determinate "not a
- * member" refuses; anything that could not be answered is a 503 so Azure redelivers.
+ * member" refuses; anything that could not be answered is a 503, which Azure resends up to 8 times over about
+ * 3 minutes, then retries on probation up to 7 more times over about 36 hours while new events are lost
+ * (receiver.mjs, WHAT A 503 MEANS).
  *
  * WHY MEMBERSHIP AND NOT A PERMISSION EVALUATION. Azure's Security namespace API can answer "may this
  * subject contribute to this repository" exactly, which is closer to the property the constitution wants.
@@ -153,8 +155,9 @@ export function makeResolveAzureAuthority({ orgUrl, token, fetchFn = fetch }) {
 	 *     `null`, which the caller refuses. This is the honest refusal: the entire directory was read.
 	 *   - the PAGE CAP was reached while Azure was still offering more -> `{ indeterminate }`, never `null`.
 	 *     The search was abandoned, not completed, and the module's own docblock is explicit that
-	 *     indeterminate and unauthorized must not be conflated: this way the receiver answers 503 and Azure
-	 *     redelivers, instead of burying an exhausted search inside a 204 that reads as a policy decision.
+	 *     indeterminate and unauthorized must not be conflated: this way the receiver answers 503, which Azure
+	 *     resends for about 3 minutes and then, on probation, for about 36 hours, instead of burying an
+	 *     exhausted search inside a 204 that reads as a policy decision.
 	 *
 	 * A FILTERED LOOKUP WOULD BE BETTER AND IS NOT USED. Nothing in the Graph surface this module already
 	 * speaks offers a by-mail filter on `graph/users` (`subjectTypes` selects kinds of subject, not

package/src/boot-retry.mjs

@@ -66,7 +66,7 @@ export const IDENTITY_ATTEMPT_TIMEOUT_MS = 10_000;
  * same-tick; on exhaustion rethrows the LAST untagged error, so the entry still exits 1 and the
  * supervisor restarts into a fresh window.
  *
- * `now` and `sleep` are seams (CLAUDE.md: a window takes an injected clock, always; issue #284);
+ * `now` and `sleep` are seams (AGENTS.md: a window takes an injected clock, always; issue #284);
  * `setTimeoutFn`/`clearTimeoutFn` are the FUSE's own pair, separately injectable so a test can prove
  * the clearing rather than trust it.
  */

package/src/cli.mjs

@@ -19,6 +19,7 @@ import { isEntryModule } from "@edgehero/pi-dispatch/entry";
 const USAGE = `pi-dispatch-receiver — the always-on trigger edge: turns GitHub activity into queued jobs
 
   pi-dispatch-receiver serve   start the webhook receiver (the default when no command is given)
+  pi-dispatch-receiver watch   poll reviewed file, journald and Loki watch sources
   pi-dispatch-receiver poll    start the polling producer — no public URL, no DNS, no tunnel: it
                                reads api.github.com with the operator's own credential instead
 
@@ -38,7 +39,7 @@ serve listens, and POLL_REPOS / POLL_INTERVAL_SECONDS shape what poll watches an
 	// injects a collector instead of reassigning `process.stdout.write`. That matters because `node --test`
 	// runs each file in a child process that serialises its own results over that same stdout, so a test
 	// holding a replacement across an `await` swallows the runner's result frames (issue #266).
-export async function main(argv = process.argv.slice(2), env = process.env, { start, startPoll, write = (chunk) => process.stdout.write(chunk) } = {}) {
+export async function main(argv = process.argv.slice(2), env = process.env, { start, startPoll, startWatch, write = (chunk) => process.stdout.write(chunk) } = {}) {
 	const cmd = argv[0];
 
 	if (cmd === undefined || cmd === "serve") {
@@ -58,6 +59,13 @@ export async function main(argv = process.argv.slice(2), env = process.env, { st
 		return 0;
 	}
 
+	if (cmd === "watch") {
+		const startWatchPuller = startWatch ?? (await import("./watch-puller.mjs")).startWatchPuller;
+		const puller = await startWatchPuller(env);
+		await puller?.done;
+		return 0;
+	}
+
 	write(`${USAGE}\n`);
 	return cmd === "--help" || cmd === "-h" ? 0 : 1; // asked-for help is success; a typo is not
 }

package/src/config.mjs

@@ -31,8 +31,9 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { groupTriggers } from "./trigger-groups.mjs";
 import { configError, loadGitHubAuth, positiveInt } from "@edgehero/pi-dispatch/config";
-import { FORGE_KINDS, PR_CLOSE_ACTIONS, parseTriggers } from "@edgehero/pi-dispatch/triggers";
+import { FORGE_KINDS, parseTriggersDocument } from "@edgehero/pi-dispatch/triggers";
 
 // Cwd-relative, matching what `pi-dispatch init` scaffolds (and the admin's default): the receiver's
 // default must be the file init just told the operator it created, not a demo buried in the repo.
@@ -100,6 +101,19 @@ export function loadReceiverConfig(env = process.env, { readFile = readFileSync,
 	};
 }
 
+/**
+ * The forges this receiver serves, in `FORGE_KINDS` order, for its status record (`INT-RECEIVER-STATUS-KEY`, issue
+ * #824): GitHub by `servesGithub` (`cfg.github` is its auth block, present whether GitHub is served or not), and every
+ * other forge by its own block, which the loader sets to null when nothing names the forge and which `startReceiver`
+ * arms a route for exactly when it is set. A kind with no block at all is a forge added to the table that this loader
+ * does not read yet, so nothing arms a route for it, and it is unserved. Throwing instead would cost the receiver its
+ * whole record, every forge's counts, at boot, for a gap the operator cannot close. The developer who adds the forge
+ * learns it from receiver/test/receiver-status-start.test.mjs, which requires a block for every `FORGE_KINDS` member.
+ */
+export function servedForges(cfg, kinds = FORGE_KINDS) {
+	return kinds.filter((kind) => kind === "github" ? cfg.servesGithub === true : Object.hasOwn(cfg, kind) && Boolean(cfg[kind]));
+}
+
 /**
  * Does this deployment actually SERVE GitHub? Three things hang off the answer -- the WEBHOOK_SECRET
  * requirement above, whether `/` is mounted (receiver.mjs), and whether boot resolves the harness's own
@@ -166,7 +180,10 @@ function loadGitLabConfig(env) {
 	}
 	// The gate needs this token BEFORE any job runs: the actor's access level is what authorises a GitLab
 	// trigger at all (CONST-TRIGGER-AUTHOR-GATE), and without a token every lookup is indeterminate and
-	// every delivery 503s. Refusing at boot is the difference between one clear message and a redelivery loop.
+	// every delivery 503s, which GitLab never resends. After 4 in a row GitLab disables the hook for a while
+	// (on gitlab.com, and a group hook anywhere; a self-managed project hook only where the
+	// `auto_disabling_web_hooks` feature flag is on). Refusing at boot is the difference between one clear
+	// message and every delivery failing, and perhaps the hook switched off.
 	if (typeof token !== "string" || token.trim() === "") {
 		throw configError("GITLAB_TOKEN is required for gitlab triggers -- the receiver resolves the actor's project access level before it may enqueue");
 	}
@@ -184,6 +201,16 @@ function loadGitLabConfig(env) {
  * `FORGEJO_BOT_ID` is optional and exists for one reason: a repository-scoped token cannot call
  * `GET /user` (see worker/src/forgejo-identity.mjs). Without it, following the token-scoping advice would
  * make the receiver unable to identify itself, and identity is not optional here.
+ *
+ * `FORGEJO_PERMISSION_TOKEN` is optional and is the author gate's alone (OQ-043). Forgejo answers a lookup of
+ * ANOTHER user's repository permission only to a site admin or a repository admin, so whichever token asks must
+ * belong to one. FORGEJO_TOKEN is also every forgejo job's token, so making ITS account an admin hands each job
+ * a token that can lift branch protection. This variable lets a DIFFERENT account, an admin of the repositories,
+ * answer that one GET with a `read:repository` token, while the job's account stays a `write` collaborator.
+ * Read here and nowhere else: it never reaches the worker's job env, and the worker refuses it in PI_FORWARD_ENV
+ * and run.secrets (WORKER_ONLY_SECRET_VARS). Unset (or blank), the lookup falls back to FORGEJO_TOKEN, which is
+ * the behaviour before it existed and works only if that account is an admin; `lookupTokenVar` names which one
+ * is in use, so the boot line and a 403's reason can say so.
  */
 function loadForgejoConfig(env) {
 	const secret = env.FORGEJO_WEBHOOK_SECRET;
@@ -202,11 +229,20 @@ function loadForgejoConfig(env) {
 	}
 	// Needed BEFORE any job runs: the actor's repository permission is what authorises a forgejo trigger at
 	// all (CONST-TRIGGER-AUTHOR-GATE), and without a token every lookup is indeterminate and every delivery
-	// 503s. Refusing at boot is the difference between one clear message and a redelivery loop.
+	// 503s, which Forgejo never resends. Refusing at boot is the difference between one clear message and
+	// every delivery failing in a history nobody is watching.
 	if (typeof token !== "string" || token.trim() === "") {
 		throw configError("FORGEJO_TOKEN is required for forgejo triggers -- the receiver resolves the actor's repository permission before it may enqueue");
 	}
-	return { secret, token, apiUrl: apiUrl.trim(), botId };
+	const permissionToken = typeof env.FORGEJO_PERMISSION_TOKEN === "string" ? env.FORGEJO_PERMISSION_TOKEN.trim() : "";
+	return {
+		secret,
+		token,
+		apiUrl: apiUrl.trim(),
+		botId,
+		lookupToken: permissionToken !== "" ? permissionToken : token,
+		lookupTokenVar: permissionToken !== "" ? "FORGEJO_PERMISSION_TOKEN" : "FORGEJO_TOKEN",
+	};
 }
 
 /**
@@ -293,61 +329,13 @@ function loadTriggers(env, readFile, fileExists) {
 		throw configError(`triggers file not found: ${path} -- run \`pi-dispatch init\` in this folder to scaffold one, or set PI_TRIGGERS_FILE to yours`);
 	}
 
-	const parsed = parseTriggers(readFile(path, "utf8"), path); // fail-loud
+	const document = parseTriggersDocument(readFile(path, "utf8"), path);
+	const parsed = document.triggers;
+	const watchSources = document.watchSources ?? {};
+	for (const source of Object.values(watchSources)) if (typeof env[source.secretEnv] !== "string" || !env[source.secretEnv].trim()) throw configError("watch: a configured source secret is missing");
 	void 0;
 
-	// Every forge gets a group whether or not the file names it, so the filter can read
-	// `cfg.triggers[kind].label` without a presence check and an unconfigured forge simply matches nothing.
-	//
-	// 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 `reloadTriggers`
-	// below 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") continue; // the worker owns cron; the receiver never fires it -- but it keeps its index
-		// 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, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, 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, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, 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, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, 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, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, 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, mcp: run.mcp, provider: run.provider, model: run.model, maxTurns: run.maxTurns, models: run.models, maxCostUsd: run.maxCostUsd, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, awaitInput: run.awaitInput, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
-		}
-	}
-
-	return { ...groups, knownFlows };
-}
-
-function emptyGroup() {
-	return { label: [], comment: null, pullRequest: [], issue: [], prClose: [] };
+	return groupTriggers(parsed, { watchSources });
 }
 
 /** The triggers file path the receiver reads (env override or the cwd default matching what `pi-dispatch init` scaffolds). */

package/src/filter-azure.mjs

@@ -25,7 +25,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
+import { escapeRegExp, firstMatchingRule, heldCandidateOr, labelSet, matchedLabel, matchesRule, steerModeOf } from "./predicate.mjs";
 import { PR_COMMENT_EVENT, PR_EVENTS, WORK_ITEM_EVENTS } from "./azure-subset.mjs";
 import { hasParkedLabel } from "@edgehero/pi-dispatch/parked";
 
@@ -80,95 +80,120 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		return { enqueue: false, reason: "unhandled-event" };
 	}
 
-	if (!resolved.enqueue) return resolved; // carries the drop reason
+	// A drop is returned as it is, except a phrase-free reply that failed ONLY for the missing parked marker (issue #638,
+	// DES-AWAIT-INPUT-ENDS-THE-JOB): that one also carries `heldCandidate`, the job the parked-reply route would have
+	// built, through the SAME `build` below, so the receiver can hold it for a run that is parking right now and the job
+	// that run starts is byte for byte the one the marker would have produced. Still a drop: nothing here enqueues it.
+	if (!resolved.enqueue) return heldCandidateOr(resolved, build);
+	return build(resolved);
 
-	// WHICH REPOSITORY the job clones. A pull-request event names its own and that is authoritative. A WORK
-	// ITEM names none -- Azure work items belong to a project, and a project may hold many repositories --
-	// so the matched rule's `run.repository` supplies it. The loader requires that field on exactly the
-	// azure trigger types a work item can fire, so reaching here without one is not possible; the guard is
-	// here anyway because "not possible" and "cannot happen" are different claims and only one is testable.
-	const scope = resolveScope(subset, resolved);
-	if (scope === null) {
-		return { enqueue: false, reason: "no-repository" };
-	}
-	resolved.repo = scope.repo;
-	resolved.azure = scope.azure;
+	// The job from a resolved route. One function for every route and for the held candidate (issue #638), declared
+	// here so it closes over this delivery's subset and ids.
+	function build(resolved) {
+		// WHICH REPOSITORY the job clones. A pull-request event names its own and that is authoritative. A WORK
+		// ITEM names none -- Azure work items belong to a project, and a project may hold many repositories --
+		// so the matched rule's `run.repository` supplies it. The loader requires that field on exactly the
+		// azure trigger types a work item can fire, so reaching here without one is not possible; the guard is
+		// here anyway because "not possible" and "cannot happen" are different claims and only one is testable.
+		const scope = resolveScope(subset, resolved);
+		if (scope === null) {
+			return { enqueue: false, reason: "no-repository" };
+		}
+		resolved.repo = scope.repo;
+		resolved.azure = scope.azure;
 
-	const job = {
-		// `<project>/<repository>`, WITHOUT the organization -- exactly as a gitlab job's `repo` omits the
-		// instance. A deployment has one AZURE_ORG_URL, so the org is constant across every azure job here
-		// and repeating it in a pause-window scope and a run-record label would be noise, not information.
-		repo: resolved.repo,
-		// The structured triple the API paths need, alongside the human-readable label -- the same split
-		// gitlab makes when it carries `projectId` next to `repo`.
-		azure: resolved.azure,
-		target: resolved.target,
-		// 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 } : {}),
-		// #227. A SEPARATE spread, and this is the whole of the bug it replaces: folded into the `image`
-		// conditional above, a trigger that named a venue but no image had its venue silently dropped here --
-		// it loaded, validated, reached this function on the rule, and then ran on the default. That is
-		// exactly the destructive absence `validateBackend`'s near-miss sweep refuses a misspelling for,
-		// arriving through the plumbing instead of the spelling, one file downstream of the guard.
-		...(resolved.backend !== undefined ? { backend: resolved.backend } : {}),
-		// #291. A separate spread, filter.mjs's backend rule: a dropped exclusion runs the job WITH the tool.
-		...(resolved.excludeTools !== undefined ? { excludeTools: resolved.excludeTools } : {}),
-		// REQ-MCP-OPERATOR-SERVERS. Its own spread, the excludeTools rule above: a dropped list runs
-		// the job without its servers.
-		...(resolved.mcp !== undefined ? { mcp: resolved.mcp } : {}),
-		// #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
-		// basename(folder) restraint already exists to prevent.
-		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
-		// REQ-TRIGGER-SECRETS. Conditional exactly like skillsDir above, so a trigger that binds no
-		// secret enqueues the job data it always has. The map holds REFERENCES, never values: the
-		// receiver has no resolver and reaches no vault -- the worker resolves them pre-spend.
-		...(resolved.secrets !== undefined ? { secrets: resolved.secrets } : {}),
-		...(resolved.secretsProfile !== undefined ? { secretsProfile: resolved.secretsProfile } : {}),
-		...(resolved.waitFor !== undefined ? { waitFor: resolved.waitFor } : {}),
-		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
-		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
-		// REQ-AWAIT-INPUT (issue #625): whether the job may end awaiting a person's answer. Present only when armed,
-		// resume's rule, so an unflagged job's data stays byte-identical.
-		...(resolved.awaitInput === true ? { awaitInput: true } : {}),
-		// A phrase-free reply to a parked issue (issue #625): the worker gates it on the `parked` sidecar before any spend.
-		...(resolved.parkedReply === true ? { parkedReply: true } : {}),
-		// 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,
-			deliveryId,
-			// A GUID when the delivery carried one, else a HASH of the address -- never the address itself.
-			// A work-item payload offers nothing but `"Display Name <email>"`, and this object is copied
-			// verbatim into /job/event.json and summarised into the durable run record, both of which are
-			// PII-free BY CONSTRUCTION. Hashing keeps "the same actor twice" answerable without putting
-			// somebody's email in a file the agent reads and an operator greps -- the same move
-			// `session-key.mjs` makes for branch names.
-			sender: { id: hasId ? actor.id : stableActorId(actor.email) },
-			matched: resolved.matched,
-			...(resolved.comment ? { comment: resolved.comment } : {}),
-		},
-	};
-	return { enqueue: true, job };
+		const job = {
+			// `<project>/<repository>`, WITHOUT the organization -- exactly as a gitlab job's `repo` omits the
+			// instance. A deployment has one AZURE_ORG_URL, so the org is constant across every azure job here
+			// and repeating it in a pause-window scope and a run-record label would be noise, not information.
+			repo: resolved.repo,
+			// The structured triple the API paths need, alongside the human-readable label -- the same split
+			// gitlab makes when it carries `projectId` next to `repo`.
+			azure: resolved.azure,
+			target: resolved.target,
+			// 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 } : {}),
+			// #227. A SEPARATE spread, and this is the whole of the bug it replaces: folded into the `image`
+			// conditional above, a trigger that named a venue but no image had its venue silently dropped here --
+			// it loaded, validated, reached this function on the rule, and then ran on the default. That is
+			// exactly the destructive absence `validateBackend`'s near-miss sweep refuses a misspelling for,
+			// arriving through the plumbing instead of the spelling, one file downstream of the guard.
+			...(resolved.backend !== undefined ? { backend: resolved.backend } : {}),
+			// #291. A separate spread, filter.mjs's backend rule: a dropped exclusion runs the job WITH the tool.
+			...(resolved.excludeTools !== undefined ? { excludeTools: resolved.excludeTools } : {}),
+			// Issue #800, each its own spread by the same rule: a dropped list runs the job with what the file takes away.
+			...(resolved.excludeExtensions !== undefined ? { excludeExtensions: resolved.excludeExtensions } : {}),
+			...(resolved.excludeExtensionTools !== undefined ? { excludeExtensionTools: resolved.excludeExtensionTools } : {}),
+			// REQ-MCP-OPERATOR-SERVERS. Its own spread, the excludeTools rule above: a dropped list runs
+			// the job without its servers.
+			...(resolved.mcp !== undefined ? { mcp: resolved.mcp } : {}),
+			// #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 } : {}), ...(resolved.fallbackModels !== undefined ? { fallbackModels: resolved.fallbackModels } : {}),
+			// #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
+			// basename(folder) restraint already exists to prevent.
+			...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+			// REQ-TRIGGER-SECRETS. Conditional exactly like skillsDir above, so a trigger that binds no
+			// secret enqueues the job data it always has. The map holds REFERENCES, never values: the
+			// receiver has no resolver and reaches no vault -- the worker resolves them pre-spend.
+			...(resolved.secrets !== undefined ? { secrets: resolved.secrets } : {}),
+			...(resolved.secretsProfile !== undefined ? { secretsProfile: resolved.secretsProfile } : {}),
+			...(resolved.waitFor !== undefined ? { waitFor: resolved.waitFor } : {}),
+			...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
+			...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+			// REQ-AWAIT-INPUT (issue #625): whether the job may end awaiting a person's answer. Present only when armed,
+			// resume's rule, so an unflagged job's data stays byte-identical.
+			...(resolved.awaitInput === true ? { awaitInput: true } : {}),
+			...(resolved.gates !== undefined ? { gates: resolved.gates, ...(resolved.gateTimeout !== undefined ? { gateTimeout: resolved.gateTimeout } : {}), ...(resolved.gateBudgetRaiseUsd !== undefined ? { gateBudgetRaiseUsd: resolved.gateBudgetRaiseUsd } : {}) } : {}),
+			// Issue #644: the progress tool and the forge status comment, each present only when armed, awaitInput's rule.
+			...(resolved.progress === true ? { progress: true } : {}),
+			...(resolved.statusComment === true ? { statusComment: true } : {}),
+			// Issue #645: durable runs, present only when armed, the same rule.
+			...(resolved.recover === true ? { recover: true } : {}),
+			// Issue #646: steering a running job, present only when armed, the same rule.
+			...(resolved.steer === true ? { steer: true } : {}),
+			// Issue #646: how this phrase comment steers a job of its trigger that is already running, set only on the comment
+			// route of a steer-armed trigger (never a parked reply, never a command). The receiver reads it to try the run's
+			// inbox before it enqueues, and `enqueueForgeJob` names its fields, so it never reaches a queue. At JOB level, never
+			// inside `trigger`, which is copied verbatim into /job/event.json.
+			...(resolved.steerMode !== undefined ? { steerMode: resolved.steerMode } : {}),
+			// A phrase-free reply to a parked issue (issue #625): the worker gates it on the `parked` sidecar before any spend.
+			...(resolved.parkedReply === true ? { parkedReply: true } : {}),
+			// 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,
+				deliveryId,
+				// A GUID when the delivery carried one, else a HASH of the address -- never the address itself.
+				// A work-item payload offers nothing but `"Display Name <email>"`, and this object is copied
+				// verbatim into /job/event.json and summarised into the durable run record, both of which are
+				// PII-free BY CONSTRUCTION. Hashing keeps "the same actor twice" answerable without putting
+				// somebody's email in a file the agent reads and an operator greps -- the same move
+				// `session-key.mjs` makes for branch names.
+				sender: { id: hasId ? actor.id : stableActorId(actor.email) },
+				matched: resolved.matched,
+				...(resolved.comment ? { comment: resolved.comment } : {}),
+			},
+		};
+		return { enqueue: true, job };
+	}
 }
 
 /**
@@ -212,15 +237,19 @@ function matchLabelRules(subset, triggers, labels, action) {
 		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 		repository: rule.repository,
 		packages: rule.packages,
-		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools, mcp: rule.mcp,
-		provider: rule.provider, model: rule.model, maxTurns: rule.maxTurns, models: rule.models, maxCostUsd: rule.maxCostUsd,
+		image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools, excludeExtensions: rule.excludeExtensions, excludeExtensionTools: rule.excludeExtensionTools, mcp: rule.mcp,
+		provider: rule.provider, model: rule.model, maxTurns: rule.maxTurns, models: rule.models, fallbackModels: rule.fallbackModels, maxCostUsd: rule.maxCostUsd,
 		skillsDir: rule.skillsDir,
 		secrets: rule.secrets,
 		secretsProfile: rule.secretsProfile,
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
-		awaitInput: rule.awaitInput,
+		awaitInput: rule.awaitInput, gates: rule.gates, gateTimeout: rule.gateTimeout, gateBudgetRaiseUsd: rule.gateBudgetRaiseUsd,
+		progress: rule.progress,
+		statusComment: rule.statusComment,
+		recover: rule.recover,
+		steer: rule.steer,
 		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 },
@@ -228,7 +257,7 @@ function matchLabelRules(subset, triggers, labels, action) {
 }
 
 /** Comment path, on either a work item or a pull request. The authority gate above has already run. */
-function routeComment(subset, triggers, knownFlows, targetType) {
+function routeComment(subset, triggers, knownFlows, targetType, assumeParked = false) {
 	const phrase = triggers.comment?.phrase;
 	const body = subset.comment;
 	const phraseHit = typeof phrase === "string" && typeof body === "string" && body.includes(phrase);
@@ -237,8 +266,17 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 	// trigger arms run.resume and is not a command, and only when the forge says the issue carries the marker. The
 	// author gate above already ran: this widens WHICH comments start a job, never WHO may. The marker is a hint; the
 	// worker refuses the job before any spend unless the key's `parked` sidecar exists.
-	const parkedReply = !phraseHit && typeof phrase === "string" && typeof body === "string" && triggers.comment?.resume === true && triggers.comment?.command === undefined && targetType === "issue" && hasParkedLabel(subset.tags);
+	const parkedCandidate = !phraseHit && typeof phrase === "string" && typeof body === "string" && triggers.comment?.resume === true && triggers.comment?.command === undefined && targetType === "issue";
+	const parkedReply = parkedCandidate && (assumeParked || hasParkedLabel(subset.tags));
 	if (!phraseHit && !parkedReply) {
+		// Issue #638: a reply that fails ONLY for the missing marker (the run asked its question and is still parking, so
+		// the label is not on yet) is still a drop, but it carries the route the marker would have taken, built by this
+		// same function with the marker assumed (so every other rule above still decided it). The receiver holds it for a
+		// run that is parking on this target, or drops it exactly as today.
+		if (parkedCandidate) {
+			const held = routeComment(subset, triggers, knownFlows, targetType, true);
+			if (held.enqueue) return { enqueue: false, reason: "no-trigger-phrase", heldResolved: held };
+		}
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
 	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
@@ -265,18 +303,27 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 		...(command !== undefined ? { command } : { flow }),
 		repository: triggers.comment.repository,
 		packages: triggers.comment.packages,
-		image: triggers.comment.image, backend: triggers.comment.backend, excludeTools: triggers.comment.excludeTools, mcp: triggers.comment.mcp,
-		provider: triggers.comment.provider, model: triggers.comment.model, maxTurns: triggers.comment.maxTurns, models: triggers.comment.models, maxCostUsd: triggers.comment.maxCostUsd,
+		image: triggers.comment.image, backend: triggers.comment.backend, excludeTools: triggers.comment.excludeTools, excludeExtensions: triggers.comment.excludeExtensions, excludeExtensionTools: triggers.comment.excludeExtensionTools, mcp: triggers.comment.mcp,
+		provider: triggers.comment.provider, model: triggers.comment.model, maxTurns: triggers.comment.maxTurns, models: triggers.comment.models, fallbackModels: triggers.comment.fallbackModels, maxCostUsd: triggers.comment.maxCostUsd,
 		skillsDir: triggers.comment.skillsDir,
 		secrets: triggers.comment.secrets,
 		secretsProfile: triggers.comment.secretsProfile,
 		waitFor: triggers.comment.waitFor,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
-		awaitInput: triggers.comment.awaitInput,
+		awaitInput: triggers.comment.awaitInput, gates: triggers.comment.gates, gateTimeout: triggers.comment.gateTimeout, gateBudgetRaiseUsd: triggers.comment.gateBudgetRaiseUsd,
+		progress: triggers.comment.progress,
+		statusComment: triggers.comment.statusComment,
+		recover: triggers.comment.recover,
+		steer: triggers.comment.steer,
 		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		...(parkedReply && { parkedReply: true }),
+		// Issue #646: a phrase comment on a steer-armed trigger may steer a run of it that is already going. Only with the
+		// phrase (a parked reply is an answer to a parked run, never a steer) and never on a command rule (the loader refuses
+		// `steer` beside `command`; checked again here so a drifted file cannot reach a run). The author gate above already
+		// ran: this changes where an admitted comment goes, never who may send one. The `later` grammar is `steerModeOf`'s.
+		...(phraseHit && command === undefined && triggers.comment.steer === true && { steerMode: steerModeOf(body, phrase) }),
 		// No author_association: Azure has none, and the authority that admitted this comment was resolved
 		// from the graph, not read off the body.
 		comment: { body },
@@ -301,15 +348,19 @@ function routePullRequest(subset, triggers, action) {
 			...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
 			repository: rule.repository,
 			packages: rule.packages,
-			image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools, mcp: rule.mcp,
-			provider: rule.provider, model: rule.model, maxTurns: rule.maxTurns, models: rule.models, maxCostUsd: rule.maxCostUsd,
+			image: rule.image, backend: rule.backend, excludeTools: rule.excludeTools, excludeExtensions: rule.excludeExtensions, excludeExtensionTools: rule.excludeExtensionTools, mcp: rule.mcp,
+			provider: rule.provider, model: rule.model, maxTurns: rule.maxTurns, models: rule.models, fallbackModels: rule.fallbackModels, maxCostUsd: rule.maxCostUsd,
 			skillsDir: rule.skillsDir,
 			secrets: rule.secrets,
 			secretsProfile: rule.secretsProfile,
 			waitFor: rule.waitFor,
 			instructions: rule.instructions,
 			resume: rule.resume,
-			awaitInput: rule.awaitInput,
+			awaitInput: rule.awaitInput, gates: rule.gates, gateTimeout: rule.gateTimeout, gateBudgetRaiseUsd: rule.gateBudgetRaiseUsd,
+			progress: rule.progress,
+			statusComment: rule.statusComment,
+			recover: rule.recover,
+			steer: rule.steer,
 			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {