@edgehero/pi-dispatch 2.1.0 → 3.0.0

package/src/cli.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { loadConfig } from "./config.mjs";
-import { EXIT_POLICY, installRejectionPrinter } from "./exit-code.mjs";
+import { EXIT_POLICY, installRejectionPrinter, installStdoutPipeGuard } from "./exit-code.mjs";
 import { isEntryModule } from "./entry.mjs";
-import { gitDirty } from "./git-dirty.mjs";
+import { gitDirty, localRepoProblem } from "./git-dirty.mjs";
 import { imageRefProblem } from "./image-ref.mjs";
+import { resolveServiceEnv, serviceEnvFileOf, serviceEnvLoader } from "./service-env.mjs";
 
 /** How long the kill switch waits on the host registry before acting on the shared queue alone. */
 const FLEET_READ_TIMEOUT_MS = 2_000;
@@ -27,6 +28,12 @@ const USAGE = `pi-dispatch — run pi coding-agent flows on your own folders
 
   pi-dispatch run <folder> --task "<what to do>" [--flow <name>]
                            [--provider <p>] [--model <m>] [--max-turns <n>] [--image <ref>] [--force]
+  pi-dispatch run --trigger <cron id>
+                           fire one cron trigger now, once, exactly as its schedule would: its folder, flow,
+                           task and every other field come from the triggers file (PI_TRIGGERS_FILE, else
+                           ./triggers.json here); a second call in the same minute queues nothing.
+                           Both run forms take PI_WORKER_NAME (and --trigger PI_TRIGGERS_FILE and
+                           PI_MAX_COST_USD) from this shell, else from ./.env here, refusing a disagreement
   pi-dispatch sandbox <jobId>
                            re-open a finished run's sandbox as a shell — same image, same workspace,
                            no credentials  [--publish <port>[:<containerPort>]] [--pin]
@@ -39,6 +46,9 @@ const USAGE = `pi-dispatch — run pi coding-agent flows on your own folders
                            run the worker (or --receiver) as an OS service — the deploy/ templates
                            rendered with this host's real paths, installed user-level;
                            \`service restart --drain\` lets the in-flight job finish first
+  pi-dispatch egress render
+                           write model-endpoints.conf here from model-endpoints.json (in place), then print
+                           the command that reloads the egress proxy; it never reloads the proxy itself
   pi-dispatch pause        stop taking new jobs (durable; survives worker restart)
   pi-dispatch resume       resume taking jobs
   pi-dispatch status       show paused state + job counts
@@ -54,7 +64,7 @@ with a consent per action:  pi install npm:@edgehero/pi-dispatch-admin`;
 	// injects a collector instead of reassigning `process.stdout.write`. That matters because `node --test`
 	// runs each file in a child process that serialises its own results over that same stdout, so a test
 	// holding a replacement across an `await` swallows the runner's result frames (issue #266).
-export async function main(argv = process.argv.slice(2), env = process.env, { write = (chunk) => process.stdout.write(chunk), valkeyRefusal = valkeyRefusalAtStart } = {}) {
+export async function main(argv = process.argv.slice(2), env = process.env, { write = (chunk) => process.stdout.write(chunk), valkeyRefusal = valkeyRefusalAtStart, now = () => new Date() } = {}) {
 	const cmd = argv[0];
 
 	if (cmd === "init") {
@@ -107,6 +117,11 @@ export async function main(argv = process.argv.slice(2), env = process.env, { wr
 		return runService(argv.slice(1), { env });
 	}
 
+	if (cmd === "egress") {
+		const { runEgress } = await import("./egress-cli.mjs");
+		return runEgress(argv.slice(1), { env, out: write });
+	}
+
 	if (cmd === "run") {
 		const { values, positionals } = parseArgs({
 			args: argv.slice(1),
@@ -119,8 +134,10 @@ export async function main(argv = process.argv.slice(2), env = process.env, { wr
 				"max-turns": { type: "string" },
 				image: { type: "string" }, // the container image for this one job; blank/absent = PI_JOB_IMAGE
 				force: { type: "boolean", default: false },
+				trigger: { type: "string" }, // issue #505: fire this cron trigger once, by hand
 			},
 		});
+		if (values.trigger !== undefined) return runTrigger(values, positionals, env, { write, valkeyRefusal, now });
 		const folder = positionals[0] && resolve(positionals[0]);
 		if (!folder || !existsSync(folder)) return fail(`folder not found: ${positionals[0] ?? "(none given)"}`);
 		if (!values.task) return fail("a --task is required");
@@ -131,21 +148,31 @@ export async function main(argv = process.argv.slice(2), env = process.env, { wr
 			if (problem) return fail(`--image ${problem.reason} (got ${JSON.stringify(values.image)})`);
 		}
 
+		// The worker's folder rule, before anything is queued (issue #524): `.git` at the folder itself and a commit at
+		// HEAD. A folder that fails it used to be queued anyway and refused at pickup as a generic `config-refused`.
+		// Not waved away by --force: that flag accepts uncommitted work, and the worker refuses this either way.
+		const notARepo = localRepoProblem(folder);
+		if (notARepo) return fail(`${notARepo} Nothing was queued.`);
+
 		// A local job edits the folder IN PLACE with no undo (SECURITY.md). Refuse a dirty working
 		// tree unless --force, so a bad run cannot mix with uncommitted work the operator can't
-		// cleanly separate. A non-git folder is caught later by prepare (v1 requires a git repo).
-		if (existsSync(`${folder}/.git`) && !values.force) {
+		// cleanly separate.
+		if (!values.force) {
 			const dirty = gitDirty(folder);
 			if (dirty === null) return fail(`${folder} is not a usable git repository`);
 			if (dirty) return fail(`${folder} has uncommitted changes. Commit or stash them, or pass --force.`);
 		}
 
-		const config = loadConfig(env);
+		// Which host queue (review of PR #575): PI_WORKER_NAME by the deployment's rule, as VALKEY_URL below is, so `run`
+		// from the deployment folder queues where that folder's worker drains even when this shell does not export it.
+		const deployment = cliDeploymentEnv(env, ["PI_WORKER_NAME"]);
+		if (deployment.problem) return fail(`${deployment.problem}. Nothing was queued.`);
+		const config = loadConfig(deployment.env);
 		const { cliValkeyUrl, parseConnection } = await import("./connection.mjs");
 		// PR #475's review: VALKEY_URL as the password is read, this shell's else the deployment .env's (a disagreement
 		// named), not the shell's alone: from the folder of a Valkey on another port, `run` dialled 6379.
 		const valkeyUrl = cliValkeyUrl(env);
-		const { makeQueue, enqueueLocalJob, hostQueueName } = await import("./queue.mjs");
+		const { makeQueue, enqueueLocalJobReporting, hostQueueName, swallowedRunSentence } = await import("./queue.mjs");
 		// failFast: a one-shot enqueue must not hang forever if Valkey is down -- error clearly.
 		// Onto THIS host's queue when the deployment declares a name (issue #57). The folder was checked
 		// against this machine's filesystem a few lines up, so this machine is the only one that can run it;
@@ -159,7 +186,7 @@ export async function main(argv = process.argv.slice(2), env = process.env, { wr
 		try {
 			// Absent flags stay absent (undefined) so the value resolves at job start against the
 			// settings overlay/env, not a default frozen here (INT-CONFIG-OVERLAY-CONTRACT).
-			const jobId = await enqueueLocalJob(queue, {
+			const { id: jobId, existing } = await enqueueLocalJobReporting(queue, {
 				folder,
 				task: values.task,
 				flow: values.flow,
@@ -169,8 +196,12 @@ export async function main(argv = process.argv.slice(2), env = process.env, { wr
 				// || not the raw value: `--image ""` must collapse to absent rather than becoming a falsy string that
 				// throws inside buildDockerRunArgs after a budget slot is reserved.
 				image: values.image || undefined,
+				now: now(),
 			});
-			write(`queued ${jobId} — folder ${folder}\nrun \`pi-dispatch worker\` to process it.\n`);
+			// Issue #530: the closing line used to say "run `pi-dispatch worker` to process it" while workers ran. It now
+			// says what this queue shows, asked on the connection the enqueue already holds, and only when a job was queued.
+			const hint = existing ? null : await workerHint(queue);
+			write(runQueuedLine({ jobId, existing, folder, hint }, { swallowedRunSentence }));
 		} catch (error) {
 			return fail(error?.valkeyRefused ? error.message : `could not reach Valkey at ${(await import("./connection.mjs")).urlShown(valkeyUrl)}: ${(await import("./valkey-auth.mjs")).valkeyDownHint(valkeyUrl)}\n  ${error.message}`);
 		} finally {
@@ -241,6 +272,166 @@ async function killSwitchUrls(args, env) {
 	return { ...picked, positionals: parsed.positionals };
 }
 
+/**
+ * `pi-dispatch run --trigger <cron id>` (issue #505): fire one cron trigger now, once, as its schedule would. Typed by
+ * an operator only; no tool calls it. It is the way to run a `run.portfolio` job without waiting for its schedule
+ * (`pi-dispatch run <folder>` makes a manual job, which never carries the flag).
+ *
+ * WHICH FILE: `PI_TRIGGERS_FILE`, else `./triggers.json` in this directory, doctor's rule (`triggersPath`) and the
+ * one-shot rule the worker's own live checks read by, so the command and the worker's check of the portfolio flag
+ * read one file. Not `config.triggersFile`, whose null means "the worker schedules no cron": a trigger fired by hand
+ * does not need the worker's scheduler.
+ *
+ * WHAT IS QUEUED: the trigger's own scheduler entry, from `loadSchedules` over that file (so a file the worker would
+ * refuse is refused here, with the loader's message), and its data passed through whole. Nothing on the command line
+ * can change it, so every other `run` flag is refused beside `--trigger`. The job id is `manual:<id>:<minute>`,
+ * deduplicated through the same read back as `pi-dispatch run`.
+ *
+ * WHERE: on the queue the worker of this host schedules the trigger on (its own host queue when the deployment
+ * declares a name, else the shared one), because the trigger's folder is on this machine. A trigger whose folder is
+ * not here belongs to another host, and is refused with the command to run there: queued here, no worker could run it.
+ */
+async function runTrigger(values, positionals, env, { write, valkeyRefusal, now }) {
+	const id = values.trigger;
+	const extra = ["task", "flow", "provider", "model", "max-turns", "image"].filter((k) => values[k] !== undefined);
+	if (values.force) extra.push("force");
+	if (positionals.length > 0 || extra.length > 0) {
+		return fail(`--trigger takes no folder and no other flag (got ${[...positionals.map((p) => JSON.stringify(p)), ...extra.map((k) => `--${k}`)].join(" ")}): the trigger's own fields are what runs. Nothing was queued.`);
+	}
+	// PI_TRIGGERS_FILE and PI_WORKER_NAME by the deployment's rule (review of PR #575), the one VALKEY_URL is read by
+	// below: which file and which host queue are the deployment's facts, and a shell that does not export them must not
+	// read ./triggers.json or queue on the shared queue while the service uses the `.env`'s. PI_MAX_COST_USD too: it is
+	// the one other config value the worker's trigger loader (`loadSchedules`) accepts or refuses a file by (a trigger's
+	// `run.maxCostUsd` above it), so this command refuses exactly the files the worker refuses. `fleet` is the declared
+	// PI_WORKER_NAME, already here. Keep this list equal to the loader's config inputs.
+	const deployment = cliDeploymentEnv(env, TRIGGER_LOADER_ENV_KEYS);
+	if (deployment.problem) return fail(`${deployment.problem}. Nothing was queued.`);
+	const { triggersPath } = await import("./doctor.mjs");
+	const path = triggersPath(deployment.env, process.cwd());
+	if (path === "" || !existsSync(path)) return fail(`no triggers file at ${path === "" ? "(PI_TRIGGERS_FILE is empty)" : path}. Set PI_TRIGGERS_FILE or run this from the deployment folder. Nothing was queued.`);
+
+	const config = loadConfig(deployment.env);
+	const { loadSchedules } = await import("./schedules.mjs");
+	let schedule;
+	try {
+		// One read, validated whole by the shared loader (so a file the worker would refuse is refused here, with its
+		// message). The cron schedule is looked up FIRST: only when no cron trigger has this id is the raw file asked
+		// whether a webhook entry carries it, so a webhook entry spelling the same id never hides the cron trigger.
+		const text = readFileSync(path, "utf8");
+		schedule = loadSchedules({ ...config, triggersFile: path }, { readFileSync: () => text, fleet: config.workerNameDeclared }).find((s) => s.schedulerId === id);
+		if (!schedule) {
+			const named = JSON.parse(text).triggers.find((t) => t?.on?.id === id && t.on.type !== "cron");
+			if (named) return fail(`trigger "${id}" is a ${String(named.on.type)} trigger: only a cron trigger can be fired by hand. Nothing was queued.`);
+		}
+	} catch (error) {
+		return fail(`${error?.message ?? error}. Nothing was queued.`);
+	}
+	if (!schedule) return fail(`no cron trigger with id "${id}" in ${path}. Nothing was queued.`);
+	if (schedule.unserved) return fail(`cron trigger "${id}" runs on another host: its folder is not on this machine. Run this command on the host that has the folder. Nothing was queued.`);
+	// The worker's folder rule, `run <folder>`'s check (issue #524): `.git` at the folder and a commit at HEAD, or the job
+	// is refused at pickup. Uncommitted changes stay allowed, as they are for every scheduled tick.
+	const notARepo = localRepoProblem(schedule.data.folder);
+	if (notARepo) return fail(`cron trigger "${id}": ${notARepo} Nothing was queued.`);
+
+	const { cliValkeyUrl, parseConnection } = await import("./connection.mjs");
+	const valkeyUrl = cliValkeyUrl(env);
+	const { makeQueue, enqueueTriggerRunReporting, hostQueueName, swallowedRunSentence } = await import("./queue.mjs");
+	// The queue the worker of this host schedules this trigger on (start.mjs: `cronQueue`).
+	const hq = config.workerNameDeclared ? hostQueueName(config.workerName) : null;
+	const refused = await valkeyRefusal(valkeyUrl, env);
+	if (refused) return fail(refused);
+	const queue = makeQueue(parseConnection(valkeyUrl, { failFast: true }), { ...(hq ? { name: hq } : {}) });
+	try {
+		const { id: jobId, existing } = await enqueueTriggerRunReporting(queue, schedule, { now: now() });
+		const hint = existing ? null : await workerHint(queue);
+		write(runQueuedLine({ jobId, existing, trigger: id, hint }, { swallowedRunSentence }));
+	} catch (error) {
+		return fail(error?.valkeyRefused ? error.message : `could not reach Valkey at ${(await import("./connection.mjs")).urlShown(valkeyUrl)}: ${(await import("./valkey-auth.mjs")).valkeyDownHint(valkeyUrl)}\n  ${error.message}`);
+	} finally {
+		await queue.close().catch(() => {});
+	}
+	return 0;
+}
+
+/**
+ * The env keys `run --trigger` resolves from the deployment: the file, the host, and every config value the worker's
+ * trigger loader (`loadSchedules`: `triggersFile`, `maxCostUsd`, and `fleet` from a declared worker name) judges a file by.
+ */
+export const TRIGGER_LOADER_ENV_KEYS = Object.freeze(["PI_TRIGGERS_FILE", "PI_WORKER_NAME", "PI_MAX_COST_USD"]);
+
+/**
+ * Deployment keys for a CLI verb that acts for the deployment (review of PR #575): `keys` resolved by issue #471's rule
+ * (`resolveServiceEnv`, service-env.mjs), the one doctor and `up` read the service's keys by. This shell's value where
+ * it sets the key, else the `.env` in `cwd` from a line the service's loader reads as written. Where the two disagree,
+ * or a line naming the key cannot be read as the loader reads it, or the file cannot be read and this shell sets none,
+ * the answer is unknown and the verb refuses (`problem`), as `up` refuses on a PI_JOB_IMAGE disagreement: a job queued
+ * on a queue no worker drains, or from a triggers file the worker does not read, is a silent no-op. Returns
+ * `{ env }` (this shell's with the file's values filled in) or `{ problem }`.
+ */
+export function cliDeploymentEnv(env, keys, { cwd = process.cwd(), platform = process.platform, readFile = (p) => readFileSync(p) } = {}) {
+	const envPath = join(cwd, ".env");
+	let file;
+	try {
+		file = serviceEnvFileOf(readFile(envPath), envPath, serviceEnvLoader(platform));
+	} catch (error) {
+		const unset = keys.filter((k) => typeof env[k] !== "string");
+		if (error?.code !== "ENOENT" && unset.length > 0) return { problem: `${envPath} could not be read (${error?.code ?? "error"}), so ${unset.join(" and ")} cannot be told` };
+		return { env };
+	}
+	const read = resolveServiceEnv({ env, file, keys });
+	const [d] = read.disagreements;
+	if (d) return { problem: `${d.key} is ${JSON.stringify(d.shell)} in this shell and ${JSON.stringify(d.file)} in ${envPath}: make them agree (the service runs the file's)` };
+	const unread = [...read.unread.map((u) => u.key), ...read.hazardSkipped];
+	if (unread.length > 0) return { problem: `${envPath} has a line for ${unread.join(" and ")} that the service's loader may read differently, so it cannot be told (pi-dispatch doctor names the line)` };
+	return { env: read.env };
+}
+
+/** `workerHint`'s line when the queue cannot say, true whether or not a worker runs. */
+export const WORKER_HINT_UNKNOWN = "a worker picks it up; start one with `pi-dispatch worker` if none is running.";
+
+/**
+ * `run`'s closing line (issue #530): true with or without a running worker.
+ *
+ * It asks the queue the job went to, on the connection the enqueue already opened: `getWorkers()` (one CLIENT LIST,
+ * matched on the client names BullMQ gives a Worker of THIS queue, so a named host queue counts only that host's
+ * workers) and `isPaused()`. Measured on bullmq 5.80.4: 0 with no Worker, 1 with one, back to 0 once it closed, and
+ * the Queue's own client is never counted. A paused queue is said first, since a connected worker does not take a
+ * job from it. Any doubt falls back to a line that is true either way:
+ *   - either call fails or takes over `timeoutMs` (a Valkey whose ACL refuses CLIENT LIST, one that went away);
+ *   - an answer that is not what bullmq returns;
+ *   - bullmq's own marker for a server with no CLIENT LIST, a fake row that would read as "1 worker".
+ * A server that ignores CLIENT SETNAME lists no worker at all, which is why zero says "shows as connected" and names
+ * the command rather than claiming none runs.
+ *
+ * CLIENT LIST spans every database, and bullmq matches its rows by client NAME alone, so a Worker of a same-named
+ * queue on database 8 was counted for a job queued on database 9 (measured in PR #531's review: "1 worker is
+ * connected ... will pick it up", and no worker ever would). Only rows whose `db` is the queue client's own count; a
+ * row with no `db` field, or a client whose database cannot be read, is a doubt.
+ */
+export async function workerHint(queue, { timeoutMs = 2000 } = {}) {
+	let timer;
+	try {
+		const answer = Promise.all([queue.getWorkers(), queue.isPaused(), Promise.resolve(queue.client).then((c) => c?.options?.db ?? 0)]);
+		answer.catch(() => {});
+		const late = new Promise((resolve) => {
+			timer = setTimeout(resolve, timeoutMs, null);
+		});
+		const got = await Promise.race([answer, late]);
+		if (got === null) return WORKER_HINT_UNKNOWN;
+		const [workers, paused, db] = got;
+		if (!Array.isArray(workers) || typeof paused !== "boolean" || !Number.isInteger(Number(db))) return WORKER_HINT_UNKNOWN;
+		if (workers.some((w) => w?.name === "GCP does not support client list" || typeof w?.db !== "string")) return WORKER_HINT_UNKNOWN;
+		if (paused) return "the queue is paused: no worker takes it until `pi-dispatch resume`.";
+		const n = workers.filter((w) => w.db === String(db)).length;
+		if (n === 0) return "no worker shows as connected to this queue: start one with `pi-dispatch worker`.";
+		return `${n} ${n === 1 ? "worker is" : "workers are"} connected to this queue and will pick it up.`;
+	} catch {
+		return WORKER_HINT_UNKNOWN;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
 /** One Valkey's pause, resume or status: every queue the deployment drains there (issue #57). Returns the exit code. */
 async function killSwitch(cmd, url, { env, write, label, urlShown, valkeyRefusal }) {
 	const { parseConnection, makeRedisClient } = await import("./connection.mjs");
@@ -324,6 +515,24 @@ async function killSwitch(cmd, url, { env, write, label, urlShown, valkeyRefusal
 	return 0;
 }
 
+/**
+ * What `run` prints once the queue has answered (issue #524). Three answers, because the queue gives three.
+ *
+ * A local job's id is derived from the folder, the flow, the task, the model fields and the minute (`localJobId`), so the same `run`
+ * twice inside one minute is the same id and the queue keeps the first. That dedup is deliberate (a hasty second
+ * Enter must not pay twice) and stays; what changes is that it is said. The time is the first job's own, in this
+ * terminal's local time, and the state is the queue's word for it, or "already queued or done" when it could not be
+ * read. No flag is offered to force a second job, because none exists: a later minute is a different id.
+ * The sentence itself is `queue.mjs`'s, shared with the admin's `/dispatch run`, and handed in because this module
+ * imports the queue lazily. `hint` is `workerHint`'s closing line (issue #530); without one, the line true either way.
+ */
+export function runQueuedLine({ jobId, existing, folder, trigger, hint = WORKER_HINT_UNKNOWN }, { swallowedRunSentence }) {
+	// `trigger` (issue #505) is `run --trigger`'s cron id, said in place of the folder.
+	if (existing) return `${swallowedRunSentence(jobId, existing)}\n${trigger !== undefined ? "the same trigger queues" : "the same folder and task queue"} a new run from the next minute on.\n`;
+	const unknown = existing === undefined ? "could not check whether an identical run from this minute already held this id.\n" : "";
+	return `queued ${jobId} for ${trigger !== undefined ? `cron trigger ${trigger}` : `folder ${folder}`}\n${unknown}${hint}\n`;
+}
+
 function fail(message) {
 	process.stderr.write(`error: ${message}\n`);
 	return 1;
@@ -343,6 +552,8 @@ if (isEntryModule(import.meta.url)) {
 	// A promise nobody handled is printed as its message alone (PR #475's review): Node's own print shows the whole
 	// reason, which for a Valkey client's error could carry what it sent.
 	installRejectionPrinter();
+	// A reader that closes early (`| head -1`) ends the verb quietly instead of with an uncaught EPIPE.
+	installStdoutPipeGuard();
 	main()
 		.then((code) => {
 			if (code) process.exitCode = code;

package/src/config.mjs

@@ -15,6 +15,20 @@ import { SWEEP_INTERVAL_HOURS, SWEEP_INTERVAL_MAX_HOURS } from "./retention-swee
 import { parseSecretProfiles } from "./secret-profiles.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, WAIT_INTERVAL_FLOOR_MS, parseWaitProfiles } from "./wait-for.mjs";
 import { imageRefProblem } from "./image-ref.mjs";
+import { CONTAINER_ENV_NAMES, KEYLESS_ENV_NAME, RUNNER_ENV_NAMES } from "./reserved-env.mjs";
+import { modelListProblem } from "./model-ref.mjs";
+import { DOLLAR_ENV_NAMES, DOLLAR_WINDOW_KEYS, checkDollarInvariant, optionalUsdMicros } from "./money.mjs";
+
+/**
+ * The VALKEY_URL the worker uses when none is set. ONE constant (issue #503's review): doctor judges the model endpoints
+ * file against this port too, and a doctor that read an unset VALKEY_URL as "no queue port" passed an endpoint on 6379
+ * that the worker refuses. valkey-endpoint.mjs re-exports it.
+ */
+export const DEFAULT_VALKEY_URL = "redis://127.0.0.1:6379";
+/** The model a job runs on when nothing names one (`PI_MODEL` unset): one copy, for `loadConfig` and doctor. */
+export const DEFAULT_MODEL = "claude-sonnet-4-5-20250929";
+/** The provider a job runs on when nothing names one (`PI_PROVIDER` unset). */
+export const DEFAULT_PROVIDER = "anthropic";
 
 export function configError(message) {
 	const error = new Error(message);
@@ -86,7 +100,7 @@ function optionalBoundedInt(env, name, min, max) {
 // Split a PATH-style list on the OS path delimiter (`;` on Windows, `:` elsewhere) so a Windows
 // drive-letter colon is not mistaken for a separator. Trims, drops empties. Entries are stored
 // verbatim; downstream (task 3.1) realpaths them, so no posix normalisation happens here.
-function delimitedList(raw) {
+export function delimitedList(raw) {
 	return (raw ?? "")
 		.split(delimiter)
 		.map((s) => s.trim())
@@ -165,6 +179,28 @@ function forwardEnvList(raw, egressArmed = false) {
 			`PI_FORWARD_ENV must not forward ${workerOnly.join(", ")} -- ${workerOnly.map((n) => WORKER_ONLY_WHY[n]).join("; ")}, and a job container is the last place it belongs (CONST-TOKEN-SCOPED-PER-JOB)`,
 		);
 	}
+	// Issue #503: the keyless marker is the worker's to set, and only for a job whose provider is served by keyless
+	// endpoints alone. Forwarded, it would make any provider whose models.json key is `$PI_DISPATCH_KEYLESS` look
+	// configured, so it is refused whatever the egress policy.
+	if (names.includes(KEYLESS_ENV_NAME)) {
+		throw configError(`PI_FORWARD_ENV must not forward ${KEYLESS_ENV_NAME} -- the worker sets it itself, only for a job whose provider has every model on a keyless model endpoint (model-endpoints.json)`);
+	}
+	// Issue #502 (PR #536's review): every name the worker writes into a job's container itself. The forward loop runs
+	// AFTER that write, so a forwarded host value REPLACES the per-job one: `PI_MODEL` or `PI_PROVIDER` would run a model
+	// the pre-spend gates never checked, `PI_ALLOWED_MODELS` would swap a trigger's narrower list for the deployment's,
+	// `PI_MAX_TURNS` would lift the turn limit. One rule over the whole closed set rather than a list of the ones that
+	// happen to matter today. HOME is the one exception, and an old one: forwarding it is supported, the job-user path
+	// overrides it beside `--user` and says so at boot (`forward_env_home_overridden`).
+	const owned = names.filter((n) => CONTAINER_ENV_NAMES.has(n) && n !== "HOME" && n !== KEYLESS_ENV_NAME);
+	if (owned.length > 0) {
+		throw configError(`PI_FORWARD_ENV must not forward ${owned.join(", ")} -- the worker writes ${owned.length === 1 ? "it" : "them"} into every job's container itself, and a forwarded host value would replace the per-job one (a forwarded PI_MODEL runs a model the pre-spend checks never saw)`);
+	}
+	// Issue #500: the two names the runner sets in its own environment for its descendants (RUNNER_ENV_NAMES). A forwarded
+	// host value would sit in the runner's environment before the runner sets its own.
+	const runnerOwned = names.filter((n) => RUNNER_ENV_NAMES.has(n));
+	if (runnerOwned.length > 0) {
+		throw configError(`PI_FORWARD_ENV must not forward ${runnerOwned.join(", ")} -- the job's runner sets ${runnerOwned.length === 1 ? "it" : "them"} inside the container for its own child processes, and a forwarded value would point their usage ledger at a directory nobody reads`);
+	}
 	const egress = egressArmed ? names.filter((n) => EGRESS_ENV_VARS.has(n)) : [];
 	if (egress.length > 0) {
 		throw configError(
@@ -174,6 +210,32 @@ function forwardEnvList(raw, egressArmed = false) {
 	return names;
 }
 
+/**
+ * PI_ALLOWED_MODELS (issue #502): the deployment's allowed-model list, comma-separated `provider/model`, the
+ * grammar a trigger's `run.models` has (`modelListProblem`, model-ref.mjs), so a list means the same thing in
+ * either place. A job's effective list is its trigger's, else this one, else none (unrestricted).
+ *
+ * ENV ONLY, and never a settings-overlay key, for the reason `run.image` resolves against env only: the overlay is
+ * writable by a model-callable tool (`dispatch_set`), and a list a tool could widen is not a policy. Refused at boot
+ * when malformed, like every other knob here. Unset or empty is unrestricted: an empty env var is how an `.env`
+ * template says "not set", unlike an empty `run.models`, which a reviewed file only holds by mistake.
+ *
+ * NO WHITESPACE anywhere in the value (PR #536's lab review). The launchd and other non-systemd wrappers SOURCE the
+ * `.env` with a shell, which reads `PI_ALLOWED_MODELS=a/b, c/d` as a one-off assignment followed by a command named
+ * `c/d`: the variable is never set and every job runs unrestricted, with nothing failing. A worker that does see the
+ * spaced value (systemd reads it whole) therefore refuses it rather than trimming it, so the same line cannot mean a
+ * list on one host and no list on another. An empty segment between two commas is refused too, never skipped.
+ */
+export function allowedModelsFrom(env) {
+	const raw = env.PI_ALLOWED_MODELS;
+	if (raw === undefined || raw === "") return null;
+	if (/\s/.test(raw)) throw configError("invalid PI_ALLOWED_MODELS: write the list with no spaces (a/b,c/d) -- a shell that sources .env cuts an unquoted value at the first space and leaves the variable unset, so jobs would run with no list");
+	const list = raw.split(",");
+	const problem = modelListProblem(list);
+	if (problem !== null) throw configError(`invalid PI_ALLOWED_MODELS: the list ${problem}`);
+	return list;
+}
+
 /**
  * PI_EGRESS (REQ-EGRESS-ALLOWLIST). The parse itself lives in egress.mjs, because `doctor` and `up` read
  * the environment directly and three copies of one default is two chances to flip it in the wrong number
@@ -244,10 +306,15 @@ export function jobImageFrom(env) {
 
 // The operator's global pi overlay dir (REQ-GLOBAL-PI-OVERLAY). Unset/empty = feature off. When set it
 // must EXIST at boot -- a typo pointing at nothing would silently drop the operator's whole setup on
-// every job, so fail loud like every other config error rather than degrade to nothing.
+// every job, so fail loud like every other config error rather than degrade to nothing. And it must be
+// ABSOLUTE (PR #553's review): the value becomes the source of the job's `-v <dir>:/opt/pi-global:ro`, and a
+// relative one is resolved differently by the worker and the container runtime (the worker against its own
+// working directory; the runtime against the client's, or a bare name as a named volume or an error), so the
+// job could mount another folder, or none, than the one the worker judged. Every relative value is refused.
 function resolveGlobalPiDir(env, fileExists) {
 	const dir = env.PI_GLOBAL_PI_DIR;
 	if (dir === undefined || dir === "") return null;
+	if (!isAbsolute(dir)) throw configError(`PI_GLOBAL_PI_DIR must be an absolute path (got ${JSON.stringify(dir)}): a relative value is resolved differently by the worker and the container runtime, so a job could mount another folder than the one the worker checks`);
 	if (!fileExists(dir)) throw configError(`PI_GLOBAL_PI_DIR does not exist: ${dir}`);
 	return dir;
 }
@@ -294,14 +361,14 @@ export function globalExtensionsEnabled(env) {
  * spend caps above, the per-job token scoping, or the admin-extension recursion block.
  */
 export function loadConfig(env = process.env, { fileExists = existsSync } = {}) {
-	const model = env.PI_MODEL ?? "claude-sonnet-4-5-20250929"; // dated snapshot; deterministic per CONST-PI-VERSION-PINNED
+	const model = env.PI_MODEL ?? DEFAULT_MODEL; // dated snapshot; deterministic per CONST-PI-VERSION-PINNED
 	// #227. Hoisted above the object because `defaultBackend` INDEXES `backends`, and a property cannot read
 	// a sibling of the literal it is in. (Calling the parser twice would be harmless -- `egressEnabled` is
 	// called twice a few properties down for the same reason -- so this is about the index, not the throw.)
 	const backends = backendSet(env);
 	const backendFloor = backendFloorOf(env);
 	const config = {
-		valkeyUrl: env.VALKEY_URL ?? "redis://127.0.0.1:6379",
+		valkeyUrl: env.VALKEY_URL ?? DEFAULT_VALKEY_URL,
 		// Issue #57. What this machine calls itself: the key of its registry row, the `host` on every log
 		// line and run record, and the BullMQ worker name. Always populated -- a deployment that declares
 		// nothing still has an identity, which is what lets a fleet of two be TOLD APART before anyone has
@@ -315,11 +382,20 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		weeklyCap: optionalBoundedInt(env, "PI_WEEKLY_CAP", 1), // REQ-SPEND-CAPS-MULTI-WINDOW; null = weekly window disabled
 		monthlyCap: optionalBoundedInt(env, "PI_MONTHLY_CAP", 1), // null = monthly window disabled
 		softHoldPct: optionalBoundedInt(env, "PI_SOFT_HOLD_PCT", 1, 99), // null = soft-hold band disabled
-		provider: env.PI_PROVIDER ?? "anthropic",
+		provider: env.PI_PROVIDER ?? DEFAULT_PROVIDER,
 		model,
 		maxTurns: positiveInt(env, "PI_MAX_TURNS", 30), // pi has no turn limit; we impose one
+		allowedModels: allowedModelsFrom(env), // issue #502: the deployment's allowed-model list; null = unrestricted. ENV ONLY, never the settings overlay
 		maxTokens: optionalBoundedInt(env, "PI_MAX_TOKENS", 1), // issue #25; null = per-job token budget disabled (lagging in-run backstop)
 		dailyTokenCap: optionalBoundedInt(env, "PI_DAILY_TOKEN_CAP", 1), // issue #25; null = daily token counter disabled (check-AFTER, host-side)
+		// Issue #501. The dollar settings, each an operator's decimal (`"2.50"`) kept AS WRITTEN once it parses, so
+		// the overlay and env carry one kind of value and `effectiveJobOf` converts both to micro-dollars the same
+		// way. Unset or empty is null: no per-job cap, no window. The cross-key rule is below, after the object is
+		// built.
+		maxCostUsd: usdSetting(env, "PI_MAX_COST_USD"),
+		dailyCostUsd: usdSetting(env, "PI_DAILY_COST_USD"),
+		weeklyCostUsd: usdSetting(env, "PI_WEEKLY_COST_USD"),
+		monthlyCostUsd: usdSetting(env, "PI_MONTHLY_COST_USD"),
 		jobImage: jobImageFrom(env), // || (not ??) so an empty string falls back; "" is falsy and would throw inside buildDockerRunArgs AFTER a budget slot was reserved
 		globalPiDir: resolveGlobalPiDir(env, fileExists), // REQ-GLOBAL-PI-OVERLAY: operator's ~/.pi/agent subset, :ro-mounted; null = off
 		allowGlobalExtensions: globalExtensionsEnabled(env), // REQ-GLOBAL-PI-OVERLAY: ON unless PI_GLOBAL_ALLOW_EXTENSIONS=0
@@ -352,6 +428,9 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 		sandboxIdleMinutes: nonNegativeInt(env, "PI_SANDBOX_IDLE_MINUTES", 30), // bash's own TMOUT inside a sandbox; 0 = no idle logout
 		triggersFile: env.PI_TRIGGERS_FILE ?? null, // DES-CRON-VIA-BULLMQ-SCHEDULER: unified triggers file; null = cron disabled for the worker (it selects on.type:"cron")
 		pauseWindowsFile: pauseWindowsFilePath(env), // REQ-SCOPED-PAUSE-WINDOWS: per-folder/repo timed pause; null = no scoped pauses
+		modelEndpointsFile: modelEndpointsFilePath(env), // issue #503: the declared model endpoints (INT-MODEL-ENDPOINTS-FILE-CONTRACT); null = model-endpoints.json in the deployment folder, and a missing default file declares none
+		envelopeFile: envelopeFilePath(env), // issue #504: the allocation envelope (INT-ENVELOPE-FILE-CONTRACT); null = no envelope and no delegation anywhere
+		projectsFile: projectsFilePath(env), // issue #499: named groups of repos and folders (INT-PROJECTS-FILE-CONTRACT); null = no projects, and every record's project is null
 		scopedLimitsFile: scopedLimitsFilePath(env), // issue #242: per-scope run caps + concurrency (INT-SCOPED-LIMITS-FILE-CONTRACT); null = none. The one-job-per-folder mutex for local jobs is code, not configuration, and holds regardless
 		schedulerStallMax: positiveInt(env, "PI_SCHEDULER_STALL_MAX", 2), // CONST-RETRY-INFRA-ONLY: per-scheduler stall backstop; positiveInt rejects <1 so a 0 threshold fails closed
 		logsDir: logsDirPath(env), // || (not ??) inside logsDirPath, so an empty string falls back to the default
@@ -464,10 +543,34 @@ export function loadConfig(env = process.env, { fileExists = existsSync } = {})
 	// #227, and it runs AFTER the object is built rather than inside it: the refusal reads `egress` as well
 	// as the two backend fields, and a check woven between properties would depend on key order.
 	refuseBackendShortfall(config);
+	// Issue #501, after the object for the same reason: both rules read more than one key.
+	refuseDollarSettings(config);
 
 	return config;
 }
 
+// An optional dollar amount from env (issue #501): unset or empty is null, anything else must parse as money
+// (`parseUsdMicros`) and is kept as the string the operator wrote. The refusal names the variable, never the
+// value, which is `parseUsdMicros`' own rule.
+function usdSetting(env, name) {
+	const raw = env[name];
+	if (raw === undefined || raw === "") return null;
+	optionalUsdMicros(raw, name);
+	return raw;
+}
+
+// The env half of the dollar rule (issue #501). The overlay half runs on MERGED values per job (start.mjs);
+// this one runs on env alone at boot, where an operator is present to read the refusal: a window without a
+// per-job cap (`checkDollarInvariant`), because a window reserves each job's per-job cap and without one there
+// is no amount to reserve. The windows themselves are enforced (dollar-budget.mjs, processor.mjs).
+function refuseDollarSettings(config) {
+	const broken = checkDollarInvariant(config);
+	if (broken) {
+		const window = DOLLAR_WINDOW_KEYS.find((key) => config[key] !== null);
+		throw configError(`${DOLLAR_ENV_NAMES[window]} needs PI_MAX_COST_USD: a dollar window reserves each job's per-job cost cap before it starts, so it cannot be set without one`);
+	}
+}
+
 /**
  * Normalise an inline App private key, or refuse it. Returns `null` for absent/blank (an empty
  * `GITHUB_APP_PRIVATE_KEY=` line in a scaffolded .env means "unset", never "a key that is empty").
@@ -863,6 +966,24 @@ export function scopedLimitsFilePath(env = process.env) {
 	return env.PI_SCOPED_LIMITS_FILE ?? null;
 }
 
+/** Issue #499. `??` like the two above: an empty value is a value, so the boot load refuses it rather than reading it
+ *  as "no projects". */
+export function projectsFilePath(env = process.env) {
+	return env.PI_PROJECTS_FILE ?? null;
+}
+
+/** Issue #504. `??` like the projects key: an empty value is a value, so the boot load refuses it rather than reading
+ *  it as "no envelope". Unset turns delegation off everywhere. */
+export function envelopeFilePath(env = process.env) {
+	return env.PI_ENVELOPE_FILE ?? null;
+}
+
+/** Issue #503. `??` like the two above, so an empty value is a value, which the loader refuses rather than reading the
+ *  default file in its place. Unlike them, null does not turn anything off: it means the deployment folder's file. */
+export function modelEndpointsFilePath(env = process.env) {
+	return env.PI_MODEL_ENDPOINTS_FILE ?? null;
+}
+
 export function logsDirPath(env = process.env, home) {
 	return env.PI_LOGS_DIR || defaultLogsDir(env, home);
 }

package/src/daemon-facts.mjs

@@ -141,6 +141,9 @@ export function parsePodmanInfo(stdout) {
 	const controllers = Array.isArray(host.cgroupControllers) ? host.cgroupControllers.filter((c) => typeof c === "string" && /^[a-z][a-z0-9_]{0,31}$/.test(c)) : null;
 	return {
 		rootless: bool(host.security?.rootless),
+		// Issue #503: the rootless network helper Podman 5 names (`host.rootlessNetworkCmd`, measured `pasta` on 5.8.1;
+		// 4.9.3 has no such field). One of the two known words, lowercased, else no fact.
+		rootlessNetworkCmd: typeof host.rootlessNetworkCmd === "string" && /^(?:pasta|slirp4netns)$/i.test(host.rootlessNetworkCmd) ? host.rootlessNetworkCmd.toLowerCase() : null,
 		serviceIsRemote: bool(host.serviceIsRemote),
 		selinux: bool(host.security?.selinuxEnabled),
 		// "v2" or "v1"; anything else is no fact rather than a string an operator's terminal is handed.

package/src/deployment-venue.mjs

@@ -14,6 +14,7 @@ const COMMAND_SAYS = Object.freeze({
 	up: "up would drive the shell's venue",
 	init: "init's next steps would be for the shell's venue",
 	doctor: "doctor would judge the shell's venue",
+	egress: "the render would name the shell's venue's reload",
 });
 
 /**