@edgehero/pi-dispatch 4.3.0 → 4.3.1

package/.env.example

@@ -466,8 +466,17 @@ FORGEJO_URL=
 # A REPOSITORY-scoped token ("Specific repositories") carrying only write:repository and write:issue.
 # Narrower than GitLab's equivalent -- Forgejo has no all-or-nothing `api` scope. What it cannot do is
 # expire: there is no App or installation token, so rotation is the whole mitigation
-# (CONST-TOKEN-SCOPED-PER-JOB).
+# (CONST-TOKEN-SCOPED-PER-JOB). Every forgejo job carries this token, so its account should be a WRITE
+# collaborator of each repository, never an admin (an admin's write:repository token can change settings
+# and branch protection: OQ-043).
 FORGEJO_TOKEN=
+# The author gate's own lookup token, read ONLY by the receiver and never handed to a job (PI_FORWARD_ENV and
+# run.secrets refuse it). Forgejo answers a lookup of another user's repository permission only to a site
+# admin or a repository admin (a write collaborator gets 403, and then no trigger ever runs), so mint this
+# from an account that IS an admin (or the owner) of each repository, scoped read:repository and nothing
+# else. Unset, the lookup uses FORGEJO_TOKEN, which then has to belong to an admin: doctor warns.
+# docs/forgejo.md walks it.
+FORGEJO_PERMISSION_TOKEN=
 # only "pat", the default. See GITLAB_AUTH_SOURCE above for why it exists at all.
 # FORGEJO_AUTH_SOURCE=
 # The harness account's NUMERIC id. Required when the token above is repository-scoped, because such a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "type": "module",
   "description": "The pi-dispatch worker and CLI: runs the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
   "keywords": [

package/src/config.mjs

@@ -10,7 +10,7 @@ import { homedir, hostname, tmpdir } from "node:os";
 import { delimiter, isAbsolute, posix } from "node:path";
 import { DEFAULT_BACKEND, backendRefusals, parseBackendFloor, parseBackendList } from "./backends.mjs";
 import { egressArmed, egressProxyName } from "./egress.mjs";
-import { MINTED_TOKEN_VARS } from "./forges.mjs";
+import { MINTED_TOKEN_VARS, RECEIVER_ONLY_VARS } from "./forges.mjs";
 import { SWEEP_INTERVAL_HOURS, SWEEP_INTERVAL_MAX_HOURS } from "./retention-sweep.mjs";
 import { parseSecretProfiles } from "./secret-profiles.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, WAIT_INTERVAL_FLOOR_MS, parseWaitProfiles } from "./wait-for.mjs";
@@ -178,6 +178,14 @@ function forwardEnvList(raw, egressArmed = false) {
 			`PI_FORWARD_ENV must not forward ${minted.join(", ")} -- the worker mints a per-job token (CONST-TOKEN-SCOPED-PER-JOB) and a forwarded operator token would silently override it`,
 		);
 	}
+	// OQ-043: a receiver-only credential (FORGEJO_PERMISSION_TOKEN) is an ADMIN account's token, kept apart from the job's
+	// precisely so no job holds it. Forwarding it would undo that with one config line.
+	const receiverOnly = names.filter((n) => RECEIVER_ONLY_VARS.has(n));
+	if (receiverOnly.length > 0) {
+		throw configError(
+			`PI_FORWARD_ENV must not forward ${receiverOnly.join(", ")} -- only the receiver reads it, for the author gate's permission lookup, and it belongs to an account that is an admin of the repositories, which is exactly what a job must not hold (OQ-043)`,
+		);
+	}
 	const workerOnly = names.filter((n) => WORKER_ONLY_SECRET_VARS.has(n));
 	if (workerOnly.length > 0) {
 		throw configError(

package/src/doctor.mjs

@@ -604,7 +604,7 @@ export const GITHUB_SERVICE_KEYS = Object.freeze(["GITHUB_AUTH_SOURCE", "GITHUB_
  *  `.env`. TEMP is TMPDIR's twin in the worker's temp root; PI_CODING_AGENT_DIR is where the worker reads auth.json. */
 export const WORKER_SERVICE_KEYS = Object.freeze(["PI_JOB_IMAGE", "PI_JOB_MEMORY", "PI_JOB_CPUS", "PI_CONCURRENCY", ...Object.values(HOST_BUDGET_KEYS), "PI_TRIGGERS_FILE", "PI_LOGS_DIR", "PI_LOG_RETENTION_DAYS", "PI_SETTINGS_FILE", "PI_SESSIONS_DIR", "PI_SESSIONS_TTL_DAYS", "PI_SESSION_MAX_AGE_DAYS", "PI_SESSION_MAX_CONTEXT_PCT", "PI_SESSION_MAX_RESUME_CHAIN", "PI_GLOBAL_PI_DIR", "PI_GLOBAL_ALLOW_EXTENSIONS", "PI_FORWARD_ENV", "PI_AUTH_FROM_PI", "PI_CODING_AGENT_DIR", "PI_BACKEND_FLOOR", "PI_SECRET_PROFILES", "PI_SECRET_RESOLVER_ROOTS", "PI_WAIT_PROFILES", "PI_WAIT_AFTER_MAX_MS", "PI_SANDBOX_RETENTION_HOURS", "PI_ALLOWED_MODELS", "PI_DISPATCH_RUN_ROOTS", "GITHUB_PAT_VAR", "TEMP", ...Object.values(DOLLAR_ENV_NAMES)]);
 /** Issue #471: the receiver's keys doctor judges its boot by (the receiver's unit reads the same `.env`). */
-export const RECEIVER_SERVICE_KEYS = Object.freeze(["WEBHOOK_SECRET", "RECEIVER_PORT", "GITLAB_TOKEN", "GITLAB_URL", "GITLAB_WEBHOOK_MODE", "GITLAB_WEBHOOK_SECRET", "FORGEJO_URL", "FORGEJO_TOKEN", "FORGEJO_WEBHOOK_SECRET", "AZURE_ORG_URL", "AZURE_TOKEN", "AZURE_WEBHOOK_MODE", "AZURE_WEBHOOK_SECRET", "AZURE_WEBHOOK_HEADER"]);
+export const RECEIVER_SERVICE_KEYS = Object.freeze(["WEBHOOK_SECRET", "RECEIVER_PORT", "GITLAB_TOKEN", "GITLAB_URL", "GITLAB_WEBHOOK_MODE", "GITLAB_WEBHOOK_SECRET", "FORGEJO_URL", "FORGEJO_TOKEN", "FORGEJO_PERMISSION_TOKEN", "FORGEJO_WEBHOOK_SECRET", "AZURE_ORG_URL", "AZURE_TOKEN", "AZURE_WEBHOOK_MODE", "AZURE_WEBHOOK_SECRET", "AZURE_WEBHOOK_HEADER"]);
 /**
  * Issue #471 (follow-up): the variables the CLIs doctor spawns read from their environment, by the CLI that reads them.
  * The worker starts podman, docker and gh with its OWN environment (no `env` option: `image-preflight.mjs`,
@@ -727,7 +727,7 @@ export const DOCTOR_SHELL_KEYS = Object.freeze({
 
 /** Issue #471: the service keys whose values a disagreement line never prints (set or unset only); URLs print as
  *  `urlShown` does. Every other key's two values are shown, quoted. */
-const SECRET_SERVICE_KEYS = new Set([VALKEY_PASSWORD_KEY, "GH_TOKEN", "GITHUB_TOKEN", "GITHUB_APP_PRIVATE_KEY", "WEBHOOK_SECRET", "GITLAB_TOKEN", "GITLAB_WEBHOOK_SECRET", "FORGEJO_TOKEN", "FORGEJO_WEBHOOK_SECRET", "AZURE_TOKEN", "AZURE_WEBHOOK_SECRET"]);
+const SECRET_SERVICE_KEYS = new Set([VALKEY_PASSWORD_KEY, "GH_TOKEN", "GITHUB_TOKEN", "GITHUB_APP_PRIVATE_KEY", "WEBHOOK_SECRET", "GITLAB_TOKEN", "GITLAB_WEBHOOK_SECRET", "FORGEJO_TOKEN", "FORGEJO_PERMISSION_TOKEN", "FORGEJO_WEBHOOK_SECRET", "AZURE_TOKEN", "AZURE_WEBHOOK_SECRET"]);
 const URL_SERVICE_KEYS = new Set(["VALKEY_URL", "GITLAB_URL", "FORGEJO_URL", "AZURE_ORG_URL"]);
 
 /** `keys` narrowed to `SERVICE_ENV_KEYS` plus the provider's own key variables. */
@@ -830,6 +830,7 @@ export const EMPTY_READ_AS_UNSET = Object.freeze({
 	GITLAB_WEBHOOK_SECRET: "empty",
 	FORGEJO_URL: "empty",
 	FORGEJO_TOKEN: "empty",
+	FORGEJO_PERMISSION_TOKEN: "blank",
 	FORGEJO_WEBHOOK_SECRET: "empty",
 	AZURE_ORG_URL: "empty",
 	AZURE_TOKEN: "empty",
@@ -2005,6 +2006,27 @@ export async function collectChecks(shellVars, seams) {
 		} else {
 			checks.push({ ok: true, label: `forgejo triggers configured (${urlShown(env.FORGEJO_URL)})` });
 		}
+		// Measured on Forgejo 14.0.5: the author gate's permission lookup answers 403 unless the token's account is a site
+		// admin, a repository admin, or the actor themselves. Which token asks is the receiver's choice (OQ-043):
+		// FORGEJO_PERMISSION_TOKEN when set, a read:repository token of an admin account that no job ever holds; else
+		// FORGEJO_TOKEN, every job's token, whose account must then be an admin. Doctor cannot ask Forgejo either way
+		// (forgejo triggers name no repository, each delivery does), so it says which token is in use: a FACT LINE when the
+		// dedicated one is set, with the requirement in the label (issue #462's form), and a WARNING on the fallback,
+		// because the fallback is the configuration that puts an admin's token into every job.
+		const permissionToken = typeof env.FORGEJO_PERMISSION_TOKEN === "string" && env.FORGEJO_PERMISSION_TOKEN.trim() !== "";
+		if (permissionToken) {
+			checks.push({
+				ok: true,
+				label: "forgejo author-gate lookups use FORGEJO_PERMISSION_TOKEN: its account must be an admin (or the owner) of every repository the triggers serve and the token needs read:repository only, while FORGEJO_TOKEN, which every job carries, stays a write collaborator's (docs/forgejo.md)",
+			});
+		} else {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: "FORGEJO_PERMISSION_TOKEN is unset, so forgejo author-gate lookups use FORGEJO_TOKEN: Forgejo answers them only to a repository admin, so that account must be one, and then every forgejo job carries an admin's token that can change repository settings and branch protection (OQ-043)",
+				fix: "keep FORGEJO_TOKEN's account a write collaborator, and set FORGEJO_PERMISSION_TOKEN to a read:repository token of an account that is an admin (or the owner) of the repositories; only the receiver reads it (docs/forgejo.md)",
+			});
+		}
 	}
 
 	// Issue #508: with the egress policy on, a job reaches a forge only over https on port 443.

package/src/env-allowlist.mjs

@@ -30,7 +30,7 @@ import { join } from "node:path";
 import { findEnvKeys } from "@earendil-works/pi-ai/compat";
 import { getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
 import { egressEnv } from "./egress.mjs";
-import { forgeSpec } from "./forges.mjs";
+import { RECEIVER_ONLY_VARS, forgeSpec } from "./forges.mjs";
 import { apiKeyVariable } from "./provider-key.mjs";
 import { isDeterminateFsCode } from "./transient.mjs";
 import { KEYLESS_HOW, keylessVerdict, providerRenameHint, readOverlayModels, RENAMED_PROVIDERS } from "./model-endpoints.mjs";
@@ -558,7 +558,7 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 	delete env.PI_DISPATCH_PRICE_TABLE;
 
 	// Forge-backed jobs, and local cron jobs that opted in via run.github. Other local-folder jobs have
-	// no token (CONST-TOKEN-SCOPED-PER-JOB). The mint goes into BOTH of its forge's variables because
+	// no token (CONST-TOKEN-SCOPED-PER-JOB). The mint goes into EVERY one of its forge's variables because
 	// each CLI has its own preference -- gh prefers GH_TOKEN over GITHUB_TOKEN, glab prefers GITLAB_TOKEN
 	// -- and mirroring forecloses any precedence surprise inside the container.
 	//
@@ -583,8 +583,12 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 		}
 		for (const name of spec.tokenVars) env[name] = githubToken;
 		const host = forgeHosts?.[forgeKind];
-		if (spec.hostVar && host) env[spec.hostVar] = host;
+		if (host) for (const name of spec.hostVars) env[name] = host;
 	}
 
+	// OQ-043: the receiver's own lookup credential (FORGEJO_PERMISSION_TOKEN) is an admin account's token and never a
+	// job's. PI_FORWARD_ENV and run.secrets both refuse it upstream; this is the line that holds if either is bypassed.
+	for (const name of RECEIVER_ONLY_VARS) delete env[name];
+
 	return env;
 }

package/src/forgejo-auth.mjs

@@ -16,6 +16,10 @@
  *   - host-held           YES; it lives in the worker's env and reaches a container only as an env value.
  *   - env-injected        YES; never written to /workspace, .git/config, argv, or a log.
  *   - not merge-capable   YES in practice; branch protection is the barrier and no merge API is called.
+ *                         Provided this account stays a WRITE collaborator: the author gate's lookup needs a
+ *                         repository admin, and asks with the receiver's own FORGEJO_PERMISSION_TOKEN for that.
+ *                         Without it the lookup falls back to this token, whose account must then be an admin,
+ *                         and an admin's write:repository token can lift that protection (OQ-043).
  *   - short-lived         NO. The operator mints it by hand. Forgejo offers no installation-token
  *                         equivalent, so there is no path to a bounded expiry at all.
  *

package/src/forgejo-host.mjs

@@ -4,17 +4,25 @@
  *
  * BRANCH PROTECTION IS THE REASON TO READ THIS FILE. `github-host.mjs` treats a 404 from
  * `/repos/{o}/{r}/branches/{b}/protection` as "not protected", which is correct on GitHub, where that
- * endpoint exists and 404 means "no protection on this branch". Forgejo has no such endpoint at all -- it
- * uses `/branch_protections`, a different path with a different shape -- so carrying GitHub's assumption
- * across would make EVERY branch report unprotected and silently disarm the backstop that stops the agent
- * pushing to a protected branch. Issue #61 records this, and `REQ-BRANCH-PROTECTION-PRECONDITION` already
- * cites it by number as the failure that ordering exists to avoid.
+ * endpoint exists and 404 means "no protection on this branch". Forgejo has no such endpoint at all, so
+ * carrying GitHub's assumption across would make EVERY branch report unprotected. Issue #61 records this, and
+ * `REQ-BRANCH-PROTECTION-PRECONDITION` already cites it by number as the failure that ordering exists to avoid.
  *
- * And the fix is not simply "call the other endpoint". Forgejo's rules are GLOB patterns: a rule named
- * `release/*` protects `release/1.0` while `GET /branch_protections/release/1.0` returns 404. So this
- * LISTS the rules and matches each pattern against the branch, exactly as the GitLab host does -- and it
- * reuses that host's `matchesBranch` rather than writing a second globber, because two implementations of
- * "which branches does this rule cover" is two chances to widen it.
+ * The answer is the branch object's own `protected` field, from `GET /repos/{o}/{r}/branches/{branch}`. Forgejo
+ * computes it with the GLOB match itself: at v14.0.5 `GetBranch` (routers/api/v1/repo/branch.go) calls
+ * `GetFirstMatchProtectedBranchRule`, which loads every rule of the repository and returns the first whose
+ * `Match` covers the branch (models/git/protected_branch_list.go, protected_branch.go: a plain name compared
+ * case-insensitively, anything else as a glob), and `convert.ToBranch` sets `protected: true` exactly when a rule
+ * matched. So a `release/*` rule protects `release/1.0` here as it does in the forge. The route needs only read
+ * access to the code (`reqRepoReader(unit.TypeCode)`), which the job's `write` collaborator token has.
+ *
+ * This used to LIST `/branch_protections` and glob-match the rules here (reusing the GitLab host's
+ * `matchesBranch`). That listing is an admin route (`reqAdmin()`), so a job token of a `write` collaborator got
+ * 403 `{"message":"user should be an owner or a collaborator with admin write of a repository"}` (measured on
+ * Forgejo 14.0.5) and every job failed before spending: the check had quietly required an admin's token, which
+ * OQ-043 exists to keep out of jobs. The `protected` field is older than everything the listing supported
+ * (Gitea 1.11, and Forgejo is a fork of 1.18 and later), so no fallback to the listing is kept: it could only
+ * ever answer for a token that should not be in the job.
  *
  * A non-2xx is retryable, never `false`. Collapsing an error into "unprotected" is the same fail-open in a
  * different costume.
@@ -24,11 +32,21 @@ import { configError } from "./config.mjs";
 import { PARKED_LABEL } from "./parked.mjs";
 import { InfraRetry } from "./processor.mjs";
 import { fetchFailureReason } from "./gitlab-identity.mjs";
-import { matchesBranch } from "./gitlab-host.mjs";
 import { isDeterminateFetchFailure } from "./transient.mjs";
 
 const API_PREFIX = "/api/v1";
 
+/**
+ * A branch name as the tail of `/branches/*`. Forgejo routes that path with a wildcard (`m.Get("/*", repo.GetBranch)`),
+ * so a branch with a slash is sent with its slashes and each SEGMENT escaped, never as one `%2F`-joined token.
+ */
+function branchPath(branch) {
+	return String(branch).split("/").map(encodeURIComponent).join("/");
+}
+
+/** How many pages of repository labels the parked marker's lookup reads before it gives up (50 a page at most). */
+const MAX_LABEL_PAGES = 20;
+
 /** Build the host surface. Returns the same four methods every forge host exposes. */
 export function makeForgejoHost({ apiUrl, fetchFn = fetch } = {}) {
 	const root = `${String(apiUrl ?? "").replace(/\/+$/, "")}${API_PREFIX}`;
@@ -74,7 +92,7 @@ export function makeForgejoHost({ apiUrl, fetchFn = fetch } = {}) {
 		if (typeof branch !== "string" || branch === "") {
 			throw new InfraRetry(`forgejo-host: ${owner}/${name} reported no default_branch`);
 		}
-		const info = await get(`/repos/${owner}/${name}/branches/${encodeURIComponent(branch)}`, token);
+		const info = await get(`/repos/${owner}/${name}/branches/${branchPath(branch)}`, token);
 		// Gitea's Branch carries its tip as `commit.id`; some versions and forks also expose `commit.sha`.
 		// Both are read, and neither being a string is a hard failure rather than an undefined SHA -- a job
 		// that cannot name the commit it is standing on must not proceed to clone something else.
@@ -86,24 +104,22 @@ export function makeForgejoHost({ apiUrl, fetchFn = fetch } = {}) {
 	}
 
 	/**
-	 * Whether the default branch is covered by any protection rule.
+	 * Whether the default branch is covered by any protection rule, as Forgejo itself decides it: the branch
+	 * object's `protected` (see the module header for why this endpoint, and not the rule listing).
 	 *
-	 * See the module header: this is the endpoint and the glob matching that GitHub's 404 rule would have
-	 * got wrong in two independent ways.
+	 * A non-2xx (a missing branch's 404 included) is retryable through `get`, never `false`, and so is a body whose
+	 * `protected` is not a boolean: an instance that stops sending the field must not read as a determinate answer.
 	 */
 	async function isDefaultBranchProtected(ref, token) {
 		const [owner, name] = splitRepo(ref);
 		const repo = await get(`/repos/${owner}/${name}`, token);
 		const branch = repo?.default_branch;
 		if (typeof branch !== "string" || branch === "") return false;
-		const rules = await get(`/repos/${owner}/${name}/branch_protections`, token);
-		if (!Array.isArray(rules)) {
-			throw new InfraRetry(`forgejo-host: ${owner}/${name} branch_protections returned a non-array`);
+		const info = await get(`/repos/${owner}/${name}/branches/${branchPath(branch)}`, token);
+		if (typeof info?.protected !== "boolean") {
+			throw new InfraRetry(`forgejo-host: ${owner}/${name} branch ${branch} reported no boolean protected`);
 		}
-		// `rule_name` is the current field; `branch_name` is its deprecated predecessor and is still what
-		// older instances send. Reading only the new one would report every branch on an older Forgejo as
-		// unprotected -- the same class of silent fail-open this file exists to avoid.
-		return rules.some((rule) => matchesBranch(rule?.rule_name ?? rule?.branch_name, branch));
+		return info.protected;
 	}
 
 	/**
@@ -155,10 +171,22 @@ export function makeForgejoHost({ apiUrl, fetchFn = fetch } = {}) {
 	}
 
 	/**
-	 * Add or remove the parked marker on an issue (issue #625, parked.mjs). Forgejo adds and removes a
-	 * label by NAME (its IssueLabelsOption and the `{identifier}` path take a name or an id), but only one the repository
-	 * already has, so adding first creates the repository label; a label that already exists answers 409 or 422 there. The caller treats any throw as fail-open:
-	 * the session store's sidecar, not this label, decides whether a reply resumes anything.
+	 * Add or remove the parked marker on an issue (issue #625, parked.mjs). The caller treats any throw as fail-open: the
+	 * session store's sidecar, not this label, decides whether a reply resumes anything.
+	 *
+	 * BY ID, AFTER A LOOKUP, because Forgejo does not refuse a duplicate label name. Measured on 14.0.5: a second
+	 * `POST /repos/{o}/{r}/labels {"name":"pi-awaiting-input",...}` answers 201 and creates ANOTHER repository label of
+	 * that name (the repository's labels became ai #1, pi-awaiting-input #2, pi-awaiting-input #3 after the second park);
+	 * adding by name then attaches EVERY label of that name (the issue carried #2 and #3, two adds in its timeline); and
+	 * removing by name took off only ONE (204, #3 stayed). So the marker outlived the resumed run for good, each park added
+	 * a repository label, and every later plain reply was routed, to end as `not-parked`. The 409/422 this used to accept
+	 * on the create never happens on Forgejo 14.
+	 *
+	 * Adding: list the repository's labels, create one only when none has the exact name, and attach the LOWEST id, so a
+	 * repository that already holds duplicates stops growing them and the issue gets one marker. Removing: read the
+	 * labels the issue actually carries and remove every one of that name by id, so an issue that holds two from before
+	 * this fix is cleared too. The duplicate repository labels themselves are left alone: deleting a repository's labels
+	 * is the operator's call, and a spare one carried by no issue routes nothing (docs/forgejo.md says how to tidy them).
 	 */
 	async function setParkedLabel(ref, target, on, token) {
 		const [owner, name] = splitRepo(ref);
@@ -175,14 +203,45 @@ export function makeForgejoHost({ apiUrl, fetchFn = fetch } = {}) {
 				throw new InfraRetry(`forgejo-host: ${method} ${path} failed (${fetchFailureReason(err)})`);
 			}
 			if (!res.ok && !accept.includes(res.status)) throw new InfraRetry(`forgejo-host: ${method} ${path} returned ${res.status}`);
+			return res;
 		};
 		const issue = `/repos/${owner}/${name}/issues/${encodeURIComponent(target?.number)}/labels`;
+		const markers = (labels) => (Array.isArray(labels) ? labels : []).filter((l) => l?.name === PARKED_LABEL && Number.isSafeInteger(l?.id)).map((l) => l.id);
 		if (on) {
-			await send("POST", `/repos/${owner}/${name}/labels`, { name: PARKED_LABEL, color: "#fbca04", description: "pi-dispatch: the last run is waiting for an answer" }, [409, 422]);
-			await send("POST", issue, { labels: [PARKED_LABEL] });
+			let ids = await repoLabelIds(owner, name, token, markers);
+			if (ids.length === 0) {
+				const res = await send("POST", `/repos/${owner}/${name}/labels`, { name: PARKED_LABEL, color: "#fbca04", description: "pi-dispatch: the last run is waiting for an answer" }, [409, 422]);
+				// A forge that DOES refuse the duplicate (409/422, a Gitea or a later Forgejo) raced another park to it: list
+				// again. A 201 hands back the label, so no second read is needed.
+				const created = res.ok ? await res.json().catch(() => null) : null;
+				ids = Number.isSafeInteger(created?.id) ? [created.id] : await repoLabelIds(owner, name, token, markers);
+			}
+			if (ids.length === 0) throw new InfraRetry(`forgejo-host: ${owner}/${name} has no ${PARKED_LABEL} label after creating it`);
+			await send("POST", issue, { labels: [Math.min(...ids)] });
 			return;
 		}
-		await send("DELETE", `${issue}/${encodeURIComponent(PARKED_LABEL)}`, undefined, [404]);
+		// Already gone is success: 404 (no such issue) and, on the removal, 422 -- Forgejo's answer when no such label
+		// exists (measured on 14.0.5: {"message":"label does not exist [label_id: 0, repo_id: 1]"}). Matched on the status
+		// alone: in 14.0.5's DeleteIssueLabel the only 422 is "label does not exist", the binding's own 422 needs a request
+		// body and none is sent, and the message is free to change between versions. A stray 422 read as gone would leave
+		// a stale marker, which decides nothing.
+		const carried = markers(await get(issue, token, { notFound: [] }));
+		for (const id of carried) await send("DELETE", `${issue}/${id}`, undefined, [404, 422]);
+	}
+
+	/**
+	 * The ids of every repository label named `PARKED_LABEL`, in id order. Paged until an EMPTY page rather than until a
+	 * short one, because the instance caps the page size (`MAX_RESPONSE_ITEMS`) below what was asked for, and a short page
+	 * is then every page. Bounded, so a server that never returns an empty page cannot hold a job's teardown.
+	 */
+	async function repoLabelIds(owner, name, token, markers) {
+		const ids = [];
+		for (let page = 1; page <= MAX_LABEL_PAGES; page++) {
+			const labels = await get(`/repos/${owner}/${name}/labels?page=${page}&limit=50`, token);
+			if (!Array.isArray(labels) || labels.length === 0) return ids.sort((a, b) => a - b);
+			ids.push(...markers(labels));
+		}
+		throw new InfraRetry(`forgejo-host: ${owner}/${name} lists more than ${MAX_LABEL_PAGES} pages of labels`);
 	}
 
 	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead, setParkedLabel };

package/src/forges.mjs

@@ -37,8 +37,13 @@
  *   names that must be refused in `PI_FORWARD_ENV`, and those two lists being derived from one entry is
  *   the point: a forge added to the mint but not to the refusal set is a long-lived host token forwarded
  *   into every container, and nothing would have said so.
- * - `hostVar` is where a self-hosted instance URL lands in the container, or `null` for a forge that has
- *   no instance concept in this codebase yet.
+ * - `hostVars` are where a self-hosted instance URL lands in the container (the configured URL verbatim,
+ *   scheme included), or an empty list for a forge that has no instance concept in this codebase yet. A
+ *   LIST for the reason `tokenVars` is one: the CLI's own name is the one that matters, and a second,
+ *   forge-named copy is what scripts and skills reach for.
+ * - `receiverOnlyVars` are credentials of this forge that only the RECEIVER reads, and that must never reach a
+ *   job: refused in `PI_FORWARD_ENV`, reserved from `run.secrets`, and deleted from the container env as a
+ *   backstop (`RECEIVER_ONLY_VARS`). Empty for every forge whose author gate the job's own token can answer.
  * - `prLabelAction` is this forge's `pull_request` action meaning "a label changed", or `null` where the
  *   forge has no distinguishable one. It decides whether a rule naming that action must carry a positive
  *   selector, and the reason is independent of who is gating: a rule keyed on labels that names no labels
@@ -51,7 +56,8 @@ export const FORGES = {
 		deliveryIdName: "X-GitHub-Delivery GUID",
 		pullRequestSep: "#",
 		tokenVars: ["GITHUB_TOKEN", "GH_TOKEN"],
-		hostVar: null,
+		hostVars: [],
+		receiverOnlyVars: [],
 		prLabelAction: "labeled",
 	},
 	gitlab: {
@@ -59,7 +65,8 @@ export const FORGES = {
 		deliveryIdName: "webhook-id / Idempotency-Key",
 		pullRequestSep: "!",
 		tokenVars: ["GITLAB_TOKEN", "GL_TOKEN"],
-		hostVar: "GITLAB_HOST",
+		hostVars: ["GITLAB_HOST"],
+		receiverOnlyVars: [],
 		// A label added to a merge request arrives as a plain `update`, indistinguishable from any other
 		// edit, so there is no action for a positive-selector rule to attach to. (Separately, a GitLab label
 		// is not an approval at all -- a Guest can set one at issue creation -- which is why every gitlab
@@ -76,9 +83,23 @@ export const FORGES = {
 		// Forgejo numbers issues and pull requests from ONE per-repository sequence, exactly as GitHub does
 		// -- an issue and a PR cannot share an index. So `#` names one thing and no discriminator is needed.
 		pullRequestSep: "#",
-		// `tea` reads GITEA_SERVER_TOKEN; the unprefixed name is what the API examples and most scripts use.
-		tokenVars: ["FORGEJO_TOKEN", "GITEA_SERVER_TOKEN"],
-		hostVar: "FORGEJO_HOST",
+		// `tea` logs in from the environment ONLY through GITEA_TOKEN plus GITEA_INSTANCE_URL. Measured on the
+		// pinned tea 0.15.0 in the 4.3.0 job image against a live Forgejo 14.0.5: that pair lists issues, while
+		// GITEA_SERVER_URL + GITEA_SERVER_TOKEN (with or without GITEA_LOGIN_VIA_ENV=1), FORGEJO_HOST +
+		// GITEA_SERVER_TOKEN, and GITEA_TOKEN alone inside a clone all fail "Error: no available login". So
+		// from be1cc42e until this row changed, every `tea` command the forgejo envelope tells the agent to run
+		// failed. GITEA_SERVER_TOKEN stays: it is the default of `tea login add --token` (its --help says
+		// `[$GITEA_SERVER_TOKEN]`), so an agent that adds a login explicitly still gets the job's token, and it
+		// stays reserved. FORGEJO_TOKEN is what the API examples and most scripts use.
+		// worker/test/forges.test.mjs pins these names to the tea version image/Dockerfile installs.
+		tokenVars: ["FORGEJO_TOKEN", "GITEA_TOKEN", "GITEA_SERVER_TOKEN"],
+		// GITEA_INSTANCE_URL is tea's, and must be the full URL with its scheme (FORGEJO_URL is). FORGEJO_HOST
+		// is read by no CLI; it is kept because it has been in every forgejo job since #61 and a skill may use it.
+		hostVars: ["GITEA_INSTANCE_URL", "FORGEJO_HOST"],
+		// The author gate's own lookup token (OQ-043): Forgejo answers a lookup of another user's permission only to a
+		// repository admin, so this is a read:repository token of an account that is one, and the job's FORGEJO_TOKEN
+		// can stay a write collaborator's. A job holding it would hold an admin's token, which is the whole point lost.
+		receiverOnlyVars: ["FORGEJO_PERMISSION_TOKEN"],
 		// Forgejo names the action, so the positive-selector rule applies exactly as it does on GitHub.
 		// Note this is HYGIENE, not the gate: unlike GitHub, every forgejo trigger is additionally gated on
 		// the actor's resolved repository permission -- see filter-forgejo.mjs for why that is not
@@ -99,7 +120,8 @@ export const FORGES = {
 		pullRequestSep: "!",
 		// `az repos` reads AZURE_DEVOPS_EXT_PAT; SYSTEM_ACCESSTOKEN is what a pipeline-shaped script expects.
 		tokenVars: ["AZURE_DEVOPS_EXT_PAT", "SYSTEM_ACCESSTOKEN"],
-		hostVar: "AZURE_DEVOPS_ORG_URL",
+		hostVars: ["AZURE_DEVOPS_ORG_URL"],
+		receiverOnlyVars: [],
 		// Azure attaches no labels to a pull request at all, so there is no action to attach the rule to and
 		// a predicated PR rule could never match. The loader refuses one rather than letting it load dead.
 		prLabelAction: null,
@@ -140,14 +162,20 @@ export const MINTED_TOKEN_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[ki
  * `MINTED_TOKEN_VARS` and derived the same way, from the table rather than by hand, so a forge added
  * later cannot be missed here either.
  *
- * Separate from `MINTED_TOKEN_VARS` because `hostVar` is a separate column: the token set is
+ * Separate from `MINTED_TOKEN_VARS` because `hostVars` is a separate column: the token set is
  * `tokenVars` only, so a name like `GITLAB_HOST` is in NEITHER set until this one exists. That gap is
  * not theoretical -- `buildContainerEnv` writes this variable after the mint, so a trigger field able
  * to name it would be silently overwritten, and the job would run without the value it asked for on a
- * clean exit 0. github's row is `null` and contributes nothing, which is why the filter is here and
- * not at the call site.
+ * clean exit 0. github's row is empty and contributes nothing.
  */
-export const FORGE_HOST_VARS = new Set(FORGE_KINDS.map((kind) => FORGES[kind].hostVar).filter((name) => typeof name === "string"));
+export const FORGE_HOST_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[kind].hostVars));
+
+/**
+ * Every credential name only the receiver reads (`receiverOnlyVars`), derived from the table like the two sets above.
+ * The worker refuses each in `PI_FORWARD_ENV`, the triggers loader refuses each in `run.secrets`, and
+ * `buildContainerEnv` deletes each last, so no path puts one in a container.
+ */
+export const RECEIVER_ONLY_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[kind].receiverOnlyVars));
 
 /**
  * The separator between a repo label and a target number, for this forge and this target type: the

package/src/index.mjs

@@ -22,6 +22,7 @@ import { BUDGET_RECHECK_MS, HOST_BUDGET_TICK_MS, NEVER_FITS_RECHECK_MS, makeHost
 import { governedDollars } from "./allocation.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, WAIT_INTERVAL_FLOOR_MS, afterMs, unreadableConditions, waitArmed, waitBackoffMs, waitLabel, waitProfileNames } from "./wait-for.mjs";
 import { makeWaitState } from "./wait-state.mjs";
+import { releaseSemanticWindow } from "./queue.mjs";
 
 
 export const QUEUE = "pi-jobs";
@@ -1344,6 +1345,11 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 				// mirroring the name/signal injection above. Omitted when unwired so a bare processor falls back
 				// to runJob's no-op default (a chain fault can never flip a completed outcome either way).
 				...(deps.collectChain ? { collectChain: (ctx) => deps.collectChain({ ...ctx, job }) } : {}),
+				// DES-AWAIT-INPUT-ENDS-THE-JOB: a parked run's semantic window is closed on the REAL BullMQ job, which holds the
+				// dedup id the add stored and the compare-and-delete that frees only a key it still owns (queue.mjs). Bound
+				// unconditionally, AFTER the `...deps` spread like the injections around it: whether the key may outlive a park
+				// is not a choice a wiring gets to make by omission.
+				releaseParkedWindow: () => releaseSemanticWindow(job, deps?.log),
 				// The plan collector (issue #505) the same way and for the same reason: the writer it records is the REAL job's
 				// `.id`, and the authority it checks is `.data` as queued. The pickup's `portfolio` decision rides in `ctx`.
 				...(deps.collectPlan ? { collectPlan: (ctx) => deps.collectPlan({ ...ctx, job }) } : {}),

package/src/processor.mjs

@@ -302,6 +302,10 @@ export async function runJob(job, deps) {
 		// (job, on) => Promise<void> (issue #625): add or remove the forge's parked marker. Never throws; the marker is a
 		// hint for the receiver, and the sidecar decides. The default does nothing.
 		parkedLabel = async () => {},
+		// () => Promise<unknown> (DES-AWAIT-INPUT-ENDS-THE-JOB): close this job's semantic dedup window once it has parked,
+		// so the answer is not swallowed against it. Takes no job: the key belongs to the REAL BullMQ job, which only the
+		// wiring holds (index.mjs binds queue.mjs's `releaseSemanticWindow` to it). Never throws. The default does nothing.
+		releaseParkedWindow = async () => {},
 		// The session store's root, or null when the feature is unavailable (REQ-RESUMABLE-SESSION). Read
 		// ONLY to answer the fail-closed gate below -- nothing here opens it, and it never reaches the
 		// container env (docker-run.mjs mounts a per-job COPY, never the store).
@@ -1520,6 +1524,12 @@ export async function runJob(job, deps) {
 				// job is ignored, since that runner was never offered the tool.
 				const parked = exitReason === "awaiting-input" && job.awaitInput === true;
 				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion, context, parked }) : null;
+				// The window closes AFTER the promotion (an answer that gets in must find the `parked` mark and the transcript)
+				// and BEFORE the comment and the marker: the marker is what routes a phrase-free reply on an issue, and the
+				// comment is what tells a pull request's author to reply, so no answer they invite can meet the old key. Every
+				// park takes this path, a resumed run that parks again included. Guarded although the seam never throws: a
+				// fault here must not cost the person the comment that says how to continue.
+				if (parked) await Promise.resolve().then(releaseParkedWindow).catch(() => {});
 				if (parked) await comment(job, parkedComment(job.target));
 				// The forge marker the receiver routes a phrase-free reply on: set on a park, cleared when a run on a key that
 				// could park ends without parking. Never throws, and decides nothing: the sidecar promotion just wrote does.

package/src/queue.mjs

@@ -247,6 +247,38 @@ async function addLocalJob(queue, { folder, flow, task, command, provider, model
 // window only needs to absorb burst re-labels, not the full redelivery window.
 const SEMANTIC_WINDOW_MS = 10 * 60 * 1000;
 
+/**
+ * Close the semantic window of a run that PARKED (REQ-AWAIT-INPUT, DES-AWAIT-INPUT-ENDS-THE-JOB). Never throws.
+ *
+ * The window exists to coalesce rapid duplicate deliveries into one ACTIVE job. A ttl-mode key outlives the job it
+ * was set for (bullmq 5.80.4, `removeDeduplicationKeyIfNeededOnFinalization.lua`: a finished job deletes its key only
+ * when it has no ttl), so without this a person's answer that lands within ten minutes of the delivery that STARTED
+ * the parked run is swallowed against that finished run: the receiver answers `deduplicated`, nothing runs, and the
+ * marker stays. Once a run has parked, the next delivery on its key is a deliberate answer, never a duplicate.
+ *
+ * It asks the BullMQ job itself, rather than rebuilding the key from the job data: `job.deduplicationId` is the id
+ * the add stored with the job (`deid` in its hash), so there is no second spelling of the key format to drift from
+ * `enqueueForgeJob`'s, and it covers every suffix (the `closed:`/`cmd:` slot, a replica's `:r<n>`) by construction.
+ * And `job.removeDeduplicationKey()` is a compare-and-delete (`removeDeduplicationKey-1.lua`: DEL only when the key
+ * still holds THIS job's id), where `queue.removeDeduplicationKey(id)` is a bare DEL that could free a key a later
+ * job now holds.
+ *
+ * Fails open with a named line: a failure only leaves today's behaviour (the answer waits out the window).
+ * `released` is false, logged as a release and not as a failure, when the key is already gone (the window lapsed
+ * during a long run) or now names another job.
+ */
+export async function releaseSemanticWindow(job, log = () => {}) {
+	if (!job?.deduplicationId || typeof job.removeDeduplicationKey !== "function") return false;
+	try {
+		const released = (await job.removeDeduplicationKey()) === true;
+		log("parked_window_released", { jobId: job.id ?? null, released });
+		return released;
+	} catch (error) {
+		log("parked_window_release_failed", { jobId: job.id ?? null, code: typeof error?.code === "string" ? error.code : "error" });
+		return false;
+	}
+}
+
 /**
  * Enqueue a GitHub-triggered job. Returns `{ jobId, deduplicated, survivingJobId? }` -- the computed
  * per-delivery id, plus whether the SEMANTIC window swallowed this delivery (issue #289; the GUID

package/src/triggers.mjs

@@ -30,7 +30,7 @@ import { imageRefProblem } from "./image-ref.mjs";
 // materialize.mjs and the admin already import it, and a keep-in-sync copy would drift where a
 // traversal guard cannot). flow-gate's module body is import-inert, so this keeps parseTriggers pure.
 import { SKILL_NAME_RE } from "./flow-gate.mjs";
-import { FORGE_HOST_VARS, FORGE_KINDS, MINTED_TOKEN_VARS, RUN_KINDS, forgeSpec, isForgeKind } from "./forges.mjs";
+import { FORGE_HOST_VARS, FORGE_KINDS, MINTED_TOKEN_VARS, RECEIVER_ONLY_VARS, RUN_KINDS, forgeSpec, isForgeKind } from "./forges.mjs";
 import { findDuplicateKey } from "./json-duplicates.mjs";
 // The server-name rule, from the one module that parses the overlay's list (its body is import-inert).
 import { FORGE_MCP_KINDS, FORGE_MCP_SERVER_NAME, MCP_SERVER_NAME_RE } from "./mcp-config.mjs";
@@ -261,7 +261,7 @@ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
  * Every set is IMPORTED, never retyped, which is the rule `sandbox.test.mjs` keeps for the same reason: a
  * forge added to the table later must not need a second edit here to stay covered.
  */
-export const RESERVED_ENV_NAMES = new Set([...MINTED_TOKEN_VARS, ...FORGE_HOST_VARS, ...WORKER_ONLY_SECRET_VARS, ...EGRESS_ENV_VARS, ...CONTAINER_ENV_NAMES, ...RUNNER_ENV_NAMES, ...PROVIDER_STEERING_VARS]);
+export const RESERVED_ENV_NAMES = new Set([...MINTED_TOKEN_VARS, ...FORGE_HOST_VARS, ...RECEIVER_ONLY_VARS, ...WORKER_ONLY_SECRET_VARS, ...EGRESS_ENV_VARS, ...CONTAINER_ENV_NAMES, ...RUNNER_ENV_NAMES, ...PROVIDER_STEERING_VARS]);
 
 function isNonEmptyString(value) {
 	return typeof value === "string" && value.trim() !== "";