@edgehero/pi-dispatch 1.1.0 → 1.3.0

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";
 
 /**
@@ -44,7 +45,7 @@ export async function runJob(job, deps) {
 		// 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 }),
-		// (session, { piVersion }) => { promoted, reason, bytes }. Promotes this job's transcript back into
+		// (session, { piVersion, context }) => { promoted, reason, bytes }. Promotes this job's transcript back into
 		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
 		// it behaves exactly as before -- no store, no promotion, no session in the record.
 		promoteSession = () => null,
@@ -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 } = 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,
@@ -388,7 +488,7 @@ export async function runJob(job, deps) {
 				// (CONST-RETRY-INFRA-ONLY). Same completed-only rule INT-OUTBOX-CONTRACT already uses, and
 				// it sits beside the chain collection for the same reason: both must happen before the
 				// `finally` deletes jobDir. Never throws.
-				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion }) : null;
+				const promoted = prepared.session ? promoteSession(prepared.session, { piVersion, context }) : null;
 				return {
 					outcome: "completed",
 					exitCode: code,
@@ -455,7 +555,8 @@ export async function runJob(job, deps) {
  * and with one number alone it is indistinguishable from an ordinary cold start.
  *
  * The runner's verdict WINS on `resumed`, because it is the one that observed the outcome. The host's
- * reason is kept when the runner has none to give (a container that died before its exit line).
+ * reason is kept when the runner has none to give (a container that died before its exit line), AND when
+ * the host itself refused -- see the second precedence rule below.
  *
  * PII-free by construction: a boolean, a fixed enum, an integer. The key and the branch name are
  * deliberately absent -- this record holds no attacker-chosen string, and a branch name is one.
@@ -463,16 +564,47 @@ export async function runJob(job, deps) {
 function mergeSession(prepared, fromRunner, promoted = null) {
 	const host = prepared?.session;
 	if (!host && !fromRunner) return null;
+	// A HOST GATE THAT REFUSED OUTRANKS THE RUNNER'S `absent`, and without this rule it never reached a
+	// record at all. A refused read stages a 0-byte file rather than nothing (session-store.mjs, where the
+	// reasoning is pi's EEXIST race), the container is handed that file either way, and pi opens it and
+	// finds no messages -- so the runner reports `absent` on EVERY host refusal. Letting that win overwrote
+	// the answer with a restatement of the question: `expired` and `pi-version-changed` reached no
+	// completed record in the feature's whole life, and `docs/sessions.md`'s promise that every cold start
+	// is nameable in the record was false for them.
+	//
+	// Narrow on purpose, `host.resume === false` and the runner's token exactly `absent`. When the host
+	// DID stage a transcript and the runner still reports `absent`, the two genuinely disagree, and that
+	// disagreement is the event this object exists to show; the runner keeps winning there. So does its
+	// `unparseable`, which reports a degrade the host could not see.
+	const hostRefused = host?.resume === false && typeof host.reason === "string";
 	return {
 		resumed: fromRunner ? fromRunner.resumed : false,
 		// A promotion that was refused is the more useful reason to surface: "locked" or
 		// "not-a-regular-file" says why the NEXT run will cold-start, which is the thing an operator
 		// chasing "it never resumes" needs. It only ever replaces a reason on the completed path.
-		reason: (promoted && !promoted.promoted ? promoted.reason : null) ?? fromRunner?.reason ?? host?.reason ?? null,
+		reason:
+			(promoted && !promoted.promoted ? promoted.reason : null) ??
+			(hostRefused && fromRunner?.reason === "absent" ? host.reason : null) ??
+			fromRunner?.reason ??
+			host?.reason ??
+			null,
 		bytes: promoted?.bytes ?? host?.bytes ?? 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.
@@ -30,7 +30,7 @@ export function makeRunContainer({
 	image, // the DEPLOYMENT default (PI_JOB_IMAGE); a trigger's own run.image overrides it per job
 	hostEnv = process.env,
 	onOutput = (c) => process.stdout.write(c),
-	openJobLog = () => ({ write() {}, close: async () => ({ turns: null, tokens: null, session: null, usage: null }) }),
+	openJobLog = () => ({ write() {}, close: async () => ({ turns: null, tokens: null, session: null, usage: null, context: null }) }),
 	spawnFn = spawn,
 	globalPiDir = null, // REQ-GLOBAL-PI-OVERLAY: operator's global pi overlay dir, mounted :ro; null = off
 	allowGlobalExtensions = true, // REQ-GLOBAL-PI-OVERLAY: the staged overlay's extensions load unless PI_GLOBAL_ALLOW_EXTENSIONS=0
@@ -46,8 +46,8 @@ 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 }) {
-		if (signal?.aborted) return { code: 137, aborted: true, turns: null, tokens: null, session: null, usage: null }; // killed before it could start
+	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
 		// the provider is unconfigured -- the processor turns that into a pre-spend refusal.
@@ -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
@@ -147,20 +151,25 @@ export function makeRunContainer({
 			});
 			child.on("close", async (code) => {
 				const aborted = signal?.aborted === true; // capture BEFORE the await
-				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage fall back to null.
+				// A rejecting sink.close is swallowed so a misbehaving sink cannot hang the run; turns/tokens/session/usage/context fall back to null.
 				let turns = null;
 				let tokens = null;
 				let session = null;
 				let usage = null;
+				let context = null;
 				try {
-					({ turns, tokens, session, usage } = await sink.close());
+					// `context = null` is a DEFAULT rather than a plain destructure: an injected sink that
+					// predates the field returns no such key, and `undefined` would then reach the record's
+					// shape where every other absence is spelled `null`.
+					({ turns, tokens, session, usage, context = null } = await sink.close());
 				} catch {
 					turns = null;
 					tokens = null;
 					session = null;
 					usage = null;
+					context = null;
 				}
-				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage } : { code: code ?? 1, aborted: false, turns, tokens, session, usage });
+				resolve(aborted ? { code: code ?? 137, aborted: true, turns, tokens, session, usage, context } : { code: code ?? 1, aborted: false, turns, tokens, session, usage, context });
 			});
 		});
 

package/src/run-history.mjs

@@ -110,6 +110,43 @@ export function parseExitSession(text) {
 	return null;
 }
 
+/**
+ * The container's report of how full its context was when the run ended (issue #186). Shaped exactly
+ * like `parseExitSession` above and, like it, PASSED THROUGH rather than rebuilt: both integers are
+ * host-bounded numbers, so `parseExitUsage`'s revalidating rebuild is not what this needs -- that one
+ * exists because the ledger carries id STRINGS.
+ *
+ * Absent means ABSENT, never zero. A runner predating this field, a run pi could give no context window
+ * for, and a compaction that left the count unknown all produce no key at all, and the session store
+ * reads that as "no measurement" and passes rather than inventing a denominator.
+ */
+export function parseExitContext(text) {
+	if (typeof text !== "string") return null;
+	const lines = text.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i].trim();
+		if (line === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue; // docker/agent noise or a truncated final line
+		}
+		if (parsed?.event !== "exit") continue;
+		const c = parsed?.context;
+		// A window of 0 is not a denominator, and a negative count is not a measurement. SAFE integers
+		// specifically: `Number.isInteger` accepts up to ~1.8e308, and anything from 1e21 up stringifies to
+		// exponential notation, which the session store's own decimal round-trip then rejects on read --
+		// so a value in that range would be written into the store and be unreadable forever after, with
+		// the gate failing open on a measurement that said the context was full.
+		if (c && typeof c === "object" && !Array.isArray(c) && Number.isSafeInteger(c.tokens) && Number.isSafeInteger(c.window) && c.tokens >= 0 && c.window > 0) {
+			return { tokens: c.tokens, window: c.window };
+		}
+		return null;
+	}
+	return null;
+}
+
 export function parseExitTokens(text) {
 	if (typeof text !== "string") return null;
 	const lines = text.split("\n");
@@ -389,11 +426,12 @@ export function makeLogSink({ logsDir, enabled, fs = nodeFs, log = () => {} }) {
 		}
 
 		async function close({ timeoutMs = 2000 } = {}) {
-			// Capture turns/tokens/session/usage from the tail first, so they survive even if the flush errors or times out.
+			// Capture turns/tokens/session/usage/context from the tail first, so they survive even if the flush errors or times out.
 			const turns = parseExitTurns(tail);
 			const tokens = parseExitTokens(tail);
 			const session = parseExitSession(tail);
 			const usage = parseExitUsage(tail);
+			const context = parseExitContext(tail);
 			try {
 				if (stream !== null) {
 					const s = stream;
@@ -417,7 +455,7 @@ export function makeLogSink({ logsDir, enabled, fs = nodeFs, log = () => {} }) {
 			} catch (err) {
 				log("log_sink_error", { jobId, reason: err?.message });
 			}
-			return { turns, tokens, session, usage };
+			return { turns, tokens, session, usage, context };
 		}
 
 		return { write, close };

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.

package/src/schedules.mjs

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

package/src/secret-profiles.mjs

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