@edgehero/pi-dispatch 4.2.0 → 4.3.1

package/.env.example

@@ -33,15 +33,16 @@ ANTHROPIC_API_KEY=
 
 # --- Which provider/model to run by default (override per job with --provider / --model) ---
 PI_PROVIDER=anthropic
-# A DATED model id is deterministic; a floating alias (e.g. claude-sonnet-4-5) can change cost.
-PI_MODEL=claude-sonnet-4-5-20250929
+# Name an exact model version (claude-sonnet-5-5, or a dated id such as claude-sonnet-4-5-20250929); an alias
+# that moves to a newer model can change cost.
+PI_MODEL=claude-sonnet-5-5
 # optional: the only models a job may call, comma-separated provider/model (at most 16). A trigger's own
 # run.models replaces this list for its jobs. The default model must be on it, or every job that uses the
 # default is refused before it spends. Env only: the settings overlay cannot set or widen it.
 # Unset = any model. Needs a job image that declares the modelPolicy capability.
 # No spaces, not even after a comma: a shell that sources this file cuts the value at the first space
 # and leaves it unset, so jobs would run with no list (the worker refuses a spaced value at boot).
-# PI_ALLOWED_MODELS=anthropic/claude-sonnet-4-5-20250929,anthropic/claude-haiku-4-5-20251001
+# PI_ALLOWED_MODELS=anthropic/claude-sonnet-5-5,anthropic/claude-haiku-5-5
 
 # --- Spend + concurrency guards (money bounds; all have conservative defaults) ---
 # per-job turn cap -- pi has none of its own, so the harness imposes one
@@ -465,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.2.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": [
@@ -55,6 +55,7 @@
     "./git-dirty": "./src/git-dirty.mjs",
     "./queue": "./src/queue.mjs",
     "./capabilities": "./src/capabilities.mjs",
+    "./parked": "./src/parked.mjs",
     "./connection": "./src/connection.mjs",
     "./valkey-auth": "./src/valkey-auth.mjs",
     "./job-id": "./src/job-id.mjs",
@@ -114,7 +115,7 @@
     "start": "node src/cli.mjs worker"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "1.1.0",
+    "@earendil-works/pi-ai": "1.2.0",
     "@octokit/auth-app": "8.2.0",
     "@octokit/rest": "22.0.1",
     "bullmq": "5.80.4",

package/src/azure-host.mjs

@@ -22,6 +22,7 @@
  */
 
 import { configError } from "./config.mjs";
+import { PARKED_LABEL } from "./parked.mjs";
 import { InfraRetry } from "./processor.mjs";
 import { fetchFailureReason } from "./gitlab-identity.mjs";
 import { isDeterminateFetchFailure } from "./transient.mjs";
@@ -201,7 +202,33 @@ export function makeAzureHost({ orgUrl, fetchFn = fetch } = {}) {
 		return { headRef: stripRefsHeads(pr?.sourceRefName), headRepo: sameRepo ? job?.repo : null };
 	}
 
-	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead };
+	/**
+	 * Add or remove the parked marker on a work item, as a TAG (issue #625, parked.mjs): Azure work items have
+	 * tags, not labels, and the receiver reads `System.Tags` into the same `[{ name }]` shape. A tags field is written
+	 * whole, so this reads it, edits the one tag and writes the result; Azure creates a tag the project lacks. The caller treats any throw as fail-open:
+	 * the session store's sidecar, not this label, decides whether a reply resumes anything.
+	 */
+	async function setParkedLabel(ref, target, on, token) {
+		const { project } = scopeOf(ref);
+		const path = `/${encodeURIComponent(project)}/_apis/wit/workitems/${encodeURIComponent(target?.number)}`;
+		const item = await get(`${path}?fields=System.Tags&api-version=${API_VERSION}`, token);
+		const tags = String(item?.fields?.["System.Tags"] ?? "").split(";").map((tag) => tag.trim()).filter((tag) => tag !== "" && tag !== PARKED_LABEL);
+		const value = (on ? [...tags, PARKED_LABEL] : tags).join("; ");
+		let res;
+		try {
+			res = await fetchFn(`${root}${path}?api-version=${API_VERSION}`, {
+				method: "PATCH",
+				headers: { Authorization: authHeader(token), "content-type": "application/json-patch+json" },
+				body: JSON.stringify([{ op: "add", path: "/fields/System.Tags", value }]),
+				redirect: "error",
+			});
+		} catch (err) {
+			throw new InfraRetry(`azure-host: PATCH ${path} failed (${fetchFailureReason(err)})`);
+		}
+		if (!res.ok) throw new InfraRetry(`azure-host: PATCH ${path} returned ${res.status}`);
+	}
+
+	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead, setParkedLabel };
 }
 
 /**

package/src/azure-prompt.mjs

@@ -68,6 +68,31 @@ function prReplicaLines(replica, replicas) {
 	];
 }
 
+/**
+ * What a resumed run is told to do with the activity (issue #624). On a pull request the branch and the pull
+ * request exist, so the words are the ones this envelope always had. On a work item neither is certain: the
+ * previous run may have opened nothing (it concluded there was nothing to change, or it stopped to ask), and
+ * "push to the same branch ... do not open a second" would leave the work on a branch nobody reviews while the
+ * human who asked waits on the work item for a reply. So the issue form names the issue branch, checks for its pull
+ * request first, and replies where the activity came from. No replica argument: run.resume refuses replicas.
+ */
+function resumedActionLines(target, n) {
+	if (target?.type === "pull_request") {
+		return [
+			"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
+			"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
+			"not. Do not open a second pull request -- your push updates the existing one.",
+		];
+	}
+	const branch = issueBranch(n);
+	return [
+		"Address the activity quoted below, then reply on the work item saying what you did or why you could not.",
+		`If it asks for changes, commit them to \`${branch}\` and publish with \`git push --force-with-lease\` to that`,
+		`branch only. Check first for an active pull request from it (\`az repos pr list --source-branch ${branch} --status active\`):`,
+		`if one exists your push updates it, so do not create another; only if none exists, run \`az repos pr create --source-branch ${branch}\`.`,
+	];
+}
+
 function buildResumedPrompt(flow, target, comment, instructions) {
 	const n = normalizeNumber(target?.number);
 	const noun = target?.type === "pull_request" ? "pull request" : "work item";
@@ -81,9 +106,7 @@ function buildResumedPrompt(flow, target, comment, instructions) {
 		`\`az repos pr show --id ${n}\` (or \`az boards work-item show --id ${n}\`) before doing anything,`,
 		`then follow the "${flow}" skill from the top.`,
 		"",
-		"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
-		"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
-		"not. Do not open a second pull request -- your push updates the existing one.",
+		...resumedActionLines(target, n),
 		"",
 		// Above the never-merge paragraph, so the harness has the last word before the data region.
 		...(instructionBlock(instructions) ? [instructionBlock(instructions), ""] : []),

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";
@@ -31,7 +31,7 @@ import { DOLLAR_ENV_NAMES, DOLLAR_WINDOW_KEYS, checkDollarInvariant, optionalUsd
  */
 export const DEFAULT_VALKEY_URL = "redis://127.0.0.1:6379";
 /** The model a job runs on when nothing names one (`PI_MODEL` unset): one copy, for `loadConfig` and doctor. */
-export const DEFAULT_MODEL = "claude-sonnet-4-5-20250929";
+export const DEFAULT_MODEL = "claude-sonnet-5-5";
 /** The provider a job runs on when nothing names one (`PI_PROVIDER` unset). */
 export const DEFAULT_PROVIDER = "anthropic";
 
@@ -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(
@@ -394,7 +402,7 @@ export function globalExtensionsEnabled(env) {
  * spend caps above, the per-job token scoping, or the admin-extension recursion block.
  */
 export function loadConfig(env = process.env, { fileExists = existsSync } = {}) {
-	const model = env.PI_MODEL ?? DEFAULT_MODEL; // dated snapshot; deterministic per CONST-PI-VERSION-PINNED
+	const model = env.PI_MODEL ?? DEFAULT_MODEL; // an exact model version, not a moving alias; deterministic per CONST-PI-VERSION-PINNED
 	// #227. Hoisted above the object because `defaultBackend` INDEXES `backends`, and a property cannot read
 	// a sibling of the literal it is in. (Calling the parser twice would be harmless -- `egressEnabled` is
 	// called twice a few properties down for the same reason -- so this is about the index, not the throw.)

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";
@@ -367,7 +367,7 @@ function resolveEnvName(provider) {
  * `allowGlobalExtensions` defaults to TRUE here, matching loadConfig's default (REQ-GLOBAL-PI-OVERLAY): a
  * caller that says nothing gets the operator's staged setup, and only an explicit `false` withholds it.
  */
-export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], mcpServers = [], allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false }) {
+export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], mcpServers = [], awaitInput = false, allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false }) {
 	// The provider credential(s), by pi's expected variable name(s) -- from the worker env, or (when
 	// PI_AUTH_FROM_PI is set and the env has none) host-side from pi's auth.json. Throws (config) if
 	// neither source yields one, which the processor turns into a policy refusal that refunds any reserve
@@ -433,6 +433,9 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 		// runner can hold `/job/mcp.json` to the names the worker meant. Comma-safe for excludeTools' reason (the loader
 		// admits only lowercase letters, digits and `-`). Absent means none, never an empty string.
 		PI_MCP_SERVERS: mcpServers.length > 0 ? mcpServers.join(",") : undefined,
+		// The trigger's run.awaitInput (issue #625): "1" offers the job the tool a parked run ends on. Absent means not
+		// armed, never "0" or an empty string, for PI_PACKAGES' reason.
+		PI_AWAIT_INPUT: awaitInput === true ? "1" : undefined,
 		// The job's EFFECTIVE allowed-model list (issue #502): its trigger's `run.models`, else the deployment's
 		// PI_ALLOWED_MODELS. Comma-joined `provider/model` entries, which the runner splits at each entry's first `/`
 		// (image/runner/src/config.mjs). Comma is safe because both list parsers refuse an entry carrying one. NULL is
@@ -555,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.
 	//
@@ -580,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,30 +4,49 @@
  *
  * 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.
  */
 
 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}`;
@@ -73,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.
@@ -85,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;
 	}
 
 	/**
@@ -153,7 +170,81 @@ export function makeForgejoHost({ apiUrl, fetchFn = fetch } = {}) {
 		return { headRef: pr?.head?.ref, headRepo: pr?.head?.repo?.full_name };
 	}
 
-	return { resolveDefaultBranchSha, isDefaultBranchProtected, postStatusComment, resolvePullRequestHead };
+	/**
+	 * 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);
+		const send = async (method, path, body, accept = []) => {
+			let res;
+			try {
+				res = await fetchFn(`${root}${path}`, {
+					method,
+					headers: { Authorization: `token ${token}`, "content-type": "application/json" },
+					...(body !== undefined && { body: JSON.stringify(body) }),
+					redirect: "error",
+				});
+			} catch (err) {
+				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) {
+			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;
+		}
+		// 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/forgejo-prompt.mjs

@@ -74,6 +74,31 @@ function prReplicaLines(replica, replicas) {
  * toward the full envelope, and a bare "address the feedback" over a cold session is an agent with no idea
  * what it was asked to do. `tea`, never `gh`: this envelope's whole reason for existing.
  */
+/**
+ * What a resumed run is told to do with the activity (issue #624). On a pull request the branch and the pull
+ * request exist, so the words are the ones this envelope always had. On an issue neither is certain: the
+ * previous run may have opened nothing (it concluded there was nothing to change, or it stopped to ask), and
+ * "push to the same branch ... do not open a second" would leave the work on a branch nobody reviews while the
+ * human who asked waits on the issue for a reply. So the issue form names the issue branch, checks for its pull
+ * request first, and replies where the activity came from. No replica argument: run.resume refuses replicas.
+ */
+function resumedActionLines(target, n) {
+	if (target?.type === "pull_request") {
+		return [
+			"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
+			"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
+			"not. Do not open a second pull request -- your push updates the existing one.",
+		];
+	}
+	const branch = issueBranch(n);
+	return [
+		"Address the activity quoted below, then reply on the issue saying what you did or why you could not.",
+		`If it asks for changes, commit them to \`${branch}\` and publish with \`git push --force-with-lease\` to that`,
+		`branch only. Check first for an open pull request from it (\`tea pr list --state open\`, look for \`${branch}\`):`,
+		`if one exists your push updates it, so do not open a second; only if none exists, run \`tea pr create --head ${branch}\`.`,
+	];
+}
+
 function buildResumedPrompt(flow, target, comment, instructions) {
 	const n = normalizeNumber(target?.number);
 	const noun = target?.type === "pull_request" ? "pull request" : "issue";
@@ -86,9 +111,7 @@ function buildResumedPrompt(flow, target, comment, instructions) {
 		`If you do not recognise this ${noun}, treat this as a fresh start: read it with \`tea pr ${n}\``,
 		`(or \`tea issue ${n}\`) before doing anything, then follow the "${flow}" skill from the top.`,
 		"",
-		"Address the activity quoted below. If it asks for changes, make them, push to the same branch with",
-		"`git push --force-with-lease`, and reply on the pull request saying what you did or why you could",
-		"not. Do not open a second pull request -- your push updates the existing one.",
+		...resumedActionLines(target, n),
 		"",
 		// Above the never-merge paragraph, so the harness has the last word before the data region.
 		...(instructionBlock(instructions) ? [instructionBlock(instructions), ""] : []),