@edgehero/pi-dispatch 1.1.0 → 1.3.0

package/.env.example

@@ -56,10 +56,20 @@ PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may nam
                                     # Enforced at OPEN as well as at boot: a stale transcript is a live input to a future job, not debris
 # PI_SESSION_MAX_BYTES=             # default 8388608 (8 MiB); a transcript larger than this is not resumed; 0 = no cap
                                     # Not disk hygiene -- an oversized transcript is a prefill nobody sized PI_MAX_TOKENS for
+# PI_SESSION_MAX_AGE_DAYS=          # unset/0 = no bound. How old the CONVERSATION may be, read from the session header's own timestamp
+                                    # A DIFFERENT CLOCK from PI_SESSIONS_TTL_DAYS, not a finer setting of it: that one reads mtime, which every COMPLETED run refreshes,
+                                    # so a lineage that keeps finishing work never expires however old its first turn is. This one measures from the first turn
+                                    # A header with no readable timestamp is refused rather than assumed young (reason: conversation-too-old)
+# PI_SESSION_MAX_RESUME_CHAIN=      # unset/0 = no bound. How many times in a row one key may be resumed before the next job starts fresh
+                                    # The bound a long lineage actually needs: age and size grow slowly, a chain grows once per run
+                                    # The count is kept whether or not the bound is set, so setting it later takes effect on the next job rather than N jobs later
+# PI_SESSION_MAX_CONTEXT_PCT=       # unset = no bound; 1-100. Refuse a resume when the saved session's context is already this full, e.g. 80
+                                    # A SAFETY bound before an economic one: past pi's compaction threshold a resumed job replays a model-written summary of the transcript,
+                                    # written while that model was reading attacker-authored text (specs/open-questions.md, OQ-003). This ceiling is the host's own, and pi's threshold stays pi's
+                                    # The measurement comes from the job image's runner, so it is inert until you are running an image that reports it and each key has completed one run since
 # PI_SESSIONS_ALLOW_GH_SOURCE=      # unset = a run.resume job REFUSES to mint under GITHUB_AUTH_SOURCE=gh, pre-spend
                                     # That source is your whole gh login: full-scope and non-expiring, and a transcript is a FILE -- any command that echoed an auth header persists it
                                     # Prefer GITHUB_AUTH_SOURCE=app or a short-expiry fine-grained PAT. Set exactly 1 to accept the trade explicitly (SECURITY.md, docs/sessions.md)
-                                    # Not disk hygiene -- an oversized transcript is a prefill nobody sized PI_MAX_TOKENS for
 # PI_TRIGGERS_FILE=                 # ABSOLUTE path to the unified triggers.json, read by BOTH worker and receiver (a relative path resolves against the service's WorkingDirectory).
                                     # Unset = cron disabled for the worker; the receiver falls back to ./triggers.json in the folder it starts from (what `pi-dispatch init` scaffolds)
                                     # and refuses to start when neither exists (it holds the label/comment/pull_request trigger config)
@@ -79,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/worker-env-wrapper.cmd

@@ -72,6 +72,14 @@ if defined ENV_SETUP (
   )
 )
 
+REM WEAKER THAN THE .sh TWIN ON SIGNALS, deliberately and stated rather than discovered (issue #221).
+REM cmd has no `trap`, so there is no wrapper-level handling of a stop that arrives while `.env` is being
+REM read or while the setup script above is still running: whatever the service manager does to the tree
+REM is what happens. nssm stops with a console event to the process group (AppStopMethodConsole), so the
+REM worker is reached directly rather than through this file, which is why the .sh twin's forwarding
+REM problem has no equivalent here. The asymmetry is recorded in DES-SERVICE-ENV-SETUP-SEAM and is not
+REM closed.
+REM
 REM The argv runs verbatim -- absolute node, absolute script, composed by `pi-dispatch service` (see
 REM the .sh twin for the whole contract).
 %*

package/deploy/worker-env-wrapper.sh

@@ -36,6 +36,34 @@ if [ "$#" -eq 0 ]; then
 	exit 1
 fi
 
+# STOP HANDLING IS ARMED HERE, above everything below that can block (issue #221). It closes two windows,
+# both of which used to swallow a stop in silence.
+#
+# Until this line TERM/INT carry their DEFAULT disposition, and the sourcing below can take arbitrarily
+# long: PI_ENV_SETUP is an operator's secrets manager, so docs/secrets.md's own worked example makes a
+# network round trip inside it. A stop landing there killed this shell where it stood, mid-preparation,
+# with nothing anywhere saying the environment had been half-built. That is reachable from this project's
+# own CLI, not just from the daemon: `pi-dispatch service stop` on macOS is `launchctl kill SIGTERM` at
+# this pid.
+#
+# The other window is two instructions wide, and is closed by the re-send after `child=$!` below. The
+# handler is a FUNCTION rather than a trap string because it is installed twice -- here, and again after
+# the sourcing -- and one behaviour spelled out in two places is one behaviour that can drift.
+signaled=0
+child=
+wrapper_on_stop() {
+	signaled=1
+	# `child` is empty until the fork below has been assigned, and `kill -TERM ""` kills nothing and
+	# fails silently, so a stop arriving before then has no pid to reach. It is not lost: the re-send
+	# after `child=$!` re-delivers it, and the launch gate refuses to start at all if nothing was
+	# started yet.
+	[ -n "$child" ] && kill -TERM "$child" 2>/dev/null
+	# Never leave a nonzero status behind. `rc=$?` is read immediately after the `wait` this interrupts,
+	# and the double wait at the bottom keys on rc >= 128.
+	return 0
+}
+trap wrapper_on_stop TERM INT
+
 # The env-setup seam (issue #209): `pi-dispatch service render|install --env-setup <path>` puts an
 # operator-typed path here -- the plist's EnvironmentVariables dict on macOS, nssm's AppEnvironmentExtra
 # on Windows -- so a secrets manager can fill this process's environment without anyone hand-editing a
@@ -74,6 +102,25 @@ if [ -n "$env_setup" ]; then
 	set +a
 fi
 
+# RE-ASSERTED after the sourcing, and this is not belt-and-braces. A sourced script runs in THIS shell,
+# so a `trap ... TERM` inside one REPLACES the handler above and the drain silently disappears -- a
+# manager's cleanup helper does exactly that. One line restores it. What it cannot undo is a script that
+# IGNORES TERM (`trap '' TERM`): a signal discarded while it was ignored is already gone, and the child
+# forked below would inherit SIG_IGN and be unable to trap TERM at all. That is why docs/secrets.md now
+# tells operators not to touch signals in a setup script.
+trap wrapper_on_stop TERM INT
+
+# A stop that arrived while the environment was being prepared is honoured by NOT STARTING. Launching now
+# would hand the service manager a worker it has already asked to go away: it would reserve a budget slot
+# and take a job, and then need a drain nobody is waiting for. Exit 0 because 0 is the only code launchd's
+# KeepAlive/SuccessfulExit=false leaves stopped -- the same reason the exit-2 conversion at the bottom
+# exists. Not 2, because nothing was refused; not 1, because nothing failed; the manager's own instruction
+# was carried out, and this says so rather than exiting mute.
+if [ "$signaled" -eq 1 ]; then
+	echo "worker-env-wrapper: stopped before the worker started -- a stop signal arrived while the environment was being prepared, so the command was never launched; exiting 0 (nothing to restart)" >&2
+	exit 0
+fi
+
 # `exec` is deliberately GONE here (it used to hand this shell's pid straight to node): intercepting
 # the exit code needs a parent still alive after node exits. launchd's KeepAlive/SuccessfulExit=false
 # relaunches ANY nonzero exit -- including EXIT_POLICY (2, worker/src/exit-code.mjs), the determinate
@@ -81,13 +128,19 @@ fi
 # deliberately never retry. A relaunch loop against a paid provider is a bill, so the conversion at
 # the bottom turns exit 2 into the clean exit KeepAlive leaves stopped.
 #
-# SIGTERM still reaches node without exec: the trap forwards TERM/INT to the child, and `wait` (unlike
-# a foreground command in sh, which blocks trap delivery) is interruptible by a trapped signal, so the
-# forwarding is immediate and node gets its full graceful drain.
-signaled=0
-trap 'signaled=1; kill -TERM "$child" 2>/dev/null' TERM INT
+# SIGTERM still reaches node without exec: the handler armed at the top forwards TERM/INT to the child,
+# and `wait` (unlike a foreground command in sh, which blocks trap delivery) is interruptible by a trapped
+# signal, so the forwarding is immediate and node gets its full graceful drain.
 "$@" &
 child=$!
+# THE FORK WINDOW (issue #221). `$!` is only readable in the parent AFTER the fork, so between the two
+# lines above a child exists and its pid does not. A stop landing there ran the handler with nothing to
+# forward to, set `signaled`, and was then never looked at again -- so this wrapper waited out the
+# command's ENTIRE natural lifetime while the service manager believed it had asked it to stop. Re-sending
+# once the pid is known costs one `[` on the healthy path and is the whole difference between a graceful
+# drain and a hang as long as the job. Issue #207 found this same drop through the test that saw it and
+# fixed only the test; #221 is the same window firing through a different one.
+[ "$signaled" -eq 1 ] && kill -TERM "$child" 2>/dev/null
 wait "$child"
 rc=$?
 # The double wait is load-bearing: a trapped signal interrupts the FIRST wait early (rc = 128+signum)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.1.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);
@@ -258,10 +259,42 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		// A bound on how large a transcript may be before it stops being resumed. Not disk hygiene: an
 		// oversized transcript is a prefill an operator never sized PI_MAX_TOKENS for.
 		sessionMaxBytes: nonNegativeInt(env, "PI_SESSION_MAX_BYTES", 8 * 1024 * 1024), // 0 = no cap
+		// How old the CONVERSATION may be, which is a different clock from sessionsTtlDays above and not a
+		// finer setting of it: the TTL reads the transcript's mtime, which the PROMOTE rename refreshes (the
+		// resolve copy does not, measured -- copyFileSync stamps the destination), so it measures time since
+		// the last COMPLETED run on this key. A key whose runs keep completing never expires however old its
+		// first turn is. This one reads the session header's own timestamp.
+		// OFF by default (0) rather than defaulted to a number: an age an operator did not choose is an
+		// opinion about their lineages that this project has no basis for.
+		sessionMaxAgeDays: nonNegativeInt(env, "PI_SESSION_MAX_AGE_DAYS", 0), // 0 = no age bound
+		// How many times in a row one key may be resumed before the next job starts fresh. The bound a long
+		// lineage actually needs: age and size both grow slowly while a chain grows once per run.
+		sessionMaxResumeChain: nonNegativeInt(env, "PI_SESSION_MAX_RESUME_CHAIN", 0), // 0 = no chain bound
+		// How full the saved context may be before a resume is refused, as a percentage of the model's own
+		// window. A PERCENTAGE, so `optionalBoundedInt` on softHoldPct's precedent rather than the 0 = off
+		// sentinel its two neighbours use: 0% would mean "never resume anything", which is a different
+		// request from "no bound", and 101 is a typo rather than a ceiling.
+		sessionMaxContextPct: optionalBoundedInt(env, "PI_SESSION_MAX_CONTEXT_PCT", 1, 100), // null = no context bound
 		chainDepthMax: nonNegativeInt(env, "PI_CHAIN_DEPTH_MAX", CHAIN_DEPTH_MAX_DEFAULT), // DES-JOB-OUTBOX-CHAINING; 0 = chaining kill-switch (fail-closed)
 		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) {
@@ -1132,8 +1179,37 @@ export async function collectChecks(env, seams) {
 				ok: true,
 				warn: true,
 				label: `${resuming} trigger(s) persist agent transcripts to ${sessionsDir} -- PII-bearing, host-only, never committed`,
-				fix: "confirm it is outside every git repo and on a disk you would put issue text on; PI_SESSIONS_TTL_DAYS bounds how long a transcript stays resumable",
+				fix: "confirm it is outside every git repo and on a disk you would put issue text on; PI_SESSIONS_TTL_DAYS, PI_SESSION_MAX_AGE_DAYS, PI_SESSION_MAX_RESUME_CHAIN and PI_SESSION_MAX_CONTEXT_PCT each bound a different thing about how much history one key accumulates (docs/sessions.md)",
+			});
+			// Which of the four bounds are actually on, as a FACT LINE rather than a warning: how long a
+			// lineage may run is an operator's call, not a defect, and doctor's warnings are for things that
+			// need a decision. The line exists because these knobs are unset by default and silent when
+			// unset, so the only way to tell a deliberate "no bound" from a forgotten one is to print it.
+			const bounds = [
+				["PI_SESSIONS_TTL_DAYS", env.PI_SESSIONS_TTL_DAYS, "14"],
+				["PI_SESSION_MAX_AGE_DAYS", env.PI_SESSION_MAX_AGE_DAYS, "off"],
+				["PI_SESSION_MAX_RESUME_CHAIN", env.PI_SESSION_MAX_RESUME_CHAIN, "off"],
+				["PI_SESSION_MAX_CONTEXT_PCT", env.PI_SESSION_MAX_CONTEXT_PCT, "off"],
+			];
+			checks.push({
+				ok: true,
+				label: `Resume bounds: ${bounds.map(([name, value, fallback]) => `${name}=${value === undefined || value === "" ? fallback : value}`).join(", ")}`,
 			});
+			// The one bound that can be set and still do nothing, and the operator cannot see it from here.
+			// Its measurement is reported by the JOB IMAGE's runner (INT-RUNNER-EXIT-CODE-PROTOCOL), so an
+			// image older than that field reports none, the gate passes on no measurement by design, and the
+			// bound is inert with nothing anywhere saying so. There is deliberately no image capability to
+			// check against -- capabilities are an inclusion list for what the host DEMANDS of an image, and
+			// telemetry is not that -- so this warning is the whole detection surface, which is exactly why
+			// it exists rather than being left to a doc.
+			if (env.PI_SESSION_MAX_CONTEXT_PCT) {
+				checks.push({
+					ok: true,
+					warn: true,
+					label: `PI_SESSION_MAX_CONTEXT_PCT=${env.PI_SESSION_MAX_CONTEXT_PCT} needs a job image whose runner reports context usage`,
+					fix: `an older image reports none, and a bound with no measurement passes rather than guessing, so on such an image this bound does nothing at all. On an image that does report one the reading is kept whether or not the bound is set, so it applies from the next job. Each run's own record (${env.PI_LOGS_DIR || "the logs directory"}/<jobId>.json) carries session.reason, which names the gate that refused`,
+				});
+			}
 		}
 	}
 
@@ -1381,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
@@ -1403,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).