@edgehero/pi-dispatch 1.2.0 → 1.3.0

package/.env.example

@@ -89,6 +89,17 @@ PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may nam
 # PI_FORWARD_ENV=                   # comma-separated extra env var NAMES to forward into the container (e.g. a CUSTOM provider's key). Explicit allowlist, not a pass-through.
                                     # GITHUB_TOKEN/GH_TOKEN are refused here -- the worker mints per-job tokens
 
+# --- Per-trigger vault secrets (docs/secrets.md, issue #225) ---
+# A trigger may name references ("secrets": { "STRIPE_KEY": "op://ci/stripe/api-key" }) and the profile that
+# resolves them. The worker runs YOUR script once per reference, on the HOST, before the container starts.
+# The job receives values; it never holds your manager's credential and cannot enumerate your vault.
+# PI_SECRET_PROFILES=               # name:/absolute/path pairs, comma separated (each entry splits on its FIRST colon, so a Windows C:\ path parses).
+#                                     A resolver is one line: `exec op read --no-newline "$1"`, `exec pass show "$1"`, `exec vault kv get -field=... "$1"`.
+#                                     Exit 2 if the reference is wrong, exit 1 if you could not reach your manager (that one retries). Unset = feature off.
+# PI_SECRET_RESOLVER_ROOTS=         # OS-path-delimited (; on Windows, : elsewhere) directories a PANEL-declared resolver may live in.
+#                                     Default empty = fail-closed: `/dispatch secrets add` can declare nothing, and only PI_SECRET_PROFILES above is honoured.
+# PI_SECRET_RESOLVE_TIMEOUT_MS=     # default 10000, per reference. Sits before a paid container and is multiplied by the reference count, so tighter than doctor's 30s.
+
 PI_SCHEDULER_STALL_MAX=2            # tear down a scheduler after N consecutive stalls (money backstop)
 
 # --- Egress policy: what a job container may reach on the network (docs/egress.md) ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
   "keywords": [

package/src/config.mjs

@@ -9,6 +9,7 @@ import { existsSync } from "node:fs";
 import { delimiter } from "node:path";
 import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
 import { MINTED_TOKEN_VARS } from "./forges.mjs";
+import { parseSecretProfiles } from "./secret-profiles.mjs";
 
 export function configError(message) {
 	const error = new Error(message);
@@ -278,6 +279,22 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		chainMaxPerJob: nonNegativeInt(env, "PI_CHAIN_MAX_PER_JOB", CHAIN_MAX_PER_JOB_DEFAULT), // INT-OUTBOX-CONTRACT: max request-<n>.json collected per parent
 		dispatchRunPerHour: nonNegativeInt(env, "PI_DISPATCH_RUN_PER_HOUR", 3), // DES-ADMIN-VIA-PI-EXTENSION; 0 = disable dispatch_run
 		dispatchRunRoots: delimitedList(env.PI_DISPATCH_RUN_ROOTS), // DES-AI-TRIGGER-FLOW-GATE: default [] fails closed — no folder passes, dispatch_run refuses everything
+		// REQ-TRIGGER-SECRETS. The operator's declared resolvers, `name:absolute-path` pairs, comma separated.
+		// Each entry splits on its FIRST colon so a Windows `C:\...` path survives -- the same drive-letter
+		// hazard `delimitedList` above exists for, arriving from the other side. Unset = the feature is off and
+		// any trigger naming secrets refuses pre-spend, which is why there is no default profile to fall into.
+		secretProfiles: parseSecretProfiles(env.PI_SECRET_PROFILES),
+		// The directories a resolver may live in. Default [] FAILS CLOSED exactly as dispatchRunRoots does, and
+		// for a sharper version of its reason: this bounds paths that can arrive from the settings overlay,
+		// which is not the reviewed artifact `triggers.json` is. Unset means the panel can declare no profile
+		// at all and only PI_SECRET_PROFILES above is honoured. Env-only, never the overlay and never the
+		// deployment pointer: `deployment-pointer.mjs` already refuses to carry PI_DISPATCH_RUN_ROOTS
+		// "because a pointer that could widen the AI-run folder allowlist would be a second, unreviewed door",
+		// and a bound that can be widened from the surface it bounds is not a bound.
+		secretResolverRoots: delimitedList(env.PI_SECRET_RESOLVER_ROOTS),
+		// Per-reference ceiling. Tighter than doctor's 30s on purpose: this runs before a paid container, is
+		// multiplied by the reference count, and holds a PI_CONCURRENCY slot while it waits.
+		secretResolveTimeoutMs: positiveInt(env, "PI_SECRET_RESOLVE_TIMEOUT_MS", 10000),
 		github: { ...loadGitHubAuth(env, fileExists), allowGhResume: env.PI_SESSIONS_ALLOW_GH_SOURCE === "1" },
 		gitlab: loadGitLabAuth(env),
 		forgejo: loadForgejoAuth(env),

package/src/doctor.mjs

@@ -46,7 +46,7 @@
  */
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
 import { defaultSandboxDir, globalExtensionsEnabled } from "./config.mjs";
@@ -58,6 +58,7 @@ import { copySkillTree } from "./copy-tree.mjs";
 import { SKILL_NAME_RE } from "./flow-gate.mjs";
 import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
 import { installedUnitPaths, readUnitSeam } from "./service.mjs";
+import { parseSecretProfiles } from "./secret-profiles.mjs";
 import { parseTriggers } from "./triggers.mjs";
 
 const NODE_FLOOR = [22, 19]; // pi's engine floor (22.19.0)
@@ -263,7 +264,7 @@ export async function collectChecks(env, seams) {
 	// image checks just below, and `optingOut`/`requiring` colour the staged-packages lines further down.
 	// `optingOut` counts the only value that withholds the staged set; `requiring` counts an explicit
 	// run.packages: true, which arms nothing any more but is still an operator statement of intent.
-	const { requiring, optingOut, resuming, replicating, instructing, commands, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
+	const { requiring, optingOut, resuming, replicating, instructing, commands, secreting, secretProfiles, localSecretFolders, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
 	// FIRST, and fail rather than warn: every check below this line reads counts that a parse failure
 	// zeroed, so a green run here would be reporting on a file nobody could read. The receiver loads this
 	// file unconditionally and refuses to start without it, which is the consequence worth naming.
@@ -1096,6 +1097,52 @@ export async function collectChecks(env, seams) {
 		});
 	}
 
+	// REQ-TRIGGER-SECRETS. Only reported when a trigger actually binds one, on the run.resume block's
+	// reasoning below: a deployment that uses no secrets should not be told about a variable it has no
+	// reason to set.
+	if (secreting > 0) {
+		const declared = parseSecretProfilesSafe(env.PI_SECRET_PROFILES);
+		const names = Object.keys(declared).sort();
+		if (declared.error) {
+			checks.push({ ok: false, label: "PI_SECRET_PROFILES does not parse", fix: `${declared.error} -- the worker refuses to boot until this is fixed, rather than dropping the entry and leaving you a profile you believe is wired` });
+		} else {
+			// A HARD FAIL, not a warning, and worded like the run.resume/PI_SESSIONS_DIR check below for the
+			// same reason: these jobs refuse pre-spend until it is set, deliberately, rather than running
+			// without their secrets and looking like they worked.
+			const missing = secretProfiles.filter((name) => !(name in declared));
+			checks.push({
+				ok: missing.length === 0,
+				label: missing.length === 0 ? `${secreting} trigger(s) bind secrets, and every profile they name is declared` : `${secreting} trigger(s) bind secrets, but ${missing.length} named profile(s) are not declared: ${missing.join(", ")}`,
+				fix: `declare them in PI_SECRET_PROFILES as name:/absolute/path pairs (a resolver is one line, e.g. \`exec op read --no-newline "$1"\`) -- these jobs refuse pre-spend until you do`,
+			});
+			// The declared table, so an operator sees what is wired without reading .env. NAMES and paths only:
+			// this is doctor's own stdout on the operator's host, not a public issue comment.
+			if (names.length > 0) {
+				checks.push({ ok: true, label: `Secret resolver profiles declared: ${names.map((n) => `${n} -> ${declared[n]}`).join(", ")}` });
+			}
+			// The panel-authoring bound. Unset is the SAFE default rather than a defect, so this is a fact line
+			// when closed and a disclosure when open.
+			const roots = (env.PI_SECRET_RESOLVER_ROOTS ?? "").split(delimiter).map((r) => r.trim()).filter(Boolean);
+			checks.push({
+				ok: true,
+				...(roots.length === 0
+					? { label: "PI_SECRET_RESOLVER_ROOTS is unset, so only PI_SECRET_PROFILES declares resolvers (the panel can declare none)" }
+					: { warn: true, label: `PI_SECRET_RESOLVER_ROOTS admits panel-declared resolvers under: ${roots.join(", ")}`, fix: "keep those directories writable by nobody but the account the worker runs as: whoever can write a resolver there can run code as the worker" }),
+			});
+		}
+		// The local-workspace disclosure. Not a failure: a nightly deploy binding a secret is exactly what
+		// this feature is for. But a local job's /workspace IS the folder, read-write and un-cloned, so an
+		// agent that persists a credential to make its next command simpler writes it into a real repository.
+		if (localSecretFolders.length > 0) {
+			checks.push({
+				ok: true,
+				warn: true,
+				label: `${localSecretFolders.length} local trigger(s) bind secrets and run IN the operator's own folder: ${localSecretFolders.join(", ")}`,
+				fix: "a local job edits that folder in place, so a credential the agent writes to .env, .netrc or .git-credentials lands in your real repository (and survives in a retained sandbox for PI_SANDBOX_RETENTION_HOURS). Nothing scans for that: keep those folders out of anything you push",
+			});
+		}
+	}
+
 	// REQ-RESUMABLE-SESSION. Only reported when a trigger actually asked for it: a deployment that does
 	// not use resume should not be told about a directory it has no reason to create.
 	if (resuming > 0) {
@@ -1410,8 +1457,22 @@ async function repoFlowAtHead(spawn, folder, flow) {
 	return mode === "100644" && type === "blob" ? "present" : "absent";
 }
 
+/**
+ * `parseSecretProfiles`, but doctor never throws. A malformed PI_SECRET_PROFILES is a finding to REPORT,
+ * not a reason for the diagnostic tool to die: the operator running doctor is very likely running it
+ * BECAUSE the worker refused to boot on that exact line, and a stack trace instead of a check is the least
+ * useful possible answer. Returns the table, or `{ error }` carrying the parser's own message.
+ */
+function parseSecretProfilesSafe(raw) {
+	try {
+		return parseSecretProfiles(raw);
+	} catch (err) {
+		return { error: err?.message ?? "unparseable" };
+	}
+}
+
 function readTriggerFacts(env, fileExists, cwd) {
-	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
+	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, secreting: 0, secretProfiles: [], localSecretFolders: [], images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
 	try {
 		// Unset falls back to ./triggers.json in cwd, MIRRORING the receiver's own default
 		// (receiver/src/config.mjs) -- the two must read the same file, or doctor preflights a deployment
@@ -1432,6 +1493,17 @@ function readTriggerFacts(env, fileExists, cwd) {
 			// tuple list already filters to `typeof f.flow === "string"`, so a command trigger drops out
 			// of the flow-tier probes naturally -- no exclusion needed there.
 			commands: triggers.filter((t) => typeof t.run.command === "string").length,
+			// REQ-TRIGGER-SECRETS. Counted beside `instructing` for its reason: a per-trigger choice that
+			// changes what every job of it can reach, and one that lives only in triggers.json.
+			secreting: triggers.filter((t) => t.run.secrets !== undefined).length,
+			// The distinct profile NAMES the file selects, deduped like `images`/`skillsDirs`: the checks below
+			// cost a stat each, and two triggers naming one profile are one question. `default` is substituted
+			// for an absent field so the table answers what the worker will actually look up.
+			secretProfiles: [...new Set(triggers.filter((t) => t.run.secrets !== undefined).map((t) => t.run.secretsProfile ?? "default"))].sort(),
+			// LOCAL triggers that bind secrets, by folder. A local job's /workspace IS this folder, bind-mounted
+			// read-write with no clone, so a credential an agent writes into .env lands in the operator's real
+			// repository rather than a temp dir that gets swept. Deduped for skillsDirs' reason.
+			localSecretFolders: [...new Set(triggers.filter((t) => t.run.secrets !== undefined && t.run.kind === "local" && typeof t.run.folder === "string").map((t) => t.run.folder))].sort(),
 			optingOut: triggers.filter((t) => t.run.packages === false).length,
 			images: [...new Set(triggers.map((t) => t.run.image).filter((i) => typeof i === "string"))].sort(),
 			// REQ-PER-TRIGGER-SKILLS. The distinct host directories the file names, deduped like `images`,

package/src/env-allowlist.mjs

@@ -111,7 +111,7 @@ function resolveEnvName(provider, cred) {
  * `allowGlobalExtensions` defaults to TRUE here, matching loadConfig's default (REQ-GLOBAL-PI-OVERLAY): a
  * caller that says nothing gets the operator's staged setup, and only an explicit `false` withholds it.
  */
-export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], sessionFile = null, flow = null, command = null, authFromPi = false, egress = false, egressProxy, agentDir, readFile = readFileSync }) {
+export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, authFromPi = false, egress = false, egressProxy, agentDir, readFile = readFileSync }) {
 	// The provider credential(s), by pi's expected variable name(s) -- from the worker env, or (when
 	// PI_AUTH_FROM_PI is set and the env has none) host-side from pi's auth.json. Throws (config) if
 	// neither source yields one, which the processor turns into a pre-spend refusal.
@@ -182,6 +182,36 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, jobId,
 		if (hostEnv[name] !== undefined) env[name] = hostEnv[name];
 	}
 
+	// The trigger's own secrets (REQ-TRIGGER-SECRETS), resolved HOST-SIDE by the processor before anything
+	// spent and injected exactly the way the provider credential is -- never a vault credential handed to the
+	// container to fetch them itself. `docs/secrets.md`'s rule survives intact: what crosses the boundary is a
+	// value, and the thing that can FETCH values stays on the host.
+	//
+	// AFTER the PI_FORWARD_ENV loop, for that loop's own stated reason: a name on the operator's blanket host
+	// list must not silently outrank the specific reference this trigger declared.
+	//
+	// BEFORE the egress assign, and that direction is deliberate rather than incidental. A secret named
+	// HTTPS_PROXY that WON would point this job away from the proxy its --internal network was built around,
+	// while reading exactly like the control working -- an OUTAGE dressed as a policy. config.mjs refuses
+	// those names in PI_FORWARD_ENV outright while the policy is armed, for the same reason.
+	//
+	// BEFORE the mint below too, so the per-job scoped token still wins. A vault-supplied GITHUB_TOKEN overwriting
+	// the mint would hand every container a long-lived operator credential: CONST-TOKEN-SCOPED-PER-JOB
+	// defeated by a config line, which is the inversion forwardEnvList refuses at boot.
+	//
+	// Ordering is the BACKSTOP, not the gate. parseTriggers refuses every statically knowable one of these
+	// names at load, and the processor refuses the provider's own credential variables and the PI_FORWARD_ENV
+	// names pre-spend, where the resolved provider and the host env are in hand. This is the same division of
+	// labour the minted token already keeps ("and loadConfig refuses those names at load anyway").
+	//
+	// A LOOP rather than Object.assign, so a non-string or empty value becomes an ABSENT variable rather than
+	// `NAME=`: docker-run skips `undefined` but not `""`, and "never an empty string" is the rule PI_PACKAGES,
+	// PI_SESSION_FILE and PI_FLOW already keep. The resolver guarantees non-empty; this is the defense in
+	// depth at the DI seam that the empty-token guard keeps for the mint.
+	for (const [name, value] of Object.entries(secrets ?? {})) {
+		if (typeof value === "string" && value !== "") env[name] = value;
+	}
+
 	// The shipped egress policy's variables (REQ-EGRESS-ALLOWLIST), AFTER the PI_FORWARD_ENV loop so a
 	// forwarded name can never override them -- the same ordering, for the same reason, as the minted token
 	// below (and loadConfig refuses those names outright while the policy is armed anyway).

package/src/forges.mjs

@@ -135,6 +135,20 @@ export function forgeSpec(kind) {
  */
 export const MINTED_TOKEN_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[kind].tokenVars));
 
+/**
+ * Every environment variable name any forge's SELF-HOSTED INSTANCE URL can land in. A sibling of
+ * `MINTED_TOKEN_VARS` and derived the same way, from the table rather than by hand, so a forge added
+ * later cannot be missed here either.
+ *
+ * Separate from `MINTED_TOKEN_VARS` because `hostVar` is a separate column: the token set is
+ * `tokenVars` only, so a name like `GITLAB_HOST` is in NEITHER set until this one exists. That gap is
+ * not theoretical -- `buildContainerEnv` writes this variable after the mint, so a trigger field able
+ * to name it would be silently overwritten, and the job would run without the value it asked for on a
+ * clean exit 0. github's row is `null` and contributes nothing, which is why the filter is here and
+ * not at the call site.
+ */
+export const FORGE_HOST_VARS = new Set(FORGE_KINDS.map((kind) => FORGES[kind].hostVar).filter((name) => typeof name === "string"));
+
 /**
  * The separator between a repo label and a target number, for this forge and this target type: the
  * forge's own notation for a pull/merge request, and `#` for an issue everywhere.

package/src/index.mjs

@@ -101,6 +101,17 @@ export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, ap
 				tokenCap: settings.dailyTokenCap,
 				...deps,
 				runContainer: (ctx) => deps.runContainer({ ...ctx, name, signal }),
+				// REQ-TRIGGER-SECRETS. The resolver runs INSIDE the 30-minute kill timer armed above, so it has
+				// to be abortable for the same reason runContainer does: a resolver blocking on an unreachable
+				// vault would otherwise hold its slot until its own timeout, and an abort landing mid-resolution
+				// would neither stop it nor keep the job from going on to mint, clone and reserve budget for a
+				// container that runContainer will refuse at entry anyway. Injected here, mirroring runContainer,
+				// because `signal` exists only in this scope. Omitted when unwired so a bare processor keeps
+				// runJob's own fail-closed default.
+				// `secretProfiles` is the OVERLAY half of the resolver table, read this job-start with the ten
+				// tunables above. It is bound here rather than at construction for the reason the overlay exists:
+				// an operator who declares a profile in the panel must not have to restart the worker.
+				...(deps.resolveSecrets ? { resolveSecrets: (j) => deps.resolveSecrets(j, { signal, overlayProfiles: settings.secretProfiles ?? {} }) } : {}),
 				// collectChain (INT-OUTBOX-CONTRACT) reads the completed parent's REAL BullMQ job: its `.id`
 				// (the parent id children carry) and `.data` (kind/chainDepth). runJob's own `job` is the
 				// effectiveJob -- a spread of job.data with no `.id`/`.data` -- so inject the real wrapper here,

package/src/outbox.mjs

@@ -176,6 +176,14 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					// same operator's flows and, without them, would look up a skill that is not there, write a
 					// plausible report and exit 0. It is NOT part of chainedJobId, for the reason stated below.
 					skillsDir: job.data?.skillsDir,
+					// `secrets`/`secretsProfile` are deliberately ABSENT, and the two lines above are exactly why
+					// this comment exists: their reasoning reads as though it should apply here too, and it must
+					// not. An image and a skills directory are toolchain; a resolved credential is a capability.
+					// A child's `task` is AGENT-AUTHORED (read off the request file below), so inheriting the
+					// binding would let a completed agent re-run itself against the operator's vault with a prompt
+					// it wrote for itself. The operator's grant was to the trigger they reviewed, not to whatever
+					// that job decides to queue next. A chained child that genuinely needs a secret gets it from a
+					// trigger of its own, which is an operator edit to a reviewed file.
 					chainDepth: childDepth,
 					parentJobId: job.id,
 					// chainedJobId deliberately does NOT take the image: the child's identity is (parent, flow, task).

package/src/processor.mjs

@@ -1,6 +1,7 @@
 import { lstatSync } from "node:fs";
 import { checkTokenCap, recordTokenSpend, releaseBudget, reserveBudget } from "./budget.mjs";
 import { configError } from "./config.mjs";
+import { DEFAULT_SECRETS_PROFILE, secretsArmed } from "./secrets.mjs";
 import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
 
 /**
@@ -70,6 +71,20 @@ export async function runJob(job, deps) {
 				return false;
 			}
 		},
+		// (job) => { ok: true, secrets } | { profileUnknown } | { unresolved, ... }. The wiring binds the
+		// abort signal into it (index.mjs), the way it binds name+signal into runContainer.
+		// REQ-TRIGGER-SECRETS. Resolves this trigger's `run.secrets` references through the operator's own
+		// resolver, HOST-SIDE, before anything spends. Injected so the gate is testable without a real script.
+		//
+		// The default FAILS CLOSED, deliberately unlike imagePreflight's and egressPreflight's
+		// admit-everything defaults, and for the reason the sessionsDir default states above: an admitting
+		// default would let a job that armed run.secrets start with those variables UNSET under any wiring
+		// that omits this key. That is a false success which looks exactly like the feature working, and it
+		// is the inversion this whole gate exists to prevent. It can be UNCONDITIONALLY refusing because the
+		// gate below only calls it when the job is armed -- putting the arming test in the default instead
+		// would leave an INJECTED resolver running on every job, which is how a probe nobody wanted starts
+		// spawning a subprocess per delivery to learn nothing.
+		resolveSecrets = async (job) => ({ profileUnknown: job.secretsProfile ?? DEFAULT_SECRETS_PROFILE }),
 		// (job) => scoped short-lived token. Takes the JOB, not the repo: which forge mints -- and therefore
 		// which credential the container gets -- is a property of `job.kind`, and only the wiring knows the
 		// map. Called for forge-backed jobs and for local jobs opted in via `github: true`; unflagged local
@@ -77,7 +92,8 @@ export async function runJob(job, deps) {
 		mintToken,
 		isDefaultBranchProtected, // (job, token) => boolean; same reason -- the forge is the job's, not the process's
 		prepareWorkspace, // (job, token) => { workspaceDir, jobDir }  (clone+materialise+prompt)
-		// runContainer({ job, token, prepared, name, signal }) => { code, aborted, turns, tokens, session, usage }. It MUST honour
+		// runContainer({ job, token, prepared, secrets, name, signal }) => { code, aborted, turns, tokens, session, usage, context }.
+		// `secrets` is the resolved map from the gate above: values, already fetched, host-side. It MUST honour
 		// `signal`: stop the container on abort, and reject/exit promptly if `signal.aborted` is already
 		// true at entry (the timeout can fire during a slow prepare). The wiring injects name + signal.
 		runContainer,
@@ -279,6 +295,90 @@ export async function runJob(job, deps) {
 			return { outcome: "policy", reason: "skills-dir-missing", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
 		}
 
+		// REQ-TRIGGER-SECRETS. A trigger that named secret references the worker cannot resolve would run its
+		// flow with those variables UNSET, get a 401 from whatever it was meant to reach, write a plausible
+		// report about why the integration is down, and exit 0.
+		//
+		// PLACEMENT. Strictly before the mint below, the clone in prepareWorkspace, the token-cap read and
+		// reserveBudget, so a refusal here costs nothing (CONST-BUDGET-BEFORE-TOKENS). But it is NOT one of the
+		// "free, determinate, credential-less and I/O-less" gates above, and this comment must not claim it is:
+		// resolving spawns a subprocess per reference against the operator's manager, which is none of those
+		// four things. The precedent it actually follows is one gate LATER -- prepareWorkspace already performs
+		// a full network clone before the budget is reserved. An I/O-bound pre-budget step is established here;
+		// a free one it is not. It sits last among the pre-mint gates because it is both the narrowest and the
+		// only one that can block, so every cheaper answer is already in hand when it runs.
+		//
+		// There is deliberately no cheap "would this resolve?" probe. The reference grammar belongs to the
+		// resolver (#206, #209: the seam is a command), so this project has nothing it could validate short of
+		// asking -- the same shape the branch-protection check takes, where the check IS the real call.
+		//
+		// Guarded by `secretsArmed` at the CALL SITE, not inside the resolver: an unflagged job must not reach
+		// it under ANY wiring, and a guard that lives in the default is a guard an injected resolver skips.
+		const resolved = secretsArmed(job) ? await resolveSecrets(job) : { ok: true, secrets: {} };
+		if (resolved.profileUnknown) {
+			await comment(job, "Refused: this trigger set `run.secrets`, and the resolver profile it names is not usable on this worker host. No profile of that name is declared, or its resolver is absent or not executable. The job would have started with those variables unset, and an agent that gets a 401 writes a plausible report and exits 0. Run `pi-dispatch doctor` on the worker to see which profiles it has. Not run.");
+			// The operator's own profile LABEL, and never a path, a reference, or a byte the resolver printed.
+			// `comment` posts publicly on the issue: a resolver path there publishes the operator's filesystem
+			// layout, and the DECLARED profile names would publish their vault topology -- which is why the
+			// message points at doctor for the list instead of enumerating it. The label itself is
+			// operator-authored trigger config, the same class as the image ref the job-image refusals name.
+			log("refused_secret_profile_unknown", { kind: job.kind ?? null, profile: resolved.profileUnknown });
+			return { outcome: "policy", reason: "secret-profile-unknown", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
+		if (resolved.ambiguous) {
+			// Two sources declared one profile name. Neither wins, deliberately: runtime-settings documents the
+			// overlay's precedence as overlay > env, so inverting it here would leave two rules disagreeing about
+			// what an overlay is, while honouring it would let a settings file in a world-writable default
+			// directory redirect a profile the operator wrote in .env. This project already refuses ambiguity
+			// rather than resolving it (PI_EGRESS: "a typo must never leave you believing you have a policy you
+			// do not"), and an operator who sees this fixes it in seconds.
+			await comment(job, "Refused: this trigger set `run.secrets`, and the resolver profile it names is declared twice on this worker host, once in the environment and once in the settings overlay. Neither wins, on purpose: the job would otherwise run against whichever one happened to be picked. Remove one of the two. Not run.");
+			log("refused_secret_profile_ambiguous", { kind: job.kind ?? null, profile: resolved.ambiguous });
+			return { outcome: "policy", reason: "secret-profile-ambiguous", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
+		if (resolved.reserved) {
+			// A key the worker itself writes, and one parseTriggers could not have caught: the provider
+			// credential's variable names depend on this job's resolved provider and on what this host has set,
+			// and PI_FORWARD_ENV is an operator env list. Both are deployment state, so this is the same
+			// load-time / pre-spend split run.resume makes against PI_SESSIONS_DIR.
+			//
+			// It matters most in the direction that is hardest to see: buildContainerEnv writes the provider
+			// credential BEFORE this feature's values, so a trigger binding ANTHROPIC_API_KEY would silently
+			// redirect which credential every job of that trigger spends.
+			await comment(job, `Refused: this trigger's \`run.secrets\` binds \`${resolved.reserved}\`, and the worker sets that variable itself for every job. The container would receive the worker's value rather than this trigger's, and the trigger would look like it worked. Rename it in the triggers file. Not run.`);
+			// The variable NAME only. It is the operator's own choice of name, not payload, and naming it is what
+			// makes the refusal actionable -- but the REFERENCE behind it never appears.
+			log("refused_secret_name_reserved", { kind: job.kind ?? null, name: resolved.reserved });
+			return { outcome: "policy", reason: "secret-name-reserved", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
+		if (resolved.unresolved) {
+			// DETERMINATE: the resolver said exit 2, printed nothing, overran the size cap, or returned a value
+			// with a NUL in it. Retrying cannot change any of those, so this RETURNS (CONST-RETRY-INFRA-ONLY).
+			const why = SECRET_FAILURES[resolved.failure] ?? "did not return a value";
+			await comment(job, `Refused: this trigger set \`run.secrets\`, and the resolver for \`${resolved.unresolved}\` ${why}. The job would have started with that variable unset, and an agent that gets a 401 writes a plausible report and exits 0. Run your profile's resolver by hand against that reference to see why: this comment carries neither the reference, nor the resolver's path, nor a byte of what it printed. Not run.`);
+			// The variable NAME, never a value -- the restraint refused_sessions_dir_unset keeps, and the name is
+			// the operator's own choice rather than payload. `failure` is OUR enum, `code` the script's small
+			// integer exit, `stderrBytes` a COUNT: never the resolver's words.
+			log("refused_secret_unresolved", { kind: job.kind ?? null, name: resolved.unresolved, failure: resolved.failure ?? null, code: resolved.code ?? null, stderrBytes: resolved.stderrBytes ?? 0 });
+			return { outcome: "policy", reason: "secret-unresolved", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
+		if (resolved.unreachable) {
+			// INDETERMINATE: exit 1 ("could not reach my manager"), an exit code we do not recognise, a spawn
+			// fault, or a timeout. THROWS, so BullMQ retries per `attempts` -- the determinate/indeterminate split
+			// the image and egress preflights already draw, decided here by the resolver's own exit code rather
+			// than by matching its stderr, which image-preflight.mjs forbids for good reason. Folding this into
+			// the refusal above would permanently burn a delivery over a twenty-second vault blip, and a webhook
+			// does not redeliver itself. Nothing has spent: `budgetReserved` computes false in the catch below
+			// because `reserved` is still false here.
+			log("secret_resolver_unreachable", { kind: job.kind ?? null, name: resolved.unreachable, failure: resolved.failure ?? null, code: resolved.code ?? null, stderrBytes: resolved.stderrBytes ?? 0 });
+			throw new InfraRetry(`secret resolver could not answer for ${resolved.unreachable}`, { reason: "secret-resolver-unreachable", provider: job.provider ?? null, model: job.model ?? null });
+		}
+		const secrets = resolved.secrets ?? {};
+
 		if (wantsForgeToken) {
 			token = await mintToken(job);
 
@@ -351,7 +451,7 @@ export async function runJob(job, deps) {
 			return { outcome: "policy", reason: budget.reason, exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: true }; // return => not retried
 		}
 
-		const { code, aborted, turns, tokens, session, usage, context } = await runContainer({ job, token, prepared });
+		const { code, aborted, turns, tokens, session, usage, context } = await runContainer({ job, token, prepared, secrets });
 		log("container_exit", { exitCode: code, aborted });
 
 		// Record token spend post-run (the check-AFTER half of the lagging token cap). The container ran,
@@ -492,6 +592,19 @@ function mergeSession(prepared, fromRunner, promoted = null) {
 	};
 }
 
+/**
+ * Our own words for why a resolver did not produce a value, turned into a phrase at the refusal site --
+ * the shape the egress refusal already uses for its `state` discriminator. The `??` fallback in the caller
+ * is not decoration: a failure code added in secrets.mjs must degrade to a generic sentence rather than
+ * print `undefined` on a public issue.
+ */
+const SECRET_FAILURES = {
+	exit: "refused that reference",
+	empty: "printed nothing",
+	overflow: "printed more than the size cap allows",
+	nul: "printed a value containing a NUL byte, which cannot survive the container's argv",
+};
+
 export class InfraRetry extends Error {
 	constructor(message, { cause, reason, exitCode, turns, tokens, session, usage, provider, model, budgetReserved } = {}) {
 		super(message, cause ? { cause } : undefined);

package/src/queue.mjs

@@ -16,7 +16,7 @@ export function makeQueue(connection) {
  * 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, skillsDir, chainDepth, parentJobId, jobId, now = new Date() }) {
+export async function enqueueLocalJob(queue, { folder, flow, task, command, provider, model, maxTurns, image, 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
@@ -47,6 +47,11 @@ export async function enqueueLocalJob(queue, { folder, flow, task, command, prov
 		// than inside `trigger` because a worker-host path is an execution knob, not a fact about the
 		// delivery -- and `trigger` is the object copied into /job/event.json.
 		...(skillsDir !== undefined && { skillsDir }),
+		// REQ-TRIGGER-SECRETS, on the forge path's terms: references only, resolved by the worker at job
+		// start. A cron trigger may bind secrets (a nightly deploy is the obvious user), which is where
+		// this differs from `replicas` -- that one is refused on a local job and this one is not.
+		...(secrets !== undefined && { secrets }),
+		...(secretsProfile !== undefined && { secretsProfile }),
 		...(chainDepth !== undefined && { chainDepth }),
 		...(parentJobId !== undefined && { parentJobId }),
 	};
@@ -124,7 +129,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, skillsDir, instructions, resume, replica, replicas }) {
+export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, command, trigger, provider, model, maxTurns, packages, image, skillsDir, instructions, resume, secrets, secretsProfile, 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`
@@ -162,6 +167,13 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// delivery, and `trigger` is what /job/event.json is built from.
 		...(instructions !== undefined && { instructions }),
 		...(resume !== undefined && { resume }),
+		// REQ-TRIGGER-SECRETS. The env variables this trigger binds and the profile whose resolver reads
+		// them. REFERENCES only: no value is ever enqueued, because a queued job is durable and a resolved
+		// credential in Redis would outlive the container it was scoped to. The worker resolves them at job
+		// start, pre-spend. At JOB level rather than inside `trigger` for image/skillsDir's reason: `trigger`
+		// is copied verbatim into /job/event.json, which an agent reads.
+		...(secrets !== undefined && { secrets }),
+		...(secretsProfile !== undefined && { secretsProfile }),
 		// Conditional for the same reason packages/image/resume are: an unflagged job's data must keep
 		// exactly the keys it has today. `replica` is this job's 1-based index and `replicas` the set size;
 		// both are integers, so the run record they land in stays PII-free by construction.

package/src/reserved-env.mjs

@@ -0,0 +1,40 @@
+/**
+ * The environment variable names `buildContainerEnv` writes itself, spelled once (issue #225).
+ *
+ * This exists because `run.secrets` lets a trigger name env variables, and a trigger that names one the
+ * closed map already owns would either be silently overwritten (the job runs without the value it asked
+ * for, on a clean exit 0) or silently WIN (a trigger redirecting `PI_OFFLINE` or `PI_MAX_TURNS`). Both
+ * are the inversion `env-allowlist.mjs`'s header exists to prevent, arriving through a new door.
+ *
+ * A SEPARATE MODULE, and it has no imports at all, on purpose. `triggers.mjs` is the shared validator:
+ * it is pure and fs-free, the receiver loads it, and `admin/build.mjs` INLINES it into the published
+ * console. Importing `env-allowlist.mjs` to reach these names would drag `node:fs`, `node:os` and pi's
+ * compat shim into all three, to read a list of strings. So the list moves down here, where both can
+ * 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
+ * `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.
+ *
+ * `worker/test/env-allowlist.test.mjs` pins this set against what `buildContainerEnv` actually emits, so
+ * a variable added to the closed map and not to this list fails there rather than becoming a hole here.
+ */
+export const CONTAINER_ENV_NAMES = new Set([
+	"PI_PROVIDER",
+	"PI_MODEL",
+	"PI_MAX_TURNS",
+	"PI_MAX_TOKENS",
+	"PI_JOB_ID",
+	"PI_GLOBAL_ALLOW_EXTENSIONS",
+	"PI_PACKAGES",
+	"PI_SESSION_FILE",
+	"PI_FLOW",
+	"PI_COMMAND",
+	"PI_OFFLINE",
+	"PLAYWRIGHT_BROWSERS_PATH",
+	"PLAYWRIGHT_MCP_BROWSER",
+	"PLAYWRIGHT_MCP_SANDBOX",
+]);

package/src/run-container.mjs

@@ -7,7 +7,7 @@ import { InfraRetry } from "./processor.mjs";
 
 /**
  * The real `runContainer` the processor injects. Launches one job container and returns
- * `{ code, aborted, turns, tokens, session, usage }`, where `aborted` records whether the WORKER initiated the stop (docker stop on
+ * `{ code, aborted, turns, tokens, session, usage, context }`, where `aborted` records whether the WORKER initiated the stop (docker stop on
  * the 30-min timeout or graceful shutdown), which the processor classifies as POLICY (no retry) per
  * INT-RUNNER-EXIT-CODE-PROTOCOL. The numeric `code` alone cannot say this: a worker SIGKILL and a
  * kernel OOM both surface as 137, so the abort FLAG -- not the code -- is the discriminator.
@@ -46,7 +46,7 @@ export function makeRunContainer({
 }) {
 	// async so a synchronous throw (e.g. buildContainerEnv on an unconfigured provider) surfaces as
 	// a rejection, uniformly awaitable by the processor and by tests.
-	return async function runContainer({ job, token, prepared, name, signal }) {
+	return async function runContainer({ job, token, prepared, secrets = {}, name, signal }) {
 		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null, context: null }; // killed before it could start
 
 		// Closed env allowlist: only the provider key + the declared PI_* vars. Throws (config) if
@@ -87,6 +87,10 @@ export function makeRunContainer({
 			// mutually exclusive with it by parse -- a job carries one or the other, never both.
 			command: typeof job.command === "string" && job.command.trim() !== "" ? job.command : undefined,
 			authFromPi, // source the provider key from pi's auth.json when the env has none
+			// REQ-TRIGGER-SECRETS: this trigger's resolved secrets, fetched by the processor BEFORE anything
+			// spent. Off the call bag rather than off `job` or the closure: it is neither a per-job fact the
+			// record may carry nor a deployment setting, it is a live credential, and `token` is its precedent.
+			secrets,
 		});
 
 		// `-net` on this container's own name (egress.mjs). null when no policy is armed, and docker-run's

package/src/runtime-settings.mjs

@@ -27,6 +27,22 @@ import { defaultSettingsFile } from "./config.mjs";
 
 export const KNOWN_KEYS = ["model", "provider", "maxTurns", "dailyCap", "weeklyCap", "monthlyCap", "maxTokens", "dailyTokenCap", "concurrency", "softHoldPct"];
 
+/**
+ * Overlay keys the OVERLAY accepts but no model-callable tool may set. `secretProfiles` maps a profile name
+ * to an absolute path to a script the worker executes, which is plainly "a capability the model would
+ * GAIN" -- the test `admin/src/index.ts` already applies to `run.image` and `run.resume`.
+ *
+ * The mechanism is the OMISSION from KNOWN_KEYS above: `dispatch_set` narrows its open string parameter
+ * with `KNOWN_KEYS.includes(...)`, and the panel's generic settings dialog is a `ui.select` over the same
+ * array, so leaving the key out closes both doors at once. This constant exists so that omission has a NAME
+ * and a reason attached to it. Without one, `KNOWN_KEYS` silently stops meaning "keys the overlay accepts"
+ * and the next contributor tidies the gap away as an oversight.
+ *
+ * A profile is declared through the operator-typed `/dispatch` command instead, which pi reaches only from
+ * its own user-input path, and every declared path is bounded by PI_SECRET_RESOLVER_ROOTS in the worker.
+ */
+export const OPERATOR_ONLY_KEYS = ["secretProfiles"];
+
 function isNonEmptyString(value) {
 	return typeof value === "string" && value.trim() !== "";
 }
@@ -85,6 +101,30 @@ function validateOverlay(candidate, log) {
 				if (!isIntInRange(value, 1, 10)) return { invalid: "concurrency must be an integer 1-10" };
 				overlay[key] = value;
 				break;
+			case "secretProfiles": {
+				// REQ-TRIGGER-SECRETS. `{ [name]: "/abs/path" }`, the panel-authored half of the resolver
+				// table. The shape is checked here and the PATH BOUND is not: whether a path is allowed is
+				// PI_SECRET_RESOLVER_ROOTS' question, and it is asked in the worker at resolution time rather
+				// than here, because this same validator runs inside the admin extension where a "yes" would
+				// prove nothing about the host the job will run on.
+				//
+				// An invalid value fails the WHOLE overlay, which is this function's documented rule and is
+				// deliberate here too: a half-read profile table is a deployment that believes it has a
+				// resolver it does not.
+				if (value === null || typeof value !== "object" || Array.isArray(value)) {
+					return { invalid: "secretProfiles must be an object mapping profile names to resolver paths" };
+				}
+				for (const name of Object.keys(value)) {
+					if (!/^[A-Za-z0-9._-]+$/.test(name)) {
+						return { invalid: "secretProfiles names may use letters, digits, dot, dash and underscore only" };
+					}
+					if (typeof value[name] !== "string" || value[name].trim() === "") {
+						return { invalid: `secretProfiles.${name} must be a non-empty absolute path` };
+					}
+				}
+				overlay[key] = { ...value };
+				break;
+			}
 			case "softHoldPct":
 				// A percentage of each active cap; 100 would equal the hard wall (no band) and 0 has no meaning,
 				// so the enforced band is 1-99. Absence disables the soft-hold entirely.