@edgehero/pi-dispatch 1.10.2 → 2.0.0

package/src/provider-key.mjs

@@ -0,0 +1,41 @@
+/**
+ * Which of a provider's credential variables is the one to write, and to name (issue #311).
+ *
+ * pi's list for a provider is pi's to give: `providerKeyCandidates` in env-allowlist.mjs recovers it from
+ * `findEnvKeys` and no copy of it exists anywhere. What pi's list does NOT say is which of its entries is a
+ * subscription login rather than a service credential, and that distinction is needed in two places at once:
+ * `doctor` has to NAME a variable for an operator to set, and the worker has to CHOOSE one to inject an
+ * `auth.json` api-key login under. Those two must never answer differently -- a doctor line naming a
+ * variable the worker does not write is exactly the drift issue #286 was about.
+ *
+ * A SEPARATE MODULE with no imports at all, on the reserved-env.mjs precedent, because the import
+ * direction rules out both of the obvious homes. `env-allowlist.mjs` cannot import `doctor.mjs`: that
+ * would drag doctor's whole graph into the job path to read one regex. `doctor.mjs` cannot statically
+ * import `env-allowlist.mjs` either -- it reaches it through a DYNAMIC import on purpose, so that pi is
+ * not loaded before doctor's own Node-floor check has run and printed. A third module with no
+ * dependencies is the only shape that lets both have this for free.
+ */
+
+// The ONE credential fact this project holds itself, and it has to hold one: this is a statement ABOUT a
+// credential that must NOT be used, so it cannot come from pi's table of credentials that DO work --
+// that table says which variables pi reads, never which of them is a subscription login.
+// Checked and rejected: pi's provider descriptors carry an `auth.oauth` block, but it is per-PROVIDER,
+// not per-variable -- `github-copilot` has one and exactly ONE key variable, so "this provider supports
+// oauth" cannot name WHICH variable is the token.
+// A suffix rule rather than a one-name set, because the expensive direction is the false green: the day
+// pi adds a second provider's OAuth variable a set would silently bless it. Pinned against pi in
+// worker/test/provider-key.test.mjs -- never against a second copy of a table.
+export const OAUTH_KEY_RE = /_OAUTH_TOKEN$/;
+
+/**
+ * The api-key variable to write and to name, given pi's candidate list for a provider in pi's own
+ * precedence order. Never the OAuth token, whatever that precedence says: pi returns
+ * ANTHROPIC_OAUTH_TOKEN first, "set your subscription login" is wrong advice for an unattended service,
+ * and an api-key credential written under that name would be a value whose variable lies about what it
+ * is. Falls back to the first candidate only for a provider with no non-OAuth variable at all, which is
+ * no provider pi has today; `null` for a provider pi reads no key variable for, which is the caller's
+ * cue to refuse rather than to guess.
+ */
+export function apiKeyVariable(candidates) {
+	return candidates.find((name) => !OAUTH_KEY_RE.test(name)) ?? candidates[0] ?? null;
+}

package/src/provider-steering.mjs

@@ -0,0 +1,144 @@
+/**
+ * The environment variables pi and its provider SDKs read to CONFIGURE a provider: where the request goes,
+ * and which credentials it carries (issue #314).
+ *
+ * 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:
+ *   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
+ *
+ * The azure case is not even a shadowed default: every azure model ships `baseUrl: ""`, so there the
+ * environment is the PRIMARY source, ahead of the resource name and ahead of the model.
+ *
+ * WHAT THIS SET DOES NOT CONTAIN, and the reason is the whole shape of the design: **a provider's KEY
+ * variables**. Those are `providerKeyCandidates`' business, refused PRE-SPEND against the job's own
+ * 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.
+ * 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.
+ *
+ * `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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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",
+];
+
+export const PROVIDER_STEERING_VARS = new Set([
+	"ANTHROPIC_AUTH_TOKEN",
+	"ANTHROPIC_BASE_URL",
+	"ANTHROPIC_LOG",
+	"AWS_ACCESS_KEY_ID",
+	"AWS_BEARER_TOKEN_BEDROCK",
+	"AWS_BEDROCK_FORCE_CACHE",
+	"AWS_BEDROCK_FORCE_HTTP1",
+	"AWS_BEDROCK_SKIP_AUTH",
+	"AWS_CONTAINER_CREDENTIALS_FULL_URI",
+	"AWS_CONTAINER_CREDENTIALS_RELATIVE_URI",
+	"AWS_DEFAULT_REGION",
+	"AWS_PROFILE",
+	"AWS_REGION",
+	"AWS_SECRET_ACCESS_KEY",
+	"AWS_SESSION_TOKEN",
+	"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",
+	"GCLOUD_PROJECT",
+	"GEMINI_NEXT_GEN_API_BASE_URL",
+	"GEMINI_NEXT_GEN_API_LOG",
+	"GOOGLE_API_KEY",
+	"GOOGLE_APPLICATION_CREDENTIALS",
+	"GOOGLE_CLOUD_LOCATION",
+	"GOOGLE_CLOUD_PROJECT",
+	"GOOGLE_GEMINI_BASE_URL",
+	"GOOGLE_GENAI_USE_ENTERPRISE",
+	"GOOGLE_GENAI_USE_VERTEXAI",
+	"GOOGLE_VERTEX_BASE_URL",
+	"OPENAI_API_VERSION",
+	"OPENAI_BASE_URL",
+	"OPENAI_LOG",
+	"OPENAI_ORG_ID",
+	"OPENAI_PROJECT_ID",
+	"OPENAI_WEBHOOK_SECRET",
+	"PI_CACHE_RETENTION",
+	"PI_GATEWAY",
+	"PI_OAUTH_CALLBACK_HOST",
+	...UNREACHABLE_BY_SCAN,
+]);

package/src/queue.mjs

@@ -1,4 +1,5 @@
 import { Queue } from "bullmq";
+import { assertJudgedConnection, onValkeyError } from "./connection.mjs";
 import { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId } from "./job-id.mjs";
 import { targetSeparator } from "./forges.mjs";
 import { PR_CLOSE_ACTIONS } from "./triggers.mjs";
@@ -68,7 +69,12 @@ export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeli
  * single-host deployment never names anything else.
  */
 export function makeQueue(connection, { name = QUEUE } = {}) {
-	return new Queue(name, { connection });
+	// Issue #464: only a connection `parseConnection` built, which judges and pins the Valkey it dials.
+	assertJudgedConnection(connection);
+	const queue = new Queue(name, { connection });
+	// Issue #468: an error of this queue is one line, its message, never BullMQ's console.error of the whole object.
+	onValkeyError(queue, `queue ${name}`);
+	return queue;
 }
 
 /**
@@ -78,7 +84,7 @@ 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, skillsDir, secrets, secretsProfile, chainDepth, parentJobId, jobId, now = new Date() }) {
+export async function enqueueLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, image, backend, excludeTools, skillsDir, secrets, secretsProfile, chainDepth, parentJobId, jobId, 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
@@ -110,6 +116,10 @@ export async function enqueueLocalJob(queue, { folder, flow, task, command, prov
 		// there becomes agent-visible input, and where the box was built is the worker's business rather
 		// than the agent's.
 		...(backend !== undefined && { backend }),
+		// #291. WHAT the session's agent may not do. Conditional like `backend`, and at JOB level for the
+		// 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 }),
 		// 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
@@ -138,9 +148,13 @@ export async function enqueueLocalJob(queue, { folder, flow, task, command, prov
 const SEMANTIC_WINDOW_MS = 10 * 60 * 1000;
 
 /**
- * Enqueue a GitHub-triggered job. Returns the jobId. The data shape is what prepare/runJob consumes
- * for the github kind. No `sha` field: the commit is resolved fresh in prepare (C1), so baking a
- * possibly-stale sha here would only race the branch head.
+ * Enqueue a GitHub-triggered job. Returns `{ jobId, deduplicated, survivingJobId? }` -- the computed
+ * per-delivery id, plus whether the SEMANTIC window swallowed this delivery (issue #289; the GUID
+ * layer's replays are deliberately invisible, see the comparison below). `enqueueLocalJob` keeps its
+ * plain string return: it carries no `deduplication` option, so there is nothing the comparison could
+ * see, and its return is consumed as a bare id by the CLI and the outbox. The data shape is what
+ * prepare/runJob consumes for the github kind. No `sha` field: the commit is resolved fresh in prepare
+ * (C1), so baking a possibly-stale sha here would only race the branch head.
  *
  * `target` is the discriminated subject of the job -- `{ type:"issue"|"pull_request", number, title,
  * body, ... }` -- built by the receiver's filter from the INT-WEBHOOK-PAYLOAD-SUBSET fields. Its `number`
@@ -197,7 +211,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, skillsDir, instructions, resume, secrets, secretsProfile, waitFor, replica, replicas }) {
+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 }) {
 	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`
@@ -231,6 +245,10 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// there becomes agent-visible input, and where the box was built is the worker's business rather
 		// than the agent's.
 		...(backend !== undefined && { backend }),
+		// #291. WHAT the session's agent may not do. Conditional like `backend`, and at JOB level for the
+		// 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 }),
 		// 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
@@ -279,7 +297,7 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 	// narrow to the matched action word, like the PR half already does.
 	const isCloseJob = matched?.type === "issue" || (matched?.type === "pull_request" && PR_CLOSE_WORDS.has(matched?.action));
 	const flowSlot = `${isCloseJob ? "closed:" : ""}${command !== undefined ? `cmd:${command}` : flow}`;
-	await queue.add(kind, data, {
+	const added = await queue.add(kind, data, {
 		jobId,
 		// A command job (issue #189) fills the semantic key's flow slot with `cmd:<command>`: a command
 		// trigger carries no flow, so the slot would otherwise read `undefined` for every command and one
@@ -293,7 +311,16 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		removeOnComplete: { age: 31 * 24 * 3600 }, // age in seconds -- do not cross units with the ms ttl above
 		removeOnFail: { age: 31 * 24 * 3600 },
 	});
-	return jobId;
+	// Issue #289: WHICH of the two dedup layers spoke is readable off `queue.add`'s return, and only one
+	// of them is. Verified at bullmq 5.80.4's own Lua: a jobId collision (the GUID shield,
+	// REQ-DEDUP-BY-DELIVERY-GUID) returns THE SAME id -- structurally invisible here, and correctly so,
+	// because a forge retry of a delivery that IS queued deserves the answer "queued" -- while the
+	// `deduplication` option (the 10-minute semantic window) returns the EXISTING job's DIFFERENT id.
+	// So `added.id !== jobId` means this delivery was swallowed by the window and created nothing, which
+	// the receiver used to log as `enqueued` and answer as success. A defensive undefined (a fake queue
+	// predating the comparison) reads as not-deduplicated, today's behaviour exactly.
+	if (added?.id && added.id !== jobId) return { jobId, deduplicated: true, survivingJobId: added.id };
+	return { jobId, deduplicated: false };
 }
 
 /**

package/src/redact.mjs

@@ -0,0 +1,84 @@
+/**
+ * Take credentials out of a subprocess's own words, so a fault line can carry them (issue #339).
+ *
+ * IMPORT-FREE, and it has to stay that way. `backend-registry.mjs` and `retention-sweep.mjs` import nothing
+ * at all today, and this is their first import; a heavy one would pull the docker adapter into every graph
+ * that reaches `reapAll`. Same shape as `transient.mjs`, which says the same thing about itself.
+ *
+ * WHY A SCRUBBER AND NOT A FIXED TOKEN, which is the other shape this repo already uses
+ * (`classifyEndpointFailure` classifies on values and never reads stderr). The twelve call sites are not one
+ * kind of error. Five carry filesystem faults where the message IS the diagnosis (`EACCES: permission
+ * denied, scandir '/var/lib/...'`), and two exist to catch a throwing FACTORY, where `makeSandboxReaperFn is
+ * not a function` is the entire value of the line. A token would delete the diagnosis at most sites to
+ * protect three. A byte COUNTER (`secrets.mjs`) is right where the text is always secret-adjacent; here it
+ * is usually not.
+ *
+ * THE RULE IS THE URL GRAMMAR, never any runtime's prose, so Podman's different wording and its own
+ * connection URIs (`ssh://user@host:22/run/user/1000/podman/podman.sock`) are covered by construction.
+ * Nothing here mentions docker, a daemon, a context or an exit code.
+ *
+ * WHAT IT DOES NOT CATCH, stated rather than implied. A credential holding whitespace or a bare quote that
+ * the runtime printed UNQUOTED: both docker and podman print an unparseable endpoint through Go's `%q`,
+ * which quotes and escapes it, and the quoted rule covers that exactly. Closing the unquoted case needs a
+ * rule that crosses whitespace, and such a rule eats the useful half of every line holding an unrelated `@`.
+ * It also does not catch a secret that is not in a userinfo position: a bearer token echoed as a bare word,
+ * a registry auth blob, the contents of a key. And it deliberately keeps the HOST, which is the fact an
+ * operator needs and is never credential material.
+ */
+
+/**
+ * `scheme://userinfo@host` inside a Go `%q`-quoted region, where `\X` is an escape rather than a delimiter.
+ * Both runtimes print an endpoint they could not parse this way, and it is the only form that survives a
+ * credential containing whitespace or a quote.
+ */
+const QUOTED_USERINFO = /"([a-z][a-z0-9+.-]*:\/\/)?(?:[^"\\\n]|\\.)*@/gi;
+/** The same, unquoted: a run of non-delimiter characters up to and including the LAST `@` in it. */
+const BARE_USERINFO = /([a-z][a-z0-9+.-]*:\/\/)?[^\s"'`<>]*@/gi;
+/** The account segment of a home path, which an identity-file error carries (no-pii-in-logs). */
+const POSIX_HOME = /(\/(?:home|Users)\/)[^/\s"'`<>:,;]+/g;
+const WINDOWS_HOME = /([A-Za-z]:\\Users\\)[^\\\s"'`<>,;]+/g;
+
+/**
+ * The cap. Applied AFTER scrubbing, never before: a cut that lands inside a credential leaves its prefix,
+ * which is the whole failure mode this file exists to prevent.
+ */
+export const SCRUBBED_MAX = 300;
+
+/** Any `"..."` region, so a fragment repeated outside its URL can be checked against what was just taken. */
+const QUOTED_REGION = /"((?:[^"\\\n]|\\.)*)"/g;
+/** Below this, a fragment is too short to redact elsewhere without eating the diagnosis around it. */
+const MIN_ECHOED = 2;
+
+/**
+ * A subprocess's message with anything in a userinfo position, and any home-directory account, replaced.
+ *
+ * TWO PASSES, because one is not enough against a MEASURED error. Go's URL parser quotes the offending
+ * fragment a second time in its own words: `parse "ssh://bob:pa?ss@remote": invalid port ":pa" after host`.
+ * The first pass takes the userinfo inside the URL and leaves `":pa"` standing beside it. So whatever the
+ * first pass removed is treated as a known secret for the rest of the string, and any QUOTED region that is
+ * a substring of it goes too.
+ *
+ * QUOTED regions only, and a length floor, because the safe direction here has a cost: a one-character
+ * password would otherwise redact every occurrence of that character and destroy the diagnosis this file
+ * exists to preserve. A fragment shorter than two characters, or one echoed UNQUOTED, survives -- stated
+ * rather than claimed away, and neither runtime is known to echo one that way.
+ */
+export function scrubCredentials(value) {
+	if (typeof value !== "string" || value === "") return "unknown";
+	const taken = [];
+	const remember = (m, scheme) => {
+		taken.push(m);
+		return `${scheme ?? ""}[redacted]@`;
+	};
+	let out = value
+		.replace(QUOTED_USERINFO, (m, scheme) => `"${remember(m.slice(1), scheme)}`)
+		.replace(BARE_USERINFO, remember)
+		.replace(POSIX_HOME, "$1[redacted]")
+		.replace(WINDOWS_HOME, "$1[redacted]");
+	if (taken.length > 0) {
+		out = out.replace(QUOTED_REGION, (m, inner) =>
+			inner.length >= MIN_ECHOED && taken.some((t) => t.includes(inner)) ? '"[redacted]"' : m,
+		);
+	}
+	return out.length > SCRUBBED_MAX ? `${out.slice(0, SCRUBBED_MAX)}\u2026` : out;
+}

package/src/reserved-env.mjs

@@ -13,9 +13,9 @@
  * have it for free.
  *
  * Only the STATIC names live here. The rest of the closed map is deployment state and cannot be known
- * from a triggers file at all: the provider credential's variable names come from `findEnvKeys(provider,
- * hostEnv)`, and `PI_FORWARD_ENV` is an operator env list. Those two are refused PRE-SPEND, in the
- * processor, where the resolved provider and the host env are both in hand. `MINTED_TOKEN_VARS` and
+ * from a triggers file at all: the provider's credential variable names come from `providerKeyCandidates`
+ * once the job's provider is resolved, and `PI_FORWARD_ENV` is an operator env list. Those two are refused
+ * PRE-SPEND, in the processor, where the resolved provider and the operator's forward list are in hand. `MINTED_TOKEN_VARS` and
  * `FORGE_HOST_VARS` (forges.mjs) and `EGRESS_ENV_VARS`/`WORKER_ONLY_SECRET_VARS` (config.mjs) stay in
  * their own modules and are imported by the validator beside this one, never copied into it.
  *
@@ -33,8 +33,12 @@ export const CONTAINER_ENV_NAMES = new Set([
 	"PI_SESSION_FILE",
 	"PI_FLOW",
 	"PI_COMMAND",
+	"PI_EXCLUDE_TOOLS",
 	"PI_OFFLINE",
 	"PLAYWRIGHT_BROWSERS_PATH",
 	"PLAYWRIGHT_MCP_BROWSER",
 	"PLAYWRIGHT_MCP_SANDBOX",
+	// 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",
 ]);

package/src/retention-sweep.mjs

@@ -0,0 +1,178 @@
+// The one import this module takes, and it is otherwise an import-free leaf (issue #339).
+import { scrubCredentials } from "./redact.mjs";
+
+/**
+ * The periodic retention sweep (issue #292, OQ-007).
+ *
+ * Every reaper in this project swept ONCE, at boot: the run history (`makeLogReaper`), the retained
+ * sandboxes (`makeSandboxReaper`) and the session store (`sessionStore.reapSessions`). The supported
+ * deployment shape is a service unit that restarts only on failure, so the healthy worker was exactly
+ * the one that never re-swept. Thirty days of uptime held thirty days of GROWTH, not thirty days of
+ * retention, and the three windows an operator configured described nothing.
+ *
+ * This is one `.unref()`'d interval that re-runs the three closures boot already built. It rebuilds
+ * nothing, so one configuration read serves boot and every tick after it and the two cannot drift.
+ *
+ * A MODULE rather than a few lines inline in `start.mjs`, for a reason that is about testing and not
+ * about tidiness: `worker/test/start-wiring.test.mjs` skips its entire file unless `VALKEY_TEST_URL` is
+ * set, so anything living in the boot function is exercised only in CI. The sharp edges of an interval
+ * -- re-entrancy, an idempotent close, a sweep still running when the next tick fires -- are precisely
+ * what wants pinning on a laptop, and here they get a plain test file with no queue in it.
+ *
+ * REJECTED: a `while (!stopped) { await sweep(); await sleep(ms); }` loop on `receiver/src/poller.mjs`'s
+ * pattern. It gets non-overlap for free and is already proven testable in this repo, but its `setTimeout`
+ * is not unref'd and would hold the worker's event loop open for up to a day, and `close()` becomes a
+ * promise handshake rather than a `clearInterval`. The poller IS its process's main loop and wants to
+ * hold the loop open; a background sweep must not.
+ *
+ * The interval idiom is `host-registry.mjs`'s, deliberately, down to the ordering inside `close()`. Two
+ * divergences from it are marked at their sites, because a reader who knows that file will otherwise
+ * "fix" them back.
+ *
+ * WHAT THIS COSTS THAT THE BOOT SWEEP DID NOT, and it is the one genuinely new failure mode here. All
+ * three reapers delete SYNCHRONOUSLY (`rmSync`, `unlinkSync`), which was free at boot because nothing was
+ * in flight, and is not free on a timer beside draining jobs: a long delete blocks the event loop, and
+ * `index.mjs` sets `maxStalledCount: 0` against BullMQ's 30s lock, so a loop blocked past the renewal
+ * window FAILS a paid job rather than silently re-running it. The direction is safe and the outcome is
+ * still new. Two things bound it: this loop yields between stores, and the sandbox reaper -- the only one
+ * that deletes whole trees, each a repository clone -- yields between entries. What remains is one
+ * directory's own `rmSync`, which is why that residual is stated here rather than implied.
+ */
+
+/** The default cadence. A named constant on HOST_BEAT_MS's precedent, not a literal at the call site. */
+export const SWEEP_INTERVAL_HOURS = 24;
+
+/**
+ * How long `close()` will wait for an in-flight sweep before giving up on it.
+ *
+ * `index.mjs`'s shutdown says a closer that never settles blocks `process.exit(0)`, "which no closer
+ * here does" -- and an unbounded drain would have made that sentence false. The obvious defence, that
+ * the sweep's own docker call is capped at 5s, is NOT true: `listRunningSandboxes` uses
+ * `execFile`'s `timeout`, which only sends SIGTERM and then still waits for the child's `close`, so a
+ * `docker ps` wedged on a dead daemon socket never settles at all.
+ *
+ * NOT unref'd, on `host-registry`'s own reasoning: an unref'd timer does not fire when nothing else
+ * holds the loop, which is exactly the shutdown this bound exists for. The cost is that a hung sweep
+ * delays exit by at most this long, which is the point.
+ */
+const SWEEP_DRAIN_TIMEOUT_MS = 10_000;
+
+/**
+ * The ceiling, and it is not decoration. `setInterval` clamps a delay above 2^31-1 ms (about 24.85 days)
+ * to 1ms, so a fat-fingered `PI_SWEEP_INTERVAL_HOURS=1000` would silently become a hot loop sweeping the
+ * filesystem as fast as the event loop allows. One week is the refusal point rather than Node's own
+ * ceiling, because an interval longer than a week is not a sweep, it is `0` with extra steps, and `0`
+ * already says that clearly.
+ */
+export const SWEEP_INTERVAL_MAX_HOURS = 168;
+
+/**
+ * Build the sweep. `reapers` is an ORDERED array of `{ name, reap }` -- logs, sandboxes, sessions, the
+ * same order boot runs them in, so a tick's log lines read like a boot's. An object would read as
+ * unordered, and this one is not.
+ *
+ * `setIntervalFn`/`clearIntervalFn` are injected. No production caller passes them; they exist because
+ * this repo has no fake-timer infrastructure at all and its stated doctrine is to inject a seam rather
+ * than reach for a global. The alternative -- a 1ms interval and a real `sleep` in the test -- would be a
+ * wall-clock-dependent test, which is the exact class issue #293 exists to eliminate, landing in the same
+ * change that adds #293's guard.
+ */
+export function makeRetentionSweep({ reapers, intervalMs, log = () => {}, setIntervalFn = setInterval, clearIntervalFn = clearInterval }) {
+	let timer = null;
+	let closed = false;
+	let inFlight = null;
+
+	async function sweepOnce() {
+		if (closed) return;
+		// DIVERGENCE from host-registry, which has no overlap guard: a beat is three bounded Redis writes
+		// against a 15s interval and two overlapping beats write the same values, while a sweep is
+		// unbounded filesystem I/O with `rmSync` in it. At the 24h default this is close to unreachable --
+		// `listRunningSandboxes` alone is capped at 5s by its own exec timeout -- but it is what keeps a
+		// short PI_SWEEP_INTERVAL_HOURS against a slow network filesystem from stacking sweeps that race
+		// each other's deletes.
+		if (inFlight) {
+			log("retention_sweep_overlapped", {});
+			return;
+		}
+		const startedAt = Date.now();
+		inFlight = (async () => {
+			for (const entry of reapers) {
+				try {
+					// Destructured INSIDE the try: a malformed entry must be one log line like any other
+					// reaper fault, not a rejection out of a function the interval calls with `void`.
+					const { name, reap } = entry;
+					await reap();
+					// Between stores, so one tick is never a single uninterruptible block. See the note on
+					// synchronous deletes in the module docblock.
+					await new Promise((resolve) => setImmediate(resolve));
+				} catch (err) {
+					// The existing per-store event names, reused rather than invented: an operator greps one
+					// name and gets both the boot sweep and every tick. Fault isolation per store, so one
+					// broken reaper cannot stop the other two.
+					// SCRUBBED here as well as at each store's own catch, and that is not belt-and-braces: this line
+					// re-emits every one of those families on the TIMER, so a fix confined to the boot paths would
+					// leave every tick uncovered (issue #339).
+					log(`${entry?.name}_reaper_skipped`, { reason: scrubCredentials(err?.message) });
+				}
+			}
+		})();
+		try {
+			await inFlight;
+			log("retention_sweep", { ms: Date.now() - startedAt });
+		} catch {
+			// Unreachable today: every reaper is wrapped above. Here because the interval calls this with
+			// `void`, so ANY rejection is an unhandled rejection, and Node kills the process for one by
+			// default. A sweep must never be able to take the worker down.
+		} finally {
+			inFlight = null;
+		}
+	}
+
+	return {
+		sweepOnce,
+
+		/**
+		 * Arm the interval. DIVERGENCE from `host-registry.start`, which beats immediately: boot has just
+		 * run all three reapers, so an immediate sweep would double the boot work and break the call-order
+		 * pins in start-wiring. The first tick lands one full interval after boot.
+		 */
+		start() {
+			if (closed || timer) return; // a second start would leak the first interval
+			// A non-positive interval must arm NOTHING. setInterval(fn, 0) is a hot loop, and the caller
+			// already gates on the knob being > 0; this is what turns a future mis-wire into a no-op rather
+			// than a disk-melting one.
+			if (!(intervalMs > 0)) return;
+			timer = setIntervalFn(() => void sweepOnce(), intervalMs);
+			timer?.unref?.();
+		},
+
+		/**
+		 * `closed` is set FIRST, for host-registry's own reason: a sweep already past the top-of-function
+		 * check must not `rmSync` after the closer has reported done. Then the in-flight sweep is drained,
+		 * so a shutdown never leaves a half-deleted retained workspace behind a worker that has already
+		 * said it stopped cleanly.
+		 *
+		 * IDEMPOTENCE COMES FROM NULLING THE TIMER, not from an `if (closed) return` at the top. There was
+		 * one here, and a mutation pass proved it pinned nothing: with `timer` already null the second call
+		 * clears nothing, awaits a settled promise and returns. Issue #295 reached the identical conclusion
+		 * about the watcher closers and removed the guard rather than documenting it, and a guard with
+		 * nothing behind it is worse than none, because it invites a reader to trust it for something.
+		 */
+		async close() {
+			closed = true;
+			if (timer) clearIntervalFn(timer);
+			timer = null;
+			if (!inFlight) return;
+			await new Promise((resolve) => {
+				const t = setTimeout(() => {
+					log("retention_sweep_drain_timeout", { ms: SWEEP_DRAIN_TIMEOUT_MS });
+					resolve();
+				}, SWEEP_DRAIN_TIMEOUT_MS);
+				inFlight.catch(() => {}).then(() => {
+					clearTimeout(t);
+					resolve();
+				});
+			});
+		},
+	};
+}