@edgehero/pi-dispatch 1.10.2 → 2.0.0

package/src/daemon-facts.mjs

@@ -0,0 +1,167 @@
+/**
+ * daemon-facts.mjs -- what a container runtime's own `info` says, parsed (issue #452, gate round 3).
+ *
+ * A LEAF, importing nothing of this project's, and that is its reason to exist: the parsers the local venue decides its
+ * job user with (`parseDaemonFacts`) and the podman venue decides its observations with (`parsePodmanInfo`) are also
+ * what the network detach gate (`netns-keeper.mjs`) reads the runtime with, and that gate is used by `egress.mjs`, which
+ * `job-user.mjs` and `backend-podman.mjs` sit above. Moved here unchanged and re-exported from both, so every existing
+ * importer and test is untouched and there is still ONE copy of each rule.
+ */
+
+/**
+ * The one daemon read. `{{json .}}` rather than a narrow template, deliberately and against `DOCKER_ENDPOINT_ARGS`'
+ * rule, for a measured reason: a template field one runtime lacks is a TEMPLATE ERROR on the client, exactly what "no
+ * daemon" and Podman's docker emulation also produce, while a missing key in a parsed body is just `null`. The body
+ * carries proxy settings and storage paths, so it is parsed here, reduced to the facts below, and never logged or
+ * returned.
+ */
+export const DAEMON_FACTS_ARGS = Object.freeze(["info", "--format={{json .}}"]);
+export const DAEMON_FACTS_MAX_BUFFER = 256 * 1024;
+// Longer than the endpoint read's 5 s: `docker info` counts containers and images, and on a busy host it is the slow
+// one. A per-job `unknown` retries the job, so a bound the host routinely misses would retry every job forever. Boot
+// is bounded separately (`settleWithin`), and a read still in flight there is joined by the first job.
+export const DAEMON_FACTS_TIMEOUT_MS = 15_000;
+
+// Podman's compat API has hard-coded this since v2 (pkg/api/handlers/compat/info.go); Docker CE packages say
+// "Community Engine" and Docker Desktop omits the key (measured). Used only to withhold credit, never to grant it.
+export const PODMAN_PRODUCT_LICENSE = "Apache-2.0";
+
+/**
+ * What a `docker info --format={{json .}}` answer says: `{ facts }`, `{ unreachable: true }`, or `null` when no line
+ * parses to either shape.
+ *
+ * NO DAEMON IS NOT A SHAPE. When the CLI's `/info` request fails, the docker CLI still exits 0 under `--format` and
+ * prints a Docker-shaped body with every server field empty and the error in `ServerErrors` (measured on 27.5.1
+ * against a missing socket). From 28.1 a CONNECTION failure exits non-zero instead, which the reader already treats
+ * as transient, but any other `/info` failure (an authorization plugin, an API version mismatch) still exits 0 with
+ * `ServerErrors` on every version (source). Read as facts, that body has no rootless marker and decides `worker`, so it is
+ * recognised FIRST: a non-empty `ServerErrors` is `unreachable` (the error text is never read), and a Docker-shaped
+ * body with no `ServerVersion` is no shape at all. A daemon that answers `/info` always sets `ServerVersion`
+ * (Docker and Podman's compat handler, source).
+ *
+ * TWO SHAPES, both measured. The real docker CLI against any daemon (Docker, or Podman's compat socket) prints the
+ * Docker shape. Podman's docker emulation (podman-docker) prints Podman's own (`host.security.rootless`,
+ * `host.serviceIsRemote`, `host.remoteSocket.path`), and that is the only facts source on that route, because it
+ * resolves no docker context.
+ *
+ * `bounds` is `null` whenever the daemon is Podman: its compat `PidsLimit` is hard-coded true and `MemoryLimit`
+ * follows the root cgroup's controllers, not whether a container's bounds apply (source; measured on a rootless host
+ * reporting both true while applying neither). CPU is never read: rootful Podman reports `CpuCfsQuota: false` while
+ * applying `--cpus` (measured).
+ */
+export function parseDaemonFacts(output) {
+	const lines = String(output ?? "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+	for (let i = lines.length - 1; i >= 0; i--) {
+		let body;
+		try {
+			body = JSON.parse(lines[i]);
+		} catch {
+			continue;
+		}
+		if (!body || typeof body !== "object" || Array.isArray(body)) continue;
+		if (Array.isArray(body.ServerErrors) && body.ServerErrors.length > 0) return { unreachable: true };
+		if (body.host && typeof body.host === "object") {
+			const rootless = body.host.security?.rootless;
+			const selinux = body.host.security?.selinuxEnabled;
+			const path = body.host.remoteSocket?.path;
+			return { facts: {
+				shape: "podman",
+				podman: true,
+				os: typeof body.host.os === "string" ? body.host.os : null,
+				rootless: typeof rootless === "boolean" ? rootless : null,
+				// Issue #355. Podman's own shape says it outright, so a missing or odd value is no fact rather than `false`.
+				selinux: typeof selinux === "boolean" ? selinux : null,
+				userns: false,
+				bounds: null,
+				serviceIsRemote: typeof body.host.serviceIsRemote === "boolean" ? body.host.serviceIsRemote : null,
+				// Only a unix path is kept, because only a unix path is ever statted. Podman fills this from the SERVICE's own
+				// listener (source): `unix://...` or `tcp://...` for a running service, the bare default path in-process.
+				remoteSocketPath: isUnixSocketPath(path) ? path : null,
+				serverVersion: displayVersion(body.version?.Version),
+			} };
+		}
+		if (typeof body.ServerVersion === "string" && body.ServerVersion !== "" && (typeof body.OperatingSystem === "string" || Array.isArray(body.SecurityOptions))) {
+			const options = Array.isArray(body.SecurityOptions) ? body.SecurityOptions.filter((o) => typeof o === "string") : [];
+			const named = (name) => options.some((o) => o.split(",").includes(`name=${name}`));
+			const podman = body.ProductLicense === PODMAN_PRODUCT_LICENSE;
+			return { facts: {
+				shape: "docker",
+				podman,
+				os: typeof body.OperatingSystem === "string" ? body.OperatingSystem : null,
+				rootless: named("rootless"),
+				// Issue #355, measured through rootful Podman 5.8.1's compat API on an enforcing Fedora 44 host:
+				// `["name=seccomp,profile=default","name=selinux"]`. Docker Engine with `selinux-enabled` says the same word,
+				// and that route is out of scope, so this fact alone decides nothing (`relabelsPrivateMounts`).
+				selinux: named("selinux"),
+				userns: named("userns"),
+				bounds: podman ? null : { pids: body.PidsLimit === true, memory: body.MemoryLimit === true },
+				serviceIsRemote: null,
+				remoteSocketPath: null,
+				serverVersion: displayVersion(body.ServerVersion),
+			} };
+		}
+	}
+	return null;
+}
+
+/**
+ * A version string fit for doctor's display line (issue #345), or `null`. Display only, never a decision: validated to a
+ * short run of version characters so a daemon's answer cannot put anything else on an operator's terminal. Exported for
+ * the podman venue's `podman info` read (issue #354), so the two runtimes' versions pass one filter.
+ */
+export function displayVersion(value) {
+	return typeof value === "string" && /^[0-9A-Za-z.+~_-]{1,40}$/.test(value) ? value : null;
+}
+
+function isUnixSocketPath(path) {
+	return typeof path === "string" && (path.startsWith("/") || path.startsWith("unix:///"));
+}
+
+
+/** The one facts read. JSON, not a template: a template field one Podman lacks is an error, a missing key is `null`. */
+export const PODMAN_INFO_ARGS = Object.freeze(["info", "--format", "json"]);
+
+/**
+ * What `podman info --format json` says, reduced to the facts this venue reads, or `null` when the output is not a JSON
+ * object with a `host` object. Every field is `null` when absent or of the wrong type, never a guess: a missing
+ * `rootless` must not read as rootless, nor a missing `serviceIsRemote` as local. Nothing else of the body (proxy
+ * settings, store paths) survives this function, so nothing else can be logged.
+ */
+export function parsePodmanInfo(stdout) {
+	let body;
+	try {
+		body = JSON.parse(String(stdout ?? "").trim());
+	} catch {
+		return null;
+	}
+	if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+	const host = body.host;
+	if (!host || typeof host !== "object" || Array.isArray(host)) return null;
+	const bool = (value) => (typeof value === "boolean" ? value : null);
+	const controllers = Array.isArray(host.cgroupControllers) ? host.cgroupControllers.filter((c) => typeof c === "string" && /^[a-z][a-z0-9_]{0,31}$/.test(c)) : null;
+	return {
+		rootless: bool(host.security?.rootless),
+		serviceIsRemote: bool(host.serviceIsRemote),
+		selinux: bool(host.security?.selinuxEnabled),
+		// "v2" or "v1"; anything else is no fact rather than a string an operator's terminal is handed.
+		cgroupVersion: typeof host.cgroupVersion === "string" && /^v[0-9]{1,2}$/.test(host.cgroupVersion) ? host.cgroupVersion : null,
+		// Issue #453: the cgroup manager Podman actually uses for this call. `cgroupfs` when it was configured so, and when a
+		// configured `systemd` could not reach the account's user manager over D-Bus (Podman then warns and falls back).
+		// A short lower-case word, else no fact.
+		cgroupManager: typeof host.cgroupManager === "string" && /^[a-z][a-z0-9_-]{0,31}$/.test(host.cgroupManager) ? host.cgroupManager : null,
+		// The controllers of the CALLING process's own cgroup, as `podman info` reports them. Kept for what it is and for
+		// nothing else: issue #453 measured it listing all five where no bound was applied, so no observation reads it.
+		controllers,
+		version: displayVersion(body.version?.Version),
+		// Issue #429: the container STORE this account's Podman uses (`store.graphRoot`), which moves with HOME,
+		// XDG_DATA_HOME or a storage.conf. Rootless `podman ps -a` over another store answers exit 0 with an EMPTY list
+		// (measured, Podman 5.8.1), so a sandbox opened with another store is invisible to the retention sweep; the
+		// sandbox and the sweep compare it with the one a run recorded. An absolute path with no control character, else
+		// no fact.
+		graphRoot: typeof body.store?.graphRoot === "string" && body.store.graphRoot.length <= 4096 && /^\/[^\u0000-\u001f\u007f]*$/.test(body.store.graphRoot) ? body.store.graphRoot : null,
+		// Issue #450: where Podman keeps its runtime state (`store.runRoot`, `/run/user/<uid>/containers` by default,
+		// measured on 5.8.1 and 4.9.3), under which Podman 5 records this account's rootless network helper. Parsed as
+		// graphRoot is: an absolute path with no control character, else no fact (and the live network check refuses).
+		runRoot: typeof body.store?.runRoot === "string" && body.store.runRoot.length <= 4096 && /^\/[^\u0000-\u001f\u007f]*$/.test(body.store.runRoot) ? body.store.runRoot : null,
+	};
+}

package/src/deployment-venue.mjs

@@ -0,0 +1,158 @@
+/**
+ * WHICH VENUE A DEPLOYMENT RUNS, decided one way for every command that asks (issue #453): `up` since #430, and `init`
+ * (its next steps) and `doctor` (what it judges) since #453, which read only their shell before and so answered for a
+ * different venue than the service they described. The deployment's `.env` is read with `readStackKeys`, exactly as
+ * `service install` reads it, and a key this shell sets differently stops the command, since the service runs the file.
+ */
+import { parseBackendList } from "./backends.mjs";
+import { egressArmed, egressProxyName } from "./egress.mjs";
+import { envValueShown } from "./env-file.mjs";
+import { STACK_KEYS, VALKEY_SHARED_KEY, readStackKeys, readValkeyKeys } from "./podman-stack.mjs";
+
+/** How each command says what a shell/file disagreement would make it do, the clause before "while the service ...". */
+const COMMAND_SAYS = Object.freeze({
+	up: "up would drive the shell's venue",
+	init: "init's next steps would be for the shell's venue",
+	doctor: "doctor would judge the shell's venue",
+});
+
+/**
+ * The venue keys this pass decides with (D2): this shell's value where it sets one, else the deployment `.env`'s, read
+ * with `readStackKeys` exactly as `service install` reads them. Returns `{ env, fromFile, disagreements }` or
+ * `{ error }`. `env` is the whole environment with the file's keys filled in; `fromFile` is only what the file
+ * supplied, for doctor's layering; `disagreements` names each key both set differently.
+ */
+export function deploymentVenueEnv({ env, fs, envPath, platform, command = "up", loader: loaderGiven = null, keys: keysWanted = STACK_KEYS }) {
+	let keys = {};
+	const notes = [];
+	// The loader of the file on THIS platform, as service.mjs reads it (round 2, E6): systemd's EnvironmentFile= on
+	// Linux, the sh wrapper on macOS, the cmd wrapper on Windows. Off Linux the venue refuses the host anyway, so a
+	// line that platform's loader reads differently is noted and never stops `up`.
+	const linux = platform === "linux";
+	// A caller with a mapping of its own passes it (doctor, so every `.env` read it makes uses one loader).
+	const loader = loaderGiven ?? (linux ? "systemd" : platform === "darwin" ? "shell" : "cmd");
+	if (fs.existsSync(envPath)) {
+		let text = null;
+		try {
+			// Bytes, not text: `readStackKeys` checks what systemd refuses to load before it decodes (issue #447).
+			text = fs.readFileSync(envPath);
+		} catch (err) {
+			// Said rather than silent (round 2 nit): the venue then comes from this shell alone.
+			notes.push(`${envPath} could not be read (${err?.message}), so PI_BACKENDS, PI_EGRESS and PI_EGRESS_PROXY come from this shell alone`);
+		}
+		if (text !== null) {
+			const read = readStackKeys(text, { loader, path: envPath });
+			if (read.error && linux) return { error: read.error };
+			if (read.error) notes.push(`${read.error}; off Linux the podman venue refuses this host anyway, so this pass reads the venue from this shell`);
+			else keys = read.keys;
+		}
+	}
+	const merged = { ...env };
+	const fromFile = {};
+	const conflicts = [];
+	// Only the keys the caller allows are taken from the file (doctor's `SERVICE_ENV_KEYS`); all of them by default.
+	for (const key of STACK_KEYS.filter((k) => keysWanted.includes(k))) {
+		if (!Object.hasOwn(keys, key)) continue;
+		if (typeof env[key] === "string") {
+			// Compared as the worker READS them (round 3, D4), not as strings: ` podman` and `podman,podman` are the list
+			// `podman`, and refusing them sent an operator to reconcile two values that already agree.
+			if (venueKeyMeaning(key, env[key]) !== venueKeyMeaning(key, keys[key])) conflicts.push(`${key} is ${quotedShown(env[key])} in this shell and ${quotedShown(keys[key])} in ${envPath}`);
+			continue;
+		}
+		merged[key] = keys[key];
+		fromFile[key] = keys[key];
+	}
+	// A KNOWN disagreement is a refusal (round 2, E5), not a warning: this pass would stand up one venue's stack and the
+	// service installed next would run the other. The file is what the service runs, so it is the one to change unless
+	// the shell's value was a one-off.
+	if (conflicts.length > 0) {
+		return { error: `${conflicts.join("; ")}. ${COMMAND_SAYS[command] ?? COMMAND_SAYS.up} while the service runs the file's. Make them agree: change ${envPath} (what the service reads), or unset the key in this shell` };
+	}
+	return { env: merged, fromFile, notes };
+}
+
+/**
+ * VALKEY_URL and PI_VALKEY_SHARED as `up` must judge them (issue #464): the deployment `.env`'s, read with the loader the
+ * service uses (`readValkeyKeys`), because the Valkey `up` adopts or refuses is the one the SERVICE's worker will use.
+ * For VALKEY_URL this shell's value is taken where the file sets none (what the wizard relies on before init has
+ * written `.env`), and both set differently is refused, as a venue key is (`deploymentVenueEnv`), since the service
+ * runs the file's. PI_VALKEY_SHARED comes from the file only, a shell value named as ignored (gate round 2); a
+ * `.env` line the loaders read differently is refused, naming what in it is the problem, on Linux (off it the podman
+ * venue refuses the host anyway, so it is a note). Returns `{ env: { VALKEY_URL?, PI_VALKEY_SHARED? }, fromFile, notes }`
+ * or `{ error }`.
+ */
+export function deploymentValkeyEnv({ env, fs, envPath, platform, command = "up" }) {
+	const linux = platform === "linux";
+	const loader = linux ? "systemd" : platform === "darwin" ? "shell" : "cmd";
+	const notes = [];
+	let keys = {};
+	if (fs.existsSync(envPath)) {
+		let text = null;
+		try {
+			// Bytes, not text (gate round 3): `readValkeyKeys` checks what systemd refuses to load before it decodes.
+			text = fs.readFileSync(envPath);
+		} catch (err) {
+			notes.push(`${envPath} could not be read (${err?.message}), so VALKEY_URL comes from this shell alone and PI_VALKEY_SHARED is unset`);
+		}
+		if (text !== null) {
+			const read = readValkeyKeys(text, { loader, path: envPath });
+			if (read.error && linux) return { error: `${read.error}. ${command} judges the Valkey the service will use, so it stops here` };
+			if (read.error) notes.push(read.error);
+			else keys = read.keys;
+		}
+	}
+	const merged = {};
+	const fromFile = {};
+	const conflicts = [];
+	{
+		const shell = typeof env.VALKEY_URL === "string" ? env.VALKEY_URL : undefined;
+		if (!Object.hasOwn(keys, "VALKEY_URL")) {
+			if (shell !== undefined) merged.VALKEY_URL = shell;
+		} else {
+			if (shell !== undefined && shell !== keys.VALKEY_URL) conflicts.push(`VALKEY_URL is ${quotedShown(shell)} in this shell and ${quotedShown(keys.VALKEY_URL)} in ${envPath}`);
+			merged.VALKEY_URL = keys.VALKEY_URL;
+			fromFile.VALKEY_URL = keys.VALKEY_URL;
+		}
+	}
+	// PI_VALKEY_SHARED from the file ONLY (gate round 2): it is the one statement that another uid's Valkey is this
+	// deployment's queue on purpose, and the worker, `service install` and doctor read it from `.env` alone, so a shell
+	// export that `up` honoured was an opt-in the service never made (measured: `up` exit 0 and a ✓ over a refused
+	// install). A shell value is ignored, and said.
+	if (Object.hasOwn(keys, VALKEY_SHARED_KEY)) {
+		merged[VALKEY_SHARED_KEY] = keys[VALKEY_SHARED_KEY];
+		fromFile[VALKEY_SHARED_KEY] = keys[VALKEY_SHARED_KEY];
+	}
+	if (typeof env[VALKEY_SHARED_KEY] === "string") notes.push(sharedShellIgnored(env[VALKEY_SHARED_KEY], envPath));
+	if (conflicts.length > 0) {
+		return { error: `${conflicts.join("; ")}. ${command} would judge the shell's Valkey while the service uses the file's. Make them agree: change ${envPath} (what the service reads), or unset the key in this shell` };
+	}
+	return { env: merged, fromFile, notes };
+}
+
+/** The sentence for a PI_VALKEY_SHARED this shell sets, which no command honours (issue #464, gate round 2). */
+export function sharedShellIgnored(value, envPath) {
+	return `${VALKEY_SHARED_KEY} is ${quotedShown(value)} in this shell: ignored, since only ${envPath} may say a Valkey is shared on purpose (the service's worker reads it there alone)`;
+}
+
+/**
+ * What a venue key MEANS to the worker, for comparing two spellings of it: the parsed list for PI_BACKENDS, on or off
+ * for PI_EGRESS, the resolved name for PI_EGRESS_PROXY exactly as egressProxyName resolves it (empty is the default
+ * name; NOT trimmed, because nothing that reads the name trims it, so " x" and "x" are different proxies to the worker
+ * and to podman). A value the worker would refuse keeps its raw spelling, so two different unreadable values still
+ * disagree and the doctor below names them.
+ */
+function venueKeyMeaning(key, value) {
+	try {
+		if (key === "PI_BACKENDS") return `list:${parseBackendList(value).join(",")}`;
+		if (key === "PI_EGRESS") return `egress:${egressArmed({ PI_EGRESS: value }) ? "on" : "off"}`;
+		return `proxy:${egressProxyName({ PI_EGRESS_PROXY: value })}`;
+	} catch {
+		return `raw:${value}`;
+	}
+}
+
+/** A value shown in quotes, so a leading space or an empty value is visible; control characters escaped as ever. */
+function quotedShown(value) {
+	const shown = envValueShown(value);
+	return shown.startsWith('"') ? shown : `"${shown}"`;
+}

package/src/docker-run.mjs

@@ -20,7 +20,8 @@
 // `buildDockerRunArgs`, which never moved; the entry that names `containerSpec` is design.md's 2026-08-31
 // row, and this move is recorded in its own row rather than by leaving that pointer to rot.
 export { containerSpec, CONTAINER_GLOBAL_PI_DIR, CONTAINER_SESSION_DIR, CONTAINER_SESSION_FILE } from "./container-spec.mjs";
-import { containerSpec } from "./container-spec.mjs";
+import { isAbsolute, relative } from "node:path";
+import { assertCidFile, assertJobUser, containerSpec } from "./container-spec.mjs";
 
 /** The fixed isolation flags. Not configurable -- these ARE the boundary. */
 export const ISOLATION_FLAGS = [
@@ -43,8 +44,8 @@ export const ISOLATION_FLAGS = [
 ];
 
 /**
- * HOW Docker spells it. The only consumer of a spec today, and the local backend's translation step:
- * a second backend implements this function's job against its own runtime and shares everything above it.
+ * HOW Docker spells it, and the local backend's translation step. Since issue #354 `podmanArgsFromSpec` below is the
+ * second, and it shares this function's body rather than copying it.
  */
 /**
  * Flags a `dockerExtra` may not carry, because docker resolves a repeated option LAST-WINS and this array
@@ -56,9 +57,9 @@ export const ISOLATION_FLAGS = [
  * The list covers every member of `ISOLATION_FLAGS`, the container name, and the near-synonyms that reach
  * the same effect without repeating a listed flag (`--volumes-from` for a mount, `--memory-swap` for the
  * memory bound). It is a DENY-list and therefore only as good as its coverage: docker's surface is large
- * and a release can add another way in. So it NARROWS the gap rather than closing it, and the backend
- * table's `isolation` and `ephemeral` words rest on this plus the single production caller passing fixed
- * literals, never on this alone.
+ * and a release can add another way in. So it NARROWS the gap rather than closing it; since issue #341 the
+ * allow-list below closes it, and the backend table's `isolation` and `ephemeral` words rest on both plus the
+ * callers passing fixed literals.
  *
  * Without this the two standing assertions that "every member of ISOLATION_FLAGS reaches the argv" would
  * still pass on an argv with no boundary left, because membership is not effectiveness. Nothing passes any
@@ -66,13 +67,22 @@ export const ISOLATION_FLAGS = [
  * which stay allowed -- so this closes a hole rather than changing a behaviour, and it makes "the builder
  * CANNOT DECLINE the boundary" true of the whole argv instead of of one boolean field.
  *
- * `--user` is DELIBERATELY NOT HERE, and it is the one that looks like it belongs. It is a documented,
- * tested feature -- the Linux-only `uid:gid` on a bind-mounted local folder, so files the agent writes into
- * an operator's own directory come back owned by the operator rather than by root. It also does not touch
- * this boundary: it changes which uid runs, not what that uid may do, and `--cap-drop=ALL` plus
- * `no-new-privileges` hold either way. What it does bear on is `nonRoot`, which the backend table already
- * declares `asserted` for the separate reason that the image's `USER pi` is what provides it. Denying it
- * here would break local-folder jobs to make a word honest that is already honest.
+ * `--user` and `-u` ARE here (issue #341), because the builder owns the job user now: `containerSpec`'s `user` field,
+ * validated non-root and emitted before `dockerExtra`. A second `--user` in `dockerExtra` would win last and could
+ * name uid 0, which is `nonRoot` gone. An earlier version of this comment called `--user` "a documented, tested
+ * feature" and left it allowed; nothing documented it and nothing passed it, which is how every job on a native
+ * Linux daemon whose worker uid is not 1001 came to run as a uid that cannot read its own inputs.
+ *
+ * ONE SHORT FLAG PER TOKEN, and that is a separate rule below the list: docker parses `-u0` as `-u 0`, `-iu0` as
+ * `-i -u 0`, `-v/:/h` as a mount and `-m1g` as a memory bound, and a list compared on the text before `=` sees none
+ * of those. A single-dash token longer than two characters is refused outright; every caller passes separate tokens.
+ *
+ * AND AN ALLOW-LIST CLOSES WHAT THE DENY-LIST ONLY NARROWED (issue #341, found by an adversarial pass): a bare
+ * positional token or `--` becomes the IMAGE, with every `-e` and `-v` after it passed to that image as arguments;
+ * `--annotation run.oci.keep_original_groups=1` keeps the worker's groups on Podman; `--uidmap`/`--gidmap` remap
+ * the user on podman-docker; `--use-api-socket` mounts the daemon socket on a recent CLI. None was listed, and the
+ * next release adds another. So after the refusals above, a token must be one of what the callers actually pass,
+ * `DOCKER_EXTRA_ALLOWED`, or it is refused. The deny-list stays for its named reasons and its tests.
  */
 export const DOCKER_EXTRA_FORBIDDEN = [
 	// Each of the seven logical flags in ISOLATION_FLAGS, and the argv member beside them that the worker's
@@ -85,6 +95,9 @@ export const DOCKER_EXTRA_FORBIDDEN = [
 	// last and leaves a container no sweep finds and no timeout can stop. `ephemeral` and `abortable` both
 	// rest on it.
 	"--name",
+	// Issue #345: the run's cidfile is how a container that outlived its `docker run` is found; a second `--cidfile`
+	// would win last and write the ID where the worker does not look.
+	"--cidfile",
 	"--privileged",
 	"--cap-add",
 	"--security-opt",
@@ -118,9 +131,74 @@ export const DOCKER_EXTRA_FORBIDDEN = [
 	"--uts",
 	"--userns",
 	"--cgroupns",
+	// The job user is a spec field (issue #341). Here so a repeat cannot override it with uid 0.
+	"--user",
+	"-u",
 ];
 
+/**
+ * Everything a `dockerExtra` may say. Bare flags stand alone; a valued flag takes the NEXT token, and that token must
+ * match its pattern: an entrypoint is a command name, never a flag, and a published port is bound to loopback
+ * (`parsePublish` never builds anything else). The sandbox passes `-i -t --entrypoint bash -p 127.0.0.1:<h>:<c>`;
+ * the live probes pass `-d --entrypoint sleep` and `-d`.
+ */
+export const DOCKER_EXTRA_ALLOWED = Object.freeze({
+	bare: Object.freeze(["-i", "-t", "-d"]),
+	valued: Object.freeze({ "--entrypoint": /^[A-Za-z0-9_][A-Za-z0-9_./-]*$/, "-p": /^127\.0\.0\.1:\d{1,5}:\d{1,5}$/ }),
+});
+
 export function dockerArgsFromSpec(spec) {
+	// Issue #354. REFUSED, never dropped: the docker CLI rejects `--userns=keep-id` client-side (exit 125, measured in
+	// issue #345), and silently omitting it would run the job under the daemon's own mapping, where the "<uid>:<gid>"
+	// the caller chose for bind-mount ownership names a different host identity. `undefined` is a hand-built spec that
+	// predates the field, which asked for nothing.
+	if (spec?.userns !== null && spec?.userns !== undefined) {
+		throw new Error(`docker run: refusing a spec with userns ${JSON.stringify(spec.userns)}: the docker CLI has no --userns=keep-id, and only a podman venue builds one`);
+	}
+	return argsFromSpec(spec, { userns: null });
+}
+
+/**
+ * HOW rootless Podman spells the same box (issue #354): `dockerArgsFromSpec`'s argv with `--userns=keep-id` immediately
+ * after `--user=`, from ONE private builder, so the boundary flags, the `dockerExtra` allow-list and the mount rendering
+ * cannot drift between the two runtimes. Podman accepts every other token here as docker does (`--pull=never`,
+ * `--cidfile`, `-v host:ctr:ro,Z`: measured on 5.8.1).
+ *
+ * `keep-id` is REQUIRED, and so is a user. Without keep-id a rootless container's uid N is the host's subordinate uid, so
+ * a job run as the worker's uid cannot read `/job`. With keep-id and NO `--user`, the container runs as the IMAGE's user
+ * with the worker's gid only as a supplementary group, and `/job` is unreadable again (both measured on Fedora 44,
+ * Podman 5.8.1). Either argv would start, spend its slot and fail inside the container, so both are refused here.
+ */
+export function podmanArgsFromSpec(spec) {
+	if (spec?.userns !== "keep-id") {
+		throw new Error(`podman run: refusing a spec whose userns is not "keep-id": ${JSON.stringify(spec?.userns ?? null)} (a rootless job without it cannot read its own mounts)`);
+	}
+	if (spec.user === null || spec.user === undefined) {
+		throw new Error("podman run: refusing a keep-id spec with no job user: the image's own user would run with /job unreadable");
+	}
+	return argsFromSpec(spec, { userns: "keep-id" });
+}
+
+/**
+ * The namespaces and inheritances a rootless Podman argv pins, because the account's own containers.conf can set every
+ * container's defaults for them: `pidns` (PID), `ipcns` (IPC), `utsns` (UTS), `cgroupns` (cgroup), `env_host` and `http_proxy`. (dockerd's
+ * daemon.json can default the cgroup and IPC modes too, and the docker argv pins neither: a gap older than this venue.) Measured on Podman 5.8.1 with a user containers.conf of `pidns = "host"` and `env_host = true`: an
+ * unpinned job ran outside its own PID namespace and received the worker's environment (the provider key with it);
+ * with these flags it got its own namespaces and nothing. `http_proxy` is on by default, which copies the worker's proxy
+ * variables into every job. A job's network is pinned the same way where it has none of its own (`--network=private`,
+ * Podman's word for the rootless default), or `netns = "host"` would put it on the host's. What cannot be pinned is
+ * that network's OPTIONS: containers.conf `pasta_options` come before the command line's in pasta's argv, and a conf
+ * `-T <port>` survives even `--network=pasta:--map-host-loopback,none` (measured), so no flag here could close it. It is
+ * REFUSED instead, not left open: the venue refuses to run while the account's containers.conf sets `pasta_options`, `network_cmd_options`, `annotations`, `env`, `helper_binaries_dir`, `network_cmd_path`, `default_sysctls`, `default_ulimits`, `seccomp_profile`, `init_path`, `dns_servers`, `dns_options`, `dns_searches`, `base_hosts_file`, `oom_score_adj`, `privileged`, `label`, `cgroup_conf`, `host_containers_internal_ip`, `runtimes`, `conmon_path`, `cgroups` or `umask` at all, the list
+ * `PODMAN_WIDENING_KEYS` in backends.mjs (`podmanConfWidening` in backend-podman.mjs, issues #428 and #450).
+ */
+export const PODMAN_PINNED_FLAGS = Object.freeze(["--pid=private", "--ipc=private", "--uts=private", "--cgroupns=private", "--env-host=false", "--http-proxy=false"]);
+
+/**
+ * The shared body of both builders. `userns` is the caller's, never the spec's: each public builder has already decided
+ * what its runtime may say, and reading the spec here would let a docker argv carry a flag its CLI refuses.
+ */
+function argsFromSpec(spec, { userns }) {
 	// The builder CANNOT DECLINE the boundary. `containerSpec` cannot produce anything but `true`, so this
 	// only ever fires on a hand-built spec -- and a hand-built spec that forgot the field is exactly the
 	// case that must fail loudly rather than quietly emit a container with no isolation flags at all.
@@ -129,7 +207,9 @@ export function dockerArgsFromSpec(spec) {
 	// Same refusal, one level down. `dockerExtra` is raw Docker flags by design, and it lands after the
 	// boundary where a repeat supersedes it -- so the escape hatch is bounded by what it may not say.
 	// Split on `=` so `--network=foo` is caught alongside `--network foo`.
-	for (const flag of spec.dockerExtra ?? []) {
+	const extra = spec.dockerExtra ?? [];
+	for (let i = 0; i < extra.length; i++) {
+		const flag = extra[i];
 		// REFUSED, not skipped. Skipping a non-string still PUSHED it into the argv below, so
 		// `new String("--privileged")` and `{ toString: () => "--privileged" }` walked past the check and
 		// then reached docker as the flag they stringify to.
@@ -139,7 +219,21 @@ export function dockerArgsFromSpec(spec) {
 		if (DOCKER_EXTRA_FORBIDDEN.includes(flag.split("=", 1)[0])) {
 			throw new Error(`docker run: refusing a dockerExtra flag that would supersede the isolation boundary: ${flag}`);
 		}
+		// Fused short flags (see the list's header). After the list check, so a listed flag keeps its own refusal.
+		if (/^-[^-]/.test(flag) && flag.length > 2) {
+			throw new Error(`docker run: refusing a dockerExtra flag that would supersede the isolation boundary: ${flag} (one short flag per token)`);
+		}
+		if (DOCKER_EXTRA_ALLOWED.bare.includes(flag)) continue;
+		const valuePattern = Object.hasOwn(DOCKER_EXTRA_ALLOWED.valued, flag) ? DOCKER_EXTRA_ALLOWED.valued[flag] : null;
+		if (valuePattern && typeof extra[i + 1] === "string" && valuePattern.test(extra[i + 1])) {
+			i++;
+			continue;
+		}
+		throw new Error(`docker run: refusing a dockerExtra token outside what the builder's callers pass (-i, -t, -d, --entrypoint <command>, -p 127.0.0.1:<host>:<container>): ${JSON.stringify(flag)}`);
 	}
+	// Re-checked here for a hand-built spec, the same reason `isolated` is.
+	assertJobUser(spec.user);
+	assertCidFile(spec.cidFile);
 
 	// `--network` sits HERE, beside --memory and --cpus, and deliberately NOT inside ISOLATION_FLAGS.
 	// That array is the LITERAL, value-free, unconditional set, and two separate places assert every member
@@ -153,6 +247,14 @@ export function dockerArgsFromSpec(spec) {
 	// before this feature existed. Same shape as the sessionDir/outboxDir/globalPiDir mounts below.
 	const args = ["run", `--name=${spec.name}`, ...ISOLATION_FLAGS, `--memory=${spec.memory}`, `--cpus=${spec.cpus}`];
 	if (spec.network) args.push(`--network=${spec.network}`);
+	else if (userns) args.push("--network=private");
+	// null => ABSENT, so a job the image's own USER runs has an argv byte-identical to one built before issue #341.
+	if (spec.user) args.push(`--user=${spec.user}`);
+	// Issue #354: IMMEDIATELY after `--user=`, which it qualifies, and before `dockerExtra`, where `--userns` is refused.
+	if (userns) args.push(`--userns=${userns}`, ...PODMAN_PINNED_FLAGS);
+	// null => ABSENT, so every argv but a job's is byte-identical to one built before issue #345. BEFORE `dockerExtra`, and
+	// `--cidfile` is refused there, so no later token can move where the ID lands and turn the detached check off.
+	if (spec.cidFile) args.push(`--cidfile=${spec.cidFile}`);
 	args.push(...(spec.dockerExtra ?? []));
 
 	// Explicit env allowlist. Each entry is `-e NAME=VALUE`, built from the closed map -- so a
@@ -166,7 +268,16 @@ export function dockerArgsFromSpec(spec) {
 	// `-v` and its value stay TWO argv elements rather than one `--volume=` token. Not cosmetic: the mount
 	// assertions across this suite extract mounts by adjacency (`args[i - 1] === "-v"`), so collapsing the
 	// pair would make those filters return nothing and turn several exact-array checks vacuously green.
-	for (const m of spec.mounts ?? []) args.push("-v", `${m.host}:${m.container}${m.readOnly ? ":ro" : ""}`);
+	//
+	// The option list after the container path is `ro`, `Z`, or `ro,Z` (issue #355): one list, comma-joined, which is
+	// how both the docker CLI and Podman read it. `Z` only for a mount the spec marks `relabel: "private"`, so a spec
+	// without that field renders exactly the strings it always did. Anything else in that field is refused rather than
+	// dropped, because a mount that silently lost its label fails in the container with nothing pointing back here.
+	for (const m of spec.mounts ?? []) {
+		if (m.relabel !== undefined && m.relabel !== "private") throw new Error(`docker run: refusing a mount relabel other than "private": ${JSON.stringify(m.relabel)}`);
+		const options = [...(m.readOnly ? ["ro"] : []), ...(m.relabel === "private" ? ["Z"] : [])];
+		args.push("-v", `${m.host}:${m.container}${options.length > 0 ? `:${options.join(",")}` : ""}`);
+	}
 
 	args.push(spec.image);
 	return args;
@@ -182,3 +293,23 @@ export function dockerArgsFromSpec(spec) {
 export function buildDockerRunArgs(opts) {
 	return dockerArgsFromSpec(containerSpec(opts));
 }
+
+/**
+ * The `podman run` argv (excluding the leading "podman"), issue #354. `userns` is not the caller's to choose: a podman
+ * job runs keep-id or not at all (see `podmanArgsFromSpec`), so an opts bag carrying another value is overridden rather
+ * than read. A null `user` is refused by the builder, before anything spawns.
+ */
+export function buildPodmanRunArgs(opts) {
+	return podmanArgsFromSpec(containerSpec({ ...opts, userns: "keep-id" }));
+}
+
+/**
+ * Whether `inner` is strictly inside `outer` (issue #355). The one containment rule that decides a workspace is the
+ * worker's own and may carry a private SELinux label: the job path (run-container) and a reopened sandbox both ask it, here beside the builder that renders the label,
+ * and it fails CLOSED, on an empty or non-string path, on `outer` itself and on anything that climbs out of it.
+ */
+export function insideDir(outer, inner) {
+	if (typeof outer !== "string" || typeof inner !== "string" || outer === "" || inner === "") return false;
+	const rel = relative(outer, inner);
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}