@edgehero/pi-dispatch 0.3.0 → 1.1.0

package/src/service.mjs

@@ -94,6 +94,13 @@ export const TEMPLATE_PINS = {
 		"EnvironmentFile=/opt/pi-dispatch/.env",
 		"\nUser=pi\n",
 		"WantedBy=multi-user.target",
+		// Byte-for-byte survivors — semantics the render must not lose, matching worker.service's list
+		// above. Added with #187: the receiver had none of the three, so any config it could not parse
+		// produced an unbounded five-second restart loop, and `service install` rendering them away would
+		// put that back on a deployment that had just been fixed.
+		"RestartPreventExitStatus=2", // EXIT_POLICY is never restarted (the next start reads the same bad file)
+		"StartLimitIntervalSec=60",
+		"StartLimitBurst=5",
 		"KillSignal=SIGTERM",
 		"TimeoutStopSec=30",
 	],
@@ -118,8 +125,112 @@ export const TEMPLATE_PINS = {
 		"AppExit Default Restart",
 		"AppExit 2 Exit",
 	],
+	// The wrappers are COPIED, never substituted, so they have no substitution surface of their own.
+	// They are pinned anyway for the same reason nssm-install.cmd is: the render EMITS the variable name
+	// they read back (`--env-setup`, issue #209 — the plist's EnvironmentVariables dict on macOS, nssm's
+	// AppEnvironmentExtra on Windows), and a rename on one side with silence on the other would produce
+	// a unit that starts fine and ignores the operator's secrets manager.
+	"worker-env-wrapper.sh": ["PI_ENV_SETUP"],
+	"worker-env-wrapper.cmd": ["PI_ENV_SETUP"],
+};
+
+/**
+ * The env-setup seam (issue #209): an operator-typed path to their OWN script, sourced before the
+ * worker starts, so a secrets manager can put the provider key and the forge token into the process
+ * environment without anyone hand-editing a rendered unit. The renderer owns the `exec` that follows
+ * it, which is the whole point — the hand-edit an operator naturally reaches for (`<manager> run -- …`)
+ * reports the CHILD's exit 2 as 1, and exit 2 is the determinate policy refusal that
+ * RestartPreventExitStatus=2, nssm's `AppExit 2 Exit` and the wrapper's exit-2 conversion all key on.
+ *
+ * A PATH and not a command, deliberately. systemd expands `$…`/`${…}` inside Exec lines whatever the
+ * quoting, a plist is XML, and nssm's argv is neither, so an inline command would need three separate
+ * escaping stories — and it is the shape docs/secrets.md already tells operators not to write.
+ *
+ * Absolute, and never resolved against anything: `.` in POSIX sh SEARCHES $PATH for an operand with no
+ * slash in it, so a relative path here would be a different file depending on the service manager's
+ * environment. Refuse rather than guess.
+ *
+ * The refused characters are per platform because the constraint is: on Linux the path lands inside a
+ * systemd Exec word (which owns `$`, `"` and `\`), on macOS inside a plist <string> (XML), and on
+ * Windows inside an nssm NAME=VALUE that cmd expands with `%`. Spaces are fine everywhere: every
+ * composed form quotes.
+ */
+const ENV_SETUP_REFUSALS = {
+	linux: { re: /['"$\\\x00-\x1f\x7f]/, why: "the path lands inside a single-quoted systemd Exec word, and systemd expands $VAR there whatever the quoting" },
+	darwin: { re: /[<>&"\x00-\x1f\x7f]/, why: "the launchd unit is a plist, and the path lands in an XML <string>" },
+	win32: { re: /[%"\x00-\x1f\x7f]/, why: "cmd expands %VAR% when the wrapper runs the script" },
 };
 
+function resolveEnvSetup(ctx, raw) {
+	const path = String(raw);
+	const absolute = ctx.platform === "win32" ? /^([A-Za-z]:[\\/]|\\\\)/.test(path) : path.startsWith("/");
+	if (!absolute) {
+		return { error: `--env-setup needs an ABSOLUTE path, got: ${path}\nPOSIX \`.\` searches $PATH for an operand with no slash in it, and a service manager's environment is not your shell's, so a relative path here is a different file on every host.` };
+	}
+	const { re, why } = ENV_SETUP_REFUSALS[ctx.platform];
+	const hit = re.exec(path);
+	if (hit) {
+		const shown = hit[0].charCodeAt(0) < 0x20 || hit[0].charCodeAt(0) === 0x7f ? `\\x${hit[0].charCodeAt(0).toString(16).padStart(2, "0")}` : hit[0];
+		return { error: `--env-setup path contains ${JSON.stringify(shown)}, which cannot be rendered safely on ${ctx.platform}: ${why}. Move the script somewhere without it: ${path}` };
+	}
+	if (!ctx.fs.existsSync(path)) {
+		return { error: `--env-setup script not found: ${path}\nRefusing rather than rendering: a unit pointing at a script that is not there installs cleanly and then fails at every boot.` };
+	}
+	return { path };
+}
+
+/**
+ * The read side of the same seam (issue #216). `--env-setup` is a RENDER-TIME flag: once the unit is
+ * written, the unit is the only record of the path, so a preflight that wants to check the script has
+ * to read it back out of the file that actually boots. These patterns match exactly what
+ * composeEnvSetupExec and renderPlist emit, and they live here beside ENV_SETUP_REFUSALS so the writer
+ * and the reader cannot drift apart unnoticed — worker/test/service.test.mjs round-trips every render
+ * through readUnitSeam, so changing one half without the other turns the suite red.
+ *
+ * The capture classes are exact rather than lazy because ENV_SETUP_REFUSALS already guarantees what
+ * cannot be in the path: no `"` on any platform, so `[^"]*` ends where the renderer's quote does, and
+ * no `<`/`>`/`&` on macOS, so a plist <string> can never hold an XML entity to decode.
+ *
+ * win32 is not a file at all — the value comes back from `nssm get <service> AppEnvironmentExtra`,
+ * which some nssm builds write as UTF-16, hence the NUL strip in readUnitSeam.
+ */
+const ENV_SETUP_READERS = {
+	linux: {
+		setup: /^ExecStart=\/bin\/sh -c 'set -a; \. "([^"]*)" \|\| exit 1;/m,
+		deployDir: /^WorkingDirectory=(.*)$/m,
+	},
+	darwin: {
+		setup: /<key>PI_ENV_SETUP<\/key>\s*<string>([^<]*)<\/string>/,
+		deployDir: /<key>WorkingDirectory<\/key>\s*<string>([^<]*)<\/string>/,
+	},
+	win32: {
+		setup: /^PI_ENV_SETUP=(.*)$/m,
+		// nssm holds the deployment folder in a SEPARATE property (AppDirectory), and there is only one
+		// machine-scoped service per name to confuse it with — so the caller matches on nothing here
+		// rather than spending a second `nssm get` to answer a question Windows cannot ask twice.
+		deployDir: null,
+	},
+};
+
+/**
+ * What an installed unit records: the configured `--env-setup` path and the deployment folder it
+ * serves. Both null for a unit rendered without the flag, which is every unit that predates issue #209
+ * and every default render since. Never throws: an unreadable, truncated or hand-rewritten unit simply
+ * reads as "no seam configured", because a preflight guessing at a shape it does not recognise is
+ * worse than one that says nothing.
+ */
+export function readUnitSeam(text, platform) {
+	const readers = ENV_SETUP_READERS[platform];
+	if (!readers || typeof text !== "string") return { setup: null, deployDir: null };
+	const clean = text.replace(/\0/g, "");
+	const grab = (re) => (re ? (re.exec(clean)?.[1] ?? null) : null);
+	// Only a trailing CR is stripped, never surrounding whitespace: on the quoted and XML forms the
+	// capture already ends exactly where the renderer's delimiter does, and a path is allowed to hold a
+	// space anywhere in it. An empty value means the same as no value at all.
+	const clip = (v) => (v === null ? null : v.replace(/\r$/, "") || null);
+	return { setup: clip(grab(readers.setup)), deployDir: clip(grab(readers.deployDir)) };
+}
+
 const SUBCOMMANDS = new Set(["render", "install", "uninstall", "status", "start", "stop", "restart"]);
 
 const SERVICE_USAGE = `pi-dispatch service — run the worker (or --receiver) as an OS service, rendered for THIS host
@@ -137,6 +248,9 @@ const SERVICE_USAGE = `pi-dispatch service — run the worker (or --receiver) as
          --user | --system   linux scope (default --user; --system never executes root commands)
          --force             replace an existing unit in the same scope
          --print             also print the rendered unit before installing
+         --env-setup <path>  render|install: source YOUR script before the worker starts, so a secrets
+                             manager fills the environment. Absolute path, env only (no exec, no paths):
+                             the render owns the exec, so a policy refusal still exits 2. docs/secrets.md
 `;
 
 export async function runService(argv = [], deps = {}) {
@@ -175,6 +289,7 @@ export async function runService(argv = [], deps = {}) {
 				print: { type: "boolean", default: false },
 				drain: { type: "boolean", default: false },
 				"drain-timeout": { type: "string" },
+				"env-setup": { type: "string" },
 			},
 		}));
 	} catch (error) {
@@ -224,8 +339,23 @@ export async function runService(argv = [], deps = {}) {
 		which: values.receiver ? "receiver" : "worker",
 		scope: platform === "linux" && values.system ? "system" : "user",
 		force: values.force,
+		// The operator's env-setup script, or null for the shipped default. Null is load-bearing: with no
+		// seam configured every render below is byte-identical to what it produced before issue #209.
+		envSetup: null,
 	};
 
+	if (values["env-setup"] !== undefined) {
+		// Only the two subcommands that COMPOSE a command line can honour it. Ignoring the flag on the
+		// others would be the silent no-op this project refuses on principle: an operator who typed it on
+		// `restart` would believe the seam was in place.
+		if (cmd !== "render" && cmd !== "install") {
+			return fail(err, `--env-setup applies to \`service render\` and \`service install\`, which compose the command the unit runs; \`service ${cmd}\` renders nothing. Re-render (or re-install --force) to change it.`);
+		}
+		const resolved = resolveEnvSetup(ctx, values["env-setup"]);
+		if (resolved.error) return fail(err, resolved.error);
+		ctx.envSetup = resolved.path;
+	}
+
 	switch (cmd) {
 		case "render":
 			return doRender(ctx);
@@ -282,10 +412,59 @@ function unitPaths(ctx) {
 	return { name: `pi-dispatch-${ctx.which}` };
 }
 
+/**
+ * Every unit FILE this tool could have installed on this host: both daemons, both scopes, plus the
+ * `worker.service` name the README's manual `sudo cp` instructions produce (doStatus already counts
+ * that one as a real worker unit, so a preflight reading units must too). Derived from unitPaths
+ * rather than restated, so the two cannot disagree about where a unit lives.
+ *
+ * Empty on win32 by construction: there is no file to read there, only `nssm get`.
+ */
+export function installedUnitPaths(platform, home) {
+	if (platform !== "linux" && platform !== "darwin") return [];
+	const found = [];
+	for (const which of ["worker", "receiver"]) {
+		const paths = unitPaths({ platform, home, which, scope: "user" });
+		found.push({ which, scope: "user", path: platform === "linux" ? paths.userPath : paths.installPath });
+		found.push({ which, scope: "system", path: paths.systemPath });
+		if (platform === "linux" && which === "worker") found.push({ which, scope: "system", path: "/etc/systemd/system/worker.service" });
+	}
+	return found;
+}
+
 function readTemplate(ctx, name) {
 	return ctx.fs.readFileSync(join(ctx.templatesDir, name), "utf8");
 }
 
+/**
+ * The per-host path substitutions, applied to a TEMPLATE and never to anything a render composed.
+ * /opt/pi-dispatch becomes the deployment folder (the cwd this render ran from): WorkingDirectory and
+ * EnvironmentFile stay operator territory, never the package dir npm may wipe on update.
+ *
+ * The ordering matters and used to be wrong. A composed value is already absolute for THIS host, so
+ * putting it through these rewrites a path the operator typed rather than a placeholder the template
+ * shipped — and an `--env-setup /opt/pi-dispatch/setup-env.sh` on a deployment at /srv/pi-deploy became
+ * `. "/srv/pi-deploy/setup-env.sh"`, a file resolveEnvSetup never checked, while the banner above it
+ * still named the one that was typed. Substitute first, compose second, and anchor on the substituted
+ * form.
+ */
+function subDeployDir(ctx, text) {
+	// Function replacement, here and everywhere below a computed path is the REPLACEMENT: String.replace
+	// and replaceAll both read `$&` and its relatives out of a replacement STRING, so a deployment folder
+	// holding one would splice itself into the unit. A function replacement is taken literally.
+	return text.replaceAll("/opt/pi-dispatch", () => ctx.deployDir);
+}
+
+/**
+ * subDeployDir plus the systemd unit's node: the shipped `/usr/bin/node` literal does not exist on an
+ * nvm host. The PLIST deliberately gets only subDeployDir — its header comment SHOWS
+ * `<string>/usr/bin/node</string>` as the argv an operator would append by hand, and that prose is
+ * meant to keep reading as an example rather than silently becoming this host's node.
+ */
+function subUnitPaths(ctx, text) {
+	return subDeployDir(ctx, text).replaceAll("/usr/bin/node", () => ctx.execPath);
+}
+
 /**
  * The receiver refusal, shared by render and install: a null receiverStart means the receiver package
  * is not resolvable from this worker install. Refusing beats rendering — a unit pointing at a
@@ -299,6 +478,32 @@ function refuseMissingReceiver(ctx) {
 	);
 }
 
+/**
+ * The systemd form of the env-setup seam. Three pieces, each load-bearing:
+ *
+ *   - `exec` keeps systemd watching the WORKER and not a shell in front of it, so an exit 2 arrives as
+ *     an exit 2 and RestartPreventExitStatus=2 still sees a real policy refusal. This is the whole
+ *     reason the renderer owns this line instead of leaving it to a hand-edit.
+ *   - `|| exit 1` maps a failed setup (an expired token, an unreachable manager) onto the
+ *     infrastructure code, so systemd retries it under Restart=on-failure inside the StartLimit bound,
+ *     and it can never be mistaken for the determinate refusal that must stay stopped. A setup script
+ *     that calls `exit 2` ITSELF still exits 2 — sourcing cannot intercept that — which is why
+ *     docs/secrets.md tells operators not to.
+ *   - `set -a` exports a bare KEY=value, exactly as EnvironmentFile= does, so the seam accepts both an
+ *     `export`-style script and raw dotenv output. EnvironmentFile= is untouched and still read first;
+ *     this runs after it, so the manager wins over a stale value left in the file.
+ *
+ * The whole sh script is ONE single-quoted systemd word, which is why resolveEnvSetup refuses a single
+ * quote in the path (it would end the word) and a `$` (systemd expands those inside Exec lines whatever
+ * the quoting). The inner double quotes are sh's, and they are what makes a path with spaces work.
+ * Verified against systemd 252: `systemctl show -p ExecStart` reports argv[] as /bin/sh, -c, and the
+ * whole script as one word, and a worker exiting 2 under it reports ExecMainStatus=2 with NRestarts=0.
+ */
+function composeEnvSetupExec(setup, argv) {
+	const command = argv.map((a) => `"${a}"`).join(" ");
+	return `/bin/sh -c 'set -a; . "${setup}" || exit 1; set +a; exec ${command}'`;
+}
+
 /**
  * Render worker.service / receiver.service for this host. Targeted substitution of the templates'
  * known literals (see TEMPLATE_PINS); everything else — RestartPreventExitStatus=2, the StartLimit
@@ -310,20 +515,24 @@ function renderLinuxUnit(ctx) {
 	// to a repo-root WorkingDirectory that only a checkout has. The rendered unit points at absolute
 	// entries that exist in both layouts — cliPath beside this module; the receiver package's ./start
 	// export — so ExecStart works no matter what WorkingDirectory is.
-	const execStart =
-		ctx.which === "receiver"
-			? ["ExecStart=/usr/bin/node receiver/src/start.mjs", `ExecStart=${ctx.execPath} ${ctx.receiverStart}`]
-			: ["ExecStart=/usr/bin/node worker/src/cli.mjs worker", `ExecStart=${ctx.execPath} ${ctx.cliPath} worker`];
+	const argv = ctx.which === "receiver" ? [ctx.execPath, ctx.receiverStart] : [ctx.execPath, ctx.cliPath, "worker"];
+	const templateLine =
+		ctx.which === "receiver" ? "ExecStart=/usr/bin/node receiver/src/start.mjs" : "ExecStart=/usr/bin/node worker/src/cli.mjs worker";
+	const execStart = `ExecStart=${ctx.envSetup ? composeEnvSetupExec(ctx.envSetup, argv) : argv.join(" ")}`;
 	// The banner outranks the template's own "TEMPLATE/UNTESTED EXAMPLE — set the PLACEHOLDERs" header,
 	// which renders through below (the no-markers design keeps templates byte-usable, so their prose
 	// survives): a reader of the rendered unit should know the placeholders are already substituted.
-	let unit = `# rendered by \`pi-dispatch service\` — paths computed for this host from deploy/${template};\n# the template's PLACEHOLDER prose below is already substituted.\n` +
-		readTemplate(ctx, template)
-		.replace(execStart[0], execStart[1])
-		// /opt/pi-dispatch → the deployment folder (the cwd this render ran from): WorkingDirectory and
-		// EnvironmentFile stay operator territory, never the package dir npm may wipe on update.
-		.replaceAll("/opt/pi-dispatch", ctx.deployDir)
-		.replaceAll("/usr/bin/node", ctx.execPath);
+	const seamNote = ctx.envSetup
+		? `# ExecStart also runs \`--env-setup ${ctx.envSetup}\` first: sourced with \`set -a\` (a bare\n# KEY=value exports, exactly as EnvironmentFile= does, and it runs AFTER EnvironmentFile so a secrets\n# manager wins over a stale value in .env). A failed setup exits 1, never the exit 2 below, and \`exec\`\n# keeps systemd watching the worker itself. Re-render to change it; do not hand-edit this line.\n`
+		: "";
+	// Substituted first, then the composed line goes in — see subUnitPaths for why that order is
+	// load-bearing. The anchor is the template's own ExecStart put through the same substitutions, which
+	// is what it looks like by the time we search for it. Function replacements throughout: a deployment
+	// path holding `$&` would otherwise be spliced by String.replace's own syntax.
+	const substituted = subUnitPaths(ctx, readTemplate(ctx, template));
+	let unit =
+		`# rendered by \`pi-dispatch service\` — paths computed for this host from deploy/${template};\n# the template's PLACEHOLDER prose below is already substituted.\n${seamNote}` +
+		substituted.replace(subUnitPaths(ctx, templateLine), () => execStart);
 	if (ctx.scope === "user") {
 		// A systemd --user unit always runs as the invoking user, and systemd REJECTS a User= line in
 		// user scope ("Unknown lvalue"); the line must not survive the render. The replacement is a
@@ -339,7 +548,7 @@ function renderLinuxUnit(ctx) {
 		// started. default.target is the user manager's boot target.
 		unit = unit.replace("WantedBy=multi-user.target", "WantedBy=default.target");
 	} else {
-		unit = unit.replace(/^User=pi$/m, `User=${ctx.user}`);
+		unit = unit.replace(/^User=pi$/m, () => `User=${ctx.user}`);
 	}
 	return unit;
 }
@@ -351,7 +560,10 @@ function renderLinuxUnit(ctx) {
  * receiver — it has no EXIT_POLICY — and harmless.
  */
 function renderPlist(ctx) {
-	let plist = readTemplate(ctx, "com.pi-dispatch.worker.plist");
+	// Substituted before anything composed goes in (subDeployDir): the two anchors below are therefore
+	// written in their post-substitution form, and PI_ENV_SETUP can no longer be rewritten into a path
+	// the operator never typed. Only subDeployDir here — the template's /usr/bin/node is example prose.
+	let plist = subDeployDir(ctx, readTemplate(ctx, "com.pi-dispatch.worker.plist"));
 	// One wrapper, two daemons: the exec argv IS the difference now. The wrapper sources ./.env in the
 	// unit's WorkingDirectory and runs exactly these arguments — no `receiver` selector flag, no paths
 	// guessed inside the wrapper (issue #96: the wrapper's self-relative guess broke under npm install).
@@ -366,26 +578,41 @@ function renderPlist(ctx) {
 	// the command: absolute node, absolute script. The wrapper path is module-relative (templatesDir),
 	// so it exists in a checkout AND under node_modules — unlike the old repo-root guess.
 	plist = plist.replace(
-		"<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>",
-		[
-			`<string>${ctx.wrapperSh}</string>`,
-			"<!-- the command the wrapper execs after sourcing ./.env in WorkingDirectory - absolute paths, nothing guessed -->",
-			...execArgv.map((a) => `<string>${a}</string>`),
-		].join("\n\t\t"),
+		`<string>${ctx.deployDir}/deploy/worker-env-wrapper.sh</string>`,
+		() =>
+			[
+				`<string>${ctx.wrapperSh}</string>`,
+				"<!-- the command the wrapper execs after sourcing ./.env in WorkingDirectory - absolute paths, nothing guessed -->",
+				...execArgv.map((a) => `<string>${a}</string>`),
+			].join("\n\t\t"),
 	);
 	// launchd's default PATH is /usr/bin:/bin — an nvm or Homebrew node is invisible to it. The exec
 	// argv above pins THIS node absolutely, but the worker's own children (npx-style hooks, tooling
 	// that spawns bare `node`) still resolve via PATH; prepending the render node's directory keeps
 	// them on the SAME binary. PATH is configuration, not a secret: the template's deliberate
 	// no-EnvironmentVariables stance is about credentials, which still live only in .env.
+	// The dict is built as a list so the seam below can extend it without a second anchor. Everything
+	// in it is a PATH; nothing in it is a credential, which is what keeps this file committable.
+	const envEntries = ["\t\t<key>PATH</key>", `\t\t<string>${dirname(ctx.execPath)}:/usr/bin:/bin:/usr/sbin:/sbin</string>`];
+	if (ctx.envSetup) {
+		// launchd has no EnvironmentFile and no shell in front of ProgramArguments, so the seam is a
+		// VARIABLE the wrapper reads rather than a composed command line: nothing here has to be quoted
+		// for a shell, and ProgramArguments stays byte-identical to the default render. The wrapper
+		// sources it AFTER ./.env, so a secrets manager wins over a stale key left in the file.
+		envEntries.push(
+			"\t\t<!-- `pi-dispatch service --env-setup`: worker-env-wrapper.sh sources this file after ./.env.\n\t\t     A path, not a credential. Re-render to change it. -->",
+			"\t\t<key>PI_ENV_SETUP</key>",
+			`\t\t<string>${ctx.envSetup}</string>`,
+		);
+	}
+	const workingDir = `<key>WorkingDirectory</key>\n\t<string>${ctx.deployDir}</string>`;
 	plist = plist.replace(
-		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>",
-		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>\n\n\t<!-- Injected by `pi-dispatch service`: launchd's default PATH cannot see an nvm/Homebrew node,\n\t     and child processes may call bare `node`. Not a secrets dict - credentials still live only\n\t     in .env (see the header comment). -->\n\t<key>EnvironmentVariables</key>\n\t<dict>\n\t\t<key>PATH</key>\n\t\t<string>" +
-			`${dirname(ctx.execPath)}:/usr/bin:/bin:/usr/sbin:/sbin</string>\n\t</dict>`,
+		workingDir,
+		() =>
+			`${workingDir}\n\n\t<!-- Injected by \`pi-dispatch service\`: launchd's default PATH cannot see an nvm/Homebrew node,\n\t     and child processes may call bare \`node\`. Not a secrets dict - credentials still live only\n\t     in .env (see the header comment). -->\n\t<key>EnvironmentVariables</key>\n\t<dict>\n` +
+			`${envEntries.join("\n")}\n\t</dict>`,
 	);
-	// Everything left standing on /opt/pi-dispatch — WorkingDirectory, the log paths, comment prose —
-	// belongs to the deployment folder.
-	return plist.replaceAll("/opt/pi-dispatch", ctx.deployDir);
+	return plist;
 }
 
 /**
@@ -407,6 +634,10 @@ function nssmSequence(ctx) {
 		commands: [
 			["install", service, ctx.wrapperCmd, ...execArgv],
 			["set", service, "AppDirectory", ctx.deployDir],
+			// Same seam as the plist's EnvironmentVariables dict, for the same reason: nssm takes a
+			// NAME=VALUE with no shell between it and the wrapper, so the path needs no quoting and
+			// AppParameters stays byte-identical to the default render.
+			...(ctx.envSetup ? [["set", service, "AppEnvironmentExtra", `PI_ENV_SETUP=${ctx.envSetup}`]] : []),
 			["set", service, "AppStdout", `${logDir}\\${ctx.which}.out.log`],
 			["set", service, "AppStderr", `${logDir}\\${ctx.which}.err.log`],
 			["set", service, "AppStopMethodConsole", "15000"],
@@ -426,6 +657,11 @@ function doRender(ctx) {
 		ctx.out(
 			"\n# note: ProgramArguments runs the package's worker-env-wrapper.sh, which sources ./.env in the\n# WorkingDirectory above and then runs the argv that follows it — launchd has no EnvironmentFile.\n# The wrapper also converts a policy refusal (exit 2, EXIT_POLICY) into a clean exit, so KeepAlive\n# never relaunch-loops a refusal into a provider bill.\n",
 		);
+		if (ctx.envSetup) {
+			ctx.out(
+				`# note: --env-setup is delivered as PI_ENV_SETUP above. The wrapper sources ${ctx.envSetup} AFTER\n# ./.env, so your manager wins over a stale value in the file, and a missing or failing script exits 1\n# rather than the exit 2 that means a policy refusal. With it set, ./.env becomes optional.\n`,
+			);
+		}
 		return 0;
 	}
 	if (ctx.platform === "linux") {
@@ -610,6 +846,11 @@ async function doStatus(ctx) {
 		if (status.code === null) ctx.out(`${paths.name}: cannot query — nssm.exe not on PATH (https://nssm.cc)\n`);
 		else if (status.code !== 0) ctx.out(`${paths.name}: not installed\n`);
 		else ctx.out(`${paths.name}: ${status.output.trim()}\n`);
+		if (status.code === 0) {
+			const extra = await runCapture(ctx, "nssm", ["get", paths.name, "AppEnvironmentExtra"]);
+			const setup = extra.code === 0 ? readUnitSeam(extra.output, "win32").setup : null;
+			if (setup) ctx.out(`env-setup: ${setup} (named by ${paths.name}'s AppEnvironmentExtra)\n`);
+		}
 		return 0;
 	}
 	if (ctx.platform === "darwin") {
@@ -620,6 +861,7 @@ async function doStatus(ctx) {
 			ctx.out(`user scope: not installed (${paths.installPath})\n`);
 		}
 		ctx.out(ctx.fs.existsSync(paths.systemPath) ? `system scope: ${paths.systemPath} EXISTS — not managed by this tool\n` : "system scope: none\n");
+		reportEnvSetup(ctx, [paths.installPath, paths.systemPath]);
 		return 0;
 	}
 	if (ctx.fs.existsSync(paths.userPath)) {
@@ -630,9 +872,31 @@ async function doStatus(ctx) {
 	}
 	const systemHits = [paths.systemPath, ...(ctx.which === "worker" ? ["/etc/systemd/system/worker.service"] : [])].filter((p) => ctx.fs.existsSync(p));
 	ctx.out(systemHits.length ? `system scope: ${systemHits.join(", ")} EXISTS — not managed by this tool\n` : "system scope: none\n");
+	reportEnvSetup(ctx, [paths.userPath, ...systemHits]);
 	return 0;
 }
 
+/**
+ * One informational line per unit that names an `--env-setup` script (issue #216). status REPORTS: it
+ * says where the seam is configured, and nothing about whether the script is still there, still
+ * private, or still uncommitted. Those are `doctor`'s — it is the preflight, it owns the warn tiers,
+ * and it already has the git check-ignore seam. Prints nothing when no seam is configured, so the
+ * output of every deployment that does not use one is byte-identical to before.
+ */
+function reportEnvSetup(ctx, paths) {
+	for (const path of paths) {
+		if (!ctx.fs.existsSync(path)) continue;
+		let setup = null;
+		try {
+			setup = readUnitSeam(ctx.fs.readFileSync(path, "utf8"), ctx.platform).setup;
+		} catch {
+			// Unreadable — a system-scope unit this user may not read is the ordinary case. The scope line
+			// above already reported that it exists; status never fails on what it could not look at.
+		}
+		if (setup) ctx.out(`env-setup: ${setup} (named by ${path})\n`);
+	}
+}
+
 async function doStart(ctx) {
 	return startStop(ctx, "start");
 }

package/src/start.mjs

@@ -13,6 +13,7 @@ import { makeForgejoAuth } from "./forgejo-auth.mjs";
 import { makeForgejoHost } from "./forgejo-host.mjs";
 import { makeAzureAuth } from "./azure-auth.mjs";
 import { makeAzureHost } from "./azure-host.mjs";
+import { makeEgressPreflight } from "./egress.mjs";
 import { makeImagePreflight } from "./image-preflight.mjs";
 import { createWorker } from "./index.mjs";
 import { makeCollectChain } from "./outbox.mjs";
@@ -112,6 +113,22 @@ export function makeReaper({ log }) {
 				await exec("docker", ["rm", "-f", name]);
 				log("reaped_container", { name });
 			}
+			// REQ-EGRESS-ALLOWLIST: the per-job networks those containers were on. Swept AFTER the containers,
+			// because a network with a member still attached cannot be removed -- and swept by the SAME
+			// `pi-job-` filter, so the namespace rule that keeps an operator's live sandbox safe from the
+			// container reaper keeps their sandbox NETWORK safe too, with no second rule to remember.
+			//
+			// A crashed worker is the case this exists for: `runContainer`'s own finally removes the network
+			// on every ordinary path, so anything still here outlived a process that did not get to run it.
+			// A network still in use by something else fails to remove and is skipped, which is correct: this
+			// is a best-effort sweep and never a reason not to boot.
+			const { stdout: nets } = await exec("docker", ["network", "ls", "--filter", "name=pi-job-", "--format", "{{.Name}}"]);
+			for (const net of nets.split("\n").map((n) => n.trim()).filter(Boolean)) {
+				try {
+					await exec("docker", ["network", "rm", net]);
+					log("reaped_network", { network: net });
+				} catch {} // still in use, or already gone -- either way not this boot's problem
+			}
 		} catch (err) {
 			log("reaper_skipped", { reason: err?.message });
 		}
@@ -146,6 +163,7 @@ export async function startWorker(
 		makeSandboxReaper: makeSandboxReaperFn = makeSandboxReaper,
 		makeRunContainer: makeRunContainerFn = makeRunContainer,
 		makeImagePreflight: makeImagePreflightFn = makeImagePreflight,
+		makeEgressPreflight: makeEgressPreflightFn = makeEgressPreflight,
 		makeGitLabAuth: makeGitLabAuthFn = makeGitLabAuth,
 		makeGitLabHost: makeGitLabHostFn = makeGitLabHost,
 		makeForgejoAuth: makeForgejoAuthFn = makeForgejoAuth,
@@ -386,6 +404,12 @@ export async function startWorker(
 			// one who removes it would stay admitted. Contrast the staged-package manifest, correctly read once at
 			// boot because it is deploy-time state under a :ro mount; the host's image set is not.
 			imagePreflight: makeImagePreflightFn({ image: config.jobImage }),
+			// REQ-EGRESS-ALLOWLIST, and built here for the same reason the image preflight is: one deployment
+			// value, one place, so the gate that checks the proxy and the runner that attaches to its network
+			// cannot disagree about which proxy is meant. Nothing is memoised here either -- an operator who
+			// starts the proxy mid-day must not stay refused, and one who stops it must not stay admitted.
+			// Unarmed it spawns nothing at all, so a deployment without a policy pays for none of this.
+			egressPreflight: makeEgressPreflightFn({ proxy: config.egressProxy, armed: config.egress }),
 			// Completed-only, so a policy or infra exit leaves the canonical transcript byte-identical and a
 			// retry starts from what the first attempt did (CONST-RETRY-INFRA-ONLY).
 			promoteSession: sessionStore.promoteSession,
@@ -397,6 +421,8 @@ export async function startWorker(
 			runContainer: makeRunContainerFn({
 				image: config.jobImage,
 				hostEnv: env,
+				egress: config.egress, // REQ-EGRESS-ALLOWLIST: the per-job network and the proxy variables
+				egressProxy: config.egressProxy,
 				openJobLog,
 				globalPiDir: config.globalPiDir, // REQ-GLOBAL-PI-OVERLAY: :ro overlay mount when configured
 				allowGlobalExtensions: config.allowGlobalExtensions,