@edgehero/pi-dispatch 1.2.0 → 1.4.0

package/src/queue.mjs

@@ -1,6 +1,11 @@
 import { Queue } from "bullmq";
 import { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId } from "./job-id.mjs";
 import { targetSeparator } from "./forges.mjs";
+import { PR_CLOSE_ACTIONS } from "./triggers.mjs";
+
+// The close words in every forge's spelling, derived from the one table (never re-typed here): a
+// matched PR action in this set marks a close job for the semantic-key discriminant below.
+const PR_CLOSE_WORDS = new Set(Object.values(PR_CLOSE_ACTIONS));
 
 export const QUEUE = "pi-jobs";
 export { chainedJobId, localJobId, deliveryJobId, gitlabDeliveryJobId, forgeDeliveryJobId };
@@ -16,7 +21,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 +52,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 +134,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,12 +172,34 @@ 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.
 		...(replica !== undefined && { replica }),
 		...(replicas !== undefined && { replicas }),
 	};
+	// A close-triggered job (issue #231) leads the semantic key's flow slot with `closed:`. Without it,
+	// a label/comment/PR job on the same target and flow inside the 10-minute window silently swallows
+	// the close job -- and because a swallowed close job writes no run record, the once trigger it was
+	// meant to spend never disarms: a permanently dead one-shot with nothing in the panel to say why.
+	// The discriminant is DERIVED from the matched rule (`issue` type, or a PR close action word) rather
+	// than carried as a job field: an execution detail of dedup is not a fact about the delivery, and
+	// `data`/`event.json` stay byte-identical. `:` is outside the skill-name charset -- enforced at load
+	// since #231 -- so no real flow can spell either prefixed form, and `closed:cmd:<name>` composes for
+	// close-dispatched commands (outermost discriminant first, then the entry-point prefix).
+	const matched = trigger?.matched;
+	// `type === "issue"` reads as "close" only while the issue vocabulary is close-only (it is; the
+	// tables say "one word each so far"). If that type ever grows a non-close action, this test must
+	// narrow to the matched action word, like the PR half already does.
+	const isCloseJob = matched?.type === "issue" || (matched?.type === "pull_request" && PR_CLOSE_WORDS.has(matched?.action));
+	const flowSlot = `${isCloseJob ? "closed:" : ""}${command !== undefined ? `cmd:${command}` : flow}`;
 	await queue.add(kind, data, {
 		jobId,
 		// A command job (issue #189) fills the semantic key's flow slot with `cmd:<command>`: a command
@@ -176,7 +208,7 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		// `cmd:` prefix keeps a command named X from coalescing against a flow named X -- `:` is outside
 		// the skill-name charset, so no real flow can spell the prefixed form -- and a flow job's key
 		// stays byte-identical to before the feature.
-		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${command !== undefined ? `cmd:${command}` : flow}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
+		deduplication: { id: `${repo}${targetSeparator(kind, target?.type)}${target.number}:${flowSlot}${replica !== undefined ? `:r${replica}` : ""}`, ttl: SEMANTIC_WINDOW_MS }, // ttl in ms
 		attempts: 2,
 		backoff: { type: "exponential", delay: 60_000 },
 		removeOnComplete: { age: 31 * 24 * 3600 }, // age in seconds -- do not cross units with the ms ttl above

package/src/reserved-env.mjs

@@ -0,0 +1,40 @@
+/**
+ * The environment variable names `buildContainerEnv` writes itself, spelled once (issue #225).
+ *
+ * This exists because `run.secrets` lets a trigger name env variables, and a trigger that names one the
+ * closed map already owns would either be silently overwritten (the job runs without the value it asked
+ * for, on a clean exit 0) or silently WIN (a trigger redirecting `PI_OFFLINE` or `PI_MAX_TURNS`). Both
+ * are the inversion `env-allowlist.mjs`'s header exists to prevent, arriving through a new door.
+ *
+ * A SEPARATE MODULE, and it has no imports at all, on purpose. `triggers.mjs` is the shared validator:
+ * it is pure and fs-free, the receiver loads it, and `admin/build.mjs` INLINES it into the published
+ * console. Importing `env-allowlist.mjs` to reach these names would drag `node:fs`, `node:os` and pi's
+ * compat shim into all three, to read a list of strings. So the list moves down here, where both can
+ * have it for free.
+ *
+ * Only the STATIC names live here. The rest of the closed map is deployment state and cannot be known
+ * from a triggers file at all: the provider credential's variable names come from `findEnvKeys(provider,
+ * hostEnv)`, and `PI_FORWARD_ENV` is an operator env list. Those two are refused PRE-SPEND, in the
+ * processor, where the resolved provider and the host env are both in hand. `MINTED_TOKEN_VARS` and
+ * `FORGE_HOST_VARS` (forges.mjs) and `EGRESS_ENV_VARS`/`WORKER_ONLY_SECRET_VARS` (config.mjs) stay in
+ * their own modules and are imported by the validator beside this one, never copied into it.
+ *
+ * `worker/test/env-allowlist.test.mjs` pins this set against what `buildContainerEnv` actually emits, so
+ * a variable added to the closed map and not to this list fails there rather than becoming a hole here.
+ */
+export const CONTAINER_ENV_NAMES = new Set([
+	"PI_PROVIDER",
+	"PI_MODEL",
+	"PI_MAX_TURNS",
+	"PI_MAX_TOKENS",
+	"PI_JOB_ID",
+	"PI_GLOBAL_ALLOW_EXTENSIONS",
+	"PI_PACKAGES",
+	"PI_SESSION_FILE",
+	"PI_FLOW",
+	"PI_COMMAND",
+	"PI_OFFLINE",
+	"PLAYWRIGHT_BROWSERS_PATH",
+	"PLAYWRIGHT_MCP_BROWSER",
+	"PLAYWRIGHT_MCP_SANDBOX",
+]);

package/src/run-container.mjs

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

package/src/run-history.mjs

@@ -34,13 +34,57 @@ export function sanitizeJobId(id) {
 	return s.replace(/[^A-Za-z0-9._-]/g, "_");
 }
 
+/**
+ * Parse one line of the buffered tail as a runner-emitted JSON line, or `null` for noise -- repairing
+ * the GLUED case (issue #224, OQ-003).
+ *
+ * The hazard: the runner's writes used to be newline-terminated but not newline-delimited, so a
+ * partial write from anything sharing the container's stdout (a subprocess that never flushed its
+ * trailing newline) lands as `<stray bytes><runner line>` in ONE line. A plain JSON.parse skips it,
+ * and because every parseExit* scan walks backwards past what does not parse, one un-newlined byte
+ * used to lose turns, tokens, usage, session and context at once -- or worse, hand the scan to a
+ * forged exit line placed earlier.
+ *
+ * The repair re-anchors on `{"event":"`, which is collision-free by construction: `event` is the
+ * first key both runner writers serialise, and JSON.stringify escapes every quote inside a string
+ * value, so these raw bytes cannot occur INSIDE a runner line -- only where one starts. Suffixes are
+ * tried left to right, so the leftmost complete object wins: a suffix beginning inside the stray
+ * bytes cannot parse to the line's end (nothing can close a JSON container after bytes the runner
+ * appended later, and the runner's own quotes terminate any string opened before them), so the first
+ * success is the glued runner object itself -- and this left-to-right scan, not just the quote
+ * escaping, is what keeps a would-be inner `{"event":"` from being chosen over the outer one.
+ * A line whose HEAD the capped tail sliced off is handled correctly either way: if the cut fell in a
+ * glued line's stray PREFIX the anchor survives and the genuine object is still repaired, and if it
+ * fell in or past the anchor no `{"event":"` survives and the line is skipped. A line truncated at the
+ * END (a mid-write death) has no complete object and is skipped too. A fragment is never MISREAD as a
+ * value: a broken one does not parse and an anchorless one is not repaired.
+ *
+ * NEVER throws, like the five scanners that call it.
+ */
+function parseTailLine(line) {
+	try {
+		return JSON.parse(line);
+	} catch {
+		// docker/agent noise, a truncated line, or a glued one -- try the repair before giving up.
+	}
+	let from = line.indexOf('{"event":"', 1);
+	while (from !== -1) {
+		try {
+			return JSON.parse(line.slice(from));
+		} catch {
+			from = line.indexOf('{"event":"', from + 1);
+		}
+	}
+	return null;
+}
+
 /**
  * Recover the agent's turn count from buffered container stdout, or `null` if it is not reported.
  *
  * The stream interleaves docker/agent noise and other JSON events (`pi_auto_retry`) with the runner's
  * own lines. Only the success exit line carries `turns` (`image/runner/run-job.mjs:263`); the
  * catch-path exit line (`:277`) omits it. Scan from the end and return the turns of the last `exit`
- * event that reports an integer count.
+ * event that reports an integer count, repairing a glued line on the way (`parseTailLine`).
  *
  * This is read-only telemetry: it MUST NEVER throw and MUST NOT feed exit-code or retry
  * classification -- that is the container exit code's job (INT-RUNNER-EXIT-CODE-PROTOCOL). Every parse
@@ -52,12 +96,7 @@ export function parseExitTurns(text) {
 	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
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		return Number.isInteger(parsed?.turns) ? parsed.turns : null;
 	}
@@ -94,12 +133,7 @@ export function parseExitSession(text) {
 	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
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		const sess = parsed?.session;
 		if (sess && typeof sess === "object" && !Array.isArray(sess) && typeof sess.resumed === "boolean") {
@@ -126,12 +160,7 @@ export function parseExitContext(text) {
 	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
-		}
+		const parsed = parseTailLine(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
@@ -153,12 +182,7 @@ export function parseExitTokens(text) {
 	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
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		const t = parsed?.tokens;
 		if (t && typeof t === "object" && !Array.isArray(t) && typeof t.total === "number") return t;
@@ -204,12 +228,7 @@ export function parseExitUsage(text) {
 	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
-		}
+		const parsed = parseTailLine(line);
 		if (parsed?.event !== "exit") continue;
 		return rebuildUsage(parsed?.usage);
 	}

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);
+	});
+}