@edgehero/pi-dispatch-receiver 4.2.0 → 4.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "4.2.0",
+  "version": "4.3.1",
   "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.2.0",
+    "@edgehero/pi-dispatch": "^4.3.1",
     "bullmq": "5.80.4",
     "ioredis": "5.11.1"
   }

package/src/config.mjs

@@ -184,6 +184,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;
@@ -206,7 +216,15 @@ function loadForgejoConfig(env) {
 	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",
+	};
 }
 
 /**
@@ -318,9 +336,9 @@ function loadTriggers(env, readFile, fileExists) {
 		}
 		const group = groups[run.kind];
 		if (on.type === "label") {
-			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, command: run.command, packages: run.packages, image: run.image, 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, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas, repository: run.repository });
+			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, 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, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
+			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, 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
@@ -329,17 +347,17 @@ function loadTriggers(env, readFile, fileExists) {
 			// split reads the SHARED close-word table, never a re-typed word.
 			const closeWord = PR_CLOSE_ACTIONS[run.kind];
 			if (closeWord !== undefined && on.action.includes(closeWord)) {
-				group.prClose.push({ index, actions: new Set(on.action), number: on.number, once: on.once, flow: run.flow, command: run.command, packages: run.packages, image: run.image, 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, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
+				group.prClose.push({ index, actions: new Set(on.action), number: on.number, once: on.once, flow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, 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, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
+				group.pullRequest.push({ index, actions: new Set(on.action), reviewStates: on.reviewState ? new Set(on.reviewState) : null, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, 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, secrets: run.secrets, secretsProfile: run.secretsProfile, waitFor: run.waitFor, replicas: run.replicas });
+			group.issue.push({ index, actions: new Set(on.action), number: on.number, once: on.once, flow: run.flow, command: run.command, packages: run.packages, image: run.image, backend: run.backend, excludeTools: run.excludeTools, 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 });
 		}
 	}
 

package/src/filter-azure.mjs

@@ -27,6 +27,7 @@
 import { createHash } from "node:crypto";
 import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
 import { PR_COMMENT_EVENT, PR_EVENTS, WORK_ITEM_EVENTS } from "./azure-subset.mjs";
+import { hasParkedLabel } from "@edgehero/pi-dispatch/parked";
 
 /** The `pull_request` actions a trigger may name, mirrored from the loader's azure vocabulary. */
 export const PR_ACTION_FOR = {
@@ -143,6 +144,11 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		...(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.
@@ -214,6 +220,7 @@ function matchLabelRules(subset, triggers, labels, action) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		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 },
@@ -224,7 +231,14 @@ function matchLabelRules(subset, triggers, labels, action) {
 function routeComment(subset, triggers, knownFlows, targetType) {
 	const phrase = triggers.comment?.phrase;
 	const body = subset.comment;
-	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
+	const phraseHit = typeof phrase === "string" && typeof body === "string" && body.includes(phrase);
+	// A reply WITHOUT the phrase resumes a parked issue (issue #625, parked.mjs): only on an issue (a pull request's key
+	// needs its head branch, which costs a token to read, so its reply keeps the phrase), only when the comment
+	// 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);
+	if (!phraseHit && !parkedReply) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
 	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
@@ -259,8 +273,10 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 		waitFor: triggers.comment.waitFor,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		awaitInput: triggers.comment.awaitInput,
 		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
+		...(parkedReply && { parkedReply: true }),
 		// 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 },
@@ -293,6 +309,7 @@ function routePullRequest(subset, triggers, action) {
 			waitFor: rule.waitFor,
 			instructions: rule.instructions,
 			resume: rule.resume,
+			awaitInput: rule.awaitInput,
 			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {

package/src/filter-forgejo.mjs

@@ -36,6 +36,7 @@
 import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
 import { findCloseRule } from "./close.mjs";
 import { isRecognizedAction, mapAction } from "./forgejo-subset.mjs";
+import { hasParkedLabel } from "@edgehero/pi-dispatch/parked";
 
 const LABEL_ACTIONS = new Set(["opened", "labeled", "reopened"]);
 export const PR_ACTIONS = new Set(["labeled", "opened", "synchronize", "reopened"]);
@@ -157,6 +158,11 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 		...(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.
@@ -194,6 +200,7 @@ function routeIssueLabel(subset, triggers) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		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 },
@@ -204,7 +211,14 @@ function routeIssueLabel(subset, triggers) {
 function routeComment(subset, triggers, knownFlows) {
 	const phrase = triggers.comment?.phrase;
 	const body = subset.comment?.body;
-	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
+	const phraseHit = typeof phrase === "string" && typeof body === "string" && body.includes(phrase);
+	// A reply WITHOUT the phrase resumes a parked issue (issue #625, parked.mjs): only on an issue (a pull request's key
+	// needs its head branch, which costs a token to read, so its reply keeps the phrase), only when the comment
+	// 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 && subset.isPull !== true && hasParkedLabel(subset.issue?.labels);
+	if (!phraseHit && !parkedReply) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
 	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
@@ -244,8 +258,10 @@ function routeComment(subset, triggers, knownFlows) {
 		waitFor: triggers.comment.waitFor,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		awaitInput: triggers.comment.awaitInput,
 		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
+		...(parkedReply && { parkedReply: true }),
 		// 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.
 		comment: { body: subset.comment.body },
@@ -276,6 +292,7 @@ function routePullRequest(subset, triggers, action) {
 			waitFor: rule.waitFor,
 			instructions: rule.instructions,
 			resume: rule.resume,
+			awaitInput: rule.awaitInput,
 			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {
@@ -332,6 +349,7 @@ function routeIssueClose(subset, triggers, authorized) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		replicas: rule.replicas,
 		// `once: true` rides `matched` ONLY when armed (spreading false is a no-op), so the enqueue path
 		// can see a disarm is owed without re-reading the rule table -- and a plain close rule's matched
@@ -369,6 +387,7 @@ function routePullRequestClose(subset, triggers, authorized) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		replicas: rule.replicas,
 		// No `number` on a PR close's matched record -- parallel to routePullRequest's, where the item
 		// number is the target's business; the issue route carries it because the github design does.

package/src/filter-gitlab.mjs

@@ -42,6 +42,7 @@
 
 import { firstMatchingRule, labelSet, matchedLabel } from "./predicate.mjs";
 import { findCloseRule } from "./close.mjs";
+import { hasParkedLabel } from "@edgehero/pi-dispatch/parked";
 
 /**
 /** The merge-request actions a trigger may name, mirrored from the loader's gitlab vocabulary. */
@@ -162,6 +163,11 @@ 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 } : {}),
+		// 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.
@@ -204,6 +210,7 @@ function routeLabel(subset, triggers, targetType) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(added, rule.predicate) },
 		target: buildTarget(subset, targetType),
@@ -269,6 +276,7 @@ function mrResult(subset, rule, matched) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		replicas: rule.replicas,
 		matched,
 		target: buildTarget(subset, "pull_request"),
@@ -316,6 +324,7 @@ function routeIssueClose(subset, triggers, authorized) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		replicas: rule.replicas,
 		// `once: true` rides `matched` ONLY when armed (spreading false is a no-op), so the enqueue path
 		// can see a disarm is owed without re-reading the rule table -- and a plain close rule's matched
@@ -351,6 +360,7 @@ function routeMergeRequestClose(subset, triggers, authorized) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		replicas: rule.replicas,
 		// No `number` on an MR close's matched record -- parallel to routeMergeRequest's, where the item
 		// number is the target's business; the issue route carries it because the github design does.
@@ -370,7 +380,14 @@ function routeNote(subset, triggers, knownFlows) {
 
 	const phrase = triggers?.comment?.phrase;
 	const body = subset.note;
-	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
+	const phraseHit = typeof phrase === "string" && typeof body === "string" && body.includes(phrase);
+	// A reply WITHOUT the phrase resumes a parked issue (issue #625, parked.mjs): only on an issue (a pull request's key
+	// needs its head branch, which costs a token to read, so its reply keeps the phrase), only when the comment
+	// 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 && subset.noteableType !== "MergeRequest" && hasParkedLabel(subset.target?.labels);
+	if (!phraseHit && !parkedReply) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
 	// On a COMMAND rule (issue #189) the flow-resolution block below -- default flow, the `<phrase> <flow>`
@@ -404,8 +421,10 @@ function routeNote(subset, triggers, knownFlows) {
 		waitFor: triggers.comment.waitFor,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		awaitInput: triggers.comment.awaitInput,
 		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
+		...(parkedReply && { parkedReply: true }),
 		target: buildTarget(subset, targetType),
 		// The invoking comment rides the job as DATA (CONST-ISSUE-TEXT-IS-DATA). No author_association
 		// counterpart exists on GitLab: the approval is the resolved access level, which is a harness

package/src/filter.mjs

@@ -47,6 +47,7 @@
  */
 import { findCloseRule } from "./close.mjs";
 import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
+import { hasParkedLabel } from "@edgehero/pi-dispatch/parked";
 
 const AUTHOR_ALLOWLIST = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 const LABEL_ACTIONS = new Set(["opened", "labeled", "reopened"]);
@@ -185,6 +186,11 @@ export function filter(eventName, subset, cfg, selfId, deliveryId, closerAuthori
 		// 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 } : {}),
+		// 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 like the rest, never
 		// inside `trigger`, and for the sharpest version of that reason: this is the caller's fanout count --
 		// receiver.mjs reads it to decide how many times to enqueue -- and a descriptive context object copied
@@ -232,6 +238,7 @@ function routeIssueLabel(subset, triggers) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		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 },
@@ -250,7 +257,14 @@ function routeComment(subset, triggers, knownFlows) {
 	}
 	const phrase = triggers.comment?.phrase;
 	const body = subset.comment?.body;
-	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
+	const phraseHit = typeof phrase === "string" && typeof body === "string" && body.includes(phrase);
+	// A reply WITHOUT the phrase resumes a parked issue (issue #625, parked.mjs): only on an issue (a pull request's key
+	// needs its head branch, which costs a token to read, so its reply keeps the phrase), only when the comment
+	// 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 && subset.issue?.pull_request !== true && hasParkedLabel(subset.issue?.labels);
+	if (!phraseHit && !parkedReply) {
 		return { enqueue: false, reason: "no-trigger-phrase" };
 	}
 	// On a COMMAND rule (issue #189) the whole flow-resolution block below -- default flow, the `<phrase>
@@ -293,8 +307,10 @@ function routeComment(subset, triggers, knownFlows) {
 		waitFor: triggers.comment.waitFor,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
+		awaitInput: triggers.comment.awaitInput,
 		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
+		...(parkedReply && { parkedReply: true }),
 		// The invoking comment rides on the trigger: body and author_association are both named by
 		// INT-WEBHOOK-PAYLOAD-SUBSET, and the body stays DATA all the way down (CONST-ISSUE-TEXT-IS-DATA).
 		comment: { body: subset.comment.body, author_association: subset.comment.author_association },
@@ -392,6 +408,7 @@ function routePullRequest(subset, triggers, action) {
 			waitFor: rule.waitFor,
 			instructions: rule.instructions,
 			resume: rule.resume,
+			awaitInput: rule.awaitInput,
 			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },
 			...(isReview ? { review: { id: review.id, body: review.body, state: review.state, author_association: review.author_association } } : {}),
@@ -509,6 +526,7 @@ function routeClose(rules, number, closerAuthorized, matchedFor, targetFor) {
 		waitFor: rule.waitFor,
 		instructions: rule.instructions,
 		resume: rule.resume,
+		awaitInput: rule.awaitInput,
 		replicas: rule.replicas,
 		matched: matchedFor(rule),
 		target: targetFor(),

package/src/forgejo-members.mjs

@@ -4,9 +4,12 @@
  *
  * Forgejo has no `author_association`; the concept is GitHub's. What it has instead is
  * `GET /repos/{owner}/{repo}/collaborators/{collaborator}/permission`, which answers
- * `{ permission: "admin"|"write"|"read"|"none" }`. `admin` and `write` are the honest analogue of
- * `OWNER|MEMBER|COLLABORATOR`: they are exactly the levels that can push a branch, which is the property
- * the constitution actually requires.
+ * `{ permission: "owner"|"admin"|"write"|"read"|"none" }`. `owner`, `admin` and `write` are the honest
+ * analogue of `OWNER|MEMBER|COLLABORATOR`: they are exactly the levels that can push a branch, which is the
+ * property the constitution actually requires. `owner` is not hypothetical and not rare: measured on
+ * Forgejo 14.0.5, the owner of a personal repository asking about themselves gets
+ * `{"permission":"owner","role_name":"owner",...}`, and a set without it dropped every trigger they set
+ * as `author-not-allowed`.
  *
  * The shape of this module is the GitLab resolver's, for the same three reasons, and they are worth
  * restating rather than cross-referencing:
@@ -31,18 +34,31 @@ const API_PREFIX = "/api/v1";
 /**
  * The permission levels that can push to the repository. `read` and `none` cannot, so a job started on
  * their say-so would be doing work the actor could not do themselves -- the line CONST-TRIGGER-AUTHOR-GATE
- * draws.
+ * draws. These are the strings of Forgejo's access modes (none, read, write, admin, owner); `owner` is what
+ * a personal repository's owner is answered with (measured, see the header).
  */
-const WRITE_PERMISSIONS = new Set(["admin", "write"]);
+const WRITE_PERMISSIONS = new Set(["owner", "admin", "write"]);
 
 /**
- * Build the resolver. `token` is the same operator-supplied access token the worker uses; `fetchFn` is
- * injected so the whole module is testable offline.
+ * What a 403 tells the operator to fix, by which variable's token asked. Fixed strings, never the body.
+ * With the dedicated lookup token, its account is the one that must be an admin. With the fallback, the right repair
+ * is NOT to make the job's account an admin (that hands every job a token able to lift branch protection, OQ-043) but
+ * to give the lookup its own token.
+ */
+const FORBIDDEN_REASON = Object.freeze({
+	FORGEJO_PERMISSION_TOKEN: "collaborator permission lookup returned 403 (the account behind FORGEJO_PERMISSION_TOKEN must be an admin or the owner of the repository, and the token must carry read:repository)",
+	FORGEJO_TOKEN: "collaborator permission lookup returned 403 (FORGEJO_TOKEN's account is not an admin of the repository: set FORGEJO_PERMISSION_TOKEN to a read:repository token of an account that is, docs/forgejo.md)",
+});
+
+/**
+ * Build the resolver. `token` is the lookup token (FORGEJO_PERMISSION_TOKEN, or FORGEJO_TOKEN as the fallback) and
+ * `tokenVar` names which, for a 403's reason; `fetchFn` is injected so the whole module is testable offline.
  *
  * Returns `resolveAuthority(repoFullName, login)` -> `{ authorized: boolean }` | `{ indeterminate: string }`
  * -- the same shape every forge's resolver returns.
  */
-export function makeResolveForgejoAuthority({ apiUrl, token, fetchFn = fetch }) {
+export function makeResolveForgejoAuthority({ apiUrl, token, tokenVar = "FORGEJO_TOKEN", fetchFn = fetch }) {
+	const forbidden = FORBIDDEN_REASON[tokenVar] ?? FORBIDDEN_REASON.FORGEJO_TOKEN;
 	return async function resolveAuthority(repoFullName, login) {
 		// Both halves have to be present AND well-formed before they become path segments. A slash or a `..`
 		// in either would reach a different endpoint than the one this function believes it is asking, and
@@ -68,6 +84,23 @@ export function makeResolveForgejoAuthority({ apiUrl, token, fetchFn = fetch })
 			// a refusal rather than a failure.
 			return { authorized: false };
 		}
+		if (res.status === 403) {
+			// A CONFIGURATION error, named as one. Forgejo lets only a site admin, a repository admin, or the
+			// user themselves read a permission (measured on 14.0.5: a `write` collaborator's token gets 403
+			// {"message":"Only admins can query all permissions, repo admins can query all repo permissions,
+			// collaborators can query only their own"}; the same account raised to repo admin gets 200). The
+			// other 403s this route can give are the token's scope (`token does not have at least one of
+			// required scope(s)`, `token scope is limited to public repos`), so the dedicated token's reason names its scope too.
+			// Still indeterminate, and that is a decision, not an oversight. A retry cannot heal it, but the
+			// retry costs nothing (no token is minted and nothing spends before this answer), while the
+			// alternative is worse in the way this file's header names: a determinate refusal answers 204, which
+			// Forgejo records as a successful delivery, so the one place the operator looks would show every
+			// trigger "delivered" while nothing ran. A 503 marks each delivery failed there, the log line below
+			// names the repair, and a delivery that failed this way still describes real work to redo once the
+			// account is fixed. The body is still not read: the fixed reason is enough, and a body is not ours
+			// to log. The reason names the variable whose token asked (FORBIDDEN_REASON).
+			return { indeterminate: forbidden };
+		}
 		if (!res.ok) {
 			// Note what is NOT here: the response body. A Forgejo error body can echo the request, and the
 			// request carried the token.

package/src/start.mjs

@@ -211,10 +211,14 @@ export async function startReceiver(
 		if (cfg.forgejo) {
 			const forgejoSelfId = await retryIdentity(() => resolveForgejoSelfIdFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token, botId: cfg.forgejo.botId }), { forge: "forgejo", ...retryOpts });
 			log({ event: "self_identity", forge: "forgejo", id: forgejoSelfId, source: cfg.forgejo.botId ? "FORGEJO_BOT_ID" : "api" });
+			// The author gate's lookup token, by NAME only (OQ-043): FORGEJO_PERMISSION_TOKEN when set, else FORGEJO_TOKEN,
+			// whose account must then be a repository admin. Identity above stays FORGEJO_TOKEN's: it is the account the
+			// jobs post as, which the bot-loop guard must recognise.
+			log({ event: "forgejo_permission_token", source: cfg.forgejo.lookupTokenVar });
 			forgejo = {
 				secret: cfg.forgejo.secret,
 				selfId: forgejoSelfId,
-				resolveAuthority: makeResolveForgejoAuthorityFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token }),
+				resolveAuthority: makeResolveForgejoAuthorityFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.lookupToken, tokenVar: cfg.forgejo.lookupTokenVar }),
 			};
 		}