@edgehero/pi-dispatch 2.0.0 → 3.0.0

package/src/provider-steering.mjs

@@ -1,13 +1,14 @@
 /**
- * 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
  * nothing that says where the request goes, and that is the worse of the two: substitution spends the
  * trigger author's money, redirection sends the OPERATOR'S credential to a host the trigger chose.
  *
- * Measured against the 0.80.7 pin with a stubbed fetch and no real key, three providers, three routes:
+ * Measured against the 0.80.7 pin with a stubbed fetch and no real key, three providers, three routes (the
+ * derivation below was re-run at the 0.99.1 pin, issue #509):
  *   AZURE_OPENAI_BASE_URL   -> the request goes to the named host carrying `api-key`
  *   GOOGLE_GEMINI_BASE_URL  -> ... carrying `x-goog-api-key`
  *   AWS_ENDPOINT_URL        -> ... carrying a SigV4 signature over the operator's Bedrock credential
@@ -20,46 +21,97 @@
  * 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
- * four of pi's thirty-one key variables happen to appear as literals 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.
+ * 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
+ * `RETAINED_KEY_VARIABLES` below.
  * The AWS credential variables STAY, and they are not an exception: pi's key table has no entry for
  * `amazon-bedrock` at all (`providerKeyCandidates("amazon-bedrock")` is empty), so nothing else reserves
  * 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: 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, 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.
+ * 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.
@@ -67,78 +119,181 @@
 
 
 /**
- * The steering variables a literal scan of the packages pi imports cannot reach.
+ * Provider KEY variables that stay reserved here although the bolt subtracts key variables in general.
+ *
+ * `ANTHROPIC_AUTH_TOKEN` was in this set from issue #314 on, because at 0.80.7 it was read only by the
+ * Anthropic SDK and was no key variable of pi's. At the 0.99.1 pin pi lists it FIRST among anthropic's key
+ * variables and sends it as `Authorization: Bearer` ahead of the API key (issue #509), which would move it
+ * to the per-provider pre-spend gate and make it bindable again for every non-anthropic job. Kept instead,
+ * because a version bump must not widen what a trigger may bind without an operator deciding it, and no
+ * deployment can be relying on binding a name that has been refused at load since #314. The bolt asserts it
+ * is still both a key variable pi reads and a name the scan finds, so the day either stops holding this
+ * list is revisited rather than carried.
+ */
+const RETAINED_KEY_VARIABLES = ["ANTHROPIC_AUTH_TOKEN"];
+
+/**
+ * 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. Two reasons they are unreachable, and the test asserts BOTH still hold.
+ * 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.
  *
- * 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.
+ * `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. `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.
+ * 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_CONFIG_FILE",
-	"AWS_ENDPOINT_URL",
-	"AWS_ENDPOINT_URL_BEDROCK_RUNTIME",
-	"AWS_SHARED_CREDENTIALS_FILE",
-	"ALL_PROXY",
-	"all_proxy",
-	"http_proxy",
-	"https_proxy",
-	"no_proxy",
+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([
-	"ANTHROPIC_AUTH_TOKEN",
 	"ANTHROPIC_BASE_URL",
+	"ANTHROPIC_CONFIG_DIR",
+	"ANTHROPIC_CUSTOM_HEADERS",
+	"ANTHROPIC_ENVIRONMENT_ID",
+	"ANTHROPIC_ENVIRONMENT_KEY",
+	"ANTHROPIC_FEDERATION_RULE_ID",
+	"ANTHROPIC_IDENTITY_TOKEN",
+	"ANTHROPIC_IDENTITY_TOKEN_FILE",
 	"ANTHROPIC_LOG",
+	"ANTHROPIC_ORGANIZATION_ID",
+	"ANTHROPIC_PROFILE",
+	"ANTHROPIC_SCOPE",
+	"ANTHROPIC_SERVICE_ACCOUNT_ID",
+	"ANTHROPIC_SESSION_ID",
+	"ANTHROPIC_WEBHOOK_SIGNING_KEY",
+	"ANTHROPIC_WORKSPACE_ID",
+	"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",
-	"GEMINI_NEXT_GEN_API_BASE_URL",
-	"GEMINI_NEXT_GEN_API_LOG",
+	"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",
+	"OPENAI_CUSTOM_HEADERS",
 	"OPENAI_LOG",
 	"OPENAI_ORG_ID",
 	"OPENAI_PROJECT_ID",
 	"OPENAI_WEBHOOK_SECRET",
 	"PI_CACHE_RETENTION",
-	"PI_GATEWAY",
 	"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,
 ]);

package/src/queue.mjs

@@ -1,6 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { Queue } from "bullmq";
 import { assertJudgedConnection, onValkeyError } from "./connection.mjs";
-import { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId } from "./job-id.mjs";
+import { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId, manualTriggerJobId } from "./job-id.mjs";
 import { targetSeparator } from "./forges.mjs";
 import { PR_CLOSE_ACTIONS } from "./triggers.mjs";
 
@@ -62,7 +63,7 @@ export function fleetQueueNames(hosts) {
 /** The name charset, duplicated from `config.mjs` deliberately: this module imports nothing. */
 const WORKER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 
-export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId };
+export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId, manualTriggerJobId };
 
 /**
  * A queue handle. `name` defaults to the shared queue, so every existing caller is unchanged and a
@@ -84,7 +85,98 @@ export function makeQueue(connection, { name = QUEUE } = {}) {
  * removeOnComplete keeps the dedup window ~= the retention. Unlike webhooks, local jobs are not
  * redelivered, so a modest window is enough.
  */
-export async function enqueueLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, image, backend, excludeTools, skillsDir, secrets, secretsProfile, chainDepth, parentJobId, jobId, now = new Date() }) {
+export async function enqueueLocalJob(queue, fields) {
+	return (await addLocalJob(queue, fields)).id;
+}
+
+/**
+ * `enqueueLocalJob` for a caller that must SAY whether anything was queued (issue #524): the operator's
+ * `pi-dispatch run`. Returns `{ id, existing }`, where `existing` is null for a job this call created, and
+ * `{ queuedAt, state }` when the one-minute dedup answered with a job an identical earlier call made.
+ *
+ * The CLI printed "queued <id>" either way, so a second `run` inside the same minute announced a job while
+ * running nothing, under the id of one that had already finished. The dedup itself is deliberate and stays.
+ *
+ * How a duplicate is told apart, and why not by asking first. BullMQ answers a jobId that already exists by
+ * returning the existing id inside a Job object it built LOCALLY for this call, so the return value says nothing
+ * about whether anything was stored. Each call therefore puts a random nonce of its own on the job's data
+ * (`enqueueNonce`) and reads the stored job back AFTER the add: the stored nonce is this call's exactly when
+ * this call's add is the one BullMQ kept. Exactly one of any number of concurrent identical calls finds its own.
+ * The first version compared the add's timestamp instead, and PR #528's review refuted it: calls in the same
+ * millisecond share a timestamp, and ten in parallel all reported "created" while one job existed. A lookup
+ * BEFORE the add has the same flaw by construction, since every concurrent caller can see nothing.
+ *
+ * The nonce is on job data, never inside `trigger`, which is the object copied into /job/event.json: it is the
+ * producer's bookkeeping and the agent has no use for it. Only the two reporting producers add it (this one and
+ * `enqueueTriggerRunReporting`), so a job from the outbox collector or a cron tick keeps exactly the data it had.
+ *
+ * A separate function rather than a change to `enqueueLocalJob`'s return, because the outbox collector consumes
+ * that as a bare id and prints nothing to a person. It also keeps its one Valkey round trip: only this function
+ * pays for the read back.
+ *
+ * `state` is BullMQ's own word for where the job is (`waiting`, `active`, `completed`, `failed`, `delayed`
+ * and the rest), or null when the state could not be read; the caller then says it is already queued or
+ * done rather than inventing one. A read that fails outright returns `existing: undefined`: whether this
+ * call queued anything is then unknown, and the caller says so instead of guessing either way.
+ */
+export async function enqueueLocalJobReporting(queue, fields) {
+	return addReporting(queue, (enqueueNonce) => addLocalJob(queue, { ...fields, enqueueNonce }));
+}
+
+/**
+ * Fire one cron trigger by hand (`pi-dispatch run --trigger <id>`, issue #505), reporting like
+ * `enqueueLocalJobReporting` and through the same nonce and read back, so a second call in the same minute says
+ * the first job was already queued instead of announcing one it did not make.
+ *
+ * `schedule` is the trigger's own scheduler entry from `loadSchedules`, and its `data` is passed through WHOLE, with
+ * only the nonce added: the folder, the flow or command, the task, `github`, `packages`, `resume`, the model fields,
+ * `trigger: { id, pattern }` and a job-level `portfolio`. Field by field through `addLocalJob` was the other way, and
+ * it is the one that drops a field the next issue adds to the schedule. The options are the schedule's too, so the
+ * job is not retried, as a scheduled tick is not (a scheduler job carries no `attempts`). The id is
+ * `manualTriggerJobId`'s, so `localEventContext` reports `source: "cron"` with `scheduledFor: null`.
+ */
+export async function enqueueTriggerRunReporting(queue, schedule, { now = new Date() } = {}) {
+	const jobId = manualTriggerJobId({ triggerId: schedule.schedulerId, now });
+	return addReporting(queue, async (enqueueNonce) => {
+		await queue.add(schedule.name, { ...schedule.data, enqueueNonce }, { ...schedule.opts, jobId });
+		return { id: jobId };
+	});
+}
+
+/** The add, then the read back that says whether THIS call's add is the one stored (see `enqueueLocalJobReporting`). */
+async function addReporting(queue, add) {
+	const enqueueNonce = randomUUID();
+	const { id } = await add(enqueueNonce);
+	let stored;
+	try {
+		stored = await queue.getJob(id);
+	} catch {
+		return { id, existing: undefined };
+	}
+	// No stored job: it was removed between the add and this read (a `cancel` racing it). Nothing says it was
+	// a duplicate, so it reads as created, which is what the add itself answered.
+	if (!stored || stored.data?.enqueueNonce === enqueueNonce) return { id, existing: null };
+	let state = null;
+	try {
+		const s = await stored.getState();
+		state = typeof s === "string" && s !== "unknown" ? s : null;
+	} catch {}
+	return { id, existing: { queuedAt: Number.isFinite(stored.timestamp) ? stored.timestamp : null, state } };
+}
+
+/**
+ * The one sentence for a swallowed local enqueue (issue #524), shared by `pi-dispatch run` and the admin's
+ * `/dispatch run` so the two producers an operator types cannot drift apart. `existing` is
+ * `enqueueLocalJobReporting`'s: the time is the first job's own, in this process's local time, and a state the
+ * queue could not give is said as "already queued or done" rather than guessed.
+ */
+export function swallowedRunSentence(jobId, existing) {
+	const at = Number.isFinite(existing?.queuedAt) ? new Date(existing.queuedAt) : null;
+	const hhmm = at ? ` at ${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}` : "";
+	return `an identical run was queued${hhmm} as ${jobId} (${existing?.state ?? "already queued or done"}); nothing new was queued.`;
+}
+
+async function addLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, models, maxCostUsd, image, backend, excludeTools, skillsDir, secrets, secretsProfile, chainDepth, parentJobId, jobId, enqueueNonce, now = new Date() }) {
 	const minute = now.toISOString().slice(0, 16); // YYYY-MM-DDTHH:MM -- the dedup window
 	// A caller-supplied jobId (the outbox collector's retry-idempotent chainedJobId) wins; otherwise the
 	// minute-windowed localJobId is the dedup key. A command job (issue #189) fills the flow slot with
@@ -93,7 +185,7 @@ export async function enqueueLocalJob(queue, { folder, flow, task, command, prov
 	// vanish silently -- and the `cmd:` prefix keeps a command named X from colliding with a flow named X
 	// (`:` is outside the skill-name charset, so no real flow can spell the prefixed form). A flow job's
 	// key is byte-identical to before the feature.
-	const id = jobId ?? localJobId({ folder, flow: command !== undefined ? `cmd:${command}` : flow, task, minute });
+	const id = jobId ?? localJobId({ folder, flow: command !== undefined ? `cmd:${command}` : flow, task, minute, provider, model, models });
 	// image/chainDepth/parentJobId land on `data` only when present, so a plain non-chained job's data is
 	// byte-identical. `image` is the container image this job runs in (INT-TRIGGERS-FILE-CONTRACT); absent
 	// resolves the deployment default at job start, never a value frozen here.
@@ -109,6 +201,11 @@ export async function enqueueLocalJob(queue, { folder, flow, task, command, prov
 		provider,
 		model,
 		maxTurns,
+		// Issue #502: the allowed-model list, conditional like `image`, so a job whose trigger named none keeps its
+		// data byte-identical. An outbox child carries its parent's (outbox.mjs), never one its request file names.
+		...(models !== undefined && { models }),
+		// Issue #501: the per-job dollar cap, passed through for the outbox child that inherits its parent's.
+		...(maxCostUsd !== undefined && { maxCostUsd }),
 		...(image !== undefined && { image }),
 		// #227. WHERE this job's container is built. Conditional like `image`, so a trigger that named no
 		// venue produces byte-identical job data -- and at JOB level, never inside `trigger`, for the reason
@@ -132,6 +229,8 @@ export async function enqueueLocalJob(queue, { folder, flow, task, command, prov
 		...(secretsProfile !== undefined && { secretsProfile }),
 		...(chainDepth !== undefined && { chainDepth }),
 		...(parentJobId !== undefined && { parentJobId }),
+		// Issue #524: `enqueueLocalJobReporting`'s own mark, so it can tell whether ITS add is the one stored.
+		...(enqueueNonce !== undefined && { enqueueNonce }),
 	};
 	await queue.add("local", data, {
 		jobId: id,
@@ -140,7 +239,7 @@ export async function enqueueLocalJob(queue, { folder, flow, task, command, prov
 		removeOnComplete: { age: 24 * 3600 },
 		removeOnFail: { age: 7 * 24 * 3600 },
 	});
-	return id;
+	return { id };
 }
 
 // Coalesces rapid re-label spam; the GUID jobId + 31d retention handle exact redelivery, so this
@@ -211,7 +310,7 @@ export async function enqueueGitLabJob(queue, fields) {
  * window, replicas never coalesce against each other, and an unflagged job's dedup id is the same string it
  * has always been.
  */
-export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, packages, image, backend, excludeTools, skillsDir, instructions, resume, secrets, secretsProfile, waitFor, replica, replicas }) {
+export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, models, maxCostUsd, packages, image, backend, excludeTools, skillsDir, instructions, resume, secrets, secretsProfile, waitFor, replica, replicas }) {
 	const jobId = forgeDeliveryJobId(kind, trigger?.deliveryId, replica);
 	// `packages` (whether to load the operator-staged pi packages) and `image` (which container image to run)
 	// come off the MATCHED trigger (INT-TRIGGERS-FILE-CONTRACT / REQ-GLOBAL-PI-OVERLAY) and land on `data`
@@ -237,6 +336,9 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		provider,
 		model,
 		maxTurns,
+		// Issue #502: the allowed-model list, conditional like `packages` below so an unflagged trigger's job data is
+		// byte-identical, and at JOB level, never inside `trigger` (copied verbatim into /job/event.json).
+		...(models !== undefined && { models }),
 		...(packages !== undefined && { packages }),
 		...(image !== undefined && { image }),
 		// #227. WHERE this job's container is built. Conditional like `image`, so a trigger that named no
@@ -249,6 +351,9 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// same reason: `trigger` is copied verbatim into /job/event.json, and a permission boundary is the
 		// worker's business, never agent-visible input to reason about.
 		...(excludeTools !== undefined && { excludeTools }),
+		// #501. The trigger's per-job dollar cap, as written. Conditional like `excludeTools`, at JOB level for its
+		// reason, and a narrowing like it: the worker runs the job under the smaller of this and the deployment cap.
+		...(maxCostUsd !== undefined && { maxCostUsd }),
 		// The host directory of operator-authored skills this trigger injects (REQ-PER-TRIGGER-SKILLS).
 		// Conditional like `image`, so an unflagged job's data stays byte-identical, and at JOB level rather
 		// than inside `trigger` because a worker-host path is an execution knob, not a fact about the

package/src/reserved-env.mjs

@@ -1,3 +1,12 @@
+/**
+ * Issue #503: the variable a keyless provider's `models.json` key names (`"apiKey": "$PI_DISPATCH_KEYLESS"`), so pi
+ * composes the provider. `buildContainerEnv` writes it, with the fixed, non-secret value `keyless`, only when the
+ * credential gate passed the job's provider keyless (env-allowlist.mjs, `resolveProviderCredential`): a provider pi does
+ * not know, served by keyless model endpoints alone. Reserved in the set below, so neither `run.secrets` nor
+ * `PI_FORWARD_ENV` can set it.
+ */
+export const KEYLESS_ENV_NAME = "PI_DISPATCH_KEYLESS";
+
 /**
  * The environment variable names `buildContainerEnv` writes itself, spelled once (issue #225).
  *
@@ -34,6 +43,14 @@ export const CONTAINER_ENV_NAMES = new Set([
 	"PI_FLOW",
 	"PI_COMMAND",
 	"PI_EXCLUDE_TOOLS",
+	// Issues #501, #502: the per-job dollar cap (written by the worker since #501, from the trigger's and the
+	// deployment's caps) and the allowed-model list (reserved until #502 writes it). Neither can be bound through
+	// `run.secrets`: a trigger setting its own cap, or its own list, would be the policy choosing itself.
+	"PI_MAX_COST_MICROS",
+	"PI_ALLOWED_MODELS",
+	// Issue #545: tells the runner the exit line's key waits on stdin. A trigger setting it would block its own runner
+	// on a stdin no one writes, or turn the signed line off.
+	"PI_EXIT_AUTH",
 	"PI_OFFLINE",
 	"PLAYWRIGHT_BROWSERS_PATH",
 	"PLAYWRIGHT_MCP_BROWSER",
@@ -41,4 +58,17 @@ export const CONTAINER_ENV_NAMES = new Set([
 	// Issue #341: set beside `--user` so a uid with no passwd entry has a writable home. A new reservation, so a
 	// triggers file binding a secret named HOME is now refused at parse (worker, receiver and admin alike).
 	"HOME",
+	// Issue #503: written only on the keyless branch of the credential gate (see KEYLESS_ENV_NAME at the top).
+	KEYLESS_ENV_NAME,
 ]);
+
+/**
+ * Issue #500: the names the RUNNER sets in its own environment inside the container, for its descendants: the child
+ * ledger directory and the runner's pid (image/runner/src/usage-meter.mjs, openChildLedger). The worker never writes
+ * them, so they are not in the set above (which a test pins to what buildContainerEnv emits). They are reserved all the
+ * same: a trigger binding one through `run.secrets`, or a host value forwarded through `PI_FORWARD_ENV`, would arrive in
+ * the runner's environment before the runner sets its own, and a value the runner then failed to replace would point
+ * every pi child's ledger at a directory the agent chose. Refused at load in both lists, and deleted by
+ * buildContainerEnv after both loops as the backstop.
+ */
+export const RUNNER_ENV_NAMES = new Set(["PI_DISPATCH_CHILD_LEDGER", "PI_DISPATCH_RUNNER_PID"]);