@edgehero/pi-dispatch 1.2.0 → 1.3.0

package/src/schedules.mjs

@@ -74,7 +74,7 @@ function normalizeCronSchedule({ on, run }, path, existsSync) {
 	// key. A command trigger carries no flow/task at all (the validator enforces the XOR), so those two
 	// keys hold undefined here and drop at JSON serialization -- the command schedule's data is exactly
 	// kind/folder/command plus the shared fields.
-	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, ...(run.command !== undefined && { command: run.command }), provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), resume: run.resume, trigger: { id: on.id, pattern: on.pattern } };
+	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, ...(run.command !== undefined && { command: run.command }), provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), ...(run.secrets !== undefined && { secrets: run.secrets }), ...(run.secretsProfile !== undefined && { secretsProfile: run.secretsProfile }), resume: run.resume, trigger: { id: on.id, pattern: on.pattern } };
 	// Retention only; the deterministic repeat:<id>:<millis> jobId supplies dedup, so no jobId here, and
 	// scheduler jobs are not retried (DES-CRON-VIA-BULLMQ-SCHEDULER) so no attempts/backoff.
 	const opts = { removeOnComplete: { age: 24 * 3600 }, removeOnFail: { age: 7 * 24 * 3600 } };

package/src/secret-profiles.mjs

@@ -0,0 +1,119 @@
+/**
+ * The operator's declared secret-resolver profiles: parsing, merging, and the path bound (issue #225).
+ *
+ * A PROFILE is a name and an absolute path to a script the operator wrote. A trigger names the NAME; it
+ * can never name the path. That distinction is the whole reason `run.secretsProfile` is allowed to exist:
+ * `DES-SERVICE-ENV-SETUP-SEAM` rejected "making this reachable from configuration, which would turn a
+ * boot-time root-adjacent exec into something a trigger file could name", and selecting among execs the
+ * operator already declared is not naming one.
+ *
+ * PURE AND FS-FREE, like `triggers.mjs` and for a weaker but real version of its reason: `config.mjs`
+ * imports this module, `runtime-settings.mjs` imports `config.mjs`, and `admin/build.mjs` inlines that
+ * chain into the published console. Whether a path EXISTS is asked once, in `secrets.mjs`, on the worker
+ * that is about to spawn it.
+ *
+ * `configError` is a local copy rather than an import from `config.mjs`, which imports this module: the
+ * cycle would resolve (function declarations hoist) but would be a trap for the next reader. The same
+ * duplication, for a related reason, is in `env-allowlist.mjs`.
+ */
+
+import { isAbsolute, normalize, sep } from "node:path";
+
+function configError(message) {
+	const error = new Error(message);
+	error.piDispatchConfig = true;
+	return error;
+}
+
+/**
+ * A profile name. Deliberately the same charset `triggers.mjs` allows in `run.secretsProfile`, and it has
+ * to be: a name that fails here after passing there would be an operator-visible contradiction between two
+ * files that are meant to agree. Excluding `,` and `:` is load-bearing rather than tidy, since those are
+ * this variable's own separators -- a name carrying either could not round-trip through its declaration.
+ */
+const PROFILE_NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Parse `PI_SECRET_PROFILES`: `name:/abs/path,other:/abs/other`. Returns `{ [name]: path }`, empty when
+ * unset. Throws (config-tagged, so the worker refuses to boot) on anything malformed.
+ *
+ * SET-BUT-GARBLED FAILS LOUD, which is `parsePollRepos`' doctrine and matters more here: a silently
+ * dropped entry is a profile the operator believes is wired, and every trigger naming it would refuse at
+ * delivery time with the operator looking at a line that appears to declare it.
+ *
+ * Each entry splits on its FIRST colon, so `prod:C:\pi\resolve.cmd` parses on Windows. That is the same
+ * drive-letter hazard `config.mjs`'s `delimitedList` exists for, arriving from the other side: there the
+ * colon must not be read as a separator, here exactly one of them must be.
+ */
+export function parseSecretProfiles(raw) {
+	if (raw === undefined || raw === null || String(raw).trim() === "") return {};
+	const profiles = {};
+	for (const entry of String(raw).split(",")) {
+		const text = entry.trim();
+		if (text === "") continue; // a trailing comma is a typo, not a declaration
+		const cut = text.indexOf(":");
+		if (cut <= 0) {
+			throw configError(`PI_SECRET_PROFILES entries must be name:/absolute/path, got ${JSON.stringify(text)}`);
+		}
+		const name = text.slice(0, cut).trim();
+		const path = text.slice(cut + 1).trim();
+		if (!PROFILE_NAME.test(name)) {
+			throw configError(`PI_SECRET_PROFILES profile name ${JSON.stringify(name)} may use letters, digits, dot, dash and underscore only`);
+		}
+		if (name in profiles) {
+			throw configError(`PI_SECRET_PROFILES declares ${JSON.stringify(name)} twice -- one of the two is not the resolver you think is running`);
+		}
+		if (path === "" || !isAbsolutePath(path)) {
+			throw configError(`PI_SECRET_PROFILES profile ${JSON.stringify(name)} needs an ABSOLUTE path to its resolver -- a service manager's working directory is not your shell's, so a relative path is a different file on every host`);
+		}
+		profiles[name] = path;
+	}
+	return profiles;
+}
+
+/** Absolute on this platform, accepting a Windows drive letter or UNC root as `service.mjs` does. */
+function isAbsolutePath(path) {
+	return isAbsolute(path) || /^([A-Za-z]:[\\/]|\\\\)/.test(path);
+}
+
+/**
+ * Union the env-declared profiles with the overlay-declared ones, refusing a name that appears in both.
+ *
+ * NEITHER SOURCE WINS, and that is a deliberate third answer. `runtime-settings.mjs` documents the
+ * overlay's precedence as `overlay > env`, so quietly inverting it for this one key would leave two rules
+ * in the codebase disagreeing about what an overlay is. But honouring it would let a settings file -- which
+ * defaults into the OS temp directory -- redirect a profile the operator wrote in `.env`. So a collision is
+ * refused instead, per delivery and naming only the profile name. This project already refuses ambiguity
+ * rather than resolving it: `PI_EGRESS` refuses any value but 0 or 1 because "a typo must never leave you
+ * believing you have a policy you do not", and two declarations of one profile is exactly that.
+ *
+ * Returns `{ profiles }` or `{ ambiguous }` naming the first colliding profile.
+ */
+export function mergeSecretProfiles(envProfiles = {}, overlayProfiles = {}) {
+	for (const name of Object.keys(overlayProfiles)) {
+		if (name in envProfiles) return { ambiguous: name };
+	}
+	return { profiles: { ...envProfiles, ...overlayProfiles } };
+}
+
+/**
+ * Whether `candidate` sits inside one of `roots`. Empty roots means NOTHING passes.
+ *
+ * FAIL-CLOSED BY DEFAULT is the whole design: with `PI_SECRET_RESOLVER_ROOTS` unset, an overlay-declared
+ * profile resolves to no usable path, so the panel can declare nothing and the deployment is env-only. The
+ * operator opts in to panel authoring by naming the directory their resolvers already live in. This is
+ * `PI_DISPATCH_RUN_ROOTS`' shape, and `DES-PER-TRIGGER-JOB-IMAGE` predicted it: "If a future tool ever
+ * takes an image parameter, the allowlist arrives with that tool, and this row is the reason it must."
+ *
+ * The comparison is on NORMALIZED paths with a separator boundary, so `/opt/pi-evil` does not pass for the
+ * root `/opt/pi`. Callers pass a path they have already realpath'd, because normalization alone cannot see
+ * through a symlink and this is a boundary, not a hint.
+ */
+export function withinRoots(candidate, roots = []) {
+	if (!Array.isArray(roots) || roots.length === 0) return false;
+	const target = normalize(candidate);
+	return roots.some((root) => {
+		const base = normalize(root).replace(new RegExp(`${sep === "\\" ? "\\\\" : sep}+$`), "");
+		return target === base || target.startsWith(base + sep);
+	});
+}

package/src/secrets.mjs

@@ -0,0 +1,319 @@
+/**
+ * Per-trigger secret references, resolved HOST-SIDE before a container starts (REQ-TRIGGER-SECRETS, #225).
+ *
+ * A trigger may carry `run.secrets`, a map of environment variable name to an OPAQUE REFERENCE, and
+ * `run.secretsProfile`, the name of one resolver the operator declared. The worker runs that resolver once
+ * per reference, takes its stdout as the value, and injects the values into the closed container env map
+ * exactly as the provider credential is injected. The job holds no manager credential, reaches no vault,
+ * and cannot enumerate one -- so `docs/secrets.md`'s rule stays literally true: what crosses the container
+ * boundary is a value, never the thing that can fetch values.
+ *
+ * THE REFERENCE GRAMMAR IS NOT OURS. `op://vault/item/field`, `secret/data/ci#stripe` and a bare name are
+ * all correct inputs, because what parses them is a two-line script the operator wrote. #206 refused
+ * "endorsing a vendor" and #209 refused "depending on, or blessing, any particular secrets manager -- the
+ * seam is a command". This module is that seam, moved from boot time (`DES-SERVICE-ENV-SETUP-SEAM`'s
+ * `--env-setup`) to job time, and it must never grow a regex that recognises one manager's notation.
+ *
+ * THE RESOLVER'S EXIT CODE IS THE RUNNER'S EXIT CODE. `INT-RUNNER-EXIT-CODE-PROTOCOL` is reused verbatim
+ * rather than invented here: 0 carries the value, 1 says "I could not reach my manager" and RETRIES, 2 says
+ * "that reference is wrong" and does not. Folding every nonzero exit into a refusal, which is the obvious
+ * design, breaks `CONST-RETRY-INFRA-ONLY` in the expensive direction: a vault unreachable for twenty
+ * seconds would permanently burn a delivery that BullMQ's `attempts: 2` would have recovered, and a webhook
+ * does not redeliver itself. `docs/secrets.md` already tells operators to ask what a manager does to their
+ * exit code, so the question is one they are pointed at rather than one this invents for them.
+ */
+
+import { spawn } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import { providerKeyVars } from "./env-allowlist.mjs";
+import { EXIT_POLICY } from "./exit-code.mjs";
+import { mergeSecretProfiles, withinRoots } from "./secret-profiles.mjs";
+
+/**
+ * The largest value a resolver may print. `outbox.mjs` caps a request file at 4 KiB, which is too small
+ * here (a 4096-bit PEM chain, a service-account JSON -- this project already carries
+ * `GITHUB_APP_PRIVATE_KEY` as an env value), and `materialize.mjs` allows git 16 MiB, which per reference
+ * is a memory bomb. 64 KiB holds any real credential and bounds a full 16-reference job at 1 MiB.
+ *
+ * On overflow the child is killed and the job refuses. NEVER TRUNCATED: a silently shortened credential is
+ * the exact failure this gate exists to prevent, and it is the direction `execFile`'s own `maxBuffer` takes.
+ */
+export const MAX_SECRET_BYTES = 64 * 1024;
+
+/** SIGTERM, then this long, then SIGKILL. doctor's capture helper does a bare kill() with no escalation, */
+/** which is fine for a diagnostic and not for something holding a pipe in front of a paid container. */
+const KILL_GRACE_MS = 2000;
+
+/**
+ * The profile a trigger selects when it names none. A single-manager deployment declares one profile
+ * called `default` and never writes the field.
+ *
+ * A LOOKUP KEY, never a fallback: there is deliberately no "if only one profile is declared, use it" rule.
+ * `env-allowlist.mjs` records what that costs -- its forge lookup was once an `if gitlab / else github`,
+ * and the `else` handed a credential to the wrong host. A rule whose meaning changes the day an operator
+ * declares a second profile is that mistake with a slower fuse.
+ */
+export const DEFAULT_SECRETS_PROFILE = "default";
+
+/**
+ * Whether this job asked for secrets at all.
+ *
+ * EITHER field arms it. `secretsProfile` alone cannot reach a wired worker (parseTriggers refuses a profile
+ * that resolves nothing), but this predicate also guards the processor's fail-closed default, which runs
+ * under wirings that never saw the validator -- a bare `makeProcessor` in a test, or a job whose data was
+ * queued by a different version. Treating a lone profile as unarmed there would silently start a job the
+ * operator believes is bound to a vault.
+ *
+ * Exported so the gate and its default share ONE definition of "armed", which is the discipline
+ * `processor.mjs` already keeps for `run.resume` (`=== true`, spelled the same in the gate and in
+ * prepare-github, "so the gate and the feature cannot disagree about what armed means").
+ */
+export function secretsArmed(job) {
+	if (typeof job?.secretsProfile === "string" && job.secretsProfile !== "") return true;
+	const secrets = job?.secrets;
+	return secrets !== null && typeof secrets === "object" && Object.keys(secrets).length > 0;
+}
+
+/**
+ * Run one resolver against one reference. Resolves a discriminated result; never throws, never rejects.
+ *
+ * `failure` is OUR vocabulary, never the resolver's words:
+ *   - `policy`   the reference is wrong, absent or denied (exit 2), or the output was empty, oversized,
+ *                or carried a NUL. Determinate: retrying cannot change the answer.
+ *   - `infra`    the manager could not be reached (exit 1), an unrecognised exit, a spawn fault, a timeout.
+ *
+ * An unrecognised exit code is INFRA on `decideRetry`'s own reasoning: a runner that exits with something
+ * we do not recognise is one we cannot reason about, and retrying-then-alerting beats accepting it as done.
+ */
+function runResolver(spawnFn, path, reference, { timeoutMs, hostEnv, signal }) {
+	return new Promise((resolve) => {
+		let child;
+		try {
+			child = spawnFn(path, [reference], {
+				// stdin IGNORED, so a resolver that prompts (`op signin`, `vault login`) dies at once rather
+				// than blocking to the timeout behind an invisible password prompt on a headless host.
+				//
+				// stdout and stderr are SEPARATE pipes. doctor's capture helper merges them, and its stated
+				// reason (gh moves human output between the two) does not survive here: a merge splices a
+				// deprecation warning into the secret, and because the value is printed nowhere the corruption
+				// stays invisible until the container authenticates with a wrong string and the agent writes a
+				// plausible report about why the integration is down.
+				stdio: ["ignore", "pipe", "pipe"],
+				// The worker's own environment, verbatim. The resolver has to authenticate to the manager, and
+				// the whole architecture of docs/secrets.md is that its credential lives here. Narrowing would
+				// mean naming each vendor's variables, which is blessing vendors, and would be theatre anyway:
+				// a script running as the worker user can read /proc/self/environ. What it does NOT see is a
+				// forge token, and that is free rather than arranged -- this runs before the mint.
+				env: hostEnv,
+				// An ARRAY and never a shell string: no interpolation, no injection. docker-run.mjs states the
+				// rule for the only other place this project spawns on the job path.
+				shell: false,
+			});
+		} catch {
+			resolve({ value: null, failure: "infra", detail: "spawn", code: null, stderrBytes: 0 });
+			return;
+		}
+
+		const chunks = [];
+		let bytes = 0;
+		let stderrBytes = 0;
+		let done = false;
+		let overflowed = false;
+		let killTimer = null;
+
+		const finish = (result) => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			signal?.removeEventListener?.("abort", onAbort);
+			resolve(result);
+		};
+		// SIGTERM, then SIGKILL after a grace. The kill timer is deliberately NOT cleared by `finish`: the
+		// promise settles now, and the escalation still has to land on a child that ignored the first signal.
+		const stop = (why) => {
+			try {
+				child.kill();
+			} catch {}
+			killTimer = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+			}, KILL_GRACE_MS);
+			killTimer.unref?.();
+			finish({ value: null, failure: why === "overflow" ? "policy" : "infra", detail: why, code: null, stderrBytes });
+		};
+
+		const timer = setTimeout(() => stop("timeout"), timeoutMs);
+		const onAbort = () => stop("aborted");
+		signal?.addEventListener?.("abort", onAbort, { once: true });
+
+		child.stdout?.on("data", (d) => {
+			bytes += d.length;
+			if (bytes > MAX_SECRET_BYTES) {
+				overflowed = true;
+				stop("overflow");
+				return;
+			}
+			chunks.push(d);
+		});
+		// A COUNTER, never a string. Keeping the bytes would leave the resolver's own words one refactor away
+		// from a public issue comment, and a resolver's stderr can echo the reference, the vault path, or in a
+		// careless tool the value itself. A count still tells an operator to go run it by hand.
+		child.stderr?.on("data", (d) => (stderrBytes += d.length));
+		child.on("error", () => finish({ value: null, failure: "infra", detail: "spawn", code: null, stderrBytes }));
+		child.on("close", (code) => {
+			if (overflowed || done) return;
+			if (code === EXIT_POLICY) return finish({ value: null, failure: "policy", detail: "exit", code, stderrBytes });
+			if (code !== 0) return finish({ value: null, failure: "infra", detail: "exit", code, stderrBytes });
+			const value = stripOneNewline(Buffer.concat(chunks).toString("utf8"));
+			// Exit 0 printing nothing is the silent-no-op class: a vault CLI that says nothing and succeeds
+			// would otherwise bind an empty variable and let the job run as though it were configured.
+			if (value === "") return finish({ value: null, failure: "policy", detail: "empty", code, stderrBytes });
+			// `-e NAME=VALUE` is an execve argv element and truncates at a NUL, silently handing the container
+			// a shortened credential. Interior NEWLINES are fine and must stay fine: it is an argv, not a
+			// shell string, and a PEM has them.
+			if (/\u0000/.test(value)) return finish({ value: null, failure: "policy", detail: "nul", code, stderrBytes });
+			finish({ value, failure: null, detail: null, code, stderrBytes });
+		});
+	});
+}
+
+/**
+ * Strip EXACTLY ONE trailing newline, and a `\r` before it only if that strip happened.
+ *
+ * Every CLI in this space terminates with one newline (`vault kv get -field=`, `pass show`, `gcloud secrets
+ * versions access`), and leaving it in puts a newline inside an HTTP header value: some clients reject it,
+ * some send it, and the failure names nothing. `op read --no-newline` prints none and must keep working,
+ * which is why this is idempotent rather than a loop.
+ *
+ * NOT `.trim()`, in either direction. A passphrase may legitimately begin or end with a space, and a PEM
+ * ends with a newline whose removal must not cascade into the body. Silently mangling a credential is the
+ * same class of harm as splicing stderr into it.
+ */
+function stripOneNewline(text) {
+	if (text.endsWith("\r\n")) return text.slice(0, -2);
+	if (text.endsWith("\n")) return text.slice(0, -1);
+	return text;
+}
+
+/**
+ * Build the pre-spend resolver the processor injects.
+ *
+ * `(job) => { ok, secrets } | { profileUnknown } | { ambiguous } | { unresolved, ... } | { unreachable, ... }`
+ *
+ * `envProfiles` is parsed at BOOT by `config.mjs`; `overlayProfiles` arrives per job, because the settings
+ * overlay is read at each job start (INT-CONFIG-OVERLAY-CONTRACT) and an operator who declares a profile in
+ * the panel should not have to restart the worker. The processor never reads a file: the table arrives
+ * already parsed, exactly as `sessionsDir` does.
+ *
+ * SEQUENTIAL, in the operator's own writing order, deduped by unique reference. Not throughput: with two
+ * broken references `Promise.all` refuses on whichever loses the race, so one broken trigger would blame a
+ * different variable on different runs. Sequential always names the first, so an operator fixes them in the
+ * order they wrote them. It also caps the blast radius of a refusal at the references BEFORE the failure,
+ * rather than pulling all sixteen live credentials into memory for a job that will never run, and spares
+ * every managed vault a burst of N x PI_CONCURRENCY parallel reads nobody sized for. The cost is nil: this
+ * band is followed immediately by a git clone measured in tens of seconds.
+ *
+ * NOTHING IS ZEROED, and saying so is the honest half. JS strings are immutable and unzeroable; pretending
+ * otherwise would be theatre. What IS true: the returned map is a block-scoped local in `runJob`, never
+ * attached to `job` or `prepared`, never returned in a result, never passed to `log`, `comment` or
+ * `recordRun` -- and `buildRecord` is an explicit literal with no spread, so it cannot pick it up by
+ * accident. That property is load-bearing now, not incidental.
+ */
+export function makeSecretsResolver({
+	envProfiles = {},
+	roots = [],
+	// The operator's PI_FORWARD_ENV names. Needed here rather than in triggers.mjs because that validator
+	// is env-free: see the reserved-name check below.
+	forwardEnv = [],
+	timeoutMs = 10000,
+	spawnFn = spawn,
+	hostEnv = process.env,
+	// Injected so the executable probe is testable without a real script on disk. `statSync`, NOT `lstat`,
+	// which is a deliberate divergence from processor.mjs's isReadableDir: that one judges a symlinked
+	// DIRECTORY on its own inode, while this must answer the same question `spawn` will ask, and `spawn`
+	// follows symlinks -- so `lstat` would refuse an ordinary /usr/local/bin/op -> ../Cellar/... The mode is
+	// deliberately NOT checked here: a group- or world-writable resolver is a doctor WARNING, on the
+	// env-setup precedent, because refusing a job over a mode bit at job time is a new class of refusal.
+	realExecutablePath = (p) => {
+		const real = realpathSync(p);
+		const st = statSync(real);
+		return st.isFile() && (st.mode & 0o111) !== 0 ? real : null;
+	},
+	log = () => {},
+} = {}) {
+	return async function resolveSecrets(job, { signal, overlayProfiles = {} } = {}) {
+		const merged = mergeSecretProfiles(envProfiles, overlayProfiles);
+		if (merged.ambiguous) return { ambiguous: merged.ambiguous };
+
+		const wanted = typeof job?.secretsProfile === "string" && job.secretsProfile !== "" ? job.secretsProfile : DEFAULT_SECRETS_PROFILE;
+		const declared = merged.profiles[wanted];
+		// A LOOKUP, never a fallback. There is deliberately no "if only one profile is declared, use it"
+		// rule: env-allowlist.mjs records what the last `else` of that shape cost, and a default whose
+		// meaning changes the day a second profile appears is that mistake with a slower fuse.
+		if (typeof declared !== "string") return { profileUnknown: wanted };
+
+		let path;
+		try {
+			path = realExecutablePath(declared);
+		} catch {
+			path = null;
+		}
+		if (!path) return { profileUnknown: wanted };
+		// The bound is checked on the REALPATH, and in the WORKER rather than only where a profile is
+		// written. A panel-side check alone would be cosmetic: the settings overlay defaults into the OS
+		// temp directory, so on a multi-user host the directory can be pre-created by anyone. Checking here
+		// caps a tampered overlay at "choose among scripts the operator allowlisted" instead of "name any
+		// executable on the host". An env-declared profile is exempt: PI_SECRET_PROFILES already lives
+		// beside the forge tokens and the App key, so requiring roots for it would bound nothing and would
+		// break every deployment that never wanted panel authoring.
+		const fromOverlay = !(wanted in envProfiles);
+		if (fromOverlay && !withinRoots(path, roots)) return { profileUnknown: wanted };
+
+		const references = job?.secrets ?? {};
+
+		// The half of the reserved-name refusal that parseTriggers structurally cannot make. It refuses every
+		// STATICALLY knowable name (the mint's, each forge's host var, the worker-only secrets, the egress
+		// policy's, and the closed map's own PI_*/PLAYWRIGHT_*), but two more sets are DEPLOYMENT STATE:
+		//
+		//   - the provider credential's variable names, which come from `findEnvKeys(provider, hostEnv)` and so
+		//     depend on the job's resolved provider AND on what this host has set;
+		//   - PI_FORWARD_ENV, which is an operator env list.
+		//
+		// Both are load-bearing rather than tidy. buildContainerEnv writes the provider credential BEFORE this
+		// feature's assignment, so a trigger binding ANTHROPIC_API_KEY would silently replace the credential
+		// every job of that trigger spends -- verbatim the failure env-allowlist.mjs's header exists to
+		// prevent, arriving through a new door. PI_FORWARD_ENV is a second route to the same place, because
+		// that list is how a CUSTOM provider's key reaches the container.
+		//
+		// Refused rather than resolved by ordering, which is the division of labour the mint already keeps:
+		// ordering is the backstop, the refusal is the gate.
+		const reserved = new Set([...(providerKeyVars(job?.provider, hostEnv) ?? []), ...forwardEnv]);
+		for (const name of Object.keys(references)) {
+			if (reserved.has(name)) return { reserved: name };
+		}
+		const secrets = {};
+		const seen = new Map();
+		for (const [name, reference] of Object.entries(references)) {
+			if (seen.has(reference)) {
+				// Two names sharing one reference resolve once, so they are guaranteed identical rather than
+				// straddling a rotation that lands between two reads.
+				secrets[name] = seen.get(reference);
+				continue;
+			}
+			const outcome = await runResolver(spawnFn, path, reference, { timeoutMs, hostEnv, signal });
+			if (outcome.failure) {
+				// The NAME, our own failure vocabulary, the script's small integer exit and a byte COUNT.
+				// Never the resolver's words, never the reference, never the path (no-pii-in-logs).
+				log("secret_resolve_failed", { name, failure: outcome.failure, detail: outcome.detail, code: outcome.code ?? null, stderrBytes: outcome.stderrBytes });
+				const shape = { failure: outcome.detail, code: outcome.code ?? null, stderrBytes: outcome.stderrBytes };
+				// The whole job refuses, never a partial set: a job missing one of three secrets fails deep
+				// inside a paid container in a way that reads as a flow bug.
+				return outcome.failure === "infra" ? { unreachable: name, ...shape } : { unresolved: name, ...shape };
+			}
+			seen.set(reference, outcome.value);
+			secrets[name] = outcome.value;
+		}
+		return { ok: true, secrets };
+	};
+}

package/src/start.mjs

@@ -25,6 +25,7 @@ import { makeSessionStore } from "./session-store.mjs";
 import { loadPauseWindows, pauseUntilMs } from "./pause-windows.mjs";
 import { makeQueue } from "./queue.mjs";
 import { makeRunContainer } from "./run-container.mjs";
+import { makeSecretsResolver } from "./secrets.mjs";
 import { buildRecord, makeFindPreviousRun, makeLogReaper, makeLogSink, makeRecordWriter } from "./run-history.mjs";
 import { effectiveSettings, readOverlay } from "./runtime-settings.mjs";
 import { loadSchedules } from "./schedules.mjs";
@@ -162,6 +163,7 @@ export async function startWorker(
 		makeLogReaper: makeLogReaperFn = makeLogReaper,
 		makeSandboxReaper: makeSandboxReaperFn = makeSandboxReaper,
 		makeRunContainer: makeRunContainerFn = makeRunContainer,
+		makeSecretsResolver: makeSecretsResolverFn = makeSecretsResolver,
 		makeImagePreflight: makeImagePreflightFn = makeImagePreflight,
 		makeEgressPreflight: makeEgressPreflightFn = makeEgressPreflight,
 		makeGitLabAuth: makeGitLabAuthFn = makeGitLabAuth,
@@ -326,7 +328,12 @@ export async function startWorker(
 			log("settings_overlay_invalid", { reason: res.invalid, settingsFile });
 			return { invalid: res.invalid };
 		}
-		return effectiveSettings(config, res.overlay);
+		// REQ-TRIGGER-SECRETS rides ALONGSIDE the ten tunables rather than inside them. `effectiveSettings`
+		// resolves `overlay > env` over a fixed ten-key literal, and its own tests pin that key set and
+		// assert an empty overlay returns the config verbatim -- so an eleventh key there would break both,
+		// and would also claim a precedence this key deliberately does not have (a name declared in both
+		// sources is refused per delivery, not silently won by either).
+		return { ...effectiveSettings(config, res.overlay), secretProfiles: res.overlay?.secretProfiles ?? {} };
 	};
 
 	// Resolve the Worker constructor's slot count once from the overlay: a present overlay may raise or lower
@@ -421,6 +428,14 @@ export async function startWorker(
 			// real path; the difference shows under an injected env, where the store would be built from the
 			// synthetic value while the gate read the process one.
 			sessionsDir: config.sessionsDir,
+			// REQ-TRIGGER-SECRETS. Built here for the image and egress preflights' reason: one deployment
+			// value, one place, so the gate that refuses an unknown profile and the spawn that runs it cannot
+			// disagree about which resolvers exist. The env-declared table is parsed once at boot (it is env,
+			// and a change to it is a restart), while the OVERLAY half arrives per job through index.mjs,
+			// because the settings file is read at each job start and an operator who declares a profile in
+			// the panel should not have to restart the worker to use it. A deployment that declares nothing
+			// spawns nothing at all: the gate only calls this when a trigger is armed.
+			resolveSecrets: makeSecretsResolverFn({ envProfiles: config.secretProfiles, roots: config.secretResolverRoots, timeoutMs: config.secretResolveTimeoutMs, forwardEnv: config.forwardEnv, log }),
 			runContainer: makeRunContainerFn({
 				image: config.jobImage,
 				hostEnv: env,