@edgehero/pi-dispatch 1.10.3 → 2.1.0

package/src/service.mjs

@@ -41,11 +41,19 @@
  * the rest of the config is broken.
  */
 import { spawn as nodeSpawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir, userInfo } from "node:os";
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { connect as netConnect } from "node:net";
+import { homedir, networkInterfaces, tmpdir, userInfo } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+import { parseBackendList, venuesOf } from "./backends.mjs";
+import { sharedShellIgnored } from "./deployment-venue.mjs";
+import { egressArmed, egressProxyName } from "./egress.mjs";
+import { updateEnvFile } from "./env-file.mjs";
+import { VALKEY_HEALTH_SCRIPT, VALKEY_PASSWORD_KEY, VALKEY_START_SCRIPT, dollarsDoubled, newValkeyPassword, valkeyPasswordDecision } from "./valkey-auth.mjs";
+import { ALL_QUADLET_FILES, ALLOWLIST_PLACEHOLDER, NETNS_KEEPER, NETNS_KEEPER_FORMAT, judgeNetnsKeeper, keeperUnderRunningProxyHint, managerEnvRefusal, PROXY_CONF_PLACEHOLDER, QUADLET_FILES, applyStack, decideValkey, describeAction, passwdNameFrom, readSubuidRanges, readValkeyKeys, valkeySharedOn, VALKEY_SHARED_KEY, describeRollBack, journalWrite, rollBackWrites, foreignContainerRefusal, foreignContainers, lingerNote, planStack, proxyConfCopyPath, proxyRestartWarning, quadletDir, readLinger, readStackKeys, stackComponents, unknownContainerRefusal, userBusRefusal, valkeyEnvPath, valkeyPasswordRestartWarning, workerUnitDeps } from "./podman-stack.mjs";
 
 // src/ is where this module lives in BOTH layouts (worker/src in a checkout,
 // node_modules/@edgehero/pi-dispatch/src under npm). Deploy templates resolve one level up from it
@@ -74,6 +82,10 @@ function resolveReceiverStart() {
  * worker/test/service.test.mjs asserts each one is still present in the real deploy/ file, so an edit
  * to a template that would break the render fails the build instead of shipping a broken `service`.
  */
+// The two worker-template literals a podman render rewrites (issue #430), spelled once for the pin table and the render.
+const WORKER_DESCRIPTION = "Description=pi-dispatch worker (drains the job queue on the host; launches job containers via docker)";
+const WORKER_VALKEY_COMMENT = "# Valkey must be reachable (on this host, `pi-dispatch up` in the deployment folder starts it), but it is a separate\n# unit/container -- not ordered here since it may be remote.\n";
+
 export const TEMPLATE_PINS = {
 	"worker.service": [
 		"ExecStart=/usr/bin/node worker/src/cli.mjs worker", // the WHOLE line → `<execPath> <cliPath> worker` (cli.mjs sits beside this module in src/ in both layouts)
@@ -81,6 +93,9 @@ export const TEMPLATE_PINS = {
 		"EnvironmentFile=/opt/pi-dispatch/.env", // → <deployDir>/.env — the operator's .env lives beside the units, never inside the package
 		"\nUser=pi\n", // the DIRECTIVE line (the header comment also says User=pi mid-line, hence the \n anchors): stripped for --user scope; rewritten to the invoking user for --system
 		"WantedBy=multi-user.target", // → default.target in user scope (multi-user.target never runs there)
+		"\nWants=network-online.target\n", // the anchor the podman venue's Wants=/After= on its Quadlet units go after (issue #430), user scope only
+		"Description=pi-dispatch worker (drains the job queue on the host; launches job containers via docker)", // → names rootless podman on a podman deployment (issue #430)
+		"# Valkey must be reachable (on this host, `pi-dispatch up` in the deployment folder starts it), but it is a separate\n# unit/container -- not ordered here since it may be remote.\n", // → says it IS ordered, when the Quadlet Valkey is installed
 		// Byte-for-byte survivors — semantics the render must not lose:
 		"RestartPreventExitStatus=2", // EXIT_POLICY is never restarted (a retry loop is a bill)
 		"StartLimitIntervalSec=60",
@@ -132,6 +147,52 @@ export const TEMPLATE_PINS = {
 	// a unit that starts fine and ignores the operator's secrets manager.
 	"worker-env-wrapper.sh": ["PI_ENV_SETUP"],
 	"worker-env-wrapper.cmd": ["PI_ENV_SETUP"],
+	// The podman venue's stack as Quadlet units (issue #430, podman-stack.mjs). Three are copied verbatim, so what is
+	// pinned is what the worker and the installer rely on by NAME: the container and network names the worker attaches
+	// by, the unit names the worker unit Wants=, the loopback-only port, and an explicit Network= in every .container
+	// (a containers.conf `netns = "host"` would otherwise put it in the host namespace, measured).
+	"pi-dispatch-valkey.network": ["NetworkName=pi-dispatch-valkey"],
+	"pi-dispatch-valkey.container": [
+		"ContainerName=pi-dispatch-valkey",
+		"Network=pi-dispatch-valkey.network",
+		"PublishPort=127.0.0.1:6379:6379",
+		"Volume=pi-dispatch-valkey-data:/data",
+		// Issue #468: the password from a 0600 file into the container's environment, then to valkey-server as
+		// configuration on stdin, never on an argv (tini keeps its argv as PID 1, readable by every account). The two lines
+		// are pinned to the ONE copy of each script in valkey-auth.mjs, `$` written `$$` for systemd.
+		"EnvironmentFile=%h/.config/pi-dispatch/valkey.env",
+		`Exec=sh -c '${dollarsDoubled(VALKEY_START_SCRIPT)}'`,
+		`HealthCmd=${dollarsDoubled(VALKEY_HEALTH_SCRIPT)}`,
+		"WantedBy=default.target",
+	],
+	"pi-dispatch-egress-out.network": ["NetworkName=pi-dispatch-egress-out"],
+	"pi-dispatch-egress-proxy.container": [
+		`Volume=${PROXY_CONF_PLACEHOLDER}:/etc/squid/squid.conf:ro,z`, // → the account-owned COPY of the package's egress-proxy.conf (~/.config/pi-dispatch/egress-proxy.conf, podman-stack.mjs proxyConfCopyPath), because `z` cannot relabel a root-owned package file (measured)
+		`Volume=${ALLOWLIST_PLACEHOLDER}:/etc/pi-dispatch/allowlist.conf:ro,z`, // → <deployDir>/egress-allowlist.conf, the list `init` scaffolds
+		"ContainerName=pi-dispatch-egress-proxy",
+		"Network=pi-dispatch-egress-out.network",
+		"WantedBy=default.target",
+	],
+	// The rootless network keeper (issue #458), copied verbatim. Pinned: the names (outside every sweep's prefix, and
+	// what doctor reads), its own network with no route and no DNS, and every line that keeps it from widening anything
+	// (podman-stack.test.mjs reads the same lines back as the argv they generate).
+	"pi-dispatch-netns-keeper.network": ["NetworkName=pi-dispatch-netns-keeper", "Internal=true", "DisableDNS=true"],
+	"pi-dispatch-netns-keeper.container": [
+		"ContainerName=pi-dispatch-netns-keeper",
+		"Network=pi-dispatch-netns-keeper.network",
+		"ReadOnly=true",
+		"DropCapability=all",
+		"NoNewPrivileges=true",
+		"User=65534",
+		"Group=65534",
+		"RunInit=true",
+		"ExecStartPre=/usr/bin/podman network create --ignore --disable-dns --internal pi-dispatch-netns-keeper",
+		"Restart=always",
+		"RestartSec=1s",
+		"StartLimitIntervalSec=0",
+		"SuccessExitStatus=143",
+		"WantedBy=default.target",
+	],
 };
 
 /**
@@ -231,6 +292,19 @@ export function readUnitSeam(text, platform) {
 	return { setup: clip(grab(readers.setup)), deployDir: clip(grab(readers.deployDir)) };
 }
 
+/**
+ * The account a SYSTEM unit runs the worker as (`User=`), or `null` when it names none (issue #341). Only systemd has
+ * one: a user-scope unit, a launchd agent and an nssm service run as whoever installed them. Separate from
+ * `readUnitSeam` because it is not part of the render round trip (a `--system` render writes the invoking user, a
+ * `--user` render strips the line). Read as systemd does: whitespace around `=` allowed, and the LAST assignment wins.
+ */
+export function readUnitUser(text, platform) {
+	if (platform !== "linux" || typeof text !== "string") return null;
+	const hits = [...text.replace(/\0/g, "").matchAll(/^[ \t]*User[ \t]*=[ \t]*(.*?)[ \t]*\r?$/gm)];
+	const value = hits.at(-1)?.[1];
+	return value ? value : null;
+}
+
 const SUBCOMMANDS = new Set(["render", "install", "uninstall", "status", "start", "stop", "restart"]);
 
 const SERVICE_USAGE = `pi-dispatch service — run the worker (or --receiver) as an OS service, rendered for THIS host
@@ -269,13 +343,26 @@ export async function runService(argv = [], deps = {}) {
 		// this command. An operator changes it by running the command as someone else, not by declaring it.
 		user = env.USER || userInfo().username,
 		tmp = tmpdir(),
-		fs = { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync },
+		fs = { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, chmodSync, statSync, renameSync, realpathSync },
 		spawn = nodeSpawn,
 		out = (s) => process.stdout.write(s),
 		err = (s) => process.stderr.write(s),
 		sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
 		now = () => Date.now(),
 		queue = null, // test seam; production builds one lazily in doRestart from VALKEY_URL
+		// Is anything on 127.0.0.1:6379? Asked only on a podman deployment, to decide whether the Quadlet Valkey is
+		// wanted (issue #430); the same plain TCP connect `up` uses, for up's reason. Issue #464: asked of every address
+		// VALKEY_URL's host resolves to (`lookup`, as the worker's client resolves it), and `interfaces` says which of
+		// them are this host's.
+		probeTcp = defaultProbeTcp,
+		lookup = (host, opts) => dnsLookup(host, opts),
+		interfaces = networkInterfaces,
+		// Issue #464 (gate round 2): how `getsubids` is run for this account's subordinate ranges (null: not installed).
+		runSync = undefined,
+		// PR #463: how a path resolves through symlinks, for the manager-environment rule (a symlinked home).
+		realpath = (p) => realpathSync(p),
+		// Issue #468: how a new Valkey password is made (a test's seam; 32 random bytes, hex, never shown).
+		newPassword = newValkeyPassword,
 	} = deps;
 
 	let values, positionals;
@@ -338,6 +425,12 @@ export async function runService(argv = [], deps = {}) {
 		sleep,
 		now,
 		queue,
+		probeTcp,
+		lookup,
+		interfaces,
+		runSync,
+		realpath,
+		newPassword,
 		which: values.receiver ? "receiver" : "worker",
 		scope: platform === "linux" && values.system ? "system" : "user",
 		force: values.force,
@@ -363,7 +456,7 @@ export async function runService(argv = [], deps = {}) {
 			return doRender(ctx);
 		case "install":
 			// --print is implied for render and opt-in here: see what will be written, then write it.
-			if (values.print) doRender(ctx);
+			if (values.print) await doRender(ctx);
 			return doInstall(ctx);
 		case "uninstall":
 			return doUninstall(ctx);
@@ -511,7 +604,7 @@ function composeEnvSetupExec(setup, argv) {
  * known literals (see TEMPLATE_PINS); everything else — RestartPreventExitStatus=2, the StartLimit
  * crash-loop bound, KillSignal, TimeoutStopSec — passes through byte-for-byte.
  */
-function renderLinuxUnit(ctx) {
+function renderLinuxUnit(ctx, stackUnits = [], venues = null) {
 	const template = ctx.which === "receiver" ? "receiver.service" : "worker.service";
 	// The ExecStart line is replaced WHOLE, not path-by-path: the template's script path is relative
 	// to a repo-root WorkingDirectory that only a checkout has. The rendered unit points at absolute
@@ -549,6 +642,19 @@ function renderLinuxUnit(ctx) {
 		// symlink into a .wants/ directory no user-instance boot ever walks — enabled but never
 		// started. default.target is the user manager's boot target.
 		unit = unit.replace("WantedBy=multi-user.target", "WantedBy=default.target");
+		// The podman venue's Quadlet units (issue #430), which live in this same user manager, so the worker can be
+		// ordered after them. Nothing is added when there are none, which keeps every other render byte-identical.
+		const deps = workerUnitDeps(stackUnits);
+		if (deps) unit = unit.replace("\nWants=network-online.target\n", () => `\nWants=network-online.target\n${deps}`);
+		// The template's own words, made true for a podman deployment (round 2 nit): its Description says jobs launch
+		// via docker, and its comment says Valkey is not ordered here. Both anchors are TEMPLATE_PINS.
+		if (venues?.podmanUsed) {
+			const runtime = venues.localUsed ? "docker and rootless podman" : "rootless podman";
+			unit = unit.replace(WORKER_DESCRIPTION, () => `Description=pi-dispatch worker (drains the job queue on the host; launches job containers via ${runtime})`);
+			if (stackUnits.includes(QUADLET_FILES.valkey.unit)) {
+				unit = unit.replace(WORKER_VALKEY_COMMENT, () => "# Valkey is the podman venue's Quadlet unit in this same user manager, so the worker is ordered after it\n# (the Wants=/After= lines `pi-dispatch service install` added below).\n");
+			}
+		}
 	} else {
 		unit = unit.replace(/^User=pi$/m, () => `User=${ctx.user}`);
 	}
@@ -558,8 +664,11 @@ function renderLinuxUnit(ctx) {
 /**
  * Render the launchd plist for this host. For --receiver the worker plist is DERIVED, not a second
  * template: same KeepAlive/ExitTimeOut shape, label and log names swapped, and the shared wrapper given
- * the receiver's exec argv instead of the worker's. The wrapper's exit-2 conversion is a no-op for the
- * receiver — it has no EXIT_POLICY — and harmless.
+ * the receiver's exec argv instead of the worker's. The wrapper's exit-2 conversion is LOAD-BEARING for
+ * the receiver too, not the no-op an earlier version of this comment claimed: since
+ * receiver/src/cli.mjs gained entryExitCode, a determinate receiver refusal exits EXIT_POLICY (2), and
+ * the wrapper's conversion to a clean 0 is exactly what KeepAlive/SuccessfulExit=false reads as
+ * "leave it stopped" -- launchd's only way to spell RestartPreventExitStatus=2.
  */
 function renderPlist(ctx) {
 	// Substituted before anything composed goes in (subDeployDir): the two anchors below are therefore
@@ -650,7 +759,151 @@ function nssmSequence(ctx) {
 	};
 }
 
-function doRender(ctx) {
+/**
+ * Does this worker deployment run the podman venue, per the `.env` its unit loads? `{ used: false }`, `{ error }`,
+ * or `{ used: true, venues, env }`. Only the worker has a stack: the receiver runs no job and needs no Podman.
+ *
+ * The keys come from the deployment's `.env`, the file the unit's `EnvironmentFile=` loads, read the way that loader
+ * reads it (`readStackKeys`, shared with `up`). NOT this shell's environment: nothing in this project loads `.env` into
+ * a process (docs/secrets.md), so a shell that exports PI_BACKENDS=podman says nothing about what the SERVICE will
+ * run, and installing Quadlet units off it would stand up a stack for a worker that then runs docker. A key an
+ * `--env-setup` script exports is invisible here for the same reason, which docs/podman.md says.
+ *
+ * On macOS and Windows the answer decides only a NOTE (the venue runs only on Linux, so there is no stack to
+ * install), so it is read with that platform's own loader (the wrapper sources the file with sh; the cmd wrapper
+ * splits it) and a file it cannot read there is not a refusal: refusing an install over a key that could change
+ * nothing about it would be a refusal with no remedy.
+ */
+function podmanVenue(ctx) {
+	if (ctx.which !== "worker") return { used: false };
+	const envPath = join(ctx.deployDir, ".env");
+	const linux = ctx.platform === "linux";
+	let fileKeys = {};
+	if (ctx.fs.existsSync(envPath)) {
+		let text;
+		try {
+			// Bytes, not text: `readStackKeys` checks what systemd refuses to load before it decodes (issue #447).
+			text = ctx.fs.readFileSync(envPath);
+		} catch (err) {
+			if (!linux) return { used: false };
+			return { error: `cannot read ${envPath} to learn whether this deployment runs the podman venue: ${err?.message}` };
+		}
+		const loader = linux ? "systemd" : ctx.platform === "darwin" ? "shell" : "cmd";
+		const read = readStackKeys(text, { loader, path: envPath });
+		if (read.error) return linux ? { error: read.error } : { used: false };
+		fileKeys = read.keys;
+		// Issue #464: where the worker's queue is, and whether a Valkey another uid holds may be it (PI_VALKEY_SHARED), as
+		// the service reads them, for the Valkey rule (`decideValkey`). A line the loaders read differently is refused,
+		// naming what in it is the problem, rather than guessed at.
+		const valkey = readValkeyKeys(text, { loader, path: envPath });
+		if (valkey.error) return linux ? { error: valkey.error } : { used: false };
+		fileKeys = { ...fileKeys, ...valkey.keys };
+	}
+	// Refused here, unlike doctor's venuesOf, which reads an unparseable list as `local`: doctor then reports the parse,
+	// but an install that guessed would write a unit and a stack for a deployment the worker refuses to boot.
+	try {
+		parseBackendList(fileKeys.PI_BACKENDS);
+	} catch (err) {
+		return linux ? { error: `${envPath}: ${err.message}` } : { used: false };
+	}
+	const venues = venuesOf(fileKeys);
+	if (!venues.podmanUsed) return { used: false };
+	return { used: true, venues, env: fileKeys };
+}
+
+/**
+ * The refusal for the podman venue in SYSTEM scope. Not "podman cannot run under a system unit": a system unit with
+ * `User=` runs rootless Podman fine (measured, docs/podman.md step 2). The stack is the problem. Its Quadlet units
+ * belong to the account's own user manager, and a system unit cannot `Wants=`/`After=` a unit of another manager, so
+ * the worker would race its own queue at every boot; and installing them means writing into a user's config from a
+ * command whose system-scope doctrine is to write nothing. User scope with linger does both properly.
+ */
+function refusePodmanSystemScope(ctx) {
+	return fail(
+		ctx.err,
+		`PI_BACKENDS in ${join(ctx.deployDir, ".env")} lists podman, and the podman venue's stack (Valkey, the egress proxy) runs as Quadlet units in the worker account's OWN user manager, which a system unit cannot order itself after. Install in user scope (drop --system) with linger on:  sudo loginctl enable-linger ${ctx.user}\nOr keep a hand-written system unit and start the stack by hand (docs/podman.md, steps 6 and 7).`,
+	);
+}
+
+/**
+ * The podman venue's stack for this install: which parts, rendered, with the actions that install them. `{ error }`
+ * for what cannot be installed, else `{ components, plan, notes }`. The Valkey rule differs from `up`'s on purpose:
+ * `up` starts what is not running, while an install also keeps (and orders the worker after) a Valkey unit an
+ * earlier run already installed, even though that Valkey is now the thing listening.
+ */
+async function podmanStackFor(ctx, venue, { readKeeper = false } = {}) {
+	let armed;
+	try {
+		armed = egressArmed(venue.env);
+	} catch (err) {
+		return { error: `${join(ctx.deployDir, ".env")}: ${err.message}` };
+	}
+	const installed = ctx.fs.existsSync(join(quadletDir(ctx.home), QUADLET_FILES.valkey.file));
+	// Issue #464: a listener on any address VALKEY_URL reaches is taken to be this deployment's Valkey only when it is
+	// this account's (its uid, or a subordinate uid its containers run as), or PI_VALKEY_SHARED=1 in .env says it is
+	// shared on purpose; anything else is refused, not forceably (`stackRefusal`).
+	const valkey = await decideValkey({
+		venues: venue.venues,
+		url: venue.env.VALKEY_URL,
+		installed,
+		probeTcp: ctx.probeTcp,
+		lookup: ctx.lookup,
+		interfaces: ctx.interfaces,
+		euid: ctx.euid,
+		user: ctx.user,
+		shared: valkeySharedOn(venue.env[VALKEY_SHARED_KEY]),
+		subuids: readSubuidRanges({ user: ctx.user, euid: ctx.euid, fs: ctx.fs, run: ctx.runSync }),
+		fs: ctx.fs,
+		ownerName: (uid) => passwdNameFrom(ctx.fs, uid),
+		envPath: join(ctx.deployDir, ".env"),
+	});
+	if (valkey.error) return { error: valkey.error };
+	// Issue #468: the password the Quadlet Valkey starts with, when this install includes it: the deployment's own
+	// VALKEY_PASSWORD, or a new one this install writes into .env (never over a value), unless the Valkey is shared or
+	// the operator's own (`valkeyPasswordDecision`). Generated here, written by doInstall once nothing refuses; `render`
+	// writes nothing and shows the password file by its name alone.
+	let valkeyPassword = null;
+	let pendingPassword = null;
+	const passwordNotes = [];
+	if (valkey.include) {
+		const decided = valkeyPasswordDecision(venue.env, { envPath: join(ctx.deployDir, ".env") });
+		if (decided.error) return { error: decided.error };
+		if (decided.note) passwordNotes.push(decided.note);
+		if (decided.generate) pendingPassword = ctx.newPassword();
+		valkeyPassword = decided.password ?? pendingPassword;
+	}
+	const components = stackComponents({ venues: venue.venues, env: venue.env, includeValkey: valkey.include, armed, valkeyPort: valkey.port, valkeyPassword });
+	components.notes.push(...valkey.notes, ...passwordNotes);
+	// Gate round 2: the service reads PI_VALKEY_SHARED from .env alone, so a shell export says nothing; named, not honoured.
+	if (typeof ctx.env[VALKEY_SHARED_KEY] === "string") components.notes.push(sharedShellIgnored(ctx.env[VALKEY_SHARED_KEY], join(ctx.deployDir, ".env")));
+	// The keeper, read as `up` reads it (PR #463 final review), install only (render spawns nothing): a Quadlet keeper
+	// whose file is already there and unchanged but that does not hold (stopped, paused, off its bridge) is RESTARTED,
+	// since `start` over it is a no-op for a paused one and would say nothing of the proxy either way; the plan then
+	// restarts our proxy after it (planStack), or the install names the operator's own proxy to restart.
+	let restartUnits = [];
+	if (readKeeper && components.keeper && ctx.fs.existsSync(join(quadletDir(ctx.home), QUADLET_FILES.keeper.file))) {
+		const keeper = judgeNetnsKeeper(await runQuery(ctx, "podman", ["inspect", NETNS_KEEPER_FORMAT, NETNS_KEEPER]));
+		if (!keeper.holds) restartUnits = [QUADLET_FILES.keeper.unit];
+	}
+	let plan = planStack({ components, templatesDir: ctx.templatesDir, deployDir: ctx.deployDir, home: ctx.home, fs: ctx.fs, restartUnits });
+	if (plan.error) return { error: plan.error };
+	// Issue #468: a Valkey that already ran and now gets a new password (an upgrade from a deployment that had none) is one
+	// its running clients can no longer talk to, so the worker and the receiver units this account runs are restarted
+	// after it. Asked only then (install only; render spawns nothing), and only of units the manager says are active.
+	const secret = plan.files.find((f) => f.kind === "secret");
+	const valkeyFile = plan.files.find((f) => f.unit === QUADLET_FILES.valkey.unit && f.path.endsWith(".container"));
+	if (readKeeper && secret && secret.state !== "same" && valkeyFile && valkeyFile.state !== "new") {
+		const active = [];
+		for (const unit of ["pi-dispatch-worker.service", "pi-dispatch-receiver.service"]) {
+			const res = await runQuery(ctx, "systemctl", ["--user", "is-active", unit]);
+			if (res.code === 0 && String(res.stdout ?? "").trim() === "active") active.push(unit);
+		}
+		if (active.length > 0) plan = planStack({ components, templatesDir: ctx.templatesDir, deployDir: ctx.deployDir, home: ctx.home, fs: ctx.fs, restartUnits, restartAfterValkey: active });
+	}
+	return { components, plan, notes: components.notes, venues: venue.venues, proxy: egressProxyName(venue.env), valkeyRefusal: valkey.refusal, pendingPassword };
+}
+
+async function doRender(ctx) {
 	if (ctx.which === "receiver" && !ctx.receiverStart) return refuseMissingReceiver(ctx);
 	const paths = unitPaths(ctx);
 	if (ctx.platform === "darwin") {
@@ -667,8 +920,26 @@ function doRender(ctx) {
 		return 0;
 	}
 	if (ctx.platform === "linux") {
+		const venue = podmanVenue(ctx);
+		if (venue.error) return fail(ctx.err, venue.error);
+		let stack = null;
+		if (venue.used) {
+			if (ctx.scope === "system") return refusePodmanSystemScope(ctx);
+			stack = await podmanStackFor(ctx, venue);
+			if (stack.error) return fail(ctx.err, stack.error);
+		}
 		ctx.out(`# → ${paths.installPath}\n`);
-		ctx.out(renderLinuxUnit(ctx));
+		ctx.out(renderLinuxUnit(ctx, stack?.plan.start ?? [], stack?.venues ?? null));
+		// The proxy's rules copy is named, not printed (round 3 nit): it is the package's egress-proxy.conf verbatim, and
+		// 4.7 KB of squid configuration under a "Quadlet" heading read as a unit file.
+		for (const f of stack?.plan.files ?? []) {
+			if (f.kind === "conf") ctx.out(`\n# → ${f.path} (the egress proxy's rules: install copies the package's egress-proxy.conf here, unchanged)\n`);
+			// Issue #468: the password file is NAMED, never printed: render output lands in scrollbacks and bug reports.
+			else if (f.kind === "secret") ctx.out(`\n# → ${f.path} (mode 0600: ${VALKEY_PASSWORD_KEY} for the Quadlet Valkey, ${f.text.includes(`${VALKEY_PASSWORD_KEY}=\n`) ? "empty, so it starts without a password" : "from .env or generated into it at install; the value is not shown"})\n`);
+			else ctx.out(`\n# → ${f.path} (Quadlet, podman venue)\n${f.text}`);
+		}
+		for (const note of stack?.notes ?? []) ctx.out(`# note: ${note}\n`);
+		if (stack?.valkeyRefusal) ctx.out(`# note: install refuses this: ${stack.valkeyRefusal.text}\n`);
 		return 0;
 	}
 	const { service, commands } = nssmSequence(ctx);
@@ -697,9 +968,27 @@ async function doInstall(ctx) {
 		}
 	}
 
-	if (ctx.platform === "darwin") return installDarwin(ctx, paths);
-	if (ctx.platform === "linux") return ctx.scope === "system" ? installLinuxSystem(ctx, paths) : installLinuxUser(ctx, paths);
-	return installWindows(ctx);
+	const venue = podmanVenue(ctx);
+	if (venue.error) return fail(ctx.err, venue.error);
+	if (ctx.platform === "darwin" || ctx.platform === "win32") {
+		const code = ctx.platform === "darwin" ? await installDarwin(ctx, paths) : await installWindows(ctx);
+		// Said, never silently skipped: the venue refuses every host that is not Linux (podman-platform), so there is
+		// no stack to install here, and a deployment listing it should know why nothing about Podman happened.
+		if (code === 0 && venue.used) ctx.out("note: PI_BACKENDS lists podman, and the podman venue runs only on Linux (it refuses this host as podman-platform), so no podman stack was installed here\n");
+		return code;
+	}
+	if (ctx.scope === "system") return venue.used ? refusePodmanSystemScope(ctx) : installLinuxSystem(ctx, paths);
+	let stack = null;
+	let foreign = [];
+	if (venue.used) {
+		stack = await podmanStackFor(ctx, venue, { readKeeper: true });
+		if (stack.error) return fail(ctx.err, stack.error);
+		// Every stack refusal first, the unit's own among them, so installLinuxUser's unit check never fires alone.
+		const refused = await stackRefusal(ctx, paths, stack);
+		if (refused.error) return fail(ctx.err, refused.error);
+		foreign = refused.foreign;
+	}
+	return installLinuxUser(ctx, paths, stack, foreign);
 }
 
 async function installDarwin(ctx, paths) {
@@ -721,11 +1010,18 @@ async function installDarwin(ctx, paths) {
 		// the old copy out first. "Not loaded" is a fine answer — the nonzero exit is ignored.
 		await run(ctx, "launchctl", ["bootout", `gui/${ctx.euid}/${paths.name}`]);
 	}
-	ctx.fs.mkdirSync(dirname(paths.installPath), { recursive: true });
-	// launchd creates the StandardOutPath FILES but not their parent directory: without this the job
-	// spawns and dies with its error unwritable. Done at install, not render — render stays read-only.
-	ctx.fs.mkdirSync(join(ctx.deployDir, "logs"), { recursive: true });
-	ctx.fs.writeFileSync(paths.installPath, renderPlist(ctx));
+	// Issue #464: a write that fails is said, with what this run left, rather than thrown out of the command. The plist
+	// is the one file this path writes, so a failure leaves none of ours (a failed write is put back like the Linux path's).
+	const journal = [];
+	try {
+		ctx.fs.mkdirSync(dirname(paths.installPath), { recursive: true });
+		// launchd creates the StandardOutPath FILES but not their parent directory: without this the job
+		// spawns and dies with its error unwritable. Done at install, not render: render stays read-only.
+		ctx.fs.mkdirSync(join(ctx.deployDir, "logs"), { recursive: true });
+		journalWrite(ctx.fs, journal, paths.installPath, renderPlist(ctx));
+	} catch (err) {
+		return fail(ctx.err, `could not write ${paths.installPath} (${err?.message ?? err}), so nothing was installed: ${describeRollBack(rollBackWrites(ctx.fs, journal))}`);
+	}
 	const bootstrap = await run(ctx, "launchctl", ["bootstrap", `gui/${ctx.euid}`, paths.installPath]);
 	if (bootstrap !== 0) {
 		return fail(ctx.err, `launchctl bootstrap failed (exit ${bootstrap}) — the plist is written; retry by hand: launchctl bootstrap gui/${ctx.euid} ${paths.installPath}`);
@@ -740,25 +1036,176 @@ async function installDarwin(ctx, paths) {
 	return 0;
 }
 
-async function installLinuxUser(ctx, paths) {
+/**
+ * Every reason the podman venue's stack refuses an install, gathered BEFORE anything is written (round 2, E9): the
+ * worker unit existing used to be the only thing said, so an operator re-ran with --force and then met a replaced
+ * container and a restarted proxy nobody had mentioned. `--force` is consent to exactly the list printed here. Three
+ * reasons are not forceable: a missing allowlist, a container whose state could not be read, and no user manager.
+ * Returns `{ error }` or `{ foreign }` (the foreign containers --force will replace, for the warnings).
+ */
+async function stackRefusal(ctx, paths, stack) {
+	const blocking = [];
+	const forceable = [];
+	if (ctx.fs.existsSync(paths.installPath)) forceable.push(`${paths.installPath} already exists (same non-clobber contract as init); --force replaces it`);
+	const changed = stack.plan.files.filter((f) => f.state === "changed");
+	if (changed.length > 0) forceable.push(`${changed.map((f) => f.path).join(", ")} already ${changed.length === 1 ? "exists" : "exist"} with other content than this version renders; --force replaces ${changed.length === 1 ? "it" : "them"} and restarts ${(stack.plan.restart ?? []).join(" ") || "nothing"}${proxyRestartWarning(stack.plan) ? ` (${proxyRestartWarning(stack.plan)})` : ""}`);
+	// Issue #464: a Valkey VALKEY_URL reaches that is not this account's. NOT forceable: --force is how an operator replaces
+	// a changed file, and taking another account's queue must never ride along with that. The opt-in is its own named key.
+	if (stack.valkeyRefusal) blocking.push(stack.valkeyRefusal.text);
+	const allowlist = join(ctx.deployDir, "egress-allowlist.conf");
+	if (stack.components.proxy && !ctx.fs.existsSync(allowlist)) {
+		blocking.push(`the egress policy is on, and ${allowlist} does not exist: a proxy unit mounting a missing file makes Podman create a DIRECTORY there and squid fail confusingly. Run \`pi-dispatch init\` in ${ctx.deployDir} first (it never overwrites), or set PI_EGRESS=0 in .env to opt out of the policy`);
+	}
+	const bus = stack.plan.actions.length > 0 ? userBusRefusal({ env: ctx.env, user: ctx.user, euid: ctx.euid }) : null;
+	if (bus) blocking.push(bus);
+	// The manager's own XDG_RUNTIME_DIR and XDG_CONFIG_HOME (PR #463 round 3, measured): another account's makes every
+	// unit this installs fail to start, or not exist at all. Asked only where the manager can be asked.
+	if (!bus && stack.plan.actions.length > 0) {
+		const managerEnv = managerEnvRefusal(await runQuery(ctx, "systemctl", ["--user", "show-environment"]), { home: ctx.home, euid: ctx.euid, user: ctx.user, realpath: ctx.realpath });
+		if (managerEnv) blocking.push(managerEnv);
+	}
+	// A container of the unit's name that the unit does not own would be removed by its `podman run --replace`
+	// (issue #430 review): refused unless --force says to replace it, and then said out loud.
+	const containers = await foreignContainers(stack.plan, (cmd, args) => runQuery(ctx, cmd, args));
+	const foreign = containers.found;
+	if (containers.unknown.length > 0) blocking.push(unknownContainerRefusal(containers.unknown));
+	if (foreign.length > 0) forceable.push(foreignContainerRefusal(foreign, { forceHint: "pass --force to let the Quadlet unit replace it" }));
+	if (blocking.length > 0 || (forceable.length > 0 && !ctx.force)) {
+		const lines = [...blocking, ...(ctx.force ? [] : forceable)];
+		// Worded from the counts, since both lists can hold several (round 3 nit): the blocking reasons come first.
+		const byHand = blocking.length === 1 ? "The first item must be fixed by hand" : `The first ${blocking.length} items must be fixed by hand`;
+		const tail = blocking.length === 0 ? "\n--force accepts every item above at once." : forceable.length > 0 && !ctx.force ? `\n${byHand}; --force accepts the rest.` : `\n${blocking.length === 1 ? "It" : "Each"} must be fixed by hand; --force does not apply.`;
+		return { error: `${lines.length === 1 ? lines[0] : `nothing installed, for these reasons:\n${lines.map((l) => `  - ${l}`).join("\n")}`}${lines.length > 1 ? tail : ""}` };
+	}
+	return { foreign };
+}
+
+async function installLinuxUser(ctx, paths, stack = null, foreign = []) {
 	if (ctx.fs.existsSync(paths.installPath) && !ctx.force) {
 		return fail(ctx.err, `${paths.installPath} already exists — pass --force to replace it (same non-clobber contract as init)`);
 	}
-	ctx.fs.mkdirSync(dirname(paths.installPath), { recursive: true });
-	ctx.fs.writeFileSync(paths.installPath, renderLinuxUnit(ctx));
+	// Issue #464: every file this run writes, recorded before it is written, so a failure puts them back rather than
+	// leaving half an install (seen with a root-owned ~/.config: the stack's files written, the worker unit refused). All
+	// files are written before any command runs (the worker unit inside applyStack's `beforeRuns`), which is what makes a
+	// write failure all-or-nothing. A COMMAND that fails leaves the stack's files, which units already started from, and
+	// says exactly which files this run wrote.
+	const journal = [];
+	const writeUnit = () => {
+		try {
+			ctx.fs.mkdirSync(dirname(paths.installPath), { recursive: true });
+			journalWrite(ctx.fs, journal, paths.installPath, renderLinuxUnit(ctx, stack?.plan.start ?? [], stack?.venues ?? null));
+			return { ok: true };
+		} catch (err) {
+			return { ok: false, failed: `write ${paths.installPath}`, code: null, message: err?.message };
+		}
+	};
+	const writtenList = () => [...new Set(journal.map((e) => e.path))].join(", ") || "none";
+	if (stack?.pendingPassword) {
+		// Issue #468: the new Valkey password into .env first, journalled like every other file of this run, so a write
+		// that fails later puts .env back too. Never over a value (the writer's never-clobber), the file narrowed to this
+		// account alone, the value never shown.
+		const wrote = writeValkeyPassword(ctx, stack.pendingPassword, journal);
+		if (wrote.error) return fail(ctx.err, `${wrote.error}, so nothing was installed: ${describeRollBack(rollBackWrites(ctx.fs, journal))}`);
+		ctx.out(`generated ${VALKEY_PASSWORD_KEY} into ${wrote.path} (32 random bytes, hex; the value is not shown; the file is now readable by this account only)\n`);
+	}
+	if (stack) {
+		for (const note of stack.notes) ctx.out(`note: ${note}\n`);
+		for (const f of foreign) {
+			ctx.out(`⚠ --force: ${f.container} is not managed by ${f.unit} and will be REPLACED by it${f.unit === QUADLET_FILES.proxy.unit ? "; every job running right now loses the per-job network it had on that proxy" : ""}\n`);
+		}
+		const restartWarning = proxyRestartWarning(stack.plan);
+		if (restartWarning) ctx.out(`⚠ ${restartWarning}\n`);
+		const passwordWarning = valkeyPasswordRestartWarning(stack.plan);
+		if (passwordWarning) ctx.out(`⚠ ${passwordWarning}\n`);
+		if (stack.plan.actions.length > 0) {
+			// Shown, then done: the same lines `up` asks consent for, carried out by the same function.
+			ctx.out(`podman venue (PI_BACKENDS in .env): its stack, as Quadlet units in ${stack.plan.dir}:\n`);
+			for (const action of stack.plan.actions) ctx.out(`  ${describeAction(action)}\n`);
+			const applied = await applyStack(stack.plan, { fs: ctx.fs, run: (cmd, args) => run(ctx, cmd, args), journal, beforeRuns: writeUnit });
+			if (!applied.ok) {
+				const what = `${applied.failed} failed (${applied.code === null ? applied.message ?? "command not found" : `exit ${applied.code}`})`;
+				if (!applied.ran) {
+					return fail(ctx.err, `${what}, so nothing was installed: ${describeRollBack(rollBackWrites(ctx.fs, journal))}. Fix it, then re-run this install`);
+				}
+				// A command failed: the stack's units may be running from their files, so only the worker unit is put back,
+				// and the manager is reloaded so it forgets it (best effort; the unit was never enabled or started).
+				const unitOnly = journal.filter((e) => e.path === paths.installPath);
+				const rolled = rollBackWrites(ctx.fs, unitOnly);
+				if (rolled.left.length === 0) await run(ctx, "systemctl", ["--user", "daemon-reload"]);
+				const remain = [...new Set(journal.filter((e) => e.path !== paths.installPath).map((e) => e.path))];
+				return fail(
+					ctx.err,
+					`${what}, so the worker unit was NOT installed: it would only start against a missing queue or proxy (${describeRollBack(rolled, { partial: true })}). The stack files this run wrote remain, since its units run from them: ${remain.join(", ") || "none"}. \`pi-dispatch service uninstall\` removes them if you will not retry. \`systemctl --user status ${stack.plan.start.join(" ")}\` and \`journalctl --user -u <unit>\` have the details; fix it, then re-run this install`,
+				);
+			}
+		}
+	}
+	if (!journal.some((e) => e.path === paths.installPath)) {
+		const wrote = writeUnit();
+		if (!wrote.ok) return fail(ctx.err, `${wrote.failed} failed (${wrote.message}), so nothing was installed: ${describeRollBack(rollBackWrites(ctx.fs, journal))}. Fix it, then re-run this install`);
+	}
 	const reload = await run(ctx, "systemctl", ["--user", "daemon-reload"]);
-	if (reload === null) return fail(ctx.err, `systemctl not found — is this a systemd host? The unit is written at ${paths.installPath}`);
+	if (reload === null) return fail(ctx.err, `systemctl not found: is this a systemd host? The unit is written at ${paths.installPath} (files this run wrote, which remain: ${writtenList()})`);
 	const enable = await run(ctx, "systemctl", ["--user", "enable", "--now", paths.name]);
 	if (enable !== 0) {
-		return fail(ctx.err, `systemctl --user enable --now ${paths.name} failed (exit ${enable}) — the unit is written at ${paths.installPath}; \`systemctl --user status ${paths.name}\` has the details`);
+		return fail(ctx.err, `systemctl --user enable --now ${paths.name} failed (exit ${enable}); the unit is written at ${paths.installPath}; \`systemctl --user status ${paths.name}\` has the details (files this run wrote, which remain: ${writtenList()})`);
 	}
 	ctx.out(`installed ${paths.name} → ${paths.installPath} (enabled and started in your user manager)\n`);
+	if (stack) {
+		// Said as it happened: `start` on a unit already active is a no-op, so a unit whose file this run replaced was
+		// RESTARTED (planStack), and the line names which is which rather than calling everything "started".
+		const restarted = stack.plan.restart ?? [];
+		const started = stack.plan.start.filter((u) => !restarted.includes(u));
+		if (started.length > 0) ctx.out(`started ${started.join(" ")} (Quadlet units: never enabled, the generator reads their own [Install] section; a unit already running is left as it is)\n`);
+		// Named by the file that changed (round 3 nit): the proxy also restarts for its rules copy alone.
+		for (const unit of restarted) {
+			// Issue #468: a file this install wrote NEW for a unit it restarts (the Valkey's first password file) is named too.
+			const changedFiles = stack.plan.files.filter((f) => f.state !== "same" && f.restarts === unit).map((f) => f.path);
+			// A unit restarted with its files unchanged (a keeper that did not hold, the proxy after it) says so rather than
+			// ending on "replaced " with nothing after it, as it did.
+			ctx.out(`restarted ${unit}, ${changedFiles.length > 0 ? `because this install replaced ${changedFiles.join(" and ")}` : "as the plan above says (its files are unchanged)"}\n`);
+		}
+		if ((stack.plan.clientsRestarted ?? []).length > 0) ctx.out(`restarted ${stack.plan.clientsRestarted.join(" ")} after it, so they send the new ${VALKEY_PASSWORD_KEY}\n`);
+		if (stack.plan.start.length > 0) ctx.out(`${paths.name} Wants= and is After= ${stack.plan.start.join(" ")}\n`);
+		// PR #463 round 3: a keeper started or restarted beside a proxy this install does not own (PI_EGRESS_PROXY naming
+		// the operator's own) leaves that proxy up since before the keeper; said, with its name.
+		const hint = keeperUnderRunningProxyHint(stack.plan, stack.proxy);
+		if (hint) ctx.out(`⚠ ${hint}\n`);
+		// A WARNING, not a refusal, like the note below it: a worker that runs only while its operator is logged in is a
+		// real (desktop) deployment. But on this venue linger is also what brings the queue and the proxy back, and it
+		// was measured both ways, so the line says which of the two this host is rather than the general caution.
+		ctx.out(lingerNote(await readLinger(ctx.user, (cmd, args) => runCapture(ctx, cmd, args)), ctx.user));
+		return 0;
+	}
 	// Without linger a user manager only runs while a session exists — fine on a desktop, a silent
 	// no-worker-after-reboot on a headless box. Say so instead of letting the operator find out.
 	ctx.out(`note: user units run while you have a session. For a headless host that must start at boot:  sudo loginctl enable-linger ${ctx.user}\n`);
 	return 0;
 }
 
+/**
+ * Write a new VALKEY_PASSWORD into the deployment's `.env` (issue #468) through the project's one `.env` writer, never
+ * over a value, the file narrowed to this account alone (`narrow`). Recorded in `journal` with the bytes that were there,
+ * so a later failure of the same install puts it back. `{ path }` or `{ error }`; the value is never in either.
+ */
+function writeValkeyPassword(ctx, password, journal) {
+	const envPath = join(ctx.deployDir, ".env");
+	let previous;
+	try {
+		previous = ctx.fs.readFileSync(envPath);
+	} catch (err) {
+		return { error: `${VALKEY_PASSWORD_KEY} could not be written into ${envPath}: it could not be read (${err?.message ?? err})` };
+	}
+	try {
+		const res = updateEnvFile(envPath, VALKEY_PASSWORD_KEY, password, { fs: ctx.fs, platform: ctx.platform, narrow: true });
+		if (!res.changed) return { error: `${VALKEY_PASSWORD_KEY} could not be written into ${envPath}: the file already assigns it (set while this install ran?). Re-run the install, which then uses that value` };
+	} catch (err) {
+		return { error: `${VALKEY_PASSWORD_KEY} could not be written into ${envPath}: ${err?.message ?? err}` };
+	}
+	journal.push({ path: envPath, existed: true, previous });
+	return { path: envPath };
+}
+
 async function installLinuxSystem(ctx, paths) {
 	if (ctx.fs.existsSync(paths.installPath) && !ctx.force) {
 		return fail(ctx.err, `${paths.installPath} already exists — pass --force to re-stage the render (the printed sudo commands would overwrite it)`);
@@ -815,6 +1262,20 @@ async function doUninstall(ctx) {
 		return 0;
 	}
 	const userPath = ctx.platform === "darwin" ? paths.installPath : paths.userPath;
+	// The podman venue's Quadlet units (issue #430), removed with the worker, or on their own when `up` installed them
+	// and no worker unit was ever written. Decided by what EXISTS, not by today's PI_BACKENDS: an operator who dropped
+	// podman from the list still has the units, and they are still this tool's to remove.
+	const quadlets = ctx.platform === "linux" && ctx.which === "worker" && ctx.scope === "user" ? ALL_QUADLET_FILES.filter((q) => ctx.fs.existsSync(join(quadletDir(ctx.home), q.file))) : [];
+	// No user manager to talk to (`sudo -iu`, round 3 D3, measured): every `systemctl --user` below would fail, and the
+	// old code ignored the exits, printed success with exit 0, and left the worker and the stack running with a
+	// dangling default.target.wants link. Refused before anything is touched, whenever this run would talk to it.
+	if (ctx.platform === "linux" && (ctx.fs.existsSync(userPath) || quadlets.length > 0)) {
+		const bus = userBusRefusal({ env: ctx.env, user: ctx.user, euid: ctx.euid });
+		if (bus) return fail(ctx.err, bus.replace("so `systemctl --user` would fail after the files were written", "so `systemctl --user` could stop and disable nothing"));
+	}
+	if (!ctx.fs.existsSync(userPath) && quadlets.length > 0 && !ctx.fs.existsSync(paths.systemPath)) {
+		return removeQuadlets(ctx, quadlets);
+	}
 	if (!ctx.fs.existsSync(userPath)) {
 		// Say where it looked — both scopes — and if the unit turns out to live in ROOT scope, print
 		// the removal commands instead of touching them (the same never-root doctrine as install).
@@ -833,13 +1294,94 @@ async function doUninstall(ctx) {
 		ctx.out(`uninstalled ${paths.name} (booted out of gui/${ctx.euid}, plist removed)\n`);
 		return 0;
 	}
-	await run(ctx, "systemctl", ["--user", "disable", "--now", paths.name]); // not-enabled is fine
+	// A non-zero exit here is a unit that is still enabled or still running (round 3, D3): nothing is removed and nothing
+	// is claimed. `disable --now` on an installed unit that is merely not enabled exits 0.
+	const disabled = await run(ctx, "systemctl", ["--user", "disable", "--now", paths.name]);
+	if (disabled !== 0) {
+		return fail(ctx.err, `systemctl --user disable --now ${paths.name} failed (${disabled === null ? "systemctl not found" : `exit ${disabled}`}), so nothing was removed: the worker may still be running. \`systemctl --user status ${paths.name}\` has the details`);
+	}
 	ctx.fs.unlinkSync(userPath);
-	await run(ctx, "systemctl", ["--user", "daemon-reload"]);
+	const reload = await run(ctx, "systemctl", ["--user", "daemon-reload"]);
+	if (reload !== 0) {
+		return fail(ctx.err, `${paths.name} is disabled, stopped and its unit file removed, but systemctl --user daemon-reload failed (${reload === null ? "systemctl not found" : `exit ${reload}`}): run it yourself`);
+	}
 	ctx.out(`uninstalled ${paths.name} (disabled, stopped, unit removed)\n`);
+	if (quadlets.length > 0) return removeQuadlets(ctx, quadlets);
 	return 0;
 }
 
+/**
+ * Stop and remove the podman venue's Quadlet units. `stop`, never `disable`: a generated unit cannot be disabled any
+ * more than enabled, and removing its file plus a daemon-reload is what unlinks it from default.target. The Valkey
+ * volume and the three networks are deliberately LEFT: the volume holds the queue's wait-list, and a re-install that
+ * found it gone would have dropped every waiting job on an uninstall nobody meant as a purge.
+ */
+async function removeQuadlets(ctx, quadlets) {
+	// The network units too (round 3, D2, measured): left behind, they stay `active (exited)` in the manager, so after the
+	// `podman network rm` the message below suggests, a reinstall in the same manager lifetime found its network unit
+	// already "started" and the container failed with "network not found". Containers first, then their networks.
+	const containers = quadlets.filter((q) => q.file.endsWith(".container")).map((q) => q.unit);
+	const networks = quadlets.filter((q) => q.file.endsWith(".network")).map((q) => q.unit);
+	const units = [...containers, ...networks];
+	if (units.length > 0) {
+		// A unit that is already stopped stops with exit 0; a non-zero exit is a stop that did not happen (no manager, a
+		// unit that would not die), and removing the files under a running container would leave it running unmanaged
+		// while this command claimed it was gone (round 3, D3).
+		const stopped = await run(ctx, "systemctl", ["--user", "stop", ...units]);
+		// Issue #464: a unit the manager never loaded (an install or `up` whose daemon-reload failed after writing the
+		// files) makes `stop` exit 5 ("not loaded"), and uninstall then could not remove the very files that failed run
+		// left. So a failed stop is asked about unit by unit: one that is not loaded, or loaded and not running, is
+		// stopped as far as it can be; only a unit still active refuses the removal, as before.
+		if (stopped !== 0 && stopped !== null && (await unitsStillRunning(ctx, units)).length === 0) {
+			ctx.out(`note: systemctl --user stop exited ${stopped}, and none of ${units.join(", ")} is running (not loaded, or already stopped), so their files are removed\n`);
+		} else if (stopped !== 0) {
+			return fail(ctx.err, `systemctl --user stop ${units.join(" ")} failed (${stopped === null ? "systemctl not found" : `exit ${stopped}`}), so nothing was removed: the containers may still be running. \`systemctl --user status ${units.join(" ")}\` has the details`);
+		}
+	}
+	for (const q of quadlets) ctx.fs.unlinkSync(join(quadletDir(ctx.home), q.file));
+	// The account-owned copy of the proxy's rules (E1) goes with its unit, and the Valkey's password file with its unit
+	// (issue #468; the password itself stays in the deployment's .env, where a re-install finds it).
+	const conf = proxyConfCopyPath(ctx.home);
+	if (ctx.fs.existsSync(conf)) ctx.fs.unlinkSync(conf);
+	const valkeyEnv = valkeyEnvPath(ctx.home);
+	if (quadlets.some((q) => q.file === QUADLET_FILES.valkey.file) && ctx.fs.existsSync(valkeyEnv)) ctx.fs.unlinkSync(valkeyEnv);
+	const reload = await run(ctx, "systemctl", ["--user", "daemon-reload"]);
+	if (reload !== 0) {
+		return fail(ctx.err, `the Quadlet files are removed and their units stopped, but systemctl --user daemon-reload failed (${reload === null ? "systemctl not found" : `exit ${reload}`}): run it yourself so the manager forgets them`);
+	}
+	// squid ignores SIGTERM, so its stop takes systemd's 10 s and ends in SIGKILL, exit 137, and the unit is left
+	// `failed` (measured): after the file is gone `systemctl --user list-units` would show a not-found failed unit
+	// forever. reset-failed clears it. Its exit is not checked: a unit that never failed is already what it asks for.
+	if (units.length > 0) await run(ctx, "systemctl", ["--user", "reset-failed", ...units]);
+	// The volume is named only when a Valkey unit was among what was removed (issue #452 gate round 2): a stack installed
+	// without Valkey never had one, and the line used to claim a volume nothing here made was kept.
+	const hadValkey = quadlets.some((q) => q.file === QUADLET_FILES.valkey.file);
+	ctx.out(`removed the podman venue's Quadlet units (${quadlets.map((q) => q.file).join(", ")}); ${hadValkey ? "the pi-dispatch-valkey-data volume and the networks are" : "the networks are"} kept, remove them with podman if you mean to\n`);
+	return 0;
+}
+
+/**
+ * The units of `units` the user manager still has running, asked one by one (`systemctl --user show`), for an
+ * uninstall whose `stop` failed (issue #464). A unit is taken as not running only on the manager's own answer: not
+ * loaded (`LoadState=not-found`), or loaded and `inactive` or `failed`. A unit it could not be asked about counts as
+ * running, so the removal is refused rather than guessed.
+ */
+async function unitsStillRunning(ctx, units) {
+	const running = [];
+	for (const unit of units) {
+		const shown = await runQuery(ctx, "systemctl", ["--user", "show", "--property=LoadState,ActiveState", unit]);
+		const props = Object.fromEntries(
+			String(shown.stdout ?? "")
+				.split("\n")
+				.map((l) => l.trim().split("="))
+				.filter((kv) => kv.length === 2),
+		);
+		const idle = shown.code === 0 && (props.LoadState === "not-found" || (props.LoadState === "loaded" && ["inactive", "failed"].includes(props.ActiveState)));
+		if (!idle) running.push(unit);
+	}
+	return running;
+}
+
 /** Informational only — reports every scope it knows about and always exits 0. */
 async function doStatus(ctx) {
 	const paths = unitPaths(ctx);
@@ -875,6 +1417,16 @@ async function doStatus(ctx) {
 	const systemHits = [paths.systemPath, ...(ctx.which === "worker" ? ["/etc/systemd/system/worker.service"] : [])].filter((p) => ctx.fs.existsSync(p));
 	ctx.out(systemHits.length ? `system scope: ${systemHits.join(", ")} EXISTS — not managed by this tool\n` : "system scope: none\n");
 	reportEnvSetup(ctx, [paths.userPath, ...systemHits]);
+	// The podman venue's Quadlet units, one line each, and nothing at all where there are none, so the output of every
+	// other deployment is byte-identical to before issue #430.
+	if (ctx.which === "worker") {
+		for (const q of ALL_QUADLET_FILES) {
+			const path = join(quadletDir(ctx.home), q.file);
+			if (!ctx.fs.existsSync(path)) continue;
+			const active = await runCapture(ctx, "systemctl", ["--user", "is-active", q.unit]);
+			ctx.out(`quadlet: ${path} (${q.unit}): ${active.code === null ? "systemctl not found" : active.output.trim() || "unknown"}\n`);
+		}
+	}
 	return 0;
 }
 
@@ -945,13 +1497,15 @@ async function doRestart(ctx, values) {
 		return fail(ctx.err, `--drain-timeout must be a positive number of seconds, got: ${values["drain-timeout"]}`);
 	}
 	let queue = ctx.queue;
+	let url;
 	if (!queue) {
 		// VALKEY_URL only, exactly like cli.mjs's pause/resume: the drain must work even when the rest
 		// of the config (forge auth …) is broken, and failFast keeps a down Valkey an error in seconds
 		// instead of a hung restart. Lazy imports for the same reason cli.mjs uses them: `service`
 		// subcommands that never touch the queue must not load bullmq/ioredis.
-		const url = ctx.env.VALKEY_URL ?? "redis://127.0.0.1:6379";
-		const { parseConnection } = await import("./connection.mjs");
+		// This shell's VALKEY_URL, else the deployment .env's (PR #475's review), as every CLI verb reads it.
+		const { cliValkeyUrl, parseConnection } = await import("./connection.mjs");
+		url = cliValkeyUrl(ctx.env, { cwd: ctx.deployDir, warn: (line) => ctx.err(line) });
 		const { makeQueue } = await import("./queue.mjs");
 		queue = makeQueue(parseConnection(url, { failFast: true }));
 	}
@@ -981,7 +1535,7 @@ async function doRestart(ctx, values) {
 		// this command would otherwise be doing: reporting a drained queue it cannot see all of.
 		const delayed = await queue.getJobCounts("delayed").then((c) => Number(c?.delayed ?? 0), () => 0);
 		if (delayed > 0) {
-			ctx.out(`note: ${delayed} job(s) sit in the delayed set (cron next-occurrences, retry backoff, quiet hours, or jobs held on run.waitFor). None is active, so none blocked this drain; they will wake against the new version.\n`);
+			ctx.out(`note: ${delayed} job(s) sit in the delayed set (cron next-occurrences, retry backoff, quiet hours, scope/host deferrals, or jobs held on run.waitFor). None is active, so none blocked this drain; they will wake against the new version.\n`);
 		}
 		const stopped = await doStop(ctx);
 		if (stopped !== 0) {
@@ -997,7 +1551,7 @@ async function doRestart(ctx, values) {
 		ctx.out("resumed — drained restart complete\n");
 		return 0;
 	} catch (error) {
-		return fail(ctx.err, `could not reach Valkey — is it running? (docker compose up)\n  ${error.message}`);
+		return fail(ctx.err, `could not reach Valkey: ${(await import("./valkey-auth.mjs")).valkeyDownHint(url)}\n  ${error.message}`);
 	} finally {
 		await queue.close().catch(() => {});
 	}
@@ -1013,6 +1567,20 @@ function quoteArgs(args) {
 	return args.map((a) => (a.includes(" ") || a.includes("\\") ? `"${a}"` : a)).join(" ");
 }
 
+/** Is anything listening on host:port? up.mjs's probe, for up.mjs's reason: a plain connect, no protocol. */
+function defaultProbeTcp(host, port, timeoutMs = 1500) {
+	return new Promise((resolvePromise) => {
+		const socket = netConnect({ host, port });
+		const done = (result) => {
+			socket.destroy();
+			resolvePromise(result);
+		};
+		socket.setTimeout(timeoutMs, () => done(false));
+		socket.on("connect", () => done(true));
+		socket.on("error", () => done(false));
+	});
+}
+
 /** Exit code of a spawned command; null when it could not launch (not on PATH) — the up.mjs pattern. */
 function run(ctx, cmd, args) {
 	return new Promise((resolvePromise) => {
@@ -1028,6 +1596,28 @@ function run(ctx, cmd, args) {
 	});
 }
 
+/**
+ * Like runCapture() with the two streams SEPARATE, for a query whose answer is stdout alone (round 2, E2): podman
+ * prints warnings on stderr on ordinary accounts, and merged into the answer they made a label read as someone else's.
+ */
+function runQuery(ctx, cmd, args) {
+	return new Promise((resolvePromise) => {
+		let child;
+		try {
+			child = ctx.spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+		} catch {
+			resolvePromise({ code: null, stdout: "", stderr: "" });
+			return;
+		}
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.on("data", (d) => (stdout += d));
+		child.stderr?.on("data", (d) => (stderr += d));
+		child.on("error", () => resolvePromise({ code: null, stdout, stderr }));
+		child.on("close", (code) => resolvePromise({ code, stdout, stderr }));
+	});
+}
+
 /** Like run() but with stdout+stderr captured, for read-only lookups (nssm status, is-active …). */
 function runCapture(ctx, cmd, args) {
 	return new Promise((resolvePromise) => {