@edgehero/pi-dispatch 1.10.2 → 2.0.0

package/src/init.mjs

@@ -7,12 +7,22 @@
  * scoped pauses, an empty packages list stages nothing, an empty subscriptions list declares no plan
  * prices — so a fresh deployment starts inert and is opted into feature by feature.
  */
-import { existsSync, copyFileSync, writeFileSync } from "node:fs";
+import { existsSync, copyFileSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
+import { parseBackendList, venuesOf } from "./backends.mjs";
+import { deploymentVenueEnv } from "./deployment-venue.mjs";
+import { setEnvKeyIfEmpty } from "./env-file.mjs";
+import { PACKAGED_EGRESS_PROXY_CONF } from "./egress-conf-copy.mjs";
+import { VALKEY_PASSWORD_KEY, newValkeyPassword } from "./valkey-auth.mjs";
 
 const EMPTY_TRIGGERS = `${JSON.stringify({ triggers: [] }, null, 2)}\n`;
-const EMPTY_PAUSE_WINDOWS = `${JSON.stringify({ windows: [] }, null, 2)}\n`;
+/**
+ * EXPORTED so a test scaffolds what `init` scaffolds (issue #384). Doctor now asks the worker's own loader
+ * whether a configured file loads, and the fixtures wrote `[]` and `{}`, which those loaders refuse: a test
+ * that scaffolds content the product never writes measures the wrong deployment.
+ */
+export const EMPTY_PAUSE_WINDOWS = `${JSON.stringify({ windows: [] }, null, 2)}\n`;
 // Pinned third-party pi packages staged into the global overlay (issue #58). Empty by default: staging
 // runs third-party code inside jobs, so it is opted into package by package, never scaffolded populated.
 const EMPTY_PACKAGES = `${JSON.stringify({ packages: [] }, null, 2)}\n`;
@@ -23,14 +33,15 @@ const EMPTY_SUBSCRIPTIONS = `${JSON.stringify({ version: 1, subscriptions: [] },
 // one-job-per-folder mutex for local jobs is code, not configuration, so it needs no scaffold line.
 // Versioned for the subscriptions reason, sharpened: this is enforcement config, and a silently
 // down-read newer file would be a silently widened spend limit.
-const EMPTY_SCOPED_LIMITS = `${JSON.stringify({ version: 1, limits: [] }, null, 2)}\n`;
+export const EMPTY_SCOPED_LIMITS = `${JSON.stringify({ version: 1, limits: [] }, null, 2)}\n`;
 /**
  * The egress allowlist (REQ-EGRESS-ALLOWLIST): the hosts a job container may reach, one bare hostname per
  * line. Scaffolded with the three a job cannot work without, and NOT empty -- unlike every other scaffold
  * in this file, whose empty form is inert. An empty allowlist is not inert, it is a deployment where every
  * job dies at its first turn, so the safe default here is the working minimum rather than nothing.
  *
- * The provider is an ordinary entry. There is no address-based rule and nothing is special about it: the
+ * The provider is an ordinary entry. No address-based rule allows it (the proxy's one address rule only denies this
+ * host's loopback and link-local addresses, issue #428), and nothing is special about it: the
  * proxy carries provider traffic like everything else, because the runner's own `fetch` follows the proxy
  * once NODE_USE_ENV_PROXY is set, which the worker sets (worker/src/egress.mjs).
  */
@@ -54,56 +65,180 @@ api.anthropic.com
 registry.npmjs.org
 `;
 
+// The package's own copy of the proxy's rules, which init scaffolds (issue #480). It lives in egress-conf-copy.mjs since
+// issue #484, beside the comparison doctor and `up` make against it, and is re-exported here for init's callers.
+export { PACKAGED_EGRESS_PROXY_CONF };
+
+/**
+ * `deps.env` is the caller's environment (the CLI's and doctor's pass theirs), and `deps.venues` a venue set the caller
+ * already decided (`up` passes its own, so the two never disagree). Otherwise the venue is decided as `up` decides it
+ * (`deploymentVenueEnv`): this shell where it sets a key, else the deployment `.env`, and a disagreement between the two
+ * is said instead of any next steps. The default `env` is `{}` and not `process.env` so a test is never steered by the
+ * shell it runs in. `deps.steps: false` prints the file list and no "Next:" at all: `up` passes it (issue #480), since
+ * `up` performs that ladder itself and printing it mid-pass told a reader to do by hand what was being done for them.
+ */
 export function runInit(cwd = process.cwd(), deps = {}) {
-	const { fs = { existsSync, copyFileSync, writeFileSync }, out = (s) => process.stdout.write(s) } = deps;
+	const { fs = { existsSync, copyFileSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync }, readPackageFile = readFileSync, out = (s) => process.stdout.write(s), env = {}, platform = process.platform, newPassword = newValkeyPassword } = deps;
 	const results = [];
-
-	// .env from the example. Prefer the copy in cwd (the clone's repo root); fall back to the copy
-	// SHIPPED with the worker package (worker/.env.example, kept byte-identical to the root example by
-	// worker/test/publish.test.mjs) so init works both from elsewhere in a checkout and from an npm
-	// install, where the repo root does not exist.
+	// The list prints even when a write throws part way (PR #488's final review: a read-only deploy/ lost the seven lines
+	// of what init had already created, leaving one EACCES line), so the operator always sees what now exists.
+	const printList = () => {
+		// The name column is as wide as the longest name (issue #480): a fixed 20 put egress-allowlist.conf's note out of line.
+		const width = Math.max(...results.map(([, name]) => name.length));
+		for (const [verb, name, note] of results) {
+			out(`${verb.padEnd(7)} ${name.padEnd(width)} ${note}\n`);
+		}
+	};
 	const envPath = join(cwd, ".env");
-	if (fs.existsSync(envPath)) {
-		results.push(["kept", ".env", "already exists — left untouched"]);
+	try {
+		// .env from the example. Prefer the copy in cwd (the clone's repo root); fall back to the copy
+		// SHIPPED with the worker package (worker/.env.example, kept byte-identical to the root example by
+		// worker/test/publish.test.mjs) so init works both from elsewhere in a checkout and from an npm
+		// install, where the repo root does not exist.
+		if (fs.existsSync(envPath)) {
+			results.push(["kept", ".env", KEPT]);
+		} else {
+			const cwdExample = join(cwd, ".env.example");
+			const source = fs.existsSync(cwdExample)
+				? cwdExample
+				: fileURLToPath(new URL("../.env.example", import.meta.url));
+			// Issue #468: the new file carries this deployment's own Valkey password (the example's `# VALKEY_PASSWORD=` line
+			// filled in, never shown) and is created readable by this account alone: it holds that password and, soon, the
+			// provider key. `wx`: a file that appeared since the check above is never overwritten (init's contract).
+			const text = setEnvKeyIfEmpty(String(fs.readFileSync(source, "utf8")), VALKEY_PASSWORD_KEY, newPassword(), { platform });
+			if (createOnly(fs, envPath, text, { mode: 0o600 })) results.push(["created", ".env", `from .env.example, mode 0600, with a generated ${VALKEY_PASSWORD_KEY} (value not shown): set your provider key next`]);
+			else results.push(["kept", ".env", KEPT]);
+		}
+
+		scaffold(fs, results, join(cwd, "triggers.json"), EMPTY_TRIGGERS, "empty triggers list");
+		scaffold(fs, results, join(cwd, "pause-windows.json"), EMPTY_PAUSE_WINDOWS, "empty pause-windows list");
+		scaffold(fs, results, join(cwd, "pi-packages.json"), EMPTY_PACKAGES, "empty pi package list (stage with import-pi --with-packages)");
+		scaffold(fs, results, join(cwd, "subscriptions.json"), EMPTY_SUBSCRIPTIONS, "empty subscription list (declare plan prices for the admin's cost analytics)");
+		scaffold(fs, results, join(cwd, "scoped-limits.json"), EMPTY_SCOPED_LIMITS, "empty scoped-limits list (per repo/folder caps; the folder mutex needs no file)");
+		scaffold(fs, results, join(cwd, "egress-allowlist.conf"), DEFAULT_EGRESS_ALLOWLIST, "egress allowlist (provider + forge + registry; the egress policy is on unless PI_EGRESS=0)");
+		// Issue #480: the proxy's rules, the file beside the allowlist that the docker proxy mounts. Create-only like every
+		// scaffold here, so a clone's own deploy/egress-proxy.conf is reported and kept. The one scaffold whose content is
+		// not this module's: it is the package's file verbatim, read from the package and never through `fs` (the
+		// deployment folder's seam), as `up` reads its Quadlet templates. The podman venue does not read this copy (its unit
+		// mounts an account-owned copy `service install` writes), and it costs nothing there.
+		//
+		// Only into a deploy/ that is a real directory of this folder (PR #488's review): a symlinked deploy/ would put the
+		// file wherever the link points, so init refuses there and writes nothing, and says so. Asked again after the mkdir,
+		// so a link that appeared in between is refused too.
+		const deployDir = join(cwd, "deploy");
+		const notOurDir = () => {
+			const st = lstatOrNull(fs, deployDir);
+			return st && (st.isSymbolicLink() || !st.isDirectory()) ? (st.isSymbolicLink() ? "a symlink" : "not a directory") : null;
+		};
+		let deployRefusal = notOurDir();
+		if (!deployRefusal && !lstatOrNull(fs, deployDir)) {
+			fs.mkdirSync(deployDir, { recursive: true });
+			deployRefusal = notOurDir();
+		}
+		if (deployRefusal) {
+			results.push(["refused", "deploy/egress-proxy.conf", `deploy/ here is ${deployRefusal}, so init writes nothing into it: make deploy/ a directory of this folder, then run \`pi-dispatch init\` again`]);
+		} else {
+			scaffold(fs, results, join(deployDir, "egress-proxy.conf"), () => readPackageFile(PACKAGED_EGRESS_PROXY_CONF), "the egress proxy's rules, the package's copy (shipped, not edited; the hosts go in the allowlist)", "deploy/egress-proxy.conf");
+		}
+	} catch (err) {
+		printList();
+		throw err;
+	}
+	printList();
+	// A refused scaffold is a failed init (fail loudly): the line above says which, and the steps below still print.
+	const code = results.some(([verb]) => verb === "refused") ? 1 : 0;
+	if (deps.steps === false) return code;
+	if (deps.venues) {
+		out(nextSteps(deps.venues, { platform }));
+		return code;
+	}
+	// Decided exactly as `up` decides it (issue #453, gate round 1): a next-steps ladder for a venue `up` would refuse to
+	// guess is a ladder for the wrong venue. The files above are scaffolded either way; only the steps wait.
+	const venue = deploymentVenueEnv({ env, fs, envPath, platform, command: "init" });
+	if (venue.error) {
+		out(`\nNext: which venue this deployment runs is unknown, so no steps are shown: ${venue.error}. Then run \`pi-dispatch init\` again for them (it keeps every file above).\n`);
+		return code;
+	}
+	for (const note of venue.notes) out(`⚠ ${note}\n`);
+	try {
+		parseBackendList(venue.env.PI_BACKENDS);
+	} catch (err) {
+		out(`\nNext: which venue this deployment runs is unknown, so no steps are shown: ${err.message}. Fix PI_BACKENDS, then run \`pi-dispatch init\` again for them (it keeps every file above).\n`);
+		return code;
+	}
+	out(nextSteps(venuesOf(venue.env), { platform }));
+	return code;
+}
+
+const KEPT = "already exists, left untouched";
+
+// `name` is what the list shows, the file's own name unless it sits below the folder; `content` may be a function, so a
+// file read from the package is read only when it is about to be written.
+function scaffold(fs, results, path, content, note, name = path.split(/[\\/]/).pop()) {
+	// A DIRECTORY where the file belongs (PR #488's review) is not "kept": every reader of these files wants a file, and
+	// docker mounts a directory at deploy/egress-proxy.conf where squid reads its config. Followed through a link, too.
+	if (isDirectory(fs, path)) {
+		results.push(["refused", name, `${name} here is a directory, not a file: remove it, then run \`pi-dispatch init\` again`]);
+	} else if (fs.existsSync(path)) {
+		results.push(["kept", name, KEPT]);
+	} else if (createOnly(fs, path, typeof content === "function" ? content() : content)) {
+		results.push(["created", name, note]);
 	} else {
-		const cwdExample = join(cwd, ".env.example");
-		const source = fs.existsSync(cwdExample)
-			? cwdExample
-			: fileURLToPath(new URL("../.env.example", import.meta.url));
-		fs.copyFileSync(source, envPath);
-		results.push(["created", ".env", "from .env.example — set your provider key next"]);
+		results.push(["kept", name, KEPT]);
 	}
+}
 
-	scaffold(fs, results, join(cwd, "triggers.json"), EMPTY_TRIGGERS, "empty triggers list");
-	scaffold(fs, results, join(cwd, "pause-windows.json"), EMPTY_PAUSE_WINDOWS, "empty pause-windows list");
-	scaffold(fs, results, join(cwd, "pi-packages.json"), EMPTY_PACKAGES, "empty pi package list (stage with import-pi --with-packages)");
-	scaffold(fs, results, join(cwd, "subscriptions.json"), EMPTY_SUBSCRIPTIONS, "empty subscription list (declare plan prices for the admin's cost analytics)");
-	scaffold(fs, results, join(cwd, "scoped-limits.json"), EMPTY_SCOPED_LIMITS, "empty scoped-limits list (per repo/folder caps; the folder mutex needs no file)");
-	scaffold(fs, results, join(cwd, "egress-allowlist.conf"), DEFAULT_EGRESS_ALLOWLIST, "egress allowlist (provider + forge + registry; the egress policy is on unless PI_EGRESS=0)");
+/**
+ * Every scaffold's write (PR #488's review): `wx` (O_CREAT|O_EXCL), so nothing that exists is written through, not even
+ * a dangling symlink, which `existsSync` reports absent and a plain write follows out of the folder. EEXIST is "kept",
+ * as init's contract says; any other failure is thrown as it was.
+ */
+function createOnly(fs, path, content, opts = {}) {
+	try {
+		fs.writeFileSync(path, content, { ...opts, flag: "wx" });
+		return true;
+	} catch (err) {
+		if (err?.code === "EEXIST") return false;
+		throw err;
+	}
+}
 
-	for (const [verb, name, note] of results) {
-		out(`${verb.padEnd(7)} ${name.padEnd(20)} ${note}\n`);
+function isDirectory(fs, path) {
+	const st = lstatOrNull(fs, path);
+	if (!st) return false;
+	if (!st.isSymbolicLink()) return st.isDirectory();
+	try {
+		return typeof fs.statSync === "function" && fs.statSync(path).isDirectory();
+	} catch {
+		return false;
 	}
-	out(nextSteps());
-	return 0;
 }
 
-function scaffold(fs, results, path, content, note) {
-	const name = path.split(/[\\/]/).pop();
-	if (fs.existsSync(path)) {
-		results.push(["kept", name, "already exists — left untouched"]);
-	} else {
-		fs.writeFileSync(path, content);
-		results.push(["created", name, note]);
+function lstatOrNull(fs, path) {
+	try {
+		return fs.lstatSync(path);
+	} catch (err) {
+		if (err?.code === "ENOENT") return null;
+		throw err;
 	}
 }
 
-function nextSteps() {
+/**
+ * The docker text is the same for every set that includes `local`. Its step 2 was a compose command naming
+ * deploy/docker-compose.yml, a file a folder made by init alone does not have (issue #480), and it started no egress
+ * proxy either; it is now `pi-dispatch up`, which starts Valkey and the proxy itself. A podman-only deployment (issue
+ * #453) gets the podman ladder instead, the steps of docs/podman.md "Setup" in the order a fresh folder needs them
+ * (named by its URL since #480, because a folder made without a clone has no docs/):
+ * the job image into this account's own store, the venue key and provider key in `.env` (what `up` and `service
+ * install` read), the stack as Quadlet units, doctor, and the worker as a user service.
+ */
+export function nextSteps(venues = { localUsed: true, podmanUsed: false }, { platform = "linux" } = {}) {
+	if (venues.podmanUsed && !venues.localUsed) return platform === "linux" ? PODMAN_NEXT_STEPS : PODMAN_OFF_LINUX;
 	return `
 Next:
   1. docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest
-                                                        # the prebuilt job image (or build image/Dockerfile)
-  2. docker compose -f deploy/docker-compose.yml up -d  # the durable queue (Valkey)
+                                                        # the prebuilt job image (or build your own from a clone)
+  2. pi-dispatch up                                     # Valkey and the egress proxy (unless PI_EGRESS=0)
   3. edit .env                                          # set ANTHROPIC_API_KEY (or your provider's key)
   4. pi-dispatch doctor                                 # verify Docker, Valkey, image, and key
   5. pi-dispatch worker                                 # drain the queue
@@ -112,3 +247,27 @@ Operator panel (optional): pi install npm:@edgehero/pi-dispatch-admin   then   /
   (or let the panel do all of the above: /dispatch setup walks these steps with a consent per action)
 `;
 }
+
+// Off Linux the podman venue refuses the host (`podman-platform`: Podman machine on macOS and Windows was never
+// measured), so its ladder would walk an operator into Quadlet steps that cannot work here.
+const PODMAN_OFF_LINUX = `
+Next: PI_BACKENDS lists only the podman venue, which runs on Linux alone: on this host the worker refuses it
+(podman-platform), so there are no podman steps to run here. Run this deployment on a Linux host, or add \`local\` to
+PI_BACKENDS to run jobs on Docker here (then run \`pi-dispatch init\` again for those steps).
+`;
+
+const PODMAN_NEXT_STEPS = `
+Next (the podman venue; run these as the worker's own account. First set the account up as the Podman guide's "Setup"
+steps 1-4 say (https://github.com/edgehero/pi-dispatch/blob/main/docs/podman.md), linger included:
+sudo loginctl enable-linger <account>, without which a job gets no bounds):
+  1. podman pull ghcr.io/edgehero/pi-job:latest && podman tag ghcr.io/edgehero/pi-job:latest pi-job:latest
+                                                        # the prebuilt job image, in this account's own store
+  2. edit .env                                          # PI_BACKENDS=podman, and ANTHROPIC_API_KEY (or your provider's key)
+  3. pi-dispatch up                                     # Valkey and the egress proxy as Quadlet units in your user manager
+  4. pi-dispatch doctor                                 # verify Podman, Valkey, image, and key
+  5. pi-dispatch service install                        # the worker as a user service, after those units (also installs them)
+  6. pi-dispatch doctor --live                          # read the bounds, egress and job user back off real containers
+
+Operator panel (optional): pi install npm:@edgehero/pi-dispatch-admin   then   /dispatch
+  (or let the panel do all of the above: /dispatch setup walks these steps with a consent per action)
+`;

package/src/job-user.mjs

@@ -0,0 +1,252 @@
+/**
+ * WHICH uid a job container runs as, decided from facts rather than probed (issue #341,
+ * `DES-JOB-USER-INFERRED-READ-BACK-ON-REQUEST`).
+ *
+ * On a daemon that enforces bind-mount ownership, a job can read its 0700 job dir, write its mounts and leave files
+ * the host can remove ONLY as the uid that owns them. The image runs as uid 1001, the worker as whoever started it,
+ * and those differ on almost every native Linux host: measured, every job then fails. Docker Desktop maps ownership,
+ * so there the image's own user works and nothing may change.
+ *
+ * Decided WITHOUT starting a container. `CONST-ISOLATION-CONTAINER-PER-JOB` rejects "probing at worker boot or per
+ * job", so the decision reads what is already cheap to ask: the platform, the worker's own ids, the endpoint the
+ * docker CLI resolves, one `docker info`, and the owner of a local socket. A wrong inference is not silent: the
+ * runner refuses a job whose inputs it cannot read before any spend (`job-inputs-unreadable`), and `pi-dispatch
+ * doctor --live` reads the mounts back on request.
+ *
+ * Pure parts (`parseDaemonFacts`, `decideJobUser`, `resolveImageUser`) take values, apart from `decideJobUser`'s
+ * `os.release()` default; the two readers take seams.
+ */
+
+import { statSync } from "node:fs";
+import { release as osRelease } from "node:os";
+import { execDockerBounded } from "./backend-local.mjs";
+import { CONTAINER_HOME, SHIPPED_IMAGE_UID } from "./container-spec.mjs";
+import { DAEMON_FACTS_ARGS, DAEMON_FACTS_MAX_BUFFER, DAEMON_FACTS_TIMEOUT_MS, PODMAN_PRODUCT_LICENSE, displayVersion, parseDaemonFacts } from "./daemon-facts.mjs";
+
+// Moved to the leaf `daemon-facts.mjs` (issue #452, gate round 3) and re-exported, so every importer keeps its path.
+export { DAEMON_FACTS_ARGS, DAEMON_FACTS_TIMEOUT_MS, PODMAN_PRODUCT_LICENSE, displayVersion, parseDaemonFacts };
+
+/**
+ * Whether a job's OWN bind mounts carry `:Z` (issue #355): `true` only for a Podman daemon that reports SELinux, reached
+ * through an endpoint on this host, from a Linux worker. Measured on an enforcing Fedora 44 host (rootful Podman 5.8.1,
+ * container-selinux 2.247.0): every unlabelled bind source is denied to the container, `ls` included, with or without
+ * `:ro`, so every job on the documented Podman route failed at `/job` before it spent anything.
+ *
+ * ONE function, read by the job path, doctor and the sandbox, so the three cannot disagree about when a mount is
+ * relabelled. Each condition is a measured boundary rather than caution:
+ *   - Podman only. Docker Engine with `selinux-enabled` reports the same `name=selinux` and was not measured, so its
+ *     argv stays exactly what it was (out of scope, named in the design entry).
+ *   - `selinux === true` only: `null` (a shape that did not say) is not a reason to relabel anything.
+ *   - `endpoint.local === true` only: bind sources are the DAEMON's paths, and on another machine this worker's job
+ *     directories are not what gets relabelled.
+ *   - a Linux worker only: a Podman machine on macOS or Windows reports its Linux VM's SELinux while the bind sources are
+ *     the host's own files shared into that VM, a route nobody measured with `:Z`.
+ *
+ * WHICH mounts is `containerSpec`'s business, not this function's: only the directories the worker creates per job.
+ * `:Z` is PRIVATE (a per-container MCS pair), which is exactly right for a directory one container ever sees, and
+ * measured to lock every other container out of what it relabels. So an operator's local folder and the shared global
+ * overlay are NEVER relabelled; doctor names the `semanage fcontext` fix for those instead.
+ */
+export function relabelsPrivateMounts(facts, endpoint, platform = process.platform) {
+	return platform === "linux" && facts?.podman === true && facts?.selinux === true && endpoint?.local === true;
+}
+
+/**
+ * `async () => ({ answered: true, facts } | { answered: false, reason, transient })`.
+ *
+ * A clean exit that parses to neither shape is DETERMINATE (`unparseable`): the CLI answered and said something no
+ * rule can read. Every other failure is TRANSIENT here, on purpose and unlike the endpoint read: a clean exit whose
+ * body says no daemon answered (`daemon-unreachable`, what a daemon down or still starting gives), a non-zero exit, a
+ * timeout, a signal, no docker binary. A worker unit with `RestartPreventExitStatus=2` must never be stranded by a
+ * daemon that is merely late. No CLI text is ever read or logged.
+ */
+export function makeDaemonFactsReader({ run = (args) => execDockerBounded(args, { timeoutMs: DAEMON_FACTS_TIMEOUT_MS, maxBuffer: DAEMON_FACTS_MAX_BUFFER }) } = {}) {
+	return async function readDaemonFacts() {
+		let result;
+		try {
+			result = await run(DAEMON_FACTS_ARGS);
+		} catch (err) {
+			result = { code: null, stdout: "", error: err };
+		}
+		if (result?.error || result?.code !== 0) {
+			const error = result?.error;
+			const reason = error?.timedOut || error?.killed ? "timeout"
+				: typeof error?.signal === "string" ? `signal-${error.signal.toLowerCase()}`
+				: error?.code === "ENOENT" ? "docker-not-found"
+				: typeof result?.code === "number" ? `exit-${result.code}`
+				: typeof error?.code === "number" ? `exit-${error.code}`
+				: "spawn-failed";
+			return { answered: false, reason, transient: true };
+		}
+		const parsed = parseDaemonFacts(result.stdout);
+		if (parsed?.unreachable) return { answered: false, reason: "daemon-unreachable", transient: true };
+		return parsed ? { answered: true, facts: parsed.facts } : { answered: false, reason: "unparseable", transient: false };
+	};
+}
+
+/**
+ * `{ uid, gid }` of a local unix socket, or `null`. Takes the docker endpoint's `unix://` path or Podman's
+ * `remoteSocket.path`, which is a bare path when the service is local and `unix://...` when it is remote (both
+ * measured). `stat`, never `lstat`: `/var/run/docker.sock` is a symlink on Docker Desktop, and a link pointing at a
+ * rootless socket would read as root-owned. Any failure (EACCES on a 0700 parent, ENOENT) is simply no fact.
+ */
+export function socketFacts(path, { stat = statSync } = {}) {
+	if (typeof path !== "string") return null;
+	const bare = path.startsWith("unix://") ? path.slice("unix://".length) : path;
+	if (!bare.startsWith("/")) return null;
+	try {
+		const s = stat(bare);
+		return typeof s?.uid === "number" && typeof s?.gid === "number" ? { uid: s.uid, gid: s.gid } : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Is a Podman `remoteSocket.path` a unix socket (bare path or `unix://`), i.e. a local service? */
+// The fixed operator texts, one per cause, for the boot refusal, the sandbox and doctor. The forge comments keep
+// their own shorter texts (a comment's reader may not be the operator), and no text carries CLI output, an endpoint
+// or a path: a refusal that repeats what docker printed can repeat a credential.
+export const JOB_USER_FIX = Object.freeze({
+	rootless: "the container runtime runs rootless (a user namespace between the job and this worker), so no uid a job may run as can read the worker's 0700 job dir; run jobs on a rootful Docker or Podman daemon. If this was inferred from a socket this worker's uid owns on a rootful daemon (a systemd SocketUser= override), point the worker at the daemon's own socket",
+	"userns-remap": "the Docker daemon remaps container uids (userns-remap), so no uid a job may run as can read the worker's 0700 job dir; run jobs on a daemon without userns-remap",
+	"worker-is-root": "the worker runs as root, and a job must not run as root (nonRoot); run the worker as an unprivileged account, as deploy/worker.service's User= does",
+	"desktop-linux-userns": "Docker Desktop on Linux maps container uids like a rootless daemon, so no uid a job may run as can read the worker's 0700 job dir; use Docker Engine on this host (WSL2 is not affected)",
+	"runtime-unreadable": "the docker CLI answered `docker info` with something no rule can read, so which uid a job may run as is unknown; point the real docker CLI at a Docker or Podman daemon",
+	"root-group": "the worker's primary group is gid 0, and a job runs with that group; run the worker with an unprivileged primary group",
+	"docker-group": "the worker's primary group is the docker socket's group, and a job runs with that group; make docker a supplementary group (log out and back in rather than `newgrp docker`)",
+	// Not a daemon cause: the per-image rule's refusal (`job-image-any-uid-unsupported`), here so every surface shares one text.
+	"any-uid-unsupported": "the job image does not declare `anyUid` (`dev.pi-dispatch.capabilities`), so it cannot run as this worker's own uid, which this host's container runtime requires; rebuild it from a release that has this feature, or run the worker as uid 1001",
+});
+
+/**
+ * The daemon half of the decision. Pure apart from the `release` default. Returns `{ mode, user, cause, reason }`,
+ * one of FOUR modes:
+ *   - `image`: the image's own USER runs, argv byte-identical to before issue #341;
+ *   - `worker`: the job runs as `user`, the worker's own "<euid>:<egid>" (the per-image rule may still decline);
+ *   - `unmappable`: no uid works, `cause` names why;
+ *   - `unknown`: not decidable now (`reason`), never cached and never a boot exit.
+ *
+ * `endpoint` is the endpoint resolver's answer; `daemon` is `readDaemonFacts()`'s; `socket` is `socketFacts(...)`.
+ * The rows are ORDERED, and the order is part of the contract (the design entry's table).
+ */
+export function decideJobUser({ platform, release = osRelease(), euid, egid, endpoint, daemon, socket = null }) {
+	const image = (cause) => ({ mode: "image", user: null, cause, reason: null });
+	const unmappable = (cause) => ({ mode: "unmappable", user: null, cause, reason: null });
+	const unknown = (reason) => ({ mode: "unknown", user: null, cause: null, reason });
+
+	// A daemon on these platforms runs in a Linux VM, and Docker Desktop's file sharing maps ownership (measured), so the
+	// image's own user works. The other VM-backed daemons there (OrbStack, Colima, Podman machine) are unmeasured.
+	if (platform === "darwin" || platform === "win32") return image("desktop-platform");
+	// Bind-mount sources are another machine's paths: nothing about this host's uids applies, and doctor already warns.
+	if (endpoint?.local === false) return image("endpoint-not-local");
+	if (!daemon?.answered) return daemon?.transient === false ? unmappable("runtime-unreadable") : unknown(daemon?.reason ?? "no-daemon-facts");
+	const facts = daemon.facts;
+	if (endpoint?.local !== true) {
+		// No docker endpoint resolved. Only Podman's own shape (its docker emulation) says enough to go on; a Docker
+		// shape with no endpoint leaves the socket rows below blind.
+		if (facts.shape !== "podman") return unknown("endpoint-unresolved");
+		// A client of a service that listens on TCP: its path did not survive parsing, so there is no socket on this host
+		// to read. A client reaching a unix-socket service over ssh reports that service's own unix path and is NOT
+		// caught here (a residual the design entry names).
+		if (facts.serviceIsRemote === true && facts.remoteSocketPath === null) return image("endpoint-not-local");
+	}
+	if (facts.os === "Docker Desktop") {
+		if (!/microsoft/i.test(String(release))) return unmappable("desktop-linux-userns");
+		// WSL2 bind mounts keep uids (unmeasured): the ordinary rows decide.
+	}
+	if (facts.rootless === true) return unmappable("rootless");
+	if (facts.userns === true) return unmappable("userns-remap");
+	if (typeof euid !== "number" || typeof egid !== "number") return unknown("no-process-ids");
+	// A rootless daemon's socket belongs to the user running it. Needed for Podman before its compat info carried
+	// name=rootless (absent at v4.3.1, present at v4.9.3); narrowed to THIS uid's socket, never any non-root owner.
+	if (euid !== 0 && socket && socket.uid === euid) return unmappable("rootless");
+	if (euid === 0) return unmappable("worker-is-root");
+	return { mode: "worker", user: `${euid}:${egid}`, cause: null, reason: null };
+}
+
+/**
+ * The per-image half, for a job about to run. Returns `{ user, home }` (`user` null means the image's own USER),
+ * `{ refused, cause }` or `{ unavailable, reason }`.
+ *
+ * ORDER MATTERS. uid 1001 comes first: the image already runs as it, so no `--user` and no group rule, whatever the
+ * image declares; a uid-1001 worker whose primary group is docker works today and must keep working once the shipped
+ * image carries `anyUid`. Only a `--user` puts the worker's gid into the container, so the two group refusals live on
+ * that path alone.
+ */
+export function resolveImageUser(decision, { capabilities = [], euid, egid, socket = null } = {}) {
+	if (decision?.mode === "image") return { user: null, home: null };
+	if (decision?.mode === "unmappable") return { refused: "job-user-unmappable", cause: decision.cause };
+	if (decision?.mode !== "worker") return { unavailable: true, reason: decision?.reason ?? "unknown" };
+	if (euid === SHIPPED_IMAGE_UID) return { user: null, home: null };
+	if (!Array.isArray(capabilities) || !capabilities.includes("anyUid")) return { refused: "job-image-any-uid-unsupported", cause: "any-uid-unsupported" };
+	if (egid === 0) return { refused: "job-user-unmappable", cause: "root-group" };
+	if (socket && egid === socket.gid) return { refused: "job-user-unmappable", cause: "docker-group" };
+	return { user: decision.user, home: CONTAINER_HOME };
+}
+
+/**
+ * The causes that stop a worker whose default venue is `local` from booting: facts about the daemon or the worker's
+ * own identity, which no job on that venue can get past. ONE set, read by the worker's boot and by doctor's severity,
+ * so doctor cannot show a warning for a cause the worker refuses to boot on. The rest refuse per job: the group rows
+ * apply only to a job whose image needs `--user`, and `runtime-unreadable` describes one answer.
+ */
+// A plain Set (read with `.has` only); `Object.freeze` would not stop `.add`, so it is not pretended.
+export const BOOT_REFUSING_JOB_USER_CAUSES = new Set(["rootless", "userns-remap", "worker-is-root", "desktop-linux-userns"]);
+
+/** The operator-facing refusal for an unmappable decision or cause. */
+export function jobUserRefusal(causeOrDecision) {
+	const cause = typeof causeOrDecision === "string" ? causeOrDecision : causeOrDecision?.cause;
+	return `Refused: ${JOB_USER_FIX[cause] ?? "the job user could not be decided"} (issue #341).`;
+}
+
+/**
+ * `async ({ endpoint, key }) => ({ decision, facts, daemon, socket })`, cached by `key` (the endpoint state string the
+ * caller already keeps). Concurrent callers for one key share one read. `daemon` is the raw read result (`{ answered,
+ * facts }` or `{ answered: false, reason, transient }`), which the runtime observations read (issue #345).
+ *
+ * NOT cached: `unknown`, `unmappable` `runtime-unreadable`, and any decision made without an answered read (an `image`
+ * decided on macOS while the daemon was still starting). Each describes an answer rather than a daemon, and a cached one
+ * would retry or refuse every later job on that endpoint, or leave the observations unread, until the worker restarted.
+ * A cached decision is otherwise kept until the endpoint state changes: a daemon reconfigured behind an unchanged
+ * endpoint (rootful to rootless on one socket path) is read again only after a restart, a residual the design entry names.
+ */
+export function makeJobUserResolver({
+	readFacts,
+	platform = process.platform,
+	release = osRelease(),
+	euid = process.geteuid?.(),
+	egid = process.getegid?.(),
+	stat = statSync,
+} = {}) {
+	let cached = null;
+	const inFlight = new Map();
+	return resolveJobUser;
+	async function resolveJobUser({ endpoint, key }) {
+		if (cached && cached.key === key) return cached.value;
+		if (inFlight.has(key)) return inFlight.get(key);
+		const work = (async () => {
+			// Asked on EVERY platform and endpoint, although a VM-backed platform or an endpoint on another machine decides
+			// `image` before any daemon fact is read: the same read is where the runtime observations come from (issue
+			// #345), and a Docker Desktop host skipped here would never be credited with the bounds its daemon applies.
+			const daemon = await readFacts();
+			// A local docker endpoint's display form IS its unix path (credentials never ride a unix URL); with no endpoint,
+			// Podman's own shape names the service socket.
+			const socketPath = endpoint?.local === true && typeof endpoint.endpoint === "string" && endpoint.endpoint.startsWith("unix://")
+				? endpoint.endpoint
+				: daemon?.answered ? daemon.facts.remoteSocketPath : null;
+			const socket = socketFacts(socketPath, { stat });
+			const decision = decideJobUser({ platform, release, euid, egid, endpoint, daemon, socket });
+			const value = { decision, facts: daemon?.answered ? daemon.facts : null, daemon, socket };
+			// Cached only for an ANSWERED read: an `image` decided on a VM-backed platform while its daemon was still starting
+			// must not pin "not read" for the runtime observations until the endpoint changes.
+			if (decision.mode !== "unknown" && decision.cause !== "runtime-unreadable" && daemon?.answered === true) cached = { key, value };
+			return value;
+		})();
+		inFlight.set(key, work);
+		try {
+			return await work;
+		} finally {
+			inFlight.delete(key);
+		}
+	}
+}