@edgehero/pi-dispatch 1.0.0 → 1.1.0

package/src/doctor.mjs

@@ -46,7 +46,7 @@
  */
 import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn as nodeSpawn } from "node:child_process";
 import { defaultSandboxDir, globalExtensionsEnabled } from "./config.mjs";
@@ -56,6 +56,8 @@ import { agentDirFrom, readHostPi } from "./host-pi.mjs";
 import { PACKAGES_SUBDIR, readStagedSkills, readStageManifest } from "./packages.mjs";
 import { copySkillTree } from "./copy-tree.mjs";
 import { SKILL_NAME_RE } from "./flow-gate.mjs";
+import { DEFAULT_EGRESS_PROXY, egressArmed } from "./egress.mjs";
+import { installedUnitPaths, readUnitSeam } from "./service.mjs";
 import { parseTriggers } from "./triggers.mjs";
 
 const NODE_FLOOR = [22, 19]; // pi's engine floor (22.19.0)
@@ -100,8 +102,13 @@ export async function runDoctor(env = process.env, deps = {}) {
 		// default is a real path in the developer's home directory and the host comparison may spawn their
 		// package manager -- neither belongs in a unit test, and "no network, no Docker" is the same rule.
 		agentDir = agentDirFrom(env),
+		// Where the service manager's units live, and which formats to read them in (issue #216). Seams
+		// rather than bare process.platform/homedir() because the --env-setup check has to be exercised
+		// for all three unit formats, and only one of them exists on whichever host runs the suite.
+		platform = process.platform,
+		home = homedir(),
 	} = deps;
-	const seams = { cwd, out, spawn, probeValkey, fileExists, nodeVersion, mkdir, chmod, rm, agentDir };
+	const seams = { cwd, out, spawn, probeValkey, fileExists, nodeVersion, mkdir, chmod, rm, agentDir, platform, home };
 
 	let checks = await collectChecks(env, seams);
 	let failed = render(checks, out);
@@ -203,7 +210,7 @@ export async function defaultPromptFn(question, { input = process.stdin, output
  * a comment.
  */
 export async function collectChecks(env, seams) {
-	const { cwd, spawn, probeValkey, fileExists, nodeVersion, agentDir = agentDirFrom(env) } = seams;
+	const { cwd, spawn, probeValkey, fileExists, nodeVersion, platform, agentDir = agentDirFrom(env) } = seams;
 
 	const jobImage = env.PI_JOB_IMAGE ?? "pi-job:latest";
 	const valkeyUrl = env.VALKEY_URL ?? "redis://127.0.0.1:6379";
@@ -241,6 +248,10 @@ export async function collectChecks(env, seams) {
 		},
 	});
 
+	// Right after `.env present`, because it answers the same question that check raises: where DOES this
+	// deployment's environment come from. [] unless a seam is configured (issue #216).
+	checks.push(...(await envSetupChecks(env, seams)));
+
 	const dockerCode = await runCmd(spawn, "docker", ["info"]);
 	checks.push({
 		ok: dockerCode === 0,
@@ -252,7 +263,17 @@ export async function collectChecks(env, seams) {
 	// image checks just below, and `optingOut`/`requiring` colour the staged-packages lines further down.
 	// `optingOut` counts the only value that withholds the staged set; `requiring` counts an explicit
 	// run.packages: true, which arms nothing any more but is still an operator statement of intent.
-	const { requiring, optingOut, resuming, replicating, instructing, commands, images, skillsDirs, forges, repositories, flows } = readTriggerFacts(env, fileExists, cwd);
+	const { requiring, optingOut, resuming, replicating, instructing, commands, images, skillsDirs, forges, repositories, flows, parseError, path: triggersFilePath } = readTriggerFacts(env, fileExists, cwd);
+	// FIRST, and fail rather than warn: every check below this line reads counts that a parse failure
+	// zeroed, so a green run here would be reporting on a file nobody could read. The receiver loads this
+	// file unconditionally and refuses to start without it, which is the consequence worth naming.
+	if (parseError) {
+		checks.push({
+			ok: false,
+			label: `triggers file does not parse -- the receiver will refuse to start: ${parseError}`,
+			fix: `fix ${triggersFilePath} so it loads (the message above names the entry and the reason), then re-run doctor -- every trigger-derived check below is skipped until it parses`,
+		});
+	}
 
 	// Only meaningful if docker itself responds; otherwise the image check is noise on top of a down daemon.
 	const imageCode = dockerCode === 0 ? await runCmd(spawn, "docker", ["image", "inspect", jobImage]) : null;
@@ -439,6 +460,11 @@ export async function collectChecks(env, seams) {
 		}
 	}
 
+	// REQ-EGRESS-ALLOWLIST (issue #202). [] when PI_EGRESS=0, so a deployment that declined it gets
+	// byte-identical output. Gated on docker and the image, because two of these checks run a container and
+	// the rest are noise on top of a down daemon.
+	checks.push(...(await egressChecks(env, seams, { dockerCode, imageCode, jobImage })));
+
 	// The receiver itself, when the triggers file names ANY forge (issue #80). Only forge deliveries need
 	// the receiver at all, so a cron/local-only deployment gets no receiver noise here. WARNS rather than
 	// fails, same doctrine as the gitlab block below: a deployment can legitimately be mid-setup (or run
@@ -644,16 +670,43 @@ export async function collectChecks(env, seams) {
 				fix: setupFix,
 			});
 		}
+		// Two ways to supply the key, exactly one of them at a time (issue #208): a path to a file, or the
+		// PEM itself in GITHUB_APP_PRIVATE_KEY for a deployment whose environment comes from a secrets
+		// manager. The hygiene pass below belongs to the PATH variant -- there is no mode to check and no
+		// file to stat on a value that only ever exists in this process's environment, and whoever supplies
+		// that environment owns its hygiene. What survives for both is the shape sniff, and the rule that
+		// nothing from the key reaches output.
 		const keyPath = env.GITHUB_APP_PRIVATE_KEY_PATH;
-		if (!keyPath) {
-			checks.push({ ok: false, warn: true, label: "GITHUB_AUTH_SOURCE=app but GITHUB_APP_PRIVATE_KEY_PATH is unset -- the worker will refuse to boot", fix: setupFix });
+		const inlineKey = (env.GITHUB_APP_PRIVATE_KEY ?? "").trim();
+		if (inlineKey !== "" && keyPath) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: "GITHUB_APP_PRIVATE_KEY and GITHUB_APP_PRIVATE_KEY_PATH are both set -- the worker will refuse to boot",
+				fix: "unset one of them: the inline value for a deployment fed by a secrets manager, the path for a key on disk (docs/secrets.md)",
+			});
+		} else if (inlineKey !== "") {
+			// A flattened key still starts with the header -- the `\n` escapes come after it -- so one sniff
+			// covers both accepted forms.
+			if (inlineKey.startsWith("-----BEGIN")) {
+				checks.push({ ok: true, label: "GitHub App private key supplied inline (GITHUB_APP_PRIVATE_KEY)" });
+			} else {
+				checks.push({
+					ok: false,
+					warn: true,
+					label: `GITHUB_APP_PRIVATE_KEY does not look like a PEM (does not begin "-----BEGIN ...") -- the worker will refuse to boot; contents not shown`,
+					fix: "check for a truncated paste, or point GITHUB_APP_PRIVATE_KEY_PATH at the key file instead (docs/secrets.md)",
+				});
+			}
+		} else if (!keyPath) {
+			checks.push({ ok: false, warn: true, label: "GITHUB_AUTH_SOURCE=app but neither GITHUB_APP_PRIVATE_KEY_PATH nor GITHUB_APP_PRIVATE_KEY is set -- the worker will refuse to boot", fix: setupFix });
 		} else if (!fileExists(keyPath)) {
 			checks.push({ ok: false, warn: true, label: `GITHUB_APP_PRIVATE_KEY_PATH does not exist (${keyPath})`, fix: setupFix });
 		} else {
 			checks.push({ ok: true, label: `GitHub App private key present (${keyPath})` });
 			// POSIX mode only -- on win32 stat modes are synthetic (0666-ish for everything), so a warn
 			// there would fire on every healthy deployment and teach operators to ignore it.
-			if (process.platform !== "win32") {
+			if (platform !== "win32") {
 				try {
 					const loose = statSync(keyPath).mode & 0o077;
 					if (loose !== 0) {
@@ -689,6 +742,26 @@ export async function collectChecks(env, seams) {
 			} catch {
 				checks.push({ ok: false, warn: true, label: `the App private key at ${keyPath} exists but is not readable by this user`, fix: setupFix });
 			}
+			// Mode 0600 protects the key from other users on this host; it does nothing once the file is in
+			// a commit. `setup github` writes the key into the DEPLOYMENT FOLDER, and a deployment folder is
+			// very often a checkout -- so the last thing between an App signing key and a public repository
+			// can be one `git add -A`. This repo's own .gitignore covers *.pem; the operator's may not, and
+			// a key they renamed or brought themselves is the same accident.
+			//
+			// Exit 1 is the ONLY case that warns: git says "this is a work tree, and that path is not
+			// ignored". 0 means covered, 128 means no work tree at all, and null means git could not be
+			// launched. Every one of those is silence, because a check nobody can silence must never cry
+			// wolf -- the cost of a missed warning here is one operator reading the doc, and the cost of a
+			// false one is every operator learning to scroll past doctor.
+			const ignoreCode = await runCmd(spawn, "git", [...GIT_READ_FLAGS, "-C", dirname(keyPath), "check-ignore", "-q", keyPath]);
+			if (ignoreCode === 1) {
+				checks.push({
+					ok: false,
+					warn: true,
+					label: `the App private key at ${keyPath} is inside a git work tree that does not ignore it`,
+					fix: `move it outside that repo, or ignore it there (\`*.pem\`) -- one \`git add -A\` commits the App's signing key, which can mint a token for every repository the App is installed on, and mode 0600 does not survive a commit`,
+				});
+			}
 		}
 	}
 
@@ -1210,9 +1283,11 @@ function nodeCheck(version) {
  * Parsed with the SHARED `parseTriggers`, so doctor counts exactly the entries the worker and receiver will
  * act on -- a truthy `"true"` string is rejected there and therefore never counted here.
  *
- * Swallows ANY error to zeroes -- a missing, unreadable, or malformed triggers file already fails LOUD at
- * worker boot (config.mjs, schedules.mjs), so re-reporting the parse failure here would only bury doctor's
- * own findings under a second copy of a diagnosis the operator already gets.
+ * A missing file still reads as zeroes and says nothing: that is an ordinary cron-less deployment. A file
+ * that EXISTS and does not parse is reported instead, with the reason. The old justification here -- that
+ * such a file "already fails LOUD at worker boot" -- was false for the deployment that needs doctor most:
+ * the worker reads this file only when PI_TRIGGERS_FILE is set, so on a receiver-only host nothing else
+ * says a word, while the zeroes quietly disarm every forge, image and flow check below.
  */
 /** lstat, so a symlinked skillsDir is judged on its own inode -- copy-tree.mjs's rule, restated. */
 function dirExists(dir) {
@@ -1307,7 +1382,7 @@ async function repoFlowAtHead(spawn, folder, flow) {
 }
 
 function readTriggerFacts(env, fileExists, cwd) {
-	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, images: [], skillsDirs: [], forges: [], repositories: [], flows: [] };
+	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, commands: 0, images: [], skillsDirs: [], forges: [], repositories: [], flows: [], parseError: null, path: null };
 	try {
 		// Unset falls back to ./triggers.json in cwd, MIRRORING the receiver's own default
 		// (receiver/src/config.mjs) -- the two must read the same file, or doctor preflights a deployment
@@ -1359,9 +1434,290 @@ function readTriggerFacts(env, fileExists, cwd) {
 				}))
 				.filter((f) => typeof f.flow === "string"),
 		};
+	} catch (e) {
+		// REPORTED, not swallowed. This catch used to justify itself with "a malformed triggers file already
+		// fails LOUD at worker boot", and that premise does not hold: the worker reads the file only when
+		// PI_TRIGGERS_FILE is set, so a receiver-only deployment gets no loud failure anywhere. Worse, the
+		// zeroes below silently disarm the WEBHOOK_SECRET check, every per-forge credential check, the
+		// per-image checks and the flow-tier probes -- so doctor came back GREENER than a healthy
+		// deployment, which is the one direction a preflight must never fail in.
+		//
+		// The counts stay zero, because every downstream check reads them and a half-parsed file has no
+		// honest counts to give. What changes is that the reason travels with them.
+		// Only a TAGGED config refusal is reported. parseTriggers throws `piDispatchConfig` errors; anything
+		// else here is an fs failure on a path the guard above already said existed (a race, a permission,
+		// a directory), which is not a statement about the file's CONTENT and has no fix an operator can act
+		// on from this line. Those keep the old silent zeroes.
+		if (e?.piDispatchConfig !== true) return none;
+		return { ...none, parseError: e.message, path: triggersPath(env, cwd) };
+	}
+}
+
+/** The triggers path doctor would have read, so a parse failure can name it. */
+function triggersPath(env, cwd) {
+	return env.PI_TRIGGERS_FILE ?? join(cwd, "triggers.json");
+}
+
+/**
+ * The `--env-setup` script (issue #216). `pi-dispatch service render|install --env-setup <path>` names a
+ * script the service manager SOURCES at every boot, as the service user, with the deployment's
+ * environment -- and after that nothing ever looks at it again. resolveEnvSetup checked it existed once,
+ * at render time, on a host that may not be this one.
+ *
+ * doctor has to DISCOVER the path before it can check it, because --env-setup is a render-time flag and
+ * the rendered unit is the only place it lives. Two sources, in this order:
+ *
+ *   1. The installed units for THIS deployment -- the file that actually boots, and so the honest
+ *      answer. A unit whose WorkingDirectory names some other folder belongs to some other deployment on
+ *      the same host and is deliberately skipped: doctor is this deployment's preflight, and warning
+ *      about a neighbour's unit would fire forever on a host that runs two.
+ *   2. PI_ENV_SETUP in doctor's OWN environment, and only when (1) found nothing. That is what launchd
+ *      and nssm put in front of the wrapper, so it is the right answer for a doctor run through the same
+ *      environment the service gets. It is a different question from (1), which is why every line below
+ *      names the source it came from rather than blurring the two.
+ *
+ * Everything here is warn-tier and nothing carries a `fixAction` -- the never tier
+ * (REQ-DEPLOYMENT-BOOTSTRAP): doctor does not chmod an operator's file and does not move it. Nor does it
+ * ever OPEN the script. The script holds no secret by design, but what it holds is the commands that
+ * fetch them, and a preflight that echoed those would be publishing the map instead of the treasure.
+ *
+ * Returns [] when no seam is configured, so a deployment that does not use one gets byte-identical
+ * output.
+ */
+/**
+ * REQ-EGRESS-ALLOWLIST. What the shipped egress policy actually is on this host, read back from docker
+ * rather than assumed from the compose file that was supposed to create it.
+ *
+ * Returns [] when `PI_EGRESS=0`, so a deployment that declined the policy gets byte-identical output --
+ * the same convention envSetupChecks follows one feature over. Armed is the DEFAULT, so most deployments
+ * see these lines.
+ *
+ * TIERING, and it is the whole editorial judgement here. The proxy's PRESENCE is a hard failure when the
+ * policy is armed: the worker refuses every job pre-spend without it, so a ✓ would be a lie and a ⚠ would
+ * under-report a deployment that cannot run anything. Everything that needs the NETWORK to answer is
+ * warn-tier, on doctor's own rule that a ✗ is reserved for certainties: a custom provider base URL, a
+ * corporate egress path or a transient provider blip each make a red here a false alarm, and an operator
+ * who learns to scroll past doctor costs more than a missed warning does.
+ *
+ * NOTHING here carries a `fixAction` -- the never tier (REQ-DEPLOYMENT-BOOTSTRAP). One candidate was
+ * considered and refused: a prompt-tier offer to start the proxy, on the Valkey precedent. That offer
+ * starts a QUEUE, whose failure mode is that nothing runs. This one would stand up a SECURITY CONTROL
+ * whose allowlist the operator has not written yet, turning "no policy" into "a policy that fails every
+ * job inside a paid container". It is also not one argv but a compose profile and a file that must already
+ * exist, and doctor "never guesses a semantic env value".
+ */
+async function egressChecks(env, seams, { dockerCode, imageCode, jobImage }) {
+	const { spawn } = seams;
+	// The SAME parse the worker boots with (egress.mjs), never a second `=== "1"`: doctor reporting a
+	// policy that is off, or nothing about one that is on, is worse than doctor not checking at all.
+	// A malformed value is the worker's boot failure to report, not doctor's to guess at, so it reads as
+	// armed here and the `.env` check above is what fails.
+	let armed;
+	try {
+		armed = egressArmed(env);
 	} catch {
-		return none;
+		armed = true;
+	}
+	if (!armed) return [];
+	const proxy = env.PI_EGRESS_PROXY || DEFAULT_EGRESS_PROXY;
+	const checks = [];
+
+	if (dockerCode !== 0) {
+		checks.push({
+			ok: false,
+			warn: true,
+			label: "Egress policy: not checked (the Docker daemon did not answer)",
+			fix: "start Docker, then re-run doctor -- the policy lives in docker's own networks and containers, so none of it can be read from here",
+		});
+		return checks;
+	}
+
+	// `docker inspect` on the container, not `ps`: it answers present-vs-absent and running-vs-stopped in
+	// one call, and those are two different fixes. The FIELD_SEP habit is image-preflight.mjs's -- neither
+	// a boolean nor a health word can contain "|".
+	const state = await runCmdCapture(spawn, "docker", ["inspect", `--format={{.State.Running}}|{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}`, proxy]);
+	const [running, health] = state.code === 0 ? state.output.trim().split("|") : [];
+	const up = running === "true";
+	checks.push({
+		ok: up,
+		label: up ? `Egress proxy running (${proxy})` : state.code === 0 ? `Egress proxy is stopped (${proxy})` : `Egress proxy is not on this host (${proxy})`,
+		fix: "docker compose -f deploy/docker-compose.yml --profile egress up -d  -- the egress policy refuses every job pre-spend while this is down, which costs no budget but runs nothing (PI_EGRESS=0 opts out)",
+	});
+	if (!up) return checks;
+
+	// Advisory on purpose, and deliberately NOT what the money gate reads. A healthcheck can flap, and a
+	// pre-spend gate that refuses on a flapping signal drops real work while one that retries on it burns
+	// the second budget slot this whole requirement exists to save. Here a human is reading, so it is worth
+	// saying: a squid that parsed its config and then wedged looks identical to a healthy one from outside.
+	if (health && health !== "none") {
+		checks.push({
+			ok: health === "healthy",
+			warn: true,
+			label: `Egress proxy health: ${health}`,
+			fix: `docker logs ${proxy} -- the container is up but its listener is not answering, so jobs will start and then fail to reach anything`,
+		});
 	}
+
+	// The end-to-end probe, and the only place in this codebase that proves the policy rather than
+	// inspecting it. Two containers, on a throwaway network built exactly like a job's, gated on the image
+	// being present because it uses the job image's own node -- which is the point: it proves the operator's
+	// OWN image honours NODE_USE_ENV_PROXY, the property a stale image would silently lack and the one
+	// whose absence turns the whole policy into an outage.
+	//
+	// Credential-free by construction: `api.anthropic.com` answers 401 to an unauthenticated request, so
+	// reaching the provider and being refused for the key proves the entire path and costs nothing. That is
+	// docs/egress.md's own method, promoted from prose to a check.
+	if (imageCode !== 0) return checks;
+	const net = `pi-dispatch-egress-doctor-${process.pid}`;
+	if ((await runCmd(spawn, "docker", ["network", "create", "--internal", net])) !== 0) return checks;
+	try {
+		if ((await runCmd(spawn, "docker", ["network", "connect", net, proxy])) !== 0) return checks;
+		for (const [slug, host, url, want] of [
+			["provider", "the provider", "https://api.anthropic.com/v1/messages", true],
+			["unlisted", "an unlisted host", "https://pi-dispatch-not-on-your-allowlist.example/", false],
+		]) {
+			const probe = await runCmdCapture(spawn, "docker", [
+				"run",
+				"--rm",
+				// Named, and outside the boot reaper's `pi-job-` filter by construction. `--rm` disposes of it,
+				// so the name exists for the operator watching `docker ps` during a doctor run and for the one
+				// reading `ps` afterwards to find out what a wedged probe was doing.
+				"--name",
+				`pi-dispatch-egress-probe-${slug}`,
+				"--pull=never",
+				`--network=${net}`,
+				"-e",
+				`HTTPS_PROXY=http://${proxy}:3128`,
+				"-e",
+				"NODE_USE_ENV_PROXY=1",
+				"--entrypoint",
+				"node",
+				jobImage,
+				"-e",
+				// The URL rides ARGV, not the spawn env, and the difference from the in-image `gh` probe is
+				// deliberate: that one carries a TOKEN, which must never be visible in `ps`. This carries a
+				// public hostname, so argv is the honest place for it -- an operator reading `ps` during a
+				// doctor run can see exactly which host is being probed.
+				`fetch(${JSON.stringify(url)},{method:"POST"}).then(r=>{console.log("reached",r.status);process.exit(0)},e=>{console.log("blocked",e.cause?.code??e.message);process.exit(3)})`,
+			]);
+			const reached = probe.code === 0;
+			checks.push({
+				ok: reached === want,
+				warn: true,
+				label: reached === want
+					? want
+						? `Egress policy reaches the provider (api.anthropic.com answered, so the whole path works and no key was spent)`
+						: `Egress policy denies ${host} (the deny direction is the half an allowlist can silently lose)`
+					: want
+						? `Egress policy does NOT reach the provider (api.anthropic.com)`
+						: `Egress policy ALLOWS ${host} that is not on your allowlist`,
+				fix: want
+					? `add api.anthropic.com to egress-allowlist.conf and restart the proxy -- until then every job starts, fails at its first turn, and spends two budget slots proving it (docs/egress.md)`
+					: `check egress-allowlist.conf: a rule wider than you meant (a bare domain where you wanted a subdomain) lets a job reach hosts you did not list`,
+			});
+		}
+	} finally {
+		await runCmd(spawn, "docker", ["network", "disconnect", "-f", net, proxy]);
+		await runCmd(spawn, "docker", ["network", "rm", net]);
+	}
+	return checks;
+}
+
+async function envSetupChecks(env, seams) {
+	const { cwd, spawn, fileExists, platform, home } = seams;
+	const sources = new Map(); // setup path -> how doctor learned it; the first source to name it wins
+
+	if (platform === "win32") {
+		for (const which of ["worker", "receiver"]) {
+			const service = `pi-dispatch-${which}`;
+			const got = await runCmdCapture(spawn, "nssm", ["get", service, "AppEnvironmentExtra"]);
+			// Not installed, or nssm not on PATH: silence. Same doctrine as check-ignore below -- a check
+			// nobody can silence must never cry wolf, and "could not ask" is not "misconfigured".
+			if (got.code !== 0) continue;
+			// No deployment match here: nssm keeps the folder in a SEPARATE AppDirectory property, and there
+			// is exactly one machine-scoped service per name for it to be confused with.
+			const { setup } = readUnitSeam(got.output, "win32");
+			if (setup && !sources.has(setup)) sources.set(setup, `${service}'s AppEnvironmentExtra`);
+		}
+	} else {
+		for (const { path } of installedUnitPaths(platform, home)) {
+			if (!fileExists(path)) continue;
+			let seam;
+			try {
+				seam = readUnitSeam(readFileSync(path, "utf8"), platform);
+			} catch {
+				continue; // a system-scope unit this user may not read: which deployment it serves is unknowable
+			}
+			if (!seam.setup || seam.deployDir !== cwd) continue;
+			if (!sources.has(seam.setup)) sources.set(seam.setup, path);
+		}
+	}
+
+	const fromEnv = (env.PI_ENV_SETUP ?? "").trim();
+	if (sources.size === 0 && fromEnv) sources.set(fromEnv, "PI_ENV_SETUP in this environment");
+
+	const checks = [];
+	for (const [setup, source] of sources) {
+		if (!fileExists(setup)) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `the env-setup script at ${setup} does not exist (named by ${source})`,
+				fix: "restore it, or re-render without --env-setup -- the service manager sources it at every boot, so until it is back the unit exits 1 in a restart loop and the worker never starts (docs/secrets.md)",
+			});
+			continue;
+		}
+		checks.push({ ok: true, label: `env-setup script present (${setup}, named by ${source})` });
+
+		// WRITABILITY, not readability -- deliberately `& 0o022` and not the App key's `& 0o077`. This file
+		// is EXECUTED (sourced) by the account that holds the provider key and the forge token, so anyone
+		// who can edit it owns the worker. That it is READABLE is fine: it holds no secret by design.
+		// POSIX only, for the same reason the App key's mode check skips win32 -- stat modes are synthetic
+		// there, so this would warn on every healthy Windows deployment and teach operators to scroll past.
+		if (platform !== "win32") {
+			try {
+				if ((statSync(setup).mode & 0o022) !== 0) {
+					checks.push({
+						ok: false,
+						warn: true,
+						label: `the env-setup script at ${setup} is group/world-writable`,
+						fix: `chmod go-w ${setup} -- the service manager sources it at every boot as the account that holds the provider key and the forge token, so whoever can edit it owns the worker`,
+					});
+				}
+			} catch {
+				// stat raced a deletion or an exotic fs: the presence line above already covered existence.
+			}
+			const dir = dirname(setup);
+			try {
+				const mode = statSync(dir).mode;
+				// Sticky (0o1000) is exempt and must stay exempt: in a sticky directory a non-owner cannot
+				// rename or delete someone else's file, so "anyone can replace it" would simply be false there.
+				if ((mode & 0o022) !== 0 && (mode & 0o1000) === 0) {
+					checks.push({
+						ok: false,
+						warn: true,
+						label: `the directory holding the env-setup script (${dir}) is group/world-writable`,
+						fix: `chmod go-w ${dir} -- the script's own mode does not help when anyone can replace the file, and the manager sources whatever is there at the next boot`,
+					});
+				}
+			} catch {
+				// an unreadable parent directory: nothing to claim either way.
+			}
+		}
+
+		// The #211 question, asked of a different file. Exit 1 is again the ONLY case that speaks: 0 means
+		// ignored, 128 means no work tree, null means git could not be launched, and all three are silence.
+		const ignoreCode = await runCmd(spawn, "git", [...GIT_READ_FLAGS, "-C", dirname(setup), "check-ignore", "-q", setup]);
+		if (ignoreCode === 1) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `the env-setup script at ${setup} is inside a git work tree that does not ignore it`,
+				fix: "move it outside that repo, or ignore it there -- it holds no secret by design, but it holds the commands that FETCH them (client and project ids, a manager address, sometimes a path to a credential file), which is a map to every secret this deployment uses",
+			});
+		}
+	}
+	return checks;
 }
 
 /**