@edgehero/pi-dispatch 1.2.0 → 1.4.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/deploy/docker-compose.yml

@@ -49,7 +49,11 @@ services:
       PI_TRIGGERS_FILE: /config/triggers.json
     # The repo-root triggers.json (`pi-dispatch init` scaffolds it -- run that first: mounting a path
     # that does not exist makes Docker create it as a DIRECTORY and the boot fails confusingly).
-    # Read-only: the receiver live-reloads this file on change; it never writes it.
+    # Read-only: the receiver live-reloads this file on change; it never writes it. One consequence of
+    # a single-FILE bind mount (issue #231): every write to this file is an atomic tmp+rename that
+    # SWAPS THE INODE, and the mount stays pinned to the old one -- so the worker's one-shot disarm is
+    # invisible in here until the container restarts, and the worker's own pre-spend check is what
+    # keeps a spent one-shot from running again in the meantime. A restart picks up the current file.
     volumes:
       - ../triggers.json:/config/triggers.json:ro
     # Loopback only, like Valkey's port above: the operator's reverse proxy or tunnel (TLS, public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.2.0",
+  "version": "1.4.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": [
@@ -52,6 +52,7 @@
     "./job-id": "./src/job-id.mjs",
     "./forges": "./src/forges.mjs",
     "./triggers": "./src/triggers.mjs",
+    "./triggers-file": "./src/triggers-file.mjs",
     "./packages": "./src/packages.mjs",
     "./pause-windows": "./src/pause-windows.mjs",
     "./identity": "./src/identity.mjs",

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, onceArmed, onceSpent, 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) {
@@ -1195,6 +1242,31 @@ export async function collectChecks(env, seams) {
 		});
 	}
 
+	// One-shot close triggers (issue #231, DES-ONE-SHOT-DISARM-IN-THE-FILE). Advisory only -- doctor
+	// never touches triggers -- and counted from the RAW file (readTriggerFacts says why). Two lines
+	// with different lives: the armed line names the count and, when PI_TRIGGERS_FILE is unset, warns
+	// that the disarm resolves ./triggers.json against the WORKER SERVICE's working directory -- a
+	// service unit whose WorkingDirectory differs from the receiver's would disarm a file nobody
+	// matches against, the split-file hazard no mechanism can detect. The spent line states the
+	// deliberate degradation: a spent entry counts toward NO parsed fact above (forges, flows,
+	// webhook-secret), mirroring what the receiver serves at its next boot.
+	if (onceArmed > 0) {
+		checks.push({
+			ok: true,
+			warn: env.PI_TRIGGERS_FILE === undefined,
+			label: `${onceArmed} one-shot trigger(s) armed (on.once) -- the worker disarms the entry in ${env.PI_TRIGGERS_FILE === undefined ? "./triggers.json resolved against the worker service's working directory; set PI_TRIGGERS_FILE so worker and receiver name the same file from anywhere" : "PI_TRIGGERS_FILE"} after the run record exists`,
+			fix: "set PI_TRIGGERS_FILE to an absolute path in both services' environments",
+		});
+	}
+	if (onceSpent > 0) {
+		checks.push({
+			ok: true,
+			warn: false,
+			label: `${onceSpent} one-shot trigger(s) already spent (on.disarmed) -- spent entries match nothing and count toward no credential or flow check; delete on.disarmed to re-arm, or delete the entry once its history no longer matters`,
+			fix: "",
+		});
+	}
+
 	// REQ-SCOPED-PAUSE-WINDOWS, the panel-writes-what-the-worker-ignores trap (issue #99). Three defaults
 	// that are individually defensible and together silent:
 	//
@@ -1410,16 +1482,40 @@ 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, onceArmed: 0, onceSpent: 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
 		// the receiver will not boot. An absent file still means "no triggers at all", exactly as before.
 		const path = env.PI_TRIGGERS_FILE ?? join(cwd, "triggers.json");
 		if (!fileExists(path)) return none;
-		const triggers = parseTriggers(readFileSync(path, "utf8"), path);
+		const text = readFileSync(path, "utf8");
+		const triggers = parseTriggers(text, path);
+		// The one-shot facts are counted from the RAW entries, not the parsed records, because the
+		// validator collapses a disarmed entry to a sentinel that carries neither `once` nor
+		// `disarmed` -- exactly so nothing can match it -- which also erases it from every parsed
+		// count above. Doctor is the surface that must still SEE the spent entry: "why did nothing
+		// fire" is answered by a spent row, and only the raw file still holds it. Safe unguarded:
+		// parseTriggers just accepted this same text, so JSON.parse cannot throw here.
+		const rawEntries = JSON.parse(text)?.triggers ?? [];
 		return {
+			onceArmed: rawEntries.filter((t) => t?.on?.once === true && t.on.disarmed === undefined).length,
+			onceSpent: rawEntries.filter((t) => t?.on?.disarmed !== undefined).length,
 			requiring: triggers.filter((t) => t.run.packages === true).length,
 			resuming: triggers.filter((t) => t.run.resume === true).length,
 			// REQ-PER-TRIGGER-INSTRUCTION. Counted beside `resuming` for the same reason: it is a per-trigger
@@ -1432,6 +1528,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/get-token.mjs

@@ -104,10 +104,15 @@ export async function makeGitHubAuth(cfg, deps = {}) {
 				);
 			}
 			const repositoryNames = [repoNameOf(repo)]; // scope to the ONE repo; owner stripped
+			// An optional PERMISSIONS narrowing (issue #231): the receiver's closer-permission lookup asks
+			// for `{ metadata: "read" }`, so the token it holds for that one question cannot write anything
+			// even if leaked. Job mints never pass this and keep the installation's full grant -- narrowing
+			// is the caller's statement of intent, not a default this mint could guess.
+			const permissions = job?.permissions;
 			let minted;
 			try {
 				const appAuth = createAppAuth(auth);
-				minted = await appAuth({ type: "installation", repositoryNames });
+				minted = await appAuth({ type: "installation", repositoryNames, ...(permissions && { permissions }) });
 			} catch (error) {
 				throw classifyAppMintError(error);
 			}

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,
@@ -114,6 +125,11 @@ export function makeProcessor({ cancelJob, stopContainer, redis, getSettings, ap
 				// `queueJobId`, mirroring the collectChain injection above. Omitted when unwired so a bare
 				// processor keeps runJob's plain (job, token) call.
 				...(deps.prepareWorkspace ? { prepareWorkspace: (j, t) => deps.prepareWorkspace(j, t, { queueJobId: job.id }) } : {}),
+				// The one-shot pre-spend check (issue #231) needs the REAL BullMQ job's `.id` to excuse this
+				// delivery's own earlier attempt -- runJob's effectiveJob has no `.id`, prepareWorkspace's
+				// own injection above states why, and this one mirrors it. Omitted when unwired so a bare
+				// processor keeps runJob's admit-everything default.
+				...(deps.checkOnceSpent ? { checkOnceSpent: (j) => deps.checkOnceSpent(j, { queueJobId: job.id }) } : {}),
 			});
 			recordRun({ job, result, startedAt, endedAt: new Date().toISOString() });
 			return result;

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";
 
 /**
@@ -41,6 +42,11 @@ export async function runJob(job, deps) {
 		// this job names is on this host (image-preflight.mjs). Default admits everything, so a wiring that
 		// omits it behaves exactly as before -- the container's own failure stays the backstop.
 		imagePreflight = async () => ({ ok: true }),
+		// (job) => { ok } | { refused, at, jobId }. The one-shot pre-spend check (issue #231,
+		// DES-ONE-SHOT-DISARM-IN-THE-FILE). Default admits everything -- an unwired processor behaves
+		// exactly as before, and the gate below only calls it for a job whose matched rule was a
+		// one-shot, so the default is never a probe running on every delivery.
+		checkOnceSpent = async () => ({ ok: true }),
 		// REQ-EGRESS-ALLOWLIST. Default admits everything, so a wiring that omits it behaves exactly as a
 		// deployment with no egress policy does -- which is also what the real factory returns when unarmed.
 		egressPreflight = async () => ({ ok: true }),
@@ -70,6 +76,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 +97,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,
@@ -105,6 +126,27 @@ export async function runJob(job, deps) {
 	let reserved = false;
 
 	try {
+		// The one-shot pre-spend check (issue #231), FIRST on the ladder: one file read, cheaper than
+		// the docker inspect below, free, determinate, credential-less. Only a FOREIGN positive
+		// disarmed mark refuses -- the check excuses this queue job's own id, so a retry of the
+		// delivery that spent the trigger still runs (attempts:2 stays attempts:2) -- and anything
+		// unreadable or changed means "run": fail-open, because the disarm writer owns the loud
+		// refusals, and a broken read must never wedge every once job. In the compose topology the
+		// receiver reads a dead inode until restart, so this check is the once-enforcement layer
+		// there, not optional hardening.
+		if (job.trigger?.matched?.once === true) {
+			const spent = await checkOnceSpent(job);
+			if (spent.refused) {
+				// Commented like every sibling policy refusal: explainability is this refusal's whole
+				// purpose, and only a DISTINCT re-close reaches it past the GUID dedup, so the noise
+				// bound is the operator's own reopen-close rate. `at`/`jobId` are harness-written
+				// provenance, never payload text.
+				await comment(job, `Refused: this one-shot trigger was already spent${spent.at ? ` at ${spent.at}` : ""}${spent.jobId ? ` by job ${spent.jobId}` : ""}. The close that armed it has already produced a run; delete on.disarmed from the trigger entry to re-arm it. Not run.`);
+				log("refused_once_already_spent", { triggerIndex: job.trigger?.matched?.index ?? null });
+				return { outcome: "policy", reason: "once-already-spent", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+			}
+		}
+
 		// The job image must exist on THIS host before anything else happens. Free, determinate and
 		// credential-less, so it precedes the mint, the clone and the reservation: a host that cannot run the
 		// image refuses without minting a credential it will not use, cloning a repo it will not read, or
@@ -279,6 +321,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 +477,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 +618,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);