@edgehero/pi-dispatch 2.1.0 → 3.1.0

package/src/project-id.mjs

@@ -0,0 +1,17 @@
+/**
+ * The project id rule (issue #499, INT-PROJECTS-FILE-CONTRACT), in a module with NO imports. `run-history.mjs` checks a
+ * record's `project` against it, and the admin loads run-history inside pi, so the record module must not drag the
+ * projects parser's graph (config.mjs and its fs, os and child_process) in with it: the rule `model-ref.mjs` keeps for
+ * the same reader. `projects.mjs` re-exports both names.
+ */
+
+/**
+ * A project id: lowercase, 1 to 32 characters, free of `:`, `#` and `/`, so it can enter a run record and a Valkey key
+ * without escaping.
+ */
+export const PROJECT_ID_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+/** Is this a well-formed project id? The record path's charset check. */
+export function isProjectId(value) {
+	return typeof value === "string" && PROJECT_ID_RE.test(value);
+}

package/src/projects.mjs

@@ -0,0 +1,238 @@
+/**
+ * Projects (issue #499, INT-PROJECTS-FILE-CONTRACT): a named group of repos and folders. One `projects.json` of
+ * `{ version: 1, projects: [{ id, name?, members }] }`. A job whose scope is a member belongs to that project, and the
+ * project's id is written into the job's run record (`project`), so spend can later be read and capped per project.
+ *
+ * This module is pure and fs-injectable, on the scoped-limits.mjs pattern: `parseProjects` validates the file TEXT
+ * fail-loud, `loadProjects` layers the one fs read on top, and `projectOf` is what the pickup gate and the record path
+ * consume. The worker holds the parsed list in a watched ref with a last-good copy (start.mjs).
+ *
+ * `version` is REQUIRED and a newer one is refused: which project a scope belongs to decides which cap applies to it
+ * (issue #499 part B), so this is a money file, and a field an old build silently drops could widen a cap.
+ *
+ * `name` is display text for the panel. It never enters a record or a log line: the record carries the `id`, which is
+ * charset-checked, and so stays free of personal data by construction. For the same reason no error message here
+ * quotes a name, and an invalid-JSON error does not quote the parser's message, which carries file text.
+ *
+ * Custom: projects validated inline per scoped-limits.mjs precedent; zod not in deps
+ */
+
+import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { configError } from "./config.mjs";
+import { fingerprint } from "./fingerprint.mjs";
+import { hash16 } from "./fleet-lease.mjs";
+import { PROJECT_ID_RE, isProjectId } from "./project-id.mjs";
+import { parseScopeString, qualifiedScopeOf } from "./pause-windows.mjs";
+import { canonicalScope } from "./scoped-limits.mjs";
+
+/** The highest schema version this build reads. A file declaring a higher one is refused loudly. */
+export const PROJECTS_VERSION = 1;
+
+// The id rule lives in an import-free module, so the run record can check an id without this module's graph.
+export { PROJECT_ID_RE, isProjectId };
+
+/** The longest `name` accepted, in UTF-16 code units. A display label, not a document. */
+const NAME_MAX = 120;
+
+/**
+ * Parse, validate and normalize the projects file TEXT. Returns the normalized list: each project rebuilt as an
+ * explicit `{ id, name, members }` literal (`name` null when absent, members in their stored spelling, unknown fields
+ * dropped by the operator-file policy). Throws `configError` on anything malformed. `path` is for messages only.
+ *
+ * Members use the scope grammar of `parseScopeString` (issue #498):
+ *   - a forge-qualified scope (`github:acme/web`), stored as `<kind>:<repo>`;
+ *   - an absolute folder (`/srv/shop-tools`), stored resolved, the spelling `canonicalScope` gives a local job.
+ * A bare `owner/name` is refused: it names that repo on every forge, and this file has no legacy to keep. A relative
+ * folder, a drive path on a host where it is not absolute, `*` and globs are refused too: each would be a member no
+ * job's scope can ever equal.
+ *
+ * Refused across the file: a duplicate id, a scope claimed by two projects (both ids named, one project per scope),
+ * a scope listed twice in one project, and an empty `members`.
+ */
+export function parseProjects(text, path) {
+	try {
+		return parseProjectsText(text, path);
+	} catch (error) {
+		// Every refusal ESCAPED at the source (PR #569's review): a folder member may hold a C1 or bidi character, and this
+		// message reaches the worker's `projects_reload_invalid` log line, doctor and an admin tool's error. JSON quoting
+		// keeps C0 visible but leaves C1, bidi and zero-width characters raw.
+		if (error?.piDispatchConfig === true) error.message = escapeControls(error.message);
+		throw error;
+	}
+}
+
+/**
+ * The characters `escapeControls` writes out, the SAME set the admin panel's `escapeInterpreted` escapes (PR #569's
+ * second review; `admin/test/projects.test.mjs` compares the two over every code point): the controls (C0, DEL, C1),
+ * every format character (bidi controls and isolates, zero-width and invisible ones, the tag block) but the two joiners
+ * that compose (U+200C, U+200D), the line and paragraph separators, every blank that is not U+0020 but draws one
+ * column (the no-break and fixed-width spaces, U+2800), the Hangul fillers, and the unassigned code points the
+ * terminal draws as nothing (U+2065, U+FFF0-U+FFF8, the special-purpose plane outside its variation selectors).
+ * U+3000 is kept, as the panel keeps it: it draws two columns, an ordinary full-width space.
+ */
+const ESCAPED = /(?![\u200c\u200d\u3000\u{e0100}-\u{e01ef}])[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Zs}\u2800\u115f\u1160\u3164\uffa0\u2065\ufff0-\ufff8\u{e0000}-\u{e0fff}]/gu;
+
+/**
+ * Text with the characters that change what a reader SEES written out as `\\u{XXXX}` (`ESCAPED`), U+0020 kept. For a
+ * message about operator text that reaches a log line or a terminal. The worker's twin of the panel's
+ * `escapeInterpreted`; it imports nothing.
+ */
+export function escapeControls(text) {
+	return String(text ?? "").replace(ESCAPED, (ch) => (ch === " " ? ch : `\\u{${ch.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}}`));
+}
+
+function parseProjectsText(text, path) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		// Not the parser's own message: it quotes the file's text around the fault, and that text may be a `name`.
+		const at = /position (\d+)/.exec(String(error?.message))?.[1];
+		throw configError(`projects file is not valid JSON${at === undefined ? "" : ` (at character ${at})`}: ${path}`);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw configError(`projects file must be an object with "version" and "projects": ${path}`);
+	}
+	const version = parsed.version;
+	if (!Number.isInteger(version) || version < 1) {
+		throw configError(`projects file must have "version": ${PROJECTS_VERSION} (an integer >= 1): ${path}`);
+	}
+	if (version > PROJECTS_VERSION) {
+		throw configError(`projects file written by a newer pi-dispatch (version ${version}; this build understands ${PROJECTS_VERSION}): ${path}`);
+	}
+	if (!Array.isArray(parsed.projects)) throw configError(`projects file must have a "projects" array: ${path}`);
+	const projects = parsed.projects.map((entry, index) => normalizeProject(entry, index, path));
+	const ids = new Map();
+	const owners = new Map();
+	projects.forEach((project, index) => {
+		if (ids.has(project.id)) {
+			throw configError(`project at index ${index}: duplicate id "${project.id}" (first at index ${ids.get(project.id)}): ${path}`);
+		}
+		ids.set(project.id, index);
+		for (const member of project.members) {
+			const owner = owners.get(member);
+			// One project per scope: a job in two projects would have two project ledgers and an unclear refusal.
+			if (owner !== undefined) {
+				throw configError(`project at index ${index}: ${JSON.stringify(member)} is claimed by both "${owner}" and "${project.id}" (a scope belongs to one project): ${path}`);
+			}
+			owners.set(member, project.id);
+		}
+	});
+	return projects;
+}
+
+function normalizeProject(entry, index, path) {
+	const at = `project at index ${index}`;
+	if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw configError(`${at}: must be an object: ${path}`);
+	if (!isProjectId(entry.id)) {
+		throw configError(`${at}: id must match ${PROJECT_ID_RE.source} (lowercase letters, digits and "-", 1 to 32 characters, starting with a letter or digit): ${path}`);
+	}
+	const id = entry.id;
+	let name = null;
+	if (entry.name !== undefined && entry.name !== null) {
+		// The name's own text is never echoed: it is free text, and this message can reach a log line.
+		if (typeof entry.name !== "string" || entry.name.trim() === "" || entry.name.length > NAME_MAX || /[\u0000-\u001f\u007f]/.test(entry.name)) {
+			throw configError(`${at} ("${id}"): name, when given, must be a string of 1 to ${NAME_MAX} characters with no control characters: ${path}`);
+		}
+		name = entry.name.trim();
+	}
+	if (!Array.isArray(entry.members) || entry.members.length === 0) {
+		throw configError(`${at} ("${id}"): members must be a non-empty array of scopes (github:owner/name or an absolute folder): ${path}`);
+	}
+	const members = [];
+	entry.members.forEach((raw, m) => {
+		const member = normalizeMember(raw, `${at} ("${id}") member ${m}`, path);
+		if (members.includes(member)) throw configError(`${at} ("${id}") member ${m}: ${JSON.stringify(member)} is listed twice: ${path}`);
+		members.push(member);
+	});
+	return { id, name, members };
+}
+
+/** One member, in its stored spelling, or the refusal naming where it sits. */
+function normalizeMember(raw, at, path) {
+	if (typeof raw !== "string" || raw.trim() === "") throw configError(`${at}: must be a non-empty string: ${path}`);
+	const trimmed = raw.trim().normalize("NFC");
+	if (trimmed.includes("*")) throw configError(`${at}: members match exactly; a scope containing "*" is refused (no globs): ${path}`);
+	let form;
+	try {
+		form = parseScopeString(trimmed);
+	} catch (error) {
+		throw configError(`${at}: ${error.message}: ${path}`);
+	}
+	if (form.type === "qualified") return `${form.kind}:${form.repo}`;
+	if (form.type === "bare") {
+		throw configError(`${at}: ${JSON.stringify(trimmed)} is a bare repo, which names that repo on every forge; write it with its forge, such as github:${trimmed}, or give an absolute folder: ${path}`);
+	}
+	// `local`: platform-native isAbsolute, so a drive path on a POSIX host is refused rather than kept as a member no
+	// job here can have (scoped limits keep such a row verbatim and inert; a new file need not).
+	if (!isAbsolute(trimmed)) throw configError(`${at}: ${JSON.stringify(trimmed)} is not an absolute path on this host: ${path}`);
+	return resolve(trimmed);
+}
+
+/**
+ * Load and validate the projects file named by `config.projectsFile`. Returns `[]` when it is unset (no projects, a
+ * valid deployment). An empty string is a value, so it reaches `existsSync` and is refused, as the scoped-limits key's
+ * is. `readFileSync`/`existsSync` are injectable for tests.
+ */
+export function loadProjects(config, { readFileSync = fsReadFileSync, existsSync = fsExistsSync } = {}) {
+	const path = config.projectsFile;
+	if (path === null || path === undefined) return [];
+	if (!existsSync(path)) throw configError(`projects file does not exist: ${escapeControls(path)}`);
+	return parseProjects(readFileSync(path, "utf8"), path);
+}
+
+/**
+ * The id of the project this job belongs to, or null. `job` is job data (`kind`, `repo`, `folder`). A forge job is
+ * matched by its forge-qualified scope (`github:acme/web`), never by its bare repo, so a GitHub job and a Forgejo job
+ * for `acme/web` can sit in different projects. A local job is matched by its resolved folder (`canonicalScope`), the
+ * spelling a member is stored in, so `/srv/shop-tools/` matches the member `/srv/shop-tools`.
+ */
+export function projectOf(job, projects) {
+	if (!Array.isArray(projects) || projects.length === 0) return null;
+	const scope = memberScopeOf(job);
+	if (typeof scope !== "string" || scope === "") return null;
+	for (const project of projects) {
+		if (Array.isArray(project?.members) && project.members.includes(scope)) return project.id;
+	}
+	return null;
+}
+
+/**
+ * The scope a job is matched to a member by (`projectOf`): its forge-qualified scope, or for a local job its resolved
+ * folder. When `projectOf` found a project, this IS the member it matched, in the stored spelling a priorities plan
+ * names by `scopeRef` (issue #504 part B), so the repo share a plan gave it needs no second matching rule.
+ */
+export function memberScopeOf(job) {
+	return job?.kind === "local" ? canonicalScope(job) : qualifiedScopeOf(job);
+}
+
+/**
+ * What `fpProjects` hashes (issue #499 part C, INT-HOST-REGISTRY-CONTRACT), exported so a test can read it: one entry
+ * per project, sorted by id, as `{ id, members }` where `members` is the sorted 16-hex hash of each member. Never a
+ * `name`, which is free text, and never a member in clear: a folder member is a host path and a repo member a
+ * repository name, and the registry's content rule keeps both out of a Valkey value, even inside a digest's input.
+ * The id is charset-checked operator text, the same admissibility a run record gives it.
+ *
+ * Membership is what the comparison is about: two hosts that put one scope in two projects, or a scope in a project on
+ * one host and in none on the other, record different projects and count the scope against different project rows.
+ * A `name` decides nothing, so renaming the display text on one host is not a disagreement.
+ */
+export function projectsFingerprintInput(projects) {
+	return (Array.isArray(projects) ? projects : [])
+		.filter((p) => isProjectId(p?.id))
+		.map((p) => ({ id: p.id, members: (Array.isArray(p.members) ? p.members : []).map((m) => hash16(String(m))).sort() }))
+		.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+/**
+ * The 16-hex fingerprint `fpProjects` of a host's live projects (`fingerprint.mjs`). It never abstains: a host with no
+ * projects file publishes the fingerprint of no projects, because a host that puts a repo in no project while a peer
+ * puts it in one is the disagreement worth seeing.
+ */
+export function projectsFingerprint(projects) {
+	return fingerprint(projectsFingerprintInput(projects));
+}
+
+/** The fingerprint of no projects: how a reader tells whether projects are in use anywhere on the fleet. */
+export const EMPTY_PROJECTS_FINGERPRINT = projectsFingerprint([]);

package/src/provider-steering.mjs

@@ -1,6 +1,6 @@
 /**
- * The environment variables pi and its provider SDKs read to CONFIGURE a provider: where the request goes,
- * and which credentials it carries (issue #314).
+ * The environment variables pi and the packages it runs read to CONFIGURE a provider or pi itself: where the
+ * request goes, which credentials it carries, and where pi reads its own configuration (issues #314, #511).
  *
  * WHY THIS IS A REFUSAL. `run.secrets` lets a trigger name an environment variable, and the existing gates
  * refuse the names the worker writes and the ones pi reads the resolved provider's KEY from. They refuse
@@ -21,7 +21,7 @@
  * resolved provider, and the bound that gate keeps is deliberate and documented -- an `anthropic` job may
  * bind `OPENAI_API_KEY` for a flow that talks to OpenAI itself, because refusing it would be this project
  * claiming a namespace it does not own. Including them here would have broken that bound ARBITRARILY: only
- * five of pi's thirty-eight key variables (at the 0.99.1 pin) happen to appear as literals in a scanned
+ * six of pi's thirty-eight key variables (at the 0.99.1 pin) happen to be read by name in a scanned
  * artifact, so `OPENAI_API_KEY` would refuse while `GROQ_API_KEY` and `HF_TOKEN` stayed bindable, and the
  * documented rule would be false for reasons no operator could predict. They are subtracted, and the bolt
  * subtracts them the same way rather than by hand. ONE is kept, by name and for a stated reason, in
@@ -31,70 +31,93 @@
  * them and they are read by the SDK as provider configuration, which is exactly what this set is.
  *
  * DERIVED, AND THE DERIVATION IS BOLTED IN BOTH DIRECTIONS by `worker/test/provider-steering.test.mjs`,
- * from the pinned artifacts rather than from a second copy of them: pi's own `dist`, plus every package pi
- * imports a client from, discovered from pi's own import statements rather than from a list here -- so a
- * pi bump that adds an SDK fails the bolt too. Four accessor spellings are matched, because the SDKs do
- * not agree on one: `getProviderEnvValue`, `readEnv`, `getEnv` and `process.env["NAME"]`, the last of
- * which is the only way `AZURE_OPENAI_ENDPOINT` is read.
- *
- * That derivation is why the set holds names nobody would have written down.
- * `AWS_CONTAINER_CREDENTIALS_FULL_URI` makes the AWS SDK fetch credentials from a URL of the trigger's
- * choosing, `AWS_WEB_IDENTITY_TOKEN_FILE` and `GOOGLE_APPLICATION_CREDENTIALS` are paths to credential
- * files, `AWS_BEDROCK_SKIP_AUTH` is an auth bypass, and `GOOGLE_GENAI_USE_VERTEXAI` moves the request to a
- * different Google product.
- *
- * THREE LIMITS, stated because a set like this is only worth what its boundary is honest about.
- *
- * The scan is ONE `node_modules` HOP DEEP: pi's own dist and the packages pi imports directly. It does not
- * follow those packages' dependencies, and the AWS variables are read one level further in, inside
- * `@smithy/core`. The names measured to matter from that layer are in the residual list below; the rest of
- * that closure (`AWS_EC2_METADATA_SERVICE_ENDPOINT`, `AWS_ROLE_ARN`, `GCE_METADATA_HOST` and some forty
- * more) is NOT covered. Recursing the whole closure would reserve most of the AWS and Google SDK surface
- * and take a large bite out of what an operator may legitimately bind, so the boundary is deliberate.
+ * from the pinned artifacts rather than from a second copy of them. Every name the scan finds is in, with
+ * no judgement about which ones matter; the only subtractions are named and asserted there.
+ *
+ * TWO HOPS, THROUGH DECLARED DEPENDENCIES. Hop 1 is every package pi-ai's own dist imports, discovered
+ * from its import statements rather than listed, so a pi bump that adds an SDK fails the bolt. Hop 2 is,
+ * for each of those, the packages its sources import AND its package.json declares in `dependencies`,
+ * which is where google-auth-library, `@smithy/core` and the AWS credential chain are. The declared-
+ * dependency filter keeps out an optional peer that resolves only by an accident of layout (`openai`
+ * imports `undici` without declaring it).
+ *
+ * EVERY OCCURRENCE COUNTED, not a list of accessor spellings (a list kept missing the next one). After
+ * stripping comments, the bolt counts every occurrence that can reach the environment in every scanned
+ * file: each `env` token (so `process.env`, `ctx.env`, a parameter named `env`, `{ env: e } = process`),
+ * each `process["env"]`, each use of an alias of one (`const v = env()`, `const e = process.env`), and
+ * each call of a helper. Helpers are DERIVED: any named function one of whose own parameters is the key of
+ * an environment read (`resolveEnvConfigValue(name, env)`), so a new call of an existing helper counts. An occurrence either NAMES a variable (`.X`, `["X"]`, a key
+ * resolved through a string constant, a call `("X")`, `"X" in env`, `{ X } = env`, a selector argument
+ * beside its key) or it is a SITE, and the bolt pins every file's sites with a COUNT
+ * (`worker/test/fixtures/provider-steering-sites.json`). So a new occurrence anywhere either names
+ * something the equality sees or changes a count: a new helper reading `process.env[name]`, a key built
+ * at runtime, a new alias. A write is a site, not a read.
+ * The rule starts from an `env` token, so a form with none is NOT seen: `process["e" + "nv"]`,
+ * `const E = "env"; process[E]`, `{ ["env"]: e } = process`, `Reflect.get(process, "env")`,
+ * `require("process")["env"]`. None occurs in the pinned sources.
+ *
+ * BOTH COPIES. The hoisted pi-ai this workspace resolves, and the one the runner dispatches through,
+ * nested under pi-coding-agent with its own google-auth-library (10.6.2 there, 10.9.1 hoisted). The union
+ * of the two is reserved.
+ *
+ * LOWERCASE TWINS ARE LITERAL MEMBERS, and matching stays EXACT. google-auth-library reads
+ * `google_application_credentials`, `gcloud_project` and `google_cloud_project` beside the uppercase
+ * forms, so the scan finds them as reads and they are in. Folding case instead would refuse names no
+ * pinned source reads (`openai_base_url`, `anthropic_api_key`), which is the other half of the rule: an
+ * operator's own name stays bindable unless something pinned reads it.
+ *
+ * PI'S OWN NAMESPACE, in `PI_OWN_READS` below. Every `PI_*` name pi-coding-agent's dist and the pi
+ * packages it declares read (pi-tui runs in the same process). The agent and session directory keys are
+ * built at runtime from pi's app name, so the bolt imports pi's `config.js` to evaluate them. Two sets are
+ * subtracted: the names the worker writes into the container (`CONTAINER_ENV_NAMES`, reserved already),
+ * and the ones the runner assigns before pi runs, derived from `image/runner/src` (`PI_OFFLINE`,
+ * `PI_TELEMETRY`). `dist/bundle/`, the vendored single-file build, is not the code the runner loads and is
+ * not scanned.
+ *
+ * THE LIMITS, stated because a set like this is only worth what its boundary is honest about.
+ *
+ * Hop 3 is not followed, and these are read there and NOT reserved: in gcp-metadata (under
+ * google-auth-library) `GCE_METADATA_HOST`, `GCE_METADATA_IP`, `METADATA_SERVER_DETECTION` and `K_SERVICE`;
+ * in the AWS credential providers (under `@aws-sdk/credential-provider-node`) `AWS_ROLE_ARN` and
+ * `AWS_ROLE_SESSION_NAME` (web identity), `AWS_CONTAINER_AUTHORIZATION_TOKEN` and its `_FILE` form (http,
+ * useless without the reserved `AWS_CONTAINER_CREDENTIALS_FULL_URI`), and `AWS_ACCOUNT_ID`,
+ * `AWS_CREDENTIAL_SCOPE` and `AWS_CREDENTIAL_EXPIRATION` (env). The metadata host is the sharpest of them:
+ * it moves where google-auth-library asks for a token when no other credential is configured.
+ *
+ * pi-coding-agent's own third-party dependencies are not scanned either (undici, jiti, yaml, semver,
+ * cross-spawn, chalk and the rest). At the 0.99.1 pin they read the proxy variables (reserved by the egress
+ * policy or listed below) and tooling switches: jiti's `NODE_DEBUG` and Babel flags, chalk's
+ * `FORCE_COLOR`, yaml's `LOG_TOKENS`.
+ *
+ * Names pi reads outside its `PI_*` namespace are found and left out, and the bolt pins the list: the
+ * terminal, the OS, the editor, and the `llama.cpp` extension's `LLAMA_BASE_URL`, which pi reads both
+ * through `ctx.env` and through `process.env`. The worker cannot dispatch to that provider, and the bolt
+ * asserts it still cannot.
  *
  * `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE` and `NODE_TLS_REJECT_UNAUTHORIZED` are NOT here.
  * They subvert any provider call, but they are properties of the RUNTIME rather than of a provider, they
  * predate this gate, and `NODE_OPTIONS` additionally needs a file the attacker can place. They belong to
  * whatever closes the runtime-hijack question, not to a set derived from what pi reads about providers.
  * The same holds for `HOME`, `PATH`, `APPDATA`, `USERPROFILE` and `XDG_CONFIG_HOME`, which the scan DOES
- * reach from the 0.99.1 pin on (issue #509): the Anthropic SDK reads the four directory variables only to
- * locate its default config directory (`core/credentials`), and `PATH` inside its agent toolset, which pi
- * does not use. The bolt subtracts them by name, with that reason, and asserts the scan still finds each,
- * so a subtraction that stopped being needed is removed rather than carried. `HOME` is reserved anyway,
- * by `reserved-env.mjs`, because the worker writes it (issue #341). The Anthropic-specific switch for the
- * same directory, `ANTHROPIC_CONFIG_DIR`, IS in the set: it names a credential location outright.
- *
- * And a bound on the whole family, which no document here stated before: a trigger author picks the
- * variable NAME and a vault REFERENCE, never a value. Exploiting any of these needs the operator's own
- * vault to hold a useful string at a reference the author is allowed to name. That is equally true of
- * `AZURE_OPENAI_BASE_URL`, the variable this issue was filed about, so it bounds the severity of the whole
- * set rather than distinguishing parts of it.
+ * reach: the Anthropic SDK reads the four directory variables only to locate its default config directory
+ * (`core/credentials`), and `PATH` inside its agent toolset, which pi does not use. `HOMEDRIVE` and
+ * `HOMEPATH` join them (issue #511): `@smithy/core` reads them in the same home-directory helper. The bolt subtracts them
+ * by name, with that reason, and asserts the scan still finds each, so a subtraction that stopped being
+ * needed is removed rather than carried. `HOME` is reserved anyway, by `reserved-env.mjs`, because the
+ * worker writes it (issue #341). The Anthropic-specific switch for the same directory,
+ * `ANTHROPIC_CONFIG_DIR`, IS in the set: it names a credential location outright.
+ *
+ * And a bound on the whole family: a trigger author picks the variable NAME and a vault REFERENCE, never a
+ * value. Exploiting any of these needs the operator's own vault to hold a useful string at a reference the
+ * author is allowed to name. That is equally true of `AZURE_OPENAI_BASE_URL`, the variable #314 was filed
+ * about, so it bounds the severity of the whole set rather than distinguishing parts of it. An operator
+ * who needs one of these names in a job puts it on `PI_FORWARD_ENV`, the operator's own list.
  *
  * IMPORT-FREE, like `reserved-env.mjs` and `provider-key.mjs` beside it: `triggers.mjs` is the shared
  * validator, the receiver loads it, and `admin/build.mjs` inlines it into the published console.
  */
 
 
-/**
- * The steering variables a literal scan of the packages pi imports cannot reach.
- *
- * Named rather than quietly absent, because "derived, never curated" would otherwise be a claim the bolt
- * cannot keep. Two reasons they are unreachable, and the test asserts BOTH still hold.
- *
- * The AWS four are read inside `@smithy/core`, one dependency hop past this scan's boundary, and two of
- * them are additionally read through a key the resolver builds at runtime
- * (`AWS_ENDPOINT_URL_<SERVICEID>`). They matter because pi stops pinning the Bedrock endpoint itself as
- * soon as `AWS_REGION` or `AWS_PROFILE` is present, which is the ordinary way to configure Bedrock. Both
- * measured: `AWS_ENDPOINT_URL` redirects the call, and `AWS_SHARED_CREDENTIALS_FILE` replaces the
- * credential it is signed with. `AWS_CONFIG_FILE` does both, and can also name a `credential_process`
- * shell command.
- *
- * The proxy spellings are read by pi's own `getProxyEnv`, which lowercases and uppercases the key it is
- * given and asks for both. `EGRESS_ENV_VARS` owns `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` and keeps
- * them; what is added here is the spellings it does not have. pi reads the LOWERCASE form FIRST, so
- * `https_proxy` outranks the egress policy's own variable in pi's reader. Only the schemes a provider call
- * can use are listed: `ws_proxy` and the rest are reachable in `getProxyEnv` but not from an HTTPS request.
- */
 /**
  * Provider KEY variables that stay reserved here although the bolt subtracts key variables in general.
  *
@@ -109,16 +132,55 @@
  */
 const RETAINED_KEY_VARIABLES = ["ANTHROPIC_AUTH_TOKEN"];
 
-const UNREACHABLE_BY_SCAN = [
-	"AWS_CONFIG_FILE",
-	"AWS_ENDPOINT_URL",
-	"AWS_ENDPOINT_URL_BEDROCK_RUNTIME",
-	"AWS_SHARED_CREDENTIALS_FILE",
-	"ALL_PROXY",
-	"all_proxy",
-	"http_proxy",
-	"https_proxy",
-	"no_proxy",
+/**
+ * The steering variables the scan cannot reach.
+ *
+ * Named rather than quietly absent, because "derived, never curated" would otherwise be a claim the bolt
+ * cannot keep. Four of them, each read through a key built at runtime, and the bolt pins the key that
+ * builds it among the unresolved ones.
+ *
+ * `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` is `@smithy/core`'s `AWS_ENDPOINT_URL_<SERVICE>`. It matters because pi
+ * stops pinning the Bedrock endpoint itself as soon as `AWS_REGION` or `AWS_PROFILE` is present, which is
+ * the ordinary way to configure Bedrock. (`AWS_ENDPOINT_URL`, `AWS_CONFIG_FILE` and
+ * `AWS_SHARED_CREDENTIALS_FILE` were here until issue #511; the scan now names them.)
+ *
+ * The proxy spellings are read by pi's own `getProxyEnv`, which lowercases and uppercases the key it is
+ * given and asks for both, and builds `${protocol}_proxy`. `all_proxy` and `no_proxy` it names literally,
+ * so the scan finds those. `EGRESS_ENV_VARS` owns `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`; what is left
+ * is here. pi reads the LOWERCASE form FIRST, so `https_proxy` outranks the egress policy's own variable in
+ * pi's reader. Only the schemes a provider call can use are listed.
+ */
+const UNREACHABLE_BY_SCAN = ["AWS_ENDPOINT_URL_BEDROCK_RUNTIME", "ALL_PROXY", "http_proxy", "https_proxy"];
+
+/**
+ * pi's own reads in its `PI_*` namespace (issue #511), minus what the worker and the runner write.
+ *
+ * `PI_CODING_AGENT_DIR` points pi at another agent directory, and with it another `auth.json`, settings
+ * and models file; `PI_RADIUS_GATEWAY`, `PI_SHARE_VIEWER_URL` and `PI_INSTALLER_API_BASE` are URLs pi
+ * calls. The rest are here because the scan finds them and the rule has no judgement in it: a name the
+ * pinned pi reads for its own configuration is not a name a trigger author picks.
+ */
+const PI_OWN_READS = [
+	"PI_CLEAR_ON_SHRINK",
+	"PI_CODING_AGENT_DIR",
+	"PI_CODING_AGENT_SESSION_DIR",
+	"PI_EXPERIMENTAL",
+	"PI_HARDWARE_CURSOR",
+	"PI_HYPERLINKS",
+	"PI_IMAGE_PROTOCOL",
+	"PI_INSTALLER_API_BASE",
+	"PI_MANAGED_INSTALL_ROOT",
+	"PI_PACKAGE_DIR",
+	"PI_RADIUS_GATEWAY",
+	"PI_SHARE_VIEWER_URL",
+	"PI_SKIP_VERSION_CHECK",
+	"PI_STARTUP_BENCHMARK",
+	"PI_TIMING",
+	"PI_TRUE_COLOR",
+	"PI_TUI_DEBUG",
+	"PI_TUI_DEBUG_REDRAW",
+	"PI_TUI_ESC_TIMEOUT",
+	"PI_TUI_WRITE_LOG",
 ];
 
 export const PROVIDER_STEERING_VARS = new Set([
@@ -141,35 +203,75 @@ export const PROVIDER_STEERING_VARS = new Set([
 	"ANTHROPIC_WORK_ID",
 	"ANTHROPIC_WORK_SECRET",
 	"AWS_ACCESS_KEY_ID",
+	"AWS_ACCOUNT_ID_ENDPOINT_MODE",
+	"AWS_AUTH_SCHEME_PREFERENCE",
 	"AWS_BEARER_TOKEN_BEDROCK",
 	"AWS_BEDROCK_BASE_URL",
 	"AWS_BEDROCK_FORCE_CACHE",
 	"AWS_BEDROCK_FORCE_HTTP1",
 	"AWS_BEDROCK_SKIP_AUTH",
+	"AWS_CONFIG_FILE",
 	"AWS_CONTAINER_CREDENTIALS_FULL_URI",
 	"AWS_CONTAINER_CREDENTIALS_RELATIVE_URI",
+	"AWS_DEFAULTS_MODE",
 	"AWS_DEFAULT_REGION",
+	"AWS_DISABLE_CLOCK_SKEW_CORRECTION",
+	"AWS_EC2_METADATA_DISABLED",
+	"AWS_EC2_METADATA_SERVICE_ENDPOINT",
+	"AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE",
+	"AWS_ENDPOINT_URL",
+	"AWS_EXECUTION_ENV",
+	"AWS_IGNORE_CONFIGURED_ENDPOINT_URLS",
+	"AWS_LAMBDA_FUNCTION_NAME",
+	"AWS_MAX_ATTEMPTS",
+	"AWS_NEW_RETRIES_2026",
 	"AWS_PROFILE",
 	"AWS_REGION",
+	"AWS_RETRY_MODE",
+	"AWS_SDK_JS_NODE_VERSION_SUPPORT_WARNING_DISABLED",
+	"AWS_SDK_UA_APP_ID",
 	"AWS_SECRET_ACCESS_KEY",
 	"AWS_SESSION_TOKEN",
+	"AWS_SHARED_CREDENTIALS_FILE",
+	"AWS_SIGV4A_SIGNING_REGION_SET",
+	"AWS_USE_DUALSTACK_ENDPOINT",
+	"AWS_USE_FIPS_ENDPOINT",
 	"AWS_WEB_IDENTITY_TOKEN_FILE",
 	"AZURE_OPENAI_API_VERSION",
 	"AZURE_OPENAI_BASE_URL",
 	"AZURE_OPENAI_DEPLOYMENT_NAME_MAP",
 	"AZURE_OPENAI_ENDPOINT",
 	"AZURE_OPENAI_RESOURCE_NAME",
+	"CLOUDFLARE_ACCOUNT_ID",
+	"CLOUDFLARE_GATEWAY_ID",
+	"CLOUDSDK_CONFIG",
+	"CLOUD_RUN_JOB",
+	"DEBUG",
+	"FUNCTION_NAME",
+	"FUNCTION_TARGET",
+	"GAE_MODULE_NAME",
+	"GAE_SERVICE",
 	"GCLOUD_PROJECT",
+	"GOOGLE_API_CERTIFICATE_CONFIG",
 	"GOOGLE_API_KEY",
 	"GOOGLE_APPLICATION_CREDENTIALS",
 	"GOOGLE_CLOUD_LOCATION",
 	"GOOGLE_CLOUD_PROJECT",
+	"GOOGLE_CLOUD_QUOTA_PROJECT",
+	"GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES",
 	"GOOGLE_GEMINI_BASE_URL",
+	"GOOGLE_GENAI_ACCESS_TOKEN",
+	"GOOGLE_GENAI_API_KEY",
+	"GOOGLE_GENAI_API_VERSION",
+	"GOOGLE_GENAI_DEBUG",
+	"GOOGLE_GENAI_USER_PROJECT",
 	"GOOGLE_GENAI_USE_ENTERPRISE",
 	"GOOGLE_GENAI_USE_VERTEXAI",
 	"GOOGLE_VERTEX_BASE_URL",
+	"HOSTNAME",
 	"KIMI_CODE_OAUTH_HOST",
 	"KIMI_OAUTH_HOST",
+	"K_CONFIGURATION",
 	"OPENAI_ADMIN_KEY",
 	"OPENAI_API_VERSION",
 	"OPENAI_BASE_URL",
@@ -180,6 +282,18 @@ export const PROVIDER_STEERING_VARS = new Set([
 	"OPENAI_WEBHOOK_SECRET",
 	"PI_CACHE_RETENTION",
 	"PI_OAUTH_CALLBACK_HOST",
+	"SMITHY_NEW_RETRIES_2026",
+	"WS_NO_BUFFER_UTIL",
+	"WS_NO_UTF_8_VALIDATE",
+	"_X_AMZN_TRACE_ID",
+	// The lowercase twins google-auth-library reads beside the uppercase forms, and the two proxy spellings
+	// pi's getProxyEnv names literally (issue #511).
+	"all_proxy",
+	"gcloud_project",
+	"google_application_credentials",
+	"google_cloud_project",
+	"no_proxy",
+	...PI_OWN_READS,
 	...RETAINED_KEY_VARIABLES,
 	...UNREACHABLE_BY_SCAN,
 ]);