@edgehero/pi-dispatch 0.3.0 → 1.1.0

package/src/doctor.mjs

@@ -46,15 +46,18 @@
  */
 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";
 import { isForgeKind } from "./forges.mjs";
 import { findLiteralSecret, ADMIN_RE } from "./import-pi.mjs";
 import { agentDirFrom, readHostPi } from "./host-pi.mjs";
-import { PACKAGES_SUBDIR, readStageManifest } from "./packages.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)
@@ -99,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);
@@ -202,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";
@@ -240,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,
@@ -251,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, images, skillsDirs, forges, repositories } = 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;
@@ -325,6 +347,91 @@ export async function collectChecks(env, seams) {
 		}
 	}
 
+	// REQ-PER-TRIGGER-SKILLS (issue #189). One line per distinct (flow, folder, skillsDir, packages)
+	// question: does the flow this trigger names resolve in ANY tier this host can see? Probed in the
+	// loader's own precedence order (repo > injected > overlay > staged packages), first hit wins the
+	// line. ⚠ and NEVER ✗ when nothing resolves -- a forge trigger's repo is not on this host and
+	// mid-setup is legal -- and no fixAction (triggers content is the never tier). The runner's
+	// flow_not_loaded line is the exact, in-container half of the same answer
+	// (DES-FLOW-RESOLUTION-TWO-ADVISORY-LAYERS): these probes read dir names, and a frontmatter
+	// `name:` rename is invisible to them, so a ⚠ here can be wrong in only the loud direction.
+	// A deployment with no triggers adds no lines at all, so its output is byte-identical.
+	if (flows.length > 0) {
+		// One stage read for the whole run; each tuple's staged probe is a lookup on its result.
+		const staged = readStagedSkills({ globalPiDir: env.PI_GLOBAL_PI_DIR, readFile: (p) => readFileSync(p, "utf8"), fileExists });
+		const groups = new Map();
+		for (const f of flows) {
+			const key = JSON.stringify([f.flow, f.folder, f.skillsDir, f.packages]);
+			if (!groups.has(key)) groups.set(key, { ...f, labels: [] });
+			groups.get(key).labels.push(f.label);
+		}
+		for (const g of groups.values()) {
+			const at = g.labels.join(", ");
+			// The charset pre-check doubles as the interpolation guard for the git probe below, and it is
+			// a finding of its own: a name the skill charset refuses can never materialise in ANY tier
+			// (materialize and copy-tree enforce the same RE on the way in).
+			if (!SKILL_NAME_RE.test(g.flow)) {
+				checks.push({
+					ok: false,
+					warn: true,
+					label: `Trigger flow ${JSON.stringify(g.flow)} fails the skill name charset (${at})`,
+					fix: "a flow name must match the skill charset (lowercase alphanumerics, - and _, 64 max), or no tier can ever hold it -- fix run.flow",
+				});
+				continue;
+			}
+			let resolved = null;
+			const checked = [];
+			const unknown = [];
+			if (g.folder) {
+				const state = await repoFlowAtHead(spawn, g.folder, g.flow);
+				if (state === "present") resolved = `repo .pi/skills at HEAD of ${g.folder}`;
+				else if (state === "absent") checked.push("repo .pi/skills at HEAD");
+				else unknown.push(`repo (${g.folder} is not readable as a git repo here)`);
+			} else {
+				unknown.push("repo (a forge clone, not on this host)");
+			}
+			if (!resolved && g.skillsDir) {
+				if (fileExists(join(g.skillsDir, g.flow, "SKILL.md"))) resolved = `injected run.skillsDir ${g.skillsDir}`;
+				else checked.push("injected run.skillsDir");
+			}
+			if (!resolved && env.PI_GLOBAL_PI_DIR) {
+				if (fileExists(join(env.PI_GLOBAL_PI_DIR, "skills", g.flow, "SKILL.md"))) resolved = "the overlay skills/";
+				else checked.push("overlay skills/");
+			}
+			if (!resolved) {
+				if (!g.packages) {
+					checked.push("staged packages (withheld: run.packages false)");
+				} else {
+					const hit = staged.skills.find((s) => s.name === g.flow);
+					if (hit) resolved = `staged package ${hit.package}`;
+					else if (staged.unenumerable.length > 0) unknown.push(`staged package(s) ${staged.unenumerable.join(", ")} (manifest patterns, not enumerable here)`);
+					else checked.push("staged packages");
+				}
+			}
+			if (resolved) {
+				checks.push({ ok: true, label: `Trigger flow "${g.flow}" resolves (${at}: ${resolved})` });
+			} else {
+				checks.push({
+					ok: false,
+					warn: true,
+					label: `Trigger flow "${g.flow}" resolves in NO tier visible here (${at})`,
+					fix: `checked: ${checked.join(", ") || "nothing checkable"}${unknown.length > 0 ? `; not checkable here: ${unknown.join(", ")}` : ""} -- commit .pi/skills/${g.flow}/SKILL.md, add the skill to run.skillsDir or the overlay skills/, or stage a package shipping it; a job of this trigger runs without the flow it names (the runner logs flow_not_loaded) and still exits 0`,
+				});
+			}
+		}
+	}
+
+	// run.command triggers (issue #189): ONE advisory line, deliberately WITHOUT the per-tier probes the
+	// flow block above runs. A command is registered by extension CODE at pi startup -- repo .pi/, the
+	// overlay and staged packages all contribute, and none is enumerable host-side without executing the
+	// extension, which doctor must never do. The honest line names where the real check lives instead;
+	// unlike a missing flow, the failure there is LOUD (a refusal, not a clean exit 0), which is why this
+	// is advisory and carries no fixAction (triggers content is the never tier). A deployment with no
+	// command triggers adds no line at all, so its output is byte-identical.
+	if (commands > 0) {
+		checks.push({ ok: true, label: `${commands} command trigger(s): a command is only verifiable in-container -- the runner refuses an unregistered one pre-spend (command-unregistered)` });
+	}
+
 	// Issue #41: every DISTINCT image a trigger names in run.image, minus the deployment default already
 	// checked above. Two silent-failure modes, and both used to be impossible because there was one image.
 	//   1. the image was never built -- a job that refuses pre-spend at 03:00 in a log nobody is reading, and
@@ -353,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
@@ -558,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) {
@@ -603,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`,
+				});
+			}
 		}
 	}
 
@@ -1124,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) {
@@ -1191,8 +1352,37 @@ function aiTriggerNames(dir) {
 	return names;
 }
 
+/**
+ * Does `.pi/skills/<flow>/SKILL.md` exist at HEAD of a local folder? "present" | "absent" | "unknown".
+ *
+ * Deliberately NOT readFlowGate: that module answers WHO may fire a flow (the ai-trigger frontmatter,
+ * at a caller-pinned sha) and its catch collapses ANY git failure into deny -- fail-closed is right
+ * for a gate and exactly wrong here, where deny-because-git-broke would print a confident wrong
+ * answer on an advisory line. Doctor resolving HEAD itself is also fine: the gate's no-ref rule
+ * defends against an agent self-authorizing mid-run, and a host-side preflight has no agent. What IS
+ * the gate's, verbatim, is the ls-tree read, the 100644-blob requirement and the hardening flags --
+ * copied so the two readers cannot disagree about what "a committed skill file" means, and so a
+ * hostile repo config cannot run code during the read (flow-gate.mjs's defaultGit, restated).
+ */
+const GIT_READ_FLAGS = ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "--no-pager"];
+async function repoFlowAtHead(spawn, folder, flow) {
+	if (!SKILL_NAME_RE.test(flow)) return "unknown"; // the caller pre-checks; belt against interpolation
+	const head = await runCmdCapture(spawn, "git", [...GIT_READ_FLAGS, "-C", folder, "rev-parse", "HEAD"]);
+	const sha = head.code === 0 ? head.output.trim() : null;
+	if (!sha || !/^[0-9a-f]{40,64}$/.test(sha)) return "unknown";
+	const tree = await runCmdCapture(spawn, "git", [...GIT_READ_FLAGS, "-C", folder, "ls-tree", "-z", sha, `.pi/skills/${flow}/SKILL.md`]);
+	if (tree.code !== 0) return "unknown";
+	const record = tree.output.split("\0").find((r) => r);
+	if (!record) return "absent"; // valid sha, path absent at that commit
+	const tab = record.indexOf("\t");
+	const [mode, type] = tab === -1 ? [] : record.slice(0, tab).split(/\s+/);
+	// A symlink/gitlink entry is "absent" for this question too: the gate would refuse it, and the
+	// materialiser never copies it, so nothing downstream treats it as a skill file.
+	return mode === "100644" && type === "blob" ? "present" : "absent";
+}
+
 function readTriggerFacts(env, fileExists, cwd) {
-	const none = { requiring: 0, optingOut: 0, resuming: 0, replicating: 0, instructing: 0, images: [], skillsDirs: [], forges: [], repositories: [] };
+	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
@@ -1209,6 +1399,10 @@ function readTriggerFacts(env, fileExists, cwd) {
 			// REQ-REPLICA-RUNS. `> 1` rather than `!== undefined` because the loader already refuses anything
 			// else -- this counts triggers that will actually multiply spend, which is the only reason to say so.
 			replicating: triggers.filter((t) => t.run.replicas > 1).length,
+			// run.command triggers (issue #189), counted for the one advisory line below. The `flows`
+			// tuple list already filters to `typeof f.flow === "string"`, so a command trigger drops out
+			// of the flow-tier probes naturally -- no exclusion needed there.
+			commands: triggers.filter((t) => typeof t.run.command === "string").length,
 			optingOut: triggers.filter((t) => t.run.packages === false).length,
 			images: [...new Set(triggers.map((t) => t.run.image).filter((i) => typeof i === "string"))].sort(),
 			// REQ-PER-TRIGGER-SKILLS. The distinct host directories the file names, deduped like `images`,
@@ -1224,10 +1418,306 @@ function readTriggerFacts(env, fileExists, cwd) {
 			// would report all-green and never mention that the credential it needs was never looked for.
 			forges: [...new Set(triggers.map((t) => t.run.kind).filter(isForgeKind))].sort(),
 			repositories: [...new Set(triggers.filter((t) => t.run.kind === "github" && typeof t.run.repository === "string").map((t) => t.run.repository))].sort(),
+			// REQ-PER-TRIGGER-SKILLS (issue #189). Per-trigger TUPLES, unlike every deduped set above,
+			// because a flow-resolution answer depends on the trigger's own folder/skillsDir/packages --
+			// two triggers naming the same flow with different skillsDirs are two different questions.
+			// The label is how a line names its trigger: cron entries by their id, id-less webhook
+			// entries by raw file position (the admin's trigger:<index> identity).
+			flows: triggers
+				.map((t, index) => ({
+					label: t.on.type === "cron" ? `cron "${t.on.id}"` : `${t.on.type} trigger #${index}`,
+					flow: t.run.flow,
+					kind: t.run.kind,
+					folder: typeof t.run.folder === "string" ? t.run.folder : null,
+					skillsDir: typeof t.run.skillsDir === "string" ? t.run.skillsDir : null,
+					packages: t.run.packages !== false,
+				}))
+				.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;
 }
 
 /**