@edgehero/pi-dispatch 2.0.0 → 3.0.0

package/src/env-allowlist.mjs

@@ -1,12 +1,13 @@
 /**
  * Build the EXACT environment a job container receives. Never a pass-through.
  *
- * `no-broad-env-into-container` is a BLOCKER, and for good reason: `ANTHROPIC_OAUTH_TOKEN`
- * silently outranks `ANTHROPIC_API_KEY`, so one stray host variable would redirect which
- * credential every job spends, with no error and no log line. So we forward a closed set.
+ * `no-broad-env-into-container` is a BLOCKER, and for good reason: `ANTHROPIC_OAUTH_TOKEN` (and, from
+ * the pi 0.99.1 pin on, `ANTHROPIC_AUTH_TOKEN` ahead of it) silently outranks `ANTHROPIC_API_KEY`, so one
+ * stray host variable would redirect which credential every job spends, with no error and no log line.
+ * So we forward a closed set.
  *
  * The provider key variable is DERIVED from pi's own table, not hardcoded. Deriving it means any of
- * pi's ~30 providers works with no code change here, and the list cannot drift when pi adds one, as a
+ * pi's ~40 providers works with no code change here, and the list cannot drift when pi adds one, as a
  * hand-copied table would. `getApiKeyEnvVars` (that table) is intentionally NOT exported by pi, which
  * is why `providerKeyCandidates` below has to recover it a different way.
  *
@@ -32,6 +33,8 @@ import { egressEnv } from "./egress.mjs";
 import { forgeSpec } from "./forges.mjs";
 import { apiKeyVariable } from "./provider-key.mjs";
 import { isDeterminateFsCode } from "./transient.mjs";
+import { KEYLESS_HOW, keylessVerdict } from "./model-endpoints.mjs";
+import { KEYLESS_ENV_NAME } from "./reserved-env.mjs";
 
 function configError(message) {
 	const error = new Error(message);
@@ -89,10 +92,12 @@ export function providerKeyCandidates(provider) {
  * `getProviders` from "/compat", which is a @deprecated alias for this exact function and reaching it
  * means loading compat's module-scope provider registration.
  *
- * Only ever consulted AFTER `providerKeyCandidates` comes back empty, and the order is load-bearing:
- * the catalog is NOT a superset of the ids `findEnvKeys` answers for. `radius` is a purely dynamic
- * provider with a real key variable (PI_GATEWAY_API_KEY) and no catalog entry, so asking this first
- * would call a working configuration unknown.
+ * Only ever consulted AFTER `providerKeyCandidates` comes back empty. At the 0.80.7 pin that order was
+ * load-bearing: `radius` was a purely dynamic provider with a real key variable and no catalog entry, so
+ * asking this first would have called a working configuration unknown. At the 0.99.1 pin (issue #509)
+ * radius is a builtin provider (key variable RADIUS_API_KEY) and the catalog covers every id pi reads a key
+ * for; env-allowlist.test.mjs pins that, and the order stays because it costs nothing and is the safe one
+ * the day the two diverge again.
  */
 export function piProviders() {
 	return getBuiltinProviders();
@@ -108,8 +113,15 @@ export function piProviders() {
  * API-key credentials only; an OAuth/subscription login is refused (it expires, the container cannot refresh
  * it, and it is not the credential for an unattended service). Throws a config-tagged error (pre-spend
  * refusal) when neither source yields a credential.
+ *
+ * Third way in (issue #503), only for a provider pi does not know: a custom provider in the overlay `models.json`
+ * whose every model is served by a declared `keyless` model endpoint passes with no credential, and the answer is
+ * `{ PI_DISPATCH_KEYLESS: "keyless" }`, the fixed value its `"apiKey": "$PI_DISPATCH_KEYLESS"` resolves to in the job.
+ * `modelEndpoints` is the pickup's snapshot `{ endpoints, models }` (never a read of its own), so the free gate and
+ * the container env decide on the same declaration. A builtin provider whose baseUrl an operator pointed at a local
+ * server is NOT keyless (a named residual): pi knows it, so it still needs its key.
  */
-export function resolveProviderCredential({ provider, hostEnv, authFromPi = false, agentDir, readFile = readFileSync, forwardEnv = [] }) {
+export function resolveProviderCredential({ provider, hostEnv, authFromPi = false, agentDir, readFile = readFileSync, forwardEnv = [], modelEndpoints = null }) {
 	// The NAMES come from pi, the VALUES from `hostEnv`, and this asks each question of the thing that can
 	// answer it (issue #311). It used to be one `providerKeyVars(provider, hostEnv)` call, which conflates
 	// them: that is `findEnvKeys`, whose presence test falls back to the REAL `process.env` for any name the
@@ -126,9 +138,52 @@ export function resolveProviderCredential({ provider, hostEnv, authFromPi = fals
 	// is the DI seam that was dishonest, which is worth fixing where the seam is the whole test surface.
 	// ONE read per name, checked and returned, for the same reason: two reads could decide on one value and
 	// ship another.
-	const held = providerKeyCandidates(provider)
+	const candidates = providerKeyCandidates(provider);
+	// Issue #503: a provider pi does not know at all. The same two questions, in the same order, as the auth.json
+	// refusal below and doctor's `noKeyVariableCheck`: no key variable, and not in pi's catalog. Such a provider can
+	// never take a key through this gate (there is no variable to write it under), so it is answered HERE, before
+	// auth.json is read: either it is keyless, or it is refused with both ways in named. That used to be decided
+	// after an auth.json read, which could only end in a refusal too, and whose wording ("set the key in .env, or run
+	// `pi login`") was advice no custom provider can follow.
+	if (candidates.length === 0 && !piProviders().includes(provider)) {
+		const ids = keylessEndpointsFor(provider, modelEndpoints);
+		// The one variable this branch writes, fixed and non-secret. It is the credential's slot in the closed map,
+		// so buildContainerEnv carries it exactly when this gate passes keyless, and on no other job.
+		if (ids !== null) return { [KEYLESS_ENV_NAME]: KEYLESS_VALUE };
+		// The overlay could not be read at this pickup for a TRANSIENT reason (index.mjs, `modelsUnreadable`): the provider
+		// may well be keyless, so this is no verdict at all. UNTAGGED and marked transient, never `piDispatchConfig`: a
+		// config refusal is permanent, refunded and commented publicly, and the same job may pass on the next attempt. The
+		// processor turns this into an infra retry (CONST-RETRY-INFRA-ONLY); absent or invalid JSON stays determinate.
+		const unreadable = modelEndpoints?.modelsUnreadable;
+		if (unreadable && Array.isArray(modelEndpoints?.endpoints) && modelEndpoints.endpoints.length > 0) {
+			const error = new Error(`the overlay models.json could not be read at this pickup (${unreadable.code}), so whether provider "${provider}" is keyless is not known yet`);
+			error.piDispatchTransient = true;
+			error.code = unreadable.code;
+			throw error;
+		}
+		throw configError(unknownProviderMessage(provider));
+	}
+	const held = candidates
 		.map((name) => [name, hostEnv[name]])
 		.filter(([, value]) => value);
+	// EVERY held candidate is forwarded, in pi's order, including the two that are not API keys: a host
+	// ANTHROPIC_OAUTH_TOKEN and (from the 0.99.1 pin, issue #509) a host ANTHROPIC_AUTH_TOKEN, which pi reads
+	// FIRST among the variables and sends as `Authorization: Bearer`. Forwarded rather than refused, and the
+	// choice is the same one for both: the operator put the variable in the worker's environment, a gateway
+	// bearer token is a legitimate service credential, and the job env should carry what the worker's own
+	// environment says rather than a filtered version of it.
+	//
+	// That does NOT make the job agree with pi on this host in every case, and the case where it does not
+	// is stated rather than implied: the ENVIRONMENT is this function's first source and auth.json only its
+	// fallback, while pi itself takes a stored api_key credential FIRST (pi-ai/dist/auth/helpers.js, "a
+	// stored credential key wins") and the environment only without one. So with an api_key login in
+	// auth.json AND a host token set, the job spends the token while `pi` on the host would spend the stored
+	// key. Kept that way because the env-first order is this function's documented contract (its header)
+	// and the token is the operator's explicit setting; `doctor` is where it is said out loud, a warning
+	// that names the API key the token shadows and, in this case, that the auth.json key is not used while
+	// the token is set.
+	// What is NEVER done is WRITING an auth.json key under either token name: that choice is
+	// `apiKeyVariable`'s, below.
 	if (held.length > 0) {
 		return Object.fromEntries(held);
 	}
@@ -136,7 +191,26 @@ export function resolveProviderCredential({ provider, hostEnv, authFromPi = fals
 		const { name, value } = credentialFromPiAuth(provider, agentDir ?? defaultAgentDir(hostEnv), readFile, { hostEnv, forwardEnv });
 		return { [name]: value };
 	}
-	throw configError(`provider ${provider} has no configured credential in the worker environment`);
+	throw configError(`provider ${provider} has no configured credential in the worker environment. Set its key there, or, ${KEYLESS_HOW}.`);
+}
+
+/** The value of `PI_DISPATCH_KEYLESS`: fixed and non-secret, since the model server takes no key. */
+export const KEYLESS_VALUE = "keyless";
+
+/**
+ * The keyless endpoint ids serving this provider, or null (issue #503). Asked only for a provider pi does not know (the
+ * caller's predicate), against the pickup's snapshot `{ endpoints, models }` (index.mjs, one read per pickup). No
+ * snapshot, or no endpoint declared, is null: with nothing declared the overlay is never read, and nothing is keyless.
+ */
+export function keylessEndpointsFor(provider, modelEndpoints) {
+	const endpoints = modelEndpoints?.endpoints;
+	if (!Array.isArray(endpoints) || endpoints.length === 0) return null;
+	const verdict = keylessVerdict({ models: modelEndpoints.models, provider, endpoints });
+	return verdict.keyless ? verdict.endpoints : null;
+}
+
+function unknownProviderMessage(provider) {
+	return `pi has no provider "${provider}", so there is no key variable to give it a key. Use one of pi's provider ids with its key in the worker environment or in pi's auth.json, or, ${KEYLESS_HOW}.`;
 }
 
 function defaultAgentDir(hostEnv) {
@@ -215,8 +289,8 @@ function credentialFromPiAuth(provider, agentDir, readFile, { hostEnv = {}, forw
 	const name = resolveEnvName(provider);
 	if (!name) {
 		// Two different facts, and they need different fixes -- the same split `doctor` makes, in the same
-		// order (candidates first, catalog second: `radius` has a key variable and no catalog entry, so
-		// asking membership first would call a working configuration unknown). The old message said "set it
+		// order (candidates first, catalog second: at 0.80.7 `radius` had a key variable and no catalog entry,
+		// so asking membership first would have called a working configuration unknown). The old message said "set it
 		// in the worker environment manually" for BOTH, which for the first is advice `doctor` correctly
 		// calls impossible: there is no variable to set.
 		if (piProviders().includes(provider)) {
@@ -224,7 +298,9 @@ function credentialFromPiAuth(provider, agentDir, readFile, { hostEnv = {}, forw
 				`pi authenticates "${provider}" without an API-key environment variable (an AWS profile or an OAuth login), and the container env is a closed set of variables, so it has no way in. Configure a provider whose credential is a single environment variable.`,
 			);
 		}
-		throw configError(`could not determine the environment variable pi expects for provider "${provider}" — pi has no such provider, so check PI_PROVIDER against pi's own ids`);
+		// Unreachable through resolveProviderCredential, which answers an unknown provider before auth.json is read. Kept
+		// as the backstop with the same words, so a later caller cannot reopen the old advice.
+		throw configError(unknownProviderMessage(provider));
 	}
 	return { name, value: cred.key };
 }
@@ -239,7 +315,7 @@ function credentialFromPiAuth(provider, agentDir, readFile, { hostEnv = {}, forw
  * plus a conventional `<PROVIDER>_API_KEY`/`_KEY`. That convention is the part that drifts, and it was
  * wrong for 13 of the 34 provider ids that have a key variable at the pin -- `google` is
  * `GEMINI_API_KEY`, `huggingface` is `HF_TOKEN`, `moonshotai` is `MOONSHOT_API_KEY`, `github-copilot` is
- * `COPILOT_GITHUB_TOKEN`, `radius` is `PI_GATEWAY_API_KEY` -- so for those pi recognized nothing and a
+ * `COPILOT_GITHUB_TOKEN`, `radius` was `PI_GATEWAY_API_KEY` (RADIUS_API_KEY at 0.99.1) -- so for those pi recognized nothing and a
  * valid `pi login` refused every job. The convention happening to be right for the other 21 is what let
  * this survive: `anthropic` and `openai` are both in that set.
  *
@@ -251,7 +327,9 @@ function credentialFromPiAuth(provider, agentDir, readFile, { hostEnv = {}, forw
  * environment where every name is present -- which also closes a hermeticity hole the synthetic object
  * had: pi's `getProviderEnvValue` falls back to the real `process.env`, so on a host that exported
  * `ANTHROPIC_OAUTH_TOKEN` the old code resolved to THAT name. `apiKeyVariable` then picks the same
- * variable `doctor` names, from the same module, so the two cannot diverge again.
+ * variable `doctor` names, from the same module, so the two cannot diverge again. It skips both
+ * non-API-key kinds: the OAuth token, and (from the 0.99.1 pin, issue #509) the bearer token
+ * ANTHROPIC_AUTH_TOKEN, which pi lists first and sends as `Authorization: Bearer`.
  */
 function resolveEnvName(provider) {
 	return apiKeyVariable(providerKeyCandidates(provider));
@@ -273,12 +351,14 @@ 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, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync }) {
+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 = [], 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
 	// (issue #310); the same call is made by its free credential gate, before anything is reserved at all.
-	const credEnv = resolveProviderCredential({ provider, hostEnv, authFromPi, agentDir, readFile, forwardEnv });
+	// `modelEndpoints` is the pickup's snapshot (issue #503): the keyless branch answers `PI_DISPATCH_KEYLESS` in this
+	// map, so the variable is set exactly when the gate passed keyless and is absent on every other job.
+	const credEnv = resolveProviderCredential({ provider, hostEnv, authFromPi, agentDir, readFile, forwardEnv, modelEndpoints });
 
 	const env = {
 		PI_PROVIDER: provider,
@@ -333,6 +413,13 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId,
 		// second-validator rule directly above). Absent means the full pinned default set, never an empty
 		// string, for PI_PACKAGES' reason.
 		PI_EXCLUDE_TOOLS: excludeTools.length > 0 ? excludeTools.join(",") : 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
+		// unrestricted and emits NO variable, never an empty string: the runner refuses an empty value as a config
+		// error, because an empty allow list read as "unset" would fail open. An image too old to enforce a list is
+		// refused before this is ever built (`modelPolicy`, CAPABILITY_GATES).
+		PI_ALLOWED_MODELS: Array.isArray(allowedModels) && allowedModels.length > 0 ? allowedModels.join(",") : undefined,
 		// Kill switch for job-time package installation, UNCONDITIONAL for every job. pi's resolver shells out
 		// to a REAL `npm install` for any npm:/git: source unless offline mode is on, and `~/.pi/agent` IS
 		// writable in the container. We emit only local paths, so nothing should reach that branch -- this
@@ -408,6 +495,43 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId,
 	// env-internal HOME: written into the job's closed env map here, never read from the worker's environment.
 	if (typeof home === "string" && home !== "") env.HOME = home;
 
+	// Issue #503: PI_DISPATCH_KEYLESS is the credential gate's answer and nothing else's, so it is settled AFTER the
+	// PI_FORWARD_ENV and secrets loops, as HOME and the egress variables are: both lists refuse the name upstream, and
+	// this is the backstop that keeps a value from either one from replacing it, or from appearing on a keyed job.
+	if (credEnv[KEYLESS_ENV_NAME] === KEYLESS_VALUE) env[KEYLESS_ENV_NAME] = KEYLESS_VALUE;
+	else delete env[KEYLESS_ENV_NAME];
+
+	// Issue #501: the per-job dollar cap is the worker's answer and nothing else's, so it is settled again AFTER the
+	// PI_FORWARD_ENV and secrets loops, PI_DISPATCH_KEYLESS's backstop. Both lists refuse the name upstream (config.mjs
+	// refuses every CONTAINER_ENV_NAMES member in PI_FORWARD_ENV at boot, #502; the loader refuses it in run.secrets);
+	// this is the line that holds if either refusal is ever bypassed. A forwarded or secret PI_MAX_COST_MICROS would
+	// otherwise replace the computed cap (measured: a host value of 1e12 beat a computed 500000), and on a job with
+	// no cap it would send one past the `costCap` gate, which only runs for capped jobs, to an image that may ignore it.
+	// It is set ONLY here, once, after both loops. `!== null`, never truthiness: 0 is a real cap (no priced call at
+	// all, which a fail-closed job value reads as, `effectiveCostCapMicros`), and a truthy test would send NO cap for
+	// it, the widest one there is. Absent (null or undefined) leaves no variable, so a job with no cap carries the env
+	// it always did, and never an empty string (the runner refuses one).
+	// env-internal PI_MAX_COST_MICROS: written into the job's closed env map here, never read from the worker's environment.
+	if (maxCostMicros === null || maxCostMicros === undefined) delete env.PI_MAX_COST_MICROS;
+	else env.PI_MAX_COST_MICROS = String(maxCostMicros);
+
+	// Issue #545: the exit line's key waits on the container's stdin, and this variable tells the runner to read it.
+	// The value names the channel and is never the key: the environment is readable from /proc/1/environ by every
+	// process in the container (measured), which is why the key does not travel here. Settled after both loops like
+	// the cap above, and ONLY for a run the worker actually hands a key, so a runner never blocks on a stdin no one
+	// writes. `=== true`, so only run-container's own boolean asks for it.
+	// env-internal PI_EXIT_AUTH: written into the job's closed env map here, never read from the worker's environment.
+	if (exitAuth === true) env.PI_EXIT_AUTH = "stdin";
+	else delete env.PI_EXIT_AUTH;
+
+	// Issue #500: the runner sets these two in its own environment, for its child processes, and no value from outside
+	// may arrive first. Both lists refuse them upstream (config.mjs for PI_FORWARD_ENV, the triggers loader for
+	// run.secrets, through RUNNER_ENV_NAMES); this is the line that holds if either refusal is ever bypassed.
+	// env-internal PI_DISPATCH_CHILD_LEDGER: set by the runner inside the container, never by the worker, so removed here.
+	delete env.PI_DISPATCH_CHILD_LEDGER;
+	// env-internal PI_DISPATCH_RUNNER_PID: set by the runner inside the container, never by the worker, so removed here.
+	delete env.PI_DISPATCH_RUNNER_PID;
+
 	// 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
 	// each CLI has its own preference -- gh prefers GH_TOKEN over GITHUB_TOKEN, glab prefers GITLAB_TOKEN

package/src/env-file.mjs

@@ -17,7 +17,7 @@
  * Deliberately dependency-free (node:fs only, and only in the thin wrapper): it must stay importable
  * from any future setup command without dragging worker config or queue deps along.
  */
-import { chmodSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, chownSync, closeSync, constants as fsConstants, fchmodSync, fchownSync, fstatSync, fsyncSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 
 /**
  * Pure transform over .env TEXT: set `key` to `value` only where nothing is set yet.
@@ -104,6 +104,15 @@ function replacementLines(key, value, bare, wasComment, opts) {
  * character, a `"`, a `%`, a `!`, a `^`, a character outside ASCII, and an `=` at the start of the value. Each
  * row there says whether it is cmd's documented behaviour or a cautious refusal. `'` is ordinary there.
  */
+/**
+ * The `code` on every error `renderEnvValue` throws (issue #522): the VALUE cannot be written, so a caller may add advice
+ * about the value (`up` says where its path came from). Every other refusal of the writer is about the FILE and carries
+ * its own fix, and `up` once gave those this one's advice, telling a gid mismatch to move the deployment somewhere
+ * "without that character in its path".
+ */
+export const ENV_VALUE_UNWRITABLE = "ENV_VALUE_UNWRITABLE";
+const unwritableValue = (message) => Object.assign(new Error(message), { code: ENV_VALUE_UNWRITABLE });
+
 export function renderEnvValue(value, { platform = process.platform } = {}) {
 	const v = String(value);
 	// The Windows loader keeps surrounding quotes as part of the value ("Values MUST be UNQUOTED", its own
@@ -111,16 +120,16 @@ export function renderEnvValue(value, { platform = process.platform } = {}) {
 	// refused rather than dressed in quotes that become part of a path.
 	if (platform === "win32") {
 		const bad = cmdValueRefusal(v);
-		if (bad !== null) throw new Error(`cannot write this value into a .env on Windows: it contains ${bad}, and the .cmd wrapper (deploy/worker-env-wrapper.cmd) cannot be shown to read that back as written. Choose a value without it, or give the service this key through its own environment (pi-dispatch service install --env-setup)`);
+		if (bad !== null) throw unwritableValue(`cannot write this value into a .env on Windows: it contains ${bad}, and the .cmd wrapper (deploy/worker-env-wrapper.cmd) cannot be shown to read that back as written. Choose a value without it, or give the service this key through its own environment (pi-dispatch service install --env-setup)`);
 		return v;
 	}
 	if (UNQUOTED_PLAIN.test(v)) return v;
-	if (v.includes("'") || /[\n\r]/.test(v)) throw new Error(`cannot write this value into a .env safely: ${v.includes("'") ? "it contains a single quote" : "it contains a newline"}`);
+	if (v.includes("'") || /[\n\r]/.test(v)) throw unwritableValue(`cannot write this value into a .env safely: ${v.includes("'") ? "it contains a single quote" : "it contains a newline"}`);
 	// Gate round 2 of PR #478: a control or invisible character is read alike by every loader inside single quotes, but
 	// the reader never vouches for it (`QUOTED_CONTROL`: printing it rewrites a terminal), so writing it quoted gave doctor
 	// a line it calls unread. Refused instead, naming the character, never the value.
 	const hidden = invisibleCharacter(v);
-	if (hidden !== null) throw new Error(`cannot write this value into a .env safely: it contains ${hidden}, which doctor would not show back. Remove it`);
+	if (hidden !== null) throw unwritableValue(`cannot write this value into a .env safely: it contains ${hidden}, which doctor would not show back. Remove it`);
 	return `'${v}'`;
 }
 
@@ -869,6 +878,104 @@ export function envFileEditCheck(content, path, key, value, opts = {}) {
 	return planEnvEdit(content, path, key, value, opts).error ?? null;
 }
 
+/**
+ * The group-mismatch refusal (issue #522), its own sentence with its own fix. The group is named where `/etc/group`
+ * names it, because "gid 0" sends an operator to look it up and `wheel` does not. It is reached only where the writer
+ * could not keep the group (`updateEnvFile` gives the new file the old one wherever this account is in it), and only
+ * for a file this account OWNS (the owner refusal comes first), so "run it as another account" is no fix: any other
+ * account, a member of that group or root, gets the owner refusal instead. The two fixes are this account joining that
+ * group (a new login picks it up), or a group this account is in: `own`, this process's primary group, which an
+ * owner can always give its file, and which every later rewrite then keeps. The second is the operator's decision where
+ * a service reads the file through its present group, so the sentence says so rather than issuing the chgrp.
+ */
+export function groupRefusal(target, group, made, own, groupName = groupNameOf) {
+	const named = (id) => {
+		const name = groupName(id);
+		return name ? `${name} (gid ${id})` : `gid ${id}`;
+	};
+	const fix = own === null ? "" : `; or, if nothing reads this file through its present group, run \`chgrp ${groupName(own) ?? own} ${quotedForShell(target)}\` and run this again`;
+	return `refusing to edit ${target}: its group is ${named(group)}, which this account could not give the new file, and a new file written beside it gets ${named(made)}, so rewriting it (a new file renamed over it) would change its group, which is how a .env the service reads through its group stops being readable. To fix it, add this account to ${groupName(group) ?? `gid ${group}`} and log in again${fix}; otherwise edit the file by hand. Nothing was written`;
+}
+
+/** A group's name from `/etc/group`, or `null` (no such line, no such file, or not a POSIX host). */
+export function groupNameOf(id, read = () => readFileSync("/etc/group", "utf8")) {
+	try {
+		for (const line of String(read()).split("\n")) {
+			if (line.startsWith("#")) continue;
+			const [name, , gid] = line.split(":");
+			// A digits-only field, so an empty one (which `Number` reads as 0) never names gid 0.
+			if (name && /^\d+$/.test(gid ?? "") && Number(gid) === id) return name;
+		}
+	} catch {
+		// No group database to read: the number alone is said.
+	}
+	return null;
+}
+
+/** `p` as one shell word: bare when it is plainly safe, single-quoted otherwise. */
+function quotedForShell(p) {
+	return /^[A-Za-z0-9_./@%+=:,-]+$/.test(p) ? p : `'${String(p).replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Every call `updateEnvFile` makes, for a production caller's fs seam to spread (issue #522's review). The descriptor
+ * calls are optional on the seam, because a test fake has none, so a seam that drops one does not fail: the writer
+ * quietly goes back to chowning and chmodding the tmp BY PATH, which a swapped tmp redirects. One list, spread by
+ * `up`, `service install` and `setup github`, and pinned by a test that reads all four objects.
+ */
+export const ENV_WRITER_FS = Object.freeze({ readFileSync, writeFileSync, renameSync, statSync, chmodSync, chownSync, realpathSync, unlinkSync, openSync, fstatSync, fchownSync, fchmodSync, fsyncSync, closeSync });
+
+/** `open(2)` flags for the tmp: created here or refused, never through a link (`O_NOFOLLOW` is POSIX-only; 0 elsewhere). */
+const EXCLUSIVE_CREATE = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | (fsConstants.O_NOFOLLOW ?? 0);
+
+/**
+ * The tmp, created exclusively at 0600 with `content`, and the four things the writer does to it. Through a DESCRIPTOR
+ * where the seam has one (every production seam), so a path swapped after the create is never what is chowned or
+ * chmodded; a seam without `openSync` (a test fake) gets the same calls by path, still with the exclusive create.
+ */
+function createTmp(fs, tmp, content) {
+	if (typeof fs.openSync === "function") {
+		const fd = fs.openSync(tmp, EXCLUSIVE_CREATE, 0o600);
+		try {
+			fs.writeFileSync(fd, content);
+		} catch (err) {
+			fs.closeSync(fd);
+			try {
+				fs.unlinkSync?.(tmp);
+			} catch {
+				// The write's error is the one to report.
+			}
+			throw err;
+		}
+		let open = true;
+		const shut = () => {
+			if (open) fs.closeSync(fd);
+			open = false;
+		};
+		return {
+			gid: () => fs.fstatSync(fd).gid,
+			chgrp: (g) => fs.fchownSync(fd, -1, g),
+			chmod: (m) => fs.fchmodSync(fd, m),
+			close: () => {
+				try {
+					fs.fsyncSync?.(fd);
+				} finally {
+					shut();
+				}
+			},
+			abandon: shut,
+		};
+	}
+	fs.writeFileSync(tmp, content, { mode: 0o600, flag: "wx" });
+	return {
+		gid: () => fs.statSync(tmp).gid,
+		chgrp: (g) => fs.chownSync(tmp, -1, g),
+		chmod: (m) => fs.chmodSync(tmp, m),
+		close: () => {},
+		abandon: () => {},
+	};
+}
+
 /**
  * Read → transform → write back ATOMICALLY (tmp + rename, the same shape as the admin's
  * writeTriggers), so a watcher or a concurrent reader never sees a half-written .env. When the
@@ -895,7 +1002,7 @@ export function updateEnvFile(path, key, value, deps = {}) {
 	// and the cmd wrapper kept the quotes, making the path the worker loads wrong behind a ✓ on the key
 	// that decides forge auth. A rendering rule that every writer of this file must remember is a rule one
 	// of them will forget.
-	const { fs = { readFileSync, writeFileSync, renameSync, statSync, chmodSync, realpathSync }, overwrite = false, platform = process.platform, narrow = false } = deps;
+	const { fs = ENV_WRITER_FS, overwrite = false, platform = process.platform, narrow = false } = deps;
 	// Every refusal is `planEnvEdit`'s (bytes first, never clobber, read back), made before anything is written.
 	const plan = planEnvEdit(fs.readFileSync(path), path, key, value, { overwrite, platform, verify: deps.verify });
 	if (plan.error) throw new Error(plan.error);
@@ -911,42 +1018,104 @@ export function updateEnvFile(path, key, value, deps = {}) {
 	} catch {
 		// Not resolvable (a dangling link, a fs without the call): edit the path we were given.
 	}
-	// OWNERSHIP, before anything is written. `renameSync` makes a new inode owned by whoever runs this, so
+	// OWNERSHIP, before the file is replaced. `renameSync` makes a new inode owned by whoever runs this, so
 	// a root- or `pi`-owned `.env` at 0640 that the service reads through its group comes back owned by the
 	// operator: the service account loses read access, and `deploy/worker.service` uses a bare
 	// `EnvironmentFile=` (fatal, not `-`), so the unit stops starting. Widening the mode to compensate
 	// would publish a file holding WEBHOOK_SECRET. Refusing is the only honest third option, and the caller
-	// turns it into a line rather than a stack trace.
+	// turns it into a line rather than a stack trace. Each refusal carries its own fix (issue #522).
 	const uid = typeof process.getuid === "function" ? process.getuid() : null;
 	const gid = typeof process.getgid === "function" ? process.getgid() : null;
+	let group = null;
 	if (uid !== null) {
 		try {
-			const { uid: owner, gid: group } = fs.statSync(target);
-			// GID as well as UID, because the layout this protects is a `.env` at 0640 read by the service
-			// THROUGH ITS GROUP. With `bob:pi 0640` and the operator in group `pi` the uid matches, the
-			// rename still makes a new inode with the writer's primary gid, and the `pi` service loses read
-			// access exactly as it would have on a uid mismatch.
-			if (typeof owner === "number" && owner !== uid) throw new Error(`refusing to edit ${target}: it is owned by uid ${owner} and this process is uid ${uid}, and rewriting it would hand it to the wrong account`);
-			if (typeof group === "number" && gid !== null && group !== gid) throw new Error(`refusing to edit ${target}: its group is gid ${group} and this process is gid ${gid}, and rewriting it would hand it to the wrong group, which is how a 0640 .env stops being readable by the service`);
+			const { uid: owner, gid: had } = fs.statSync(target);
+			if (typeof owner === "number" && owner !== uid) throw new Error(`refusing to edit ${target}: it is owned by uid ${owner} and this process is uid ${uid}, and rewriting it (a new file renamed over it) would give it to this account, which is how a .env the service reads stops being readable. To fix it, run this as the account that owns it, or edit the file by hand. Nothing was written`);
+			if (typeof had === "number") group = had;
 		} catch (err) {
 			if (err instanceof Error && err.message.startsWith("refusing to edit")) throw err;
 			// Cannot stat: fall through to the write, which will fail on its own terms if it must.
 		}
 	}
 	const tmp = `${target}.tmp`;
-	fs.writeFileSync(tmp, next, { mode: 0o600 });
+	// CREATED HERE, exclusively, or not at all (issue #522's review). The folder may be one another account can write (a
+	// setgid 2770 folder shared with the service's group), and a `.env.tmp` planted there as a symlink was followed by
+	// the write, by the chown that keeps the group, and by the chmod: content at the link's target, and that file's
+	// group and mode changed. `O_EXCL` refuses any existing path, a symlink included (POSIX: not followed), and
+	// `O_NOFOLLOW` says so twice where the platform has it; everything after the create goes through the descriptor, so
+	// a tmp swapped after the create is not what is chowned or chmodded. An existing tmp is refused and left alone: it is
+	// not this writer's to remove.
+	let handle;
 	try {
-		// The operator's mode, whatever it is, not just 0600. `.env` holds WEBHOOK_SECRET and provider
-		// keys, and a rename from a fresh tmp lands at the process umask: 0640 and 0400 both came back
-		// 0644, world-readable, on the one file this project says must never reach a scrollback.
-		// `narrow` keeps only the owner's bits of it.
-		const mode = fs.statSync(target).mode & 0o7777;
-		fs.chmodSync(tmp, narrow ? mode & 0o7700 : mode);
-	} catch {
-		// The file vanished between read and write, or the fs cannot stat: the tmp keeps the 0600 it was
-		// created with rather than failing an edit that is otherwise sound.
+		handle = createTmp(fs, tmp, next);
+	} catch (err) {
+		if (err?.code === "EEXIST" || err?.code === "ELOOP") throw new Error(`refusing to edit ${target}: ${tmp} already exists (left by an edit that was interrupted, or put there by another account that can write this folder), and this writer only writes through a file it has just created. Remove it, then run this again. Nothing was written`);
+		throw err;
+	}
+	// GROUP, as well as owner, because the layout this protects is a `.env` at 0640 read by the service THROUGH ITS GROUP:
+	// with `bob:pi 0640` and the operator in group `pi`, the uid matches and the rename can still change the group.
+	// MEASURED on the tmp, not predicted from this process's gid (issue #522). Which group a new file gets is the
+	// folder's business: on macOS and the BSDs it is always the folder's group, and on Linux it is the folder's group
+	// where the folder is setgid (or mounted `grpid`), else this process's. The prediction refused every edit to a
+	// `.env` that `init` had just made in a folder of group `wheel` (gid 0, as `/private/tmp` is): the file took the
+	// folder's group, this process's was `staff`, and the rewrite would have kept `wheel` all along. The tmp holds the
+	// new content at 0600 and is removed before the refusal, so nothing the operator reads has changed.
+	// EVERYTHING after the create removes the tmp on any failure (issue #522's review, round 2): a flush or a rename that
+	// throws (EPERM from a Windows scanner holding the file, a full disk at fsync) left this writer's OWN tmp behind, and
+	// every later edit then refused it as one that "already exists". Removing it here is safe where removing one found at
+	// the create is not: this one was created by this call, exclusively. The original error is rethrown; where the tmp
+	// cannot be removed, its message says where the new content was left instead of claiming nothing was written.
+	try {
+		if (group !== null) {
+			let made = null;
+			try {
+				made = handle.gid();
+			} catch {
+				// Cannot stat what was just written: predict as a folder without setgid would make it.
+			}
+			if (typeof made !== "number") made = gid;
+			// KEPT where this account may keep it: an owner may give a file any group it is in, so the tmp takes the file's
+			// group and the rewrite changes nothing (`bob:pi` with the operator in `pi`, or a `staff` file in a `wheel`
+			// folder). Refused only where that fails, which is a group this account is not in.
+			if (made !== null && made !== group) {
+				try {
+					handle.chgrp(group);
+					made = handle.gid();
+				} catch {
+					// EPERM, a group this account is not in: the refusal below says so.
+				}
+			}
+			if (made !== null && made !== group) {
+				throw new Error(groupRefusal(target, group, made, gid, deps.groupName ?? groupNameOf));
+			}
+		}
+		try {
+			// The operator's mode, whatever it is, not just 0600. `.env` holds WEBHOOK_SECRET and provider
+			// keys, and a rename from a fresh tmp lands at the process umask: 0640 and 0400 both came back
+			// 0644, world-readable, on the one file this project says must never reach a scrollback.
+			// `narrow` keeps only the owner's bits of it.
+			const mode = fs.statSync(target).mode & 0o7777;
+			handle.chmod(narrow ? mode & 0o7700 : mode);
+		} catch {
+			// The file vanished between read and write, or the fs cannot stat: the tmp keeps the 0600 it was
+			// created with rather than failing an edit that is otherwise sound.
+		}
+		handle.close();
+		fs.renameSync(tmp, target);
+	} catch (err) {
+		handle.abandon();
+		let removed = typeof fs.unlinkSync === "function";
+		try {
+			if (removed) fs.unlinkSync(tmp);
+		} catch {
+			removed = false;
+		}
+		if (!removed && err instanceof Error) {
+			const left = `${target} itself was not changed, but the new content was left in ${tmp} (mode 0600), which could not be removed: remove it`;
+			err.message = err.message.endsWith(". Nothing was written") ? `${err.message.slice(0, -"Nothing was written".length)}${left}` : `${err.message}. ${left}`;
+		}
+		throw err;
 	}
-	fs.renameSync(tmp, target);
 	return { changed: true, ...(narrow ? { narrowed: true } : {}) };
 }