@edgehero/pi-dispatch 1.10.3 → 2.1.0

package/src/env-allowlist.mjs

@@ -1,9 +1,38 @@
+/**
+ * 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` (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 ~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.
+ *
+ * **There was a second wrapper here, `providerKeyVars`, and it is GONE (issue #309).** It was a
+ * one-line pass-through to `findEnvKeys(provider, hostEnv)`, which filters pi's list by PRESENCE and
+ * returns a single `undefined` for both "no such provider" and "known provider, nothing set". Every
+ * caller it ever had asked it the wrong question: `resolveProviderCredential` wanted the names and
+ * read the values elsewhere (issue #311), and `secrets.mjs`'s reserved-name gate wanted what a trigger
+ * may not NAME, which is a property of the provider and not of this host. The presence filter also
+ * leaks: pi's `getProviderEnvValue` is `env?.[name] || process.env[name]`, so it reports names the
+ * MACHINE carries as well. It is deleted rather than re-documented because an exported helper that
+ * answers a subtly wrong question does not stay uncalled; both defects in this cluster were somebody
+ * reaching for it. pi's own behaviour is still pinned, against `findEnvKeys` directly, in
+ * `worker/test/env-allowlist.test.mjs`.
+ */
+
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 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 { apiKeyVariable } from "./provider-key.mjs";
+import { isDeterminateFsCode } from "./transient.mjs";
 
 function configError(message) {
 	const error = new Error(message);
@@ -12,25 +41,64 @@ function configError(message) {
 }
 
 /**
- * Build the EXACT environment a job container receives. Never a pass-through.
+ * An environment in which EVERY variable is set, used only to interrogate pi.
  *
- * `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.
+ * `findEnvKeys(provider, env)` filters pi's own candidate list by PRESENCE, so against an env where
+ * nothing is absent the filter is the identity and the return value IS pi's table for that provider,
+ * in pi's own precedence order. That is how `providerKeyCandidates` recovers a list pi deliberately
+ * does not export (`getApiKeyEnvVars` is module-private). It is a dependency on pi filtering rather
+ * than short-circuiting, which is stated here rather than discovered later: it holds at the pin, it is
+ * round-tripped for every provider by env-allowlist.test.mjs, and CONST-PI-VERSION-PINNED is what
+ * makes that test the upgrade gate.
  *
- * The provider key variable is DERIVED from pi's own table, not hardcoded. `findEnvKeys(provider,
- * env)` returns the provider's key variable names that are actually PRESENT in `env`, in
- * precedence order (OAuth before API key). Deriving it means:
- *   - any of pi's ~30 providers works with no code change here;
- *   - the list cannot drift when pi adds a provider (a hand-copied table would);
- *   - `undefined` return === "this provider is not configured on this host" === refuse the job
- *     BEFORE spending, rather than launch a container that will fail auth on the first call.
+ * A Proxy rather than a literal, and the second reason is the load-bearing one:
+ *   - the candidate NAMES are the thing being asked for, so they cannot be enumerated in advance;
+ *   - `getProviderEnvValue` (pi-ai/dist/utils/provider-env.js) falls back to the REAL `process.env`
+ *     for any name the injected env has no value for. A plain `{}` therefore answers with whatever the
+ *     machine happens to export -- a doctor run on a laptop would disagree with the server it is
+ *     diagnosing, and every test injecting a fake env would be non-hermetic. A trap that always returns
+ *     a non-empty string short-circuits that `||` before the fallback is reached.
+ * Strings only: a symbol read (Symbol.toPrimitive and friends) answering with a string would make this
+ * object lie about being one.
+ */
+const EVERY_VAR_SET = new Proxy({}, { get: (_target, name) => (typeof name === "string" ? "set" : undefined) });
+
+/**
+ * Every variable pi reads this provider's key from, in pi's precedence order, set or not. `[]` means pi
+ * reads no API-key variable for this id -- either there is no such provider, or it authenticates some
+ * other way. `piProviders` is what tells those two apart.
+ *
+ * This is the ONLY question this module asks pi about variable names, and that is the point (#286, #311,
+ * #309). Asking `findEnvKeys(provider, hostEnv)` instead answers "what does this HOST have", conflates
+ * "unknown provider" with "known provider, nothing set" in one `undefined`, and decides presence partly
+ * from the real `process.env`. Three callers wanted three different things from it and all three were
+ * better served by the candidate list plus a presence test of their own: `doctor` NAMES a variable an
+ * operator should set, `resolveProviderCredential` reads values out of the env it was handed, and
+ * `secrets.mjs` reserves what a trigger may not name.
+ */
+export function providerKeyCandidates(provider) {
+	// The string filter is on the RESULT, not just on the trap. pi looks its provider up in a plain object
+	// literal, so `__proto__` and `constructor` resolve up the prototype chain and hand back a non-string
+	// "variable name"; against a real environment that candidate reads as undefined and pi drops it, but
+	// an environment where everything is present keeps it, and doctor would print `set [object Object] in
+	// .env`. pricing.mjs guards pi's other generated lookups the same way and for the same reason.
+	return (findEnvKeys(provider, EVERY_VAR_SET) ?? []).filter((name) => typeof name === "string");
+}
+
+/**
+ * pi's provider catalog, through the same side-effect-free specifier `pricing.mjs` uses -- never
+ * `getProviders` from "/compat", which is a @deprecated alias for this exact function and reaching it
+ * means loading compat's module-scope provider registration.
  *
- * `getApiKeyEnvVars` (the full candidate list) is intentionally NOT exported by pi; `findEnvKeys`
- * against our own process.env is the right tool anyway, because we only ever forward keys we have.
+ * 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 providerKeyVars(provider, hostEnv) {
-	return findEnvKeys(provider, hostEnv);
+export function piProviders() {
+	return getBuiltinProviders();
 }
 
 /**
@@ -44,13 +112,49 @@ export function providerKeyVars(provider, hostEnv) {
  * 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.
  */
-export function resolveProviderCredential({ provider, hostEnv, authFromPi = false, agentDir, readFile = readFileSync }) {
-	const envNames = providerKeyVars(provider, hostEnv);
-	if (envNames && envNames.length > 0) {
-		return Object.fromEntries(envNames.map((name) => [name, hostEnv[name]]));
+export function resolveProviderCredential({ provider, hostEnv, authFromPi = false, agentDir, readFile = readFileSync, forwardEnv = [] }) {
+	// 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
+	// given env lacks, so a name could be "present" on the strength of the machine and then be read out of
+	// an env that does not carry it, yielding `{ NAME: undefined }` -- a credential-shaped answer with no
+	// credential in it, and no fall through to the auth.json login that would have worked.
+	//
+	// `providerKeyCandidates` is the hermetic half of the same oracle, so the leaky question is not asked at
+	// all rather than asked and corrected. The result is identical by construction: a name truthy in
+	// `hostEnv` is always one `findEnvKeys` would have returned, and pi's precedence order is preserved.
+	// Truthiness matches pi's own filter, so a name kept here is a name pi would read.
+	//
+	// Unreachable in the shipped worker, where `hostEnv` IS `process.env` and the two agree by identity. It
+	// 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)
+		.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);
 	}
 	if (authFromPi) {
-		const { name, value } = credentialFromPiAuth(provider, agentDir ?? defaultAgentDir(hostEnv), readFile);
+		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`);
@@ -61,13 +165,30 @@ function defaultAgentDir(hostEnv) {
 	return hostEnv.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
 }
 
-function credentialFromPiAuth(provider, agentDir, readFile) {
+function credentialFromPiAuth(provider, agentDir, readFile, { hostEnv = {}, forwardEnv = [] } = {}) {
 	const path = join(agentDir, "auth.json");
 	let auth;
 	try {
 		auth = JSON.parse(readFile(path, "utf8"));
-	} catch {
-		throw configError(`no credential for provider "${provider}": not in the worker environment, and no pi login at ${path} — set the key in .env, or run \`pi login\``);
+	} catch (error) {
+		// ONLY the determinate failures are tagged. This used to be a bare `catch {}` that relabelled every
+		// read failure as "no pi login", and issue #310 is what made that expensive: the processor now turns
+		// a `piDispatchConfig` error into a refusal that is never retried, refunds the reserve, and posts
+		// publicly that the deployment is misconfigured. Under the old catch an EMFILE from fd exhaustion, an
+		// EIO on a network filesystem, an EACCES, an EISDIR, or a torn read while `pi login` rewrites the file
+		// all produced that verdict, on a deployment that was correctly configured the microsecond before and
+		// after. A determinate refusal is one the same inputs reproduce; these are not.
+		//
+		// Absent is determinate (there is no login), and so is unparseable (the file is there and wrong, and
+		// an operator has to fix it). Everything else propagates untagged, which is `CONST-RETRY-INFRA-ONLY`
+		// putting it back where it belongs: an infrastructure fault reported as itself, with its own message.
+		// The codes come from the shared rule rather than a second copy of them here (issue #316): this
+		// file's argument IS that rule, and restating it was how the identity modules came to disagree
+		// with the host modules about the same three conditions.
+		const absent = isDeterminateFsCode(error?.code);
+		if (!absent && !(error instanceof SyntaxError)) throw error;
+		const why = absent ? `nothing readable at ${path}` : `the pi login at ${path} is not valid JSON`;
+		throw configError(`no credential for provider "${provider}": not in the worker environment, and ${why} — set the key in .env, or run \`pi login\``);
 	}
 	const cred = auth?.[provider];
 	if (!cred) throw configError(`no credential for provider "${provider}": not in the worker environment, and ${path} has no "${provider}" login — set the key in .env, or run \`pi login\``);
@@ -77,24 +198,86 @@ function credentialFromPiAuth(provider, agentDir, readFile) {
 		);
 	}
 	if (cred.type !== "api_key" || !cred.key) throw configError(`unsupported pi credential for "${provider}" in ${path} — set an API key in .env`);
-	const name = resolveEnvName(provider, cred);
+	// `typeof`, not truthiness. A hand-edited auth.json can hold a number, an array or an object here (pi
+	// parses the file and validates no schema), and the old `!cred.key` guard passed all three: an object
+	// became `-e ANTHROPIC_API_KEY=[object Object]` in a paid container. Issue #311 made this reachable for
+	// twelve more providers, so it is guarded here rather than left to the coercion.
+	if (typeof cred.key !== "string") throw configError(`the pi login for "${provider}" in ${path} does not hold a string API key — run \`pi login\` again, or set the key in .env`);
+	// **The worker forwards this value; pi RESOLVES it.** `auth-storage.js` reads the stored key through
+	// `resolveConfigValue(cred.key, cred.env)`, a grammar where a leading "!" runs the rest as a SHELL
+	// COMMAND and takes stdout, "$VAR"/"${VAR}" interpolate from the environment, and "$$"/"$!" escape. An
+	// environment variable is read raw, through no such grammar, so a login stored in any of those forms
+	// arrives in the container as its own source text and every job spends a container to fail auth, with
+	// `doctor` green because the field is a non-empty string.
+	//
+	// This REFUSES rather than resolving. Running the command host-side is not on the table (it would
+	// execute operator shell out of a credential file, per job, in the worker); interpolating "$VAR" would
+	// be reimplementing a grammar pi does not export, which is `no-reimplementing-pi` and the same trap
+	// #311 is about. The test is deliberately a superset of pi's parse: any "$" at all, not a parse of one.
+	// A key that pi would have passed through unchanged contains neither character, and over-refusing
+	// pre-spend costs nothing, which is exactly the trade `CONST-BUDGET-BEFORE-TOKENS` asks for.
+	if (cred.key.startsWith("!") || cred.key.includes("$")) {
+		throw configError(
+			`the pi login for "${provider}" in ${path} is a command or a variable reference, not a literal key. pi resolves that form itself; this service forwards the value to a container, where it is read as-is. Resolve it and set the key in .env instead.`,
+		);
+	}
+	// The credential's companion config (`cred.env`), which is NOT a variable-name hint -- it is a
+	// `Record<string, string>` of provider settings, and for both Cloudflare providers pi returns NO auth at
+	// all without `CLOUDFLARE_ACCOUNT_ID` (and `CLOUDFLARE_GATEWAY_ID` for the gateway). The container env
+	// is a closed set, so these names do not ride along with the key; pi does fall back to the ambient
+	// environment for them, which makes `PI_FORWARD_ENV` a real answer rather than a shrug. Refuse only for
+	// the names that will NOT arrive, so a deployment that already forwards them is untouched.
+	const missing = Object.keys(cred.env ?? {}).filter((n) => !(forwardEnv.includes(n) && hostEnv?.[n]));
+	if (missing.length > 0) {
+		throw configError(
+			`the pi login for "${provider}" carries provider settings the container will not receive (${missing.join(", ")}). The job env is a closed set. Set ${missing.join(" and ")} in the worker environment and list ${missing.length > 1 ? "them" : "it"} in PI_FORWARD_ENV.`,
+		);
+	}
+	const name = resolveEnvName(provider);
 	if (!name) {
-		throw configError(`could not determine the environment variable pi expects for provider "${provider}" — set it in the worker environment manually`);
+		// Two different facts, and they need different fixes -- the same split `doctor` makes, in the same
+		// 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)) {
+			throw configError(
+				`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`);
 	}
 	return { name, value: cred.key };
 }
 
 /**
- * The env var name pi reads this provider's key from. Discovered through pi's OWN `findEnvKeys` (the
- * oracle) rather than a hand-maintained provider→var table that would drift: try the credential's own
- * `env` hint plus the conventional `<PROVIDER>_API_KEY`/`_KEY`, and forward the one pi recognizes.
+ * The env var name to write this provider's `auth.json` api key under. `null` when pi reads no key
+ * variable for the provider at all, which `credentialFromPiAuth` turns into a refusal.
+ *
+ * The oracle instinct in the old version of this comment was right and its execution was not, which is
+ * worth recording rather than deleting (issue #311). It asked pi's own `findEnvKeys` rather than keeping a
+ * provider→var table, but the CANDIDATES it asked with were hand-generated: the credential's `env` field
+ * 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` 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.
+ *
+ * The `env` candidate was dead on arrival besides: at the pin `ApiKeyCredential.env` is a
+ * `Record<string, string>` of provider config (Cloudflare account and gateway ids), never a variable
+ * name, so the string filter dropped it on every call.
+ *
+ * `providerKeyCandidates` is pi's whole list, so there is nothing left to guess, and it asks against an
+ * 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. 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, cred) {
-	const upper = provider.toUpperCase().replace(/[^A-Z0-9]/g, "_");
-	const candidates = [cred.env, `${upper}_API_KEY`, `${upper}_KEY`].filter((s) => typeof s === "string" && s.length > 0);
-	const synthetic = Object.fromEntries(candidates.map((name) => [name, cred.key]));
-	const recognized = findEnvKeys(provider, synthetic);
-	return recognized?.[0] ?? null;
+function resolveEnvName(provider) {
+	return apiKeyVariable(providerKeyCandidates(provider));
 }
 
 /**
@@ -103,7 +286,9 @@ function resolveEnvName(provider, cred) {
  * run.github).
  *
  * Throws if the provider is not configured -- a deterministic misconfiguration the caller maps to
- * a pre-spend refusal, never a launched-then-failed container.
+ * a pre-spend refusal, never a launched-then-failed container. Both halves of that are real as of issue
+ * #310: the processor probes this resolution among its free gates, and classifies the throw if one still
+ * reaches it.
  *
  * `packagePaths` is the operator-staged pi package set for THIS job: already-resolved absolute
  * CONTAINER paths under the :ro overlay, empty for a job whose trigger opted OUT (or when nothing is staged).
@@ -111,11 +296,12 @@ function resolveEnvName(provider, cred) {
  * `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, authFromPi = false, egress = false, egressProxy, agentDir, readFile = readFileSync }) {
+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 }) {
 	// 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 pre-spend refusal.
-	const credEnv = resolveProviderCredential({ provider, hostEnv, authFromPi, agentDir, readFile });
+	// 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 });
 
 	const env = {
 		PI_PROVIDER: provider,
@@ -163,6 +349,13 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId,
 		// exclusive by parse (command XOR flow); that is deliberately NOT re-enforced here -- a second
 		// validator is a second place to disagree with the first.
 		PI_COMMAND: command || undefined,
+		// The trigger's run.excludeTools, STRUCTURALLY (issue #291): the pi tool names the runner must
+		// withhold from createAgentSession, so a "read-only" trigger stops being prompt text. Comma is a
+		// safe delimiter because the loader admits only names from its pinned built-in set, none of which
+		// carries one -- that is a load-time guarantee, deliberately NOT re-enforced here (PI_COMMAND's
+		// 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,
 		// 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
@@ -177,9 +370,14 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId,
 	// Operator-declared extra vars (PI_FORWARD_ENV), forwarded by EXACT name -- the allowlist
 	// no-broad-env-into-container prescribes, not a host pass-through. This is how a CUSTOM provider's
 	// key (one pi's findEnvKeys table does not know) reaches the container. A name whose value is unset
-	// on the host is skipped, never forwarded as empty.
+	// on the host is skipped, never forwarded as empty. That second half was a claim rather than a check
+	// until issue #311: the guard tested `!== undefined`, so a name set to "" WAS forwarded, and since this
+	// loop runs after the credential assign above, `PI_FORWARD_ENV=<the provider's key variable>` with a
+	// blank value in the host env blanked a working auth.json credential and the job spent a container to
+	// fail auth. Same emptiness rule as the secrets loop below, which had it right.
 	for (const name of forwardEnv) {
-		if (hostEnv[name] !== undefined) env[name] = hostEnv[name];
+		const value = hostEnv[name];
+		if (value !== undefined && value !== "") env[name] = value;
 	}
 
 	// The trigger's own secrets (REQ-TRIGGER-SECRETS), resolved HOST-SIDE by the processor before anything
@@ -226,6 +424,13 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId,
 	// turn. It rides the closed map, never PI_FORWARD_ENV, so arming the policy cannot half-work.
 	Object.assign(env, egressEnv({ proxy: egressProxy, armed: egress }));
 
+	// Issue #341: the job's HOME, only when the worker runs it under `--user` (`home` is passed then and only then).
+	// AFTER the PI_FORWARD_ENV and secrets loops, for the egress variables' reason: a forwarded or secret HOME must
+	// not win, because a uid with no passwd entry in the image would otherwise get `HOME=/` (Docker) or
+	// `HOME=/workspace` (Podman, measured), and pi's auth.json lands nowhere or in the operator's repository.
+	// 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;
+
 	// 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