@edgehero/pi-dispatch 1.10.2 → 2.0.0

package/src/up.mjs

@@ -14,6 +14,15 @@
  *     file happens to name" (the same reasoning as jobs running with --pull=never).
  *   - no secrets printed: the generated WEBHOOK_SECRET is announced, never echoed.
  *
+ * The native rootless `podman` venue (issue #430): when PI_BACKENDS lists podman, `up` also gates on the venue's own
+ * `podman info` rule, pulls the default image into this account's Podman store, and installs Valkey and the egress
+ * proxy as Quadlet units through the installer `service install` uses (podman-stack.mjs), after init. When the list
+ * does not name `local`, nothing here runs docker at all. The docker path of a deployment that blesses `local` is
+ * unchanged, with one correction: the egress step looks for the proxy PI_EGRESS_PROXY names rather than the shipped
+ * name, and starts nothing in place of an overriding one. The venue keys (PI_BACKENDS, PI_EGRESS, PI_EGRESS_PROXY)
+ * come from this shell when it sets them and otherwise from the deployment's `.env`, the file `service install`
+ * reads, so the two entry points decide the venue from the same place (`deploymentVenueEnv`).
+ *
  * Converge-style, not transactional: a declined or failed step is reported and the pass continues, so
  * one flaky pull does not hide the doctor report that says what else is missing. Exit code mirrors
  * doctor's: 0 unless the docker daemon was unreachable up front (nothing else can be probed, so up
@@ -21,11 +30,26 @@
  */
 import { randomBytes } from "node:crypto";
 import { spawn as nodeSpawn } from "node:child_process";
-import { chmodSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync as readPackageFile } from "node:fs";
 import { connect as netConnect } from "node:net";
-import { join } from "node:path";
-import { egressArmed as egressArmedFn } from "./egress.mjs";
-import { updateEnvFile } from "./env-file.mjs";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { homedir, networkInterfaces, userInfo } from "node:os";
+import { dirname, join, posix, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PODMAN_BOOT_REFUSING_CAUSES, makePodmanInfoReader, decidePodmanJobUser, podmanJobUserRefusal } from "./backend-podman.mjs";
+import { venuesOf } from "./backends.mjs";
+import { logsDirPath, settingsFilePath } from "./config.mjs";
+import { DEFAULT_EGRESS_PROXY, egressArmed as egressArmedFn, egressProxyName } from "./egress.mjs";
+import { envKeyIsBlank, envValueShown, readEnvAssignments, updateEnvFile } from "./env-file.mjs";
+import { COMPOSE_FILE, COMPOSE_VALKEY_OVERRIDE, OWNER_MARKER_KEY, VALKEY_PASSWORD_KEY, VALKEY_PORT_KEY, OWNER_CHECK_CONTAINER, OWNER_CHECK_EXEC, VALKEY_VOLUME_RECORD, adoptVolumeQuestion, composeArgs, ownerCheckAnswer, readVolumeRecord, valkeyOwnerCheckArgs, volumeRecordMatches, volumeRecordText, composeProjectName, foreignContainerSentence, foreignMarkerRefusal, foreignVolumeLabelRefusal, foreignVolumeRefusal, foreignVolumeUsers, isLoopbackHost, newValkeyPassword, unadoptedVolumeRefusal, valkeyContainerOwner, valkeyDockerRunArgs, valkeyPasswordDecision, valkeyPortEnvDecision, valkeyVolumeCreateArgs, valkeyVolumeOwner } from "./valkey-auth.mjs";
+import { deploymentValkeyEnv, deploymentVenueEnv } from "./deployment-venue.mjs";
+import { PACKAGED_EGRESS_PROXY_CONF, judgeProxyConfCopy, packageCopyName, readPackagedProxyConf, replaceProxyConfCopy } from "./egress-conf-copy.mjs";
+import { EGRESS_PROXY_IMAGE, PROXY_STATE_FORMAT, jobNetworksOf, parseProxyState, shippedProxyDrift } from "./egress-proxy-state.mjs";
+import { DEFAULT_VALKEY_PORT, NETNS_KEEPER, NETNS_KEEPER_FORMAT, QUADLET_FILES, STACK_KEYS, applyStack, decideValkey, describeRollBack, passwdNameFrom, readSubuidRanges, rollBackWrites, valkeySharedOn, VALKEY_SHARED_KEY, readValkeyKeys, valkeyTarget, judgeNetnsKeeper, keeperUnderRunningProxyHint, managerEnvRefusal, describeAction, foreignContainerRefusal, foreignContainers, lingerNote, planStack, readLinger, readStackKeys, stackComponents, unknownContainerRefusal, userBusRefusal } from "./podman-stack.mjs";
+
+// The shipped Quadlet templates, module-relative like service.mjs's: worker/deploy in a checkout, <pkg>/deploy under npm.
+const TEMPLATES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "deploy");
 
 // The one image up may ever fetch, and the local name jobs run under. Literal on purpose (not
 // env.PI_JOB_IMAGE): an operator who pointed PI_JOB_IMAGE elsewhere has outgrown the quickstart, and
@@ -34,35 +58,20 @@ const UPSTREAM_IMAGE = "ghcr.io/edgehero/pi-job:latest";
 const LOCAL_IMAGE = "pi-job:latest";
 const PULL_ARGS = ["pull", UPSTREAM_IMAGE];
 const TAG_ARGS = ["tag", UPSTREAM_IMAGE, LOCAL_IMAGE];
+// The same two, into THIS account's rootless store (issue #430): a rootless Podman sees neither root's images nor
+// docker's. Podman's CLI takes the same argv, and `podman tag` of the short name makes `localhost/pi-job:latest`, which
+// `--pull=never` resolves `pi-job:latest` to with no registry lookup (measured, docs/podman.md step 5).
+const PODMAN_EXISTS_ARGS = ["image", "exists", LOCAL_IMAGE];
 
 // deploy/docker-compose.yml's Valkey service, reproduced as one docker run: same image, AOF on
 // (REQ-QUEUE-BURST-NO-DROP), bound to localhost only (the queue is not a public surface), same
-// healthcheck, restart unless-stopped, and a named volume standing in for the compose volume.
-const VALKEY_VOLUME_ARGS = ["volume", "create", "pi-dispatch-valkey-data"];
-const VALKEY_RUN_ARGS = [
-	"run",
-	"-d",
-	"--name",
-	"pi-dispatch-valkey",
-	"--restart",
-	"unless-stopped",
-	"-p",
-	"127.0.0.1:6379:6379",
-	"-v",
-	"pi-dispatch-valkey-data:/data",
-	"--health-cmd",
-	"valkey-cli ping",
-	"--health-interval",
-	"10s",
-	"--health-timeout",
-	"3s",
-	"--health-retries",
-	"5",
-	"valkey/valkey:8",
-	"valkey-server",
-	"--appendonly",
-	"yes",
-];
+// healthcheck, restart unless-stopped, and a named volume standing in for the compose volume. Issue #468: its password
+// travels as `-e VALKEY_PASSWORD` with the value in the docker CLI's own environment, never on an argv, and reaches
+// valkey-server as configuration on stdin (valkey-auth.mjs holds the one copy of this argv; doctor's fix runs it too).
+// The upgrade (issue #468): a pi-dispatch-valkey container that answers without a password is stopped (SIGTERM, so
+// Valkey writes its AOF out), removed, and run again from the argv above. The volume, and the queue in it, is kept.
+const VALKEY_STOP_ARGS = ["stop", "pi-dispatch-valkey"];
+const VALKEY_RM_ARGS = ["rm", "pi-dispatch-valkey"];
 
 // deploy/docker-compose.yml's `egress` profile, reproduced as one docker run (REQ-EGRESS-ALLOWLIST):
 // same digest-pinned image, same two mounts, same explicit container name, same restart policy, on the
@@ -73,6 +82,13 @@ const VALKEY_RUN_ARGS = [
 // The per-job networks are NOT here: the worker creates one per job and attaches this container to it for
 // the life of that run. This is only the proxy and its way out.
 const EGRESS_NETWORK_ARGS = ["network", "create", "pi-dispatch-egress-out"];
+// A stopped CURRENT shipped proxy is started (a paused one unpaused) as it is; a STALE one is removed and run again from
+// the argv below (issue #453; the reasons are at step e2).
+const EGRESS_START_ARGS = ["start", "pi-dispatch-egress-proxy"];
+const EGRESS_UNPAUSE_ARGS = ["unpause", "pi-dispatch-egress-proxy"];
+const EGRESS_RM_ARGS = ["rm", "-f", "pi-dispatch-egress-proxy"];
+// Issue #484: how a running proxy reads refreshed rules (see the refresh step in `runUp` for why a restart).
+const EGRESS_RESTART_ARGS = ["restart", "pi-dispatch-egress-proxy"];
 const EGRESS_RUN_ARGS = [
 	"run",
 	"-d",
@@ -82,32 +98,147 @@ const EGRESS_RUN_ARGS = [
 	"unless-stopped",
 	"--network",
 	"pi-dispatch-egress-out",
+	// `z` for the same measured reason as the compose file's mounts (issue #355): on an SELinux-enforcing host squid
+	// cannot read an unlabelled config and crash-loops; `z` (shared, never `Z`) relabels the one file so any container
+	// may read it, and is a no-op where SELinux is off.
 	"-v",
-	"./deploy/egress-proxy.conf:/etc/squid/squid.conf:ro",
+	"./deploy/egress-proxy.conf:/etc/squid/squid.conf:ro,z",
 	"-v",
-	"./egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro",
-	"ubuntu/squid@sha256:6a097f68bae708cedbabd6188d68c7e2e7a38cedd05a176e1cc0ba29e3bbe029",
+	"./egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro,z",
+	EGRESS_PROXY_IMAGE,
 ];
 
+/**
+ * Whether `p` is `folder` itself or sits inside it, compared on the separator rather than on a prefix so
+ * `/srv/deploy-old` is not read as being inside `/srv/deploy`.
+ */
+function underFolder(p, folder, platform) {
+	const norm = (x) => {
+		const slashed = String(x).replace(/\\/g, "/").replace(/\/+$/, "");
+		// Windows paths are case-insensitive and accept either separator, and `nssm-install.cmd` is a
+		// supported deployment: a byte compare there misses `c:\pi\deploy\logs` against `C:/pi/deploy`
+		// and writes exactly the value this guard exists to refuse. POSIX is case-SENSITIVE, so folding
+		// there would refuse a different directory that merely looks alike.
+		return platform === "win32" ? slashed.toLowerCase() : slashed;
+	};
+	const a = norm(p);
+	const b = norm(folder);
+	return a === b || a.startsWith(`${b}/`);
+}
+
 export async function runUp(argv = [], deps = {}) {
 	const {
 		env = process.env,
 		spawn = nodeSpawn,
 		out = (s) => process.stdout.write(s),
 		prompt = defaultPrompt,
-		fs = { existsSync, readFileSync, writeFileSync, renameSync, statSync, chmodSync },
+		// `realpathSync` is in this list for a reason worth keeping: `updateEnvFile` resolves the path so a
+		// `.env` symlinked at a shared env file is edited THROUGH the link rather than replaced by a
+		// regular file. It calls it optionally, so leaving it out here made that repair dead code in the
+		// only production caller, and the test that covered it attached the method to its own fake.
+		// `lstatSync` for the rules refresh (issue #484), which follows no symlink.
+		fs = { existsSync, lstatSync, readFileSync, writeFileSync, renameSync, statSync, chmodSync, realpathSync, unlinkSync },
 		probeTcp = defaultProbeTcp,
+		// Issue #468: whether the Valkey on 127.0.0.1:6379 answers a client that sends NO password ("ok" when it does),
+		// through the project's one connection function. Real only where the TCP probe is: a test that stands in for the
+		// host's listener answers this too, or gets "unknown".
+		probeValkeyAuth = deps.probeTcp === undefined ? (url) => defaultProbeValkeyAuth(url, { env, cwd: deps.cwd ?? process.cwd() }) : async () => "unknown",
+		// PR #475's review (the volume gap): record, then read back, the `pi-dispatch:owner` marker in a Valkey this pass
+		// started (connection.mjs' `claimValkeyOwner`). Real only where the TCP probe is, like the one above: a test that
+		// stands in for the host's listener answers this too, or gets "this folder".
+		claimValkeyOwner = deps.probeTcp === undefined ? (url, folder) => defaultClaimValkeyOwner(url, folder, { env, cwd: deps.cwd ?? process.cwd() }) : async (_url, folder) => ({ owner: folder, claimed: false }),
+		// Issue #464: VALKEY_URL's host resolved as the worker's client resolves it (every address), and which addresses
+		// are this host's, for the Valkey owner rule on the podman venue.
+		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),
 		cwd = process.cwd(),
 		// Injected so tests can assert the secret never reaches output without fishing it back out of
 		// the written file. 32 bytes hex, matching doctor's `openssl rand -hex 32` fix line.
+		// The owner check's wait while its Valkey loads the queue (PR #475's round-cap re-review); a seam for its test.
+		sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
 		randomHex = () => randomBytes(32).toString("hex"),
+		// Issue #468: the Valkey password, made the same way (valkey-auth.mjs), injected so a test can hold it never
+		// reaches the output.
+		newPassword = newValkeyPassword,
+		// Injected for the path compare below, which has to fold case on Windows and must not on POSIX.
+		platform = process.platform,
+		// The two resolved defaults `up` pins, injected for the same reason the clock is elsewhere: they
+		// read the real `homedir()`, so a test asserting the written `.env` byte for byte would otherwise
+		// assert whichever account ran it.
+		logsDirPathFn = logsDirPath,
+		settingsFilePathFn = settingsFilePath,
+		// The podman venue's seams (issue #430). The info read is the venue's own bounded reader, so `up` asks exactly
+		// the question the worker asks at boot; the ids are the ones the job-user rule judges.
+		readPodmanInfo = makePodmanInfoReader(),
+		euid = typeof process.geteuid === "function" ? process.geteuid() : null,
+		egid = typeof process.getegid === "function" ? process.getegid() : null,
+		home = homedir(),
+		// Whose linger `up` reads after starting the podman stack: the login already running it, as service.mjs reads
+		// it. Resolved LAZILY (`userName` below), never as a default here: `userInfo()` throws for a uid with no passwd
+		// entry, and the docker path, which never asks, must not die of it.
+		user,
+		userInfoFn = userInfo,
+		templatesDir = TEMPLATES_DIR,
+		// The shipped Quadlet templates are the package's files, read for real even where `fs` is a test's fake of the
+		// deployment folder; injectable so a test can hand in its own.
+		readTemplate = (name) => readPackageFile(join(templatesDir, name), "utf8"),
+		mkdir = mkdirSync,
+		// Issue #484: the installed package's rules, which a differing folder copy is compared with and refreshed from, and
+		// the clock the backup's name is stamped with.
+		readPackagedConf = readPackagedProxyConf,
+		now = Date.now,
 	} = deps;
 	let { runInitFn, runDoctorFn } = deps;
 	const yes = argv.includes("--yes");
 	const summary = [];
+	// env-internal USER: the login running `up`, only ever read on the podman path (see the `user` seam above).
+	const userName = () => user ?? (env.USER || userInfoFn().username);
 
+	// The venue keys, from the same place `service install` reads them (issue #430 review, D2). Nothing loads `.env`
+	// into a process, so `up` used to decide the venue from this shell alone: an operator who followed the docs and put
+	// PI_BACKENDS=podman in `.env` got the docker pass, and the service they installed next got podman. A key the shell
+	// sets and the file does not is taken from the shell (what the wizard relies on when it runs `up` with
+	// PI_BACKENDS=podman before init has written `.env`); `.env` fills the keys the shell leaves unset; a key BOTH set
+	// differently stops `up` (round 2, E5), because the service will run the file's value. A `.env` line touching one
+	// of these keys that the loaders read differently stops `up` before anything runs, as `service install` refuses.
+	const venue = deploymentVenueEnv({ env, fs, envPath: join(cwd, ".env"), platform, command: "up" });
+	if (venue.error) {
+		out(`✗ ${venue.error}\n\nup: cannot tell which venue this deployment runs: fix the above, then re-run \`pi-dispatch up\`.\n`);
+		return 1;
+	}
+	for (const line of venue.notes) out(`⚠ ${line}\n`);
+	const venueEnv = venue.env;
+
+	// Which runtimes this pass drives (issue #430). With `local` blessed (which the unset default is) everything below
+	// is exactly what it always was, and a list that also names podman adds the podman steps after the docker ones. A
+	// list WITHOUT `local` never touches docker at all: such a host may have no docker, and asking it would only fail.
+	const venues = venuesOf(venueEnv);
+	const dockerUsed = venues.localUsed;
+	// Issue #464: which Valkey the SERVICE's worker will use, and whether PI_VALKEY_SHARED lets it be one another uid
+	// holds, read from `.env` where `service install` reads them, with this shell's value only where the file sets none.
+	// Asked only where the podman stack decides its Valkey (docker's Valkey is the queue wherever `local` is blessed),
+	// and before anything runs, as the venue keys are.
+	let valkeyKeys = { env: {}, fromFile: {}, notes: [] };
+	if (venues.podmanUsed && !venues.localUsed) {
+		valkeyKeys = deploymentValkeyEnv({ env, fs, envPath: join(cwd, ".env"), platform });
+		if (valkeyKeys.error) {
+			out(`✗ ${valkeyKeys.error}\n\nup: cannot tell which Valkey this deployment's worker uses: fix the above, then re-run \`pi-dispatch up\`.\n`);
+			return 1;
+		}
+		for (const line of valkeyKeys.notes) out(`⚠ ${line}\n`);
+	}
+	//
+	// The docker lines below keep their original text and indentation, the `else` and the unbraced block included, so
+	// that the diff of issue #430 shows the docker path as the byte-identical thing its tests pin it to be.
+	if (!dockerUsed) out("pi-dispatch up: one pass over the quickstart for the podman venue; every podman and systemctl action asks first (--yes accepts)\n\n");
+	else
 	out("pi-dispatch up — one pass over the quickstart; every docker action asks first (--yes accepts)\n\n");
 
+	if (dockerUsed) {
 	// (a) docker binary + daemon, before anything is offered: every mutation below runs through the
 	// docker CLI, so with the daemon down the prompts would only collect consent for failures.
 	// Distinguishes not-on-PATH from daemon-down exactly as doctor does (spawn error vs nonzero exit).
@@ -144,33 +275,24 @@ export async function runUp(argv = [], deps = {}) {
 		}
 	}
 
-	// (c) Valkey. A bare TCP probe of the default bind, not a redis PING: dependency-free, and the
-	// honest claim is only "something is listening". If our own compose-named container is up, docker
-	// can say so; if a listener exists that we cannot name, up must NOT offer a second Valkey — the
-	// port is taken, and `docker run` would only fail after consent.
-	if (await probeTcp("127.0.0.1", 6379)) {
-		const ps = await runCmdCapture(spawn, "docker", ["ps", "--filter", "name=pi-dispatch-valkey", "--format", "{{.Names}}"]);
-		const ours = ps.code === 0 && ps.output.split("\n").map((l) => l.trim()).includes("pi-dispatch-valkey");
-		out(`✓ something is listening on 6379 — assuming your Valkey${ours ? " (it is the pi-dispatch-valkey container)" : ""}\n`);
-		summary.push(["valkey", ours ? "container pi-dispatch-valkey already running" : "port 6379 already has a listener — left alone"]);
-	} else {
-		const accepted = await consent(
-			"Nothing is listening on 127.0.0.1:6379. up would start Valkey (same semantics as deploy/docker-compose.yml):",
-			[`docker ${VALKEY_VOLUME_ARGS.join(" ")}`, `docker ${quoteArgs(VALKEY_RUN_ARGS)}`],
-			{ yes, out, prompt },
-		);
-		if (!accepted) {
-			out("skipped — start it later with `docker compose -f deploy/docker-compose.yml up -d`\n");
-			summary.push(["valkey", "skipped (declined) — the queue needs it before `pi-dispatch worker` can drain"]);
-		} else if (await runStreamed(spawn, "docker", VALKEY_VOLUME_ARGS, out) !== 0) {
-			out("✗ docker volume create failed — continuing; doctor below will re-check Valkey\n");
-			summary.push(["valkey", "volume create FAILED — `docker compose -f deploy/docker-compose.yml up -d` is the fallback"]);
-		} else if (await runStreamed(spawn, "docker", VALKEY_RUN_ARGS, out) !== 0) {
-			out("✗ docker run failed — continuing; doctor below will re-check Valkey\n");
-			summary.push(["valkey", "container start FAILED — `docker compose -f deploy/docker-compose.yml up -d` is the fallback"]);
+	}
+
+	// (a2)(b2) the podman venue: its gate and its job image, in this account's own store (issue #430). `podmanReady`
+	// is what lets the stack step below run at all.
+	let podmanReady = false;
+	let valkeyRefused = false;
+	if (venues.podmanUsed) {
+		const gate = await podmanGate({ readPodmanInfo, platform, euid, egid, out });
+		if (!gate.ok) {
+			summary.push(["podman", `NOT ready: ${gate.why}`]);
+			if (!dockerUsed) {
+				out("\nup: cannot continue without a usable rootless Podman: fix the above, then re-run `pi-dispatch up`.\n");
+				return 1;
+			}
+			out("  the docker steps above are unaffected; the podman steps below are skipped\n");
 		} else {
-			out("✓ started Valkey (container pi-dispatch-valkey, AOF on, bound to 127.0.0.1)\n");
-			summary.push(["valkey", "started container pi-dispatch-valkey (durable: --appendonly yes, restart unless-stopped)"]);
+			podmanReady = true;
+			await podmanImageStep({ spawn, out, yes, prompt, summary });
 		}
 	}
 
@@ -179,24 +301,453 @@ export async function runUp(argv = [], deps = {}) {
 	// nothing the operator wrote can be lost here.
 	out("\ninit (never overwrites — an existing file is reported and kept):\n");
 	runInitFn ??= (await import("./init.mjs")).runInit;
-	runInitFn(cwd, { out });
-	summary.push(["init", "ran — existing files were kept untouched, missing ones scaffolded"]);
+	// The venues THIS pass decided (issue #453), so init decides nothing of its own here. And no "Next:" from init (issue
+	// #480): that ladder is this pass, so printing it here told a reader to pull the image and start Valkey by hand while
+	// `up` was doing both; the created and kept lines stay, and `up` closes with its own next steps below.
+	// A throw here (a folder init cannot write, PR #488's review) is said and the pass goes on: the steps below and doctor
+	// still say what else is missing, and an aborted `up` said nothing after the image pull.
+	let initCode;
+	try {
+		initCode = runInitFn(cwd, { out, venues, steps: false });
+	} catch (err) {
+		initCode = null;
+		out(`✗ init could not finish: ${err?.message ?? err}\n`);
+	}
+	if (initCode === 1) summary.push(["init", "ran, and REFUSED a file (said above); the others were kept or scaffolded"]);
+	else if (initCode === null) summary.push(["init", "FAILED (said above); the steps below still ran"]);
+	else summary.push(["init", "ran: existing files were kept untouched, missing ones scaffolded"]);
 
 	// (e) WEBHOOK_SECRET, only into a .env that exists (init just scaffolded one unless the operator
 	// keeps env elsewhere — a service-manager deployment gets no file invented for it). Same
 	// never-clobber contract at key granularity: a value the operator set survives. The value itself
 	// is NEVER printed — a webhook secret in a scrollback is a webhook secret in a pastebin.
 	const envPath = join(cwd, ".env");
+	// WHAT AN EMPTY VALUE COSTS IS PER KEY, and the first version of this said one thing for all five.
+	// `config.mjs` reads these two with `??`, so an empty string survives, and `start.mjs` calls
+	// `loadPauseWindows`/`loadScopedLimits` unconditionally at boot, which throw on a path that does not
+	// exist: the worker does not ignore the feature, it refuses to start. `PI_LOGS_DIR` and
+	// `PI_SETTINGS_FILE` use `||` and fall back to the account default; `WEBHOOK_SECRET` reads as absent.
+	const EMPTY_REFUSES_BOOT = new Set(["PI_PAUSE_WINDOWS_FILE", "PI_SCOPED_LIMITS_FILE"]);
+	const emptyNote = (key) =>
+		EMPTY_REFUSES_BOOT.has(key)
+			? `left untouched: the line is there and its value is EMPTY, which is not the same as no line -- a shell that sources this file exports it as "", the worker keeps it and REFUSES TO BOOT. up never clobbers a key an operator wrote, so fill it in or delete the line`
+			: `left untouched: the line is there and its value is empty, which reads as unset. up never clobbers a key an operator wrote, so fill it in or delete the line`;
+	// The blank test is `env-file.mjs`'s, and the reader underneath it is the one doctor uses -- which is
+	// what issue #365 was actually about: two callers answering "is this key set" with two hand-rolled
+	// regexes is how `up` and doctor came to print opposite sentences about one file in one run.
+	//
+	// NOT the same CALL, since issue #384, and the difference is the consequence rather than the question.
+	// `up` prints a sentence, so it asks the loose per-line answer and prefers "EMPTY" to "already set" on a
+	// file it cannot fully read. Doctor's answer becomes an exit code, so it asks the same reader for the
+	// platform's own loader and requires the vouch beside it: a refusal reached by inference is the one
+	// verdict this project will not print.
+	const writtenButEmpty = (key) => {
+		try {
+			return envKeyIsBlank(String(fs.readFileSync(envPath, "utf8")), key);
+		} catch {
+			return false;
+		}
+	};
+	// Windows takes forward slashes everywhere Node does, and writing them is what keeps these four values
+	// inside the BARE set: `deploy/worker-env-wrapper.cmd` says "Values MUST be UNQUOTED -- cmd's `set`
+	// keeps surrounding quotes as part of the value", so a quoted `C:\pi\deploy\logs` there is a
+	// directory that does not exist, behind a ✓. `config.mjs`'s own defaults are already spelled this way.
+	const forEnvFile = (value) => (platform === "win32" ? String(value).replace(/\\/g, "/") : value);
+	// What `up` wrote, layered over `env` for its OWN doctor step below. Writing a line into `.env`
+	// configures the SERVICE (through `EnvironmentFile=` and the wrappers) and configures nothing about the
+	// process running right now, because NOTHING in this project loads `.env` into an environment -- see
+	// `docs/secrets.md`, and `worker/test/service.test.mjs` pins that a `PI_ENV_SETUP` line in `./.env` is
+	// deliberately not honoured. Without this layer, `up` would write the two files' paths and then, three
+	// lines later, warn that they are unset (issue #357).
+	const wrote = {};
 	if (fs.existsSync(envPath)) {
-		if (updateEnvFile(envPath, "WEBHOOK_SECRET", randomHex(), { fs }).changed) {
-			out("\n✓ generated WEBHOOK_SECRET into .env (32 random bytes, hex — value not shown)\n");
-			summary.push(["WEBHOOK_SECRET", "generated into .env (value not shown; the receiver verifies deliveries with it)"]);
-		} else {
-			out("\n✓ WEBHOOK_SECRET already set in .env — left untouched\n");
-			summary.push(["WEBHOOK_SECRET", "already set — left untouched"]);
+		// Wrapped like the four below it, and for the same reasons: a read-only deployment directory, a full
+		// disk, a `.env` this account does not own. Unwrapped, `up` died with a raw stack trace where a
+		// summary row was the whole point.
+		try {
+			if (updateEnvFile(envPath, "WEBHOOK_SECRET", randomHex(), { fs, platform }).changed) {
+				out("\n✓ generated WEBHOOK_SECRET into .env (32 random bytes, hex — value not shown)\n");
+				summary.push(["WEBHOOK_SECRET", "generated into .env (value not shown; the receiver verifies deliveries with it)"]);
+			} else {
+				const empty = writtenButEmpty("WEBHOOK_SECRET");
+				// ⚠ and not ✓ for the empty line: every other ✓ in this block means "this is fine", and an empty
+				// secret is a key the operator has to go and fill in.
+				out(empty ? `\n⚠ WEBHOOK_SECRET has a line in .env and its value is EMPTY — left untouched\n` : "\n✓ WEBHOOK_SECRET already set in .env — left untouched\n");
+				summary.push(["WEBHOOK_SECRET", empty ? emptyNote("WEBHOOK_SECRET") : "already set — left untouched"]);
+			}
+		} catch (err) {
+			out(`\n✗ WEBHOOK_SECRET could not be written: ${err?.message}\n`);
+			summary.push(["WEBHOOK_SECRET", `NOT written: ${err?.message}`]);
+		}
+		// (e1) the four paths four separate files already promise `up` writes, and it never did
+		// (`deploy/worker.service`, `deploy/com.pi-dispatch.worker.plist`, `deploy/nssm-install.cmd`,
+		// `.env.example`). Same never-clobber discipline as WEBHOOK_SECRET, at key granularity: a value the
+		// operator set survives untouched.
+		//
+		// TWO get the deployment folder and TWO get the RESOLVED ACCOUNT DEFAULT, and the split is the
+		// sharpest edge in this change rather than an inconsistency. `pause-windows.json` and
+		// `scoped-limits.json` are scaffolded by `init` into this folder, and the panel defaults to this
+		// folder, so pointing the worker here is what makes the three agree. `PI_LOGS_DIR` and
+		// `PI_SETTINGS_FILE` are different in kind: `makeLogReaper` unlinks EVERY `.log` and `.json` in
+		// `PI_LOGS_DIR` past the window with no name shape and no ownership check, so a deployment folder
+		// there would eat `triggers.json`, `pause-windows.json`, `scoped-limits.json` and
+		// `subscriptions.json` thirty days in, silently, and the worker would then run nothing while
+		// reporting success. `<deployment>/logs` is no better: `service.mjs` creates exactly that directory
+		// at install time and the plist puts `worker.out.log` in it. So these two get what
+		// `logsDirPath`/`settingsFilePath` would have resolved anyway: behaviour byte-unchanged, the value
+		// simply made explicit, which is the whole point -- a worker under another `User=` and the panel
+		// then cannot silently resolve two different directories.
+		for (const [key, raw, durable] of [
+			["PI_PAUSE_WINDOWS_FILE", join(cwd, "pause-windows.json"), false],
+			["PI_SCOPED_LIMITS_FILE", join(cwd, "scoped-limits.json"), false],
+			["PI_LOGS_DIR", logsDirPathFn(env), true],
+			["PI_SETTINGS_FILE", settingsFilePathFn(env), true],
+		]) {
+			const value = forEnvFile(raw);
+			// `logsDirPath` and `settingsFilePath` RESOLVE rather than default: `env.PI_LOGS_DIR || <default>`.
+			// So on a shell that already exports one of them at the deployment folder -- which three shipped
+			// files told operators to do for a year, before this change made the promise true -- `up` would
+			// persist exactly the value the rest of this block exists to prevent, and print a ✓ over it. The
+			// refusal is here rather than in the resolver because the resolver is right for every other
+			// caller: the worker SHOULD honour an exported path. What must never happen is `up` writing one
+			// into the deployment's permanent config without anyone deciding to.
+			// TWO refusals, and both are about the same resolver. `logsDirPath` is `env.PI_LOGS_DIR || <default>`,
+			// so whatever this shell exports passes straight through, unvalidated and un-absolutised.
+			//
+			// RELATIVE is the sharper of the two and it is not hypothetical: `PI_LOGS_DIR=.` resolves against
+			// the unit's `WorkingDirectory`, which IS the deployment folder, so the retention sweep then
+			// deletes `triggers.json`, `pause-windows.json`, `scoped-limits.json` and `subscriptions.json`
+			// thirty days in. All three deploy templates document this key as absolute for exactly that
+			// reason. INSIDE THIS FOLDER is the same harm reached with an absolute path.
+			//
+			// The refusals live here and not in the resolver, because the resolver is right for the worker:
+			// an exported path SHOULD be honoured at run time. What must never happen is `up` copying one
+			// into the deployment's permanent config, where it outlives the shell that set it.
+			// Only a value THIS SHELL supplied is checked, and that narrowing matters both ways. The hazard
+			// is the pass-through: `logsDirPath` is `env.PI_LOGS_DIR || <default>`, so an exported value
+			// lands in the deployment's permanent config where it outlives the shell that set it. The
+			// computed default is never a hazard even when it sits under `cwd` -- a deployment folder that
+			// IS the service account's home makes `<home>/.pi-dispatch/logs` "inside" it, and refusing
+			// there would reject the very path the worker resolves anyway, with a message blaming the
+			// operator for a layout that is fine.
+			const fromShell = typeof env[key] === "string" && env[key].trim() !== "";
+			// Both checks follow the INJECTED platform, not this process's. `node:path`'s default export is
+			// already the right one in production, but a drive-letter path is "relative" to the posix
+			// implementation, so a test running on POSIX would see the absolute check short-circuit and
+			// never reach the folder compare it meant to exercise. Choosing explicitly makes the Windows
+			// half of both rules reachable from a test on any host, which is the only way `nssm-install.cmd`
+			// gets covered at all.
+			const isAbsoluteOn = platform === "win32" ? win32.isAbsolute : posix.isAbsolute;
+			const why = !durable || !fromShell ? null : !isAbsoluteOn(value) ? "is not an absolute path, and a relative one resolves against the service's WorkingDirectory, which is this folder" : underFolder(value, cwd, platform) ? "is inside this deployment folder" : null;
+			if (why) {
+				out(`✗ ${key} is ${value} in this shell, which ${why} — not written into .env\n`);
+				summary.push([key, `NOT written: ${key} is set to ${value} in the environment you ran up from, and that ${why}. The log retention sweep deletes every .log and .json there past its window, so this would be persisted for the service. Unset it here, or set it by hand to a directory the worker owns`]);
+				continue;
+			}
+			// A path this file cannot represent so that BOTH consumers read it back is refused rather than
+			// mangled: `renderEnvValue` throws on a single quote, which the shells want escaped as `'\''`
+			// and systemd's parser does not understand.
+			let changed;
+			try {
+				({ changed } = updateEnvFile(envPath, key, value, { fs, platform }));
+			} catch (err) {
+				out(`✗ ${key} could not be written: ${err?.message}\n`);
+				summary.push([key, `NOT written: ${err?.message}. Set it by hand, or move the deployment somewhere without that character in its path`]);
+				continue;
+			}
+			if (changed) {
+				wrote[key] = value;
+				out(`✓ ${key}=${value} written into .env\n`);
+				summary.push([key, `written into .env (${value})`]);
+			} else {
+				summary.push([key, writtenButEmpty(key) ? emptyNote(key) : "already set — left untouched"]);
+			}
 		}
 	} else {
 		summary.push(["WEBHOOK_SECRET", "no .env here — skipped (set it wherever your env lives)"]);
+		for (const key of ["PI_PAUSE_WINDOWS_FILE", "PI_SCOPED_LIMITS_FILE", "PI_LOGS_DIR", "PI_SETTINGS_FILE"]) {
+			summary.push([key, "no .env here — skipped (set it wherever your env lives)"]);
+		}
+	}
+
+	// (e0) VALKEY_PASSWORD (issue #468), where docker's Valkey is the queue: generated into .env when the deployment has
+	// none and runs a Valkey of its own on this host (`valkeyPasswordDecision`), never over a value, the file narrowed to
+	// this account, the value never printed. The podman venue's Valkey gets its password in the stack step below.
+	const dockerValkeyPassword = dockerUsed ? dockerValkeyPasswordStep({ fs, envPath, platform, out, summary, newPassword }) : null;
+
+	if (dockerUsed) {
+	// (c) Valkey. A bare TCP probe of the default bind, not a redis PING: dependency-free, and the
+	// honest claim is only "something is listening". If our own compose-named container is up, docker
+	// can say so; if a listener exists that we cannot name, up must NOT offer a second Valkey; the
+	// port is taken, and `docker run` would only fail after consent.
+	//
+	// AFTER init and the .env keys since issue #468, where it used to run first: the Valkey this step starts takes its
+	// password from `.env`, which a fresh folder has only once init has scaffolded it. The prompts keep their order
+	// (the image, then Valkey, then the egress proxy), since init and the .env keys ask nothing.
+	const dockerEnv = { ...env };
+	// The deployment's password, and never a shell's: the container must start with the one the service's clients send.
+	if (dockerValkeyPassword) dockerEnv[VALKEY_PASSWORD_KEY] = dockerValkeyPassword;
+	else delete dockerEnv[VALKEY_PASSWORD_KEY];
+	// WHERE, from VALKEY_URL as the service reads it (`deploymentValkeyEnv`, the podman step's reader since #464; read
+	// here, after init, so a fresh folder's scaffolded .env counts): its loopback port is probed and published. It was
+	// always 6379, so a deployment whose VALKEY_URL named another port was told "nothing is listening" and given a
+	// Valkey its worker never dialled, or had its own listener on that port ignored. Another host: nothing is added
+	// here. An IPv6 literal cannot reach a Valkey published on 127.0.0.1, so it is refused with the fix.
+	const dockerValkey = dockerValkeyWhere({ env, fs, envPath, platform });
+	for (const note of dockerValkey.notes) out(`⚠ ${note}\n`);
+	const vport = dockerValkey.port;
+	// THE rule (PR #475's review, round 3): a Valkey container or volume is this deployment's only when it is PROVABLY
+	// this deployment's (valkey-auth.mjs, `valkeyContainerIsOurs`): up's label naming this folder, compose's working dir
+	// here, or, for a legacy unlabelled pi-dispatch-valkey, this deployment's VALKEY_URL port. Anything else is never
+	// stopped, removed or reused, and no Valkey is started on the volume while one that is not ours mounts it.
+	let deployment = cwd;
+	try {
+		deployment = realpath(cwd);
+	} catch {
+		// Unresolvable: the folder as given.
+	}
+	const dirs = [deployment, cwd];
+	const query = (cmd, args) => runCmdQuery(spawn, cmd, args);
+	const VALKEY_RUN_ARGS = valkeyDockerRunArgs({ port: vport, deployment });
+	// Labelled with this folder when up creates it (the volume gap): a label cannot be added later.
+	const VALKEY_VOLUME_ARGS = valkeyVolumeCreateArgs(deployment);
+	// PI_VALKEY_PORT into .env where VALKEY_URL's port is not 6379 (round 3), so a plain compose run in this folder
+	// publishes where the worker dials; never over a different value, which is named instead.
+	if (!dockerValkey.error && !dockerValkey.remote) dockerValkeyPortStep({ fs, envPath, platform, port: vport, out, summary });
+	// Before any start on pi-dispatch-valkey-data: refused, named, while a container that is not ours mounts it.
+	const volumeClear = async () => {
+		const check = await foreignVolumeUsers({ dirs, port: vport, query });
+		if (!check.unknown && check.foreign.length === 0) return true;
+		valkeyRefused = "volume";
+		out(`✗ ${foreignVolumeRefusal(check)}\n`);
+		summary.push(["valkey", `NOT started: ${foreignVolumeRefusal(check)}`]);
+		return false;
+	};
+	// The volume's own owner (PR #475's review, the volume gap: with no container on it, a second deployment's `up` started
+	// on the first one's queue). Another folder's label: never used. No label (made before the label, or by hand): used
+	// only after a question that --yes does not answer, since that queue cannot be attributed; `servedByOurs` where this
+	// deployment's own container serves it now (the upgrade restart), which attributes it. Sets `volumeState`.
+	let volumeState = null;
+	const volumeUsable = async ({ servedByOurs = false } = {}) => {
+		const v = await valkeyVolumeOwner({ dirs, query });
+		const refuse = (why) => {
+			valkeyRefused = "volume";
+			out(`✗ ${why}\n`);
+			summary.push(["valkey", `NOT started: ${why}`]);
+			return false;
+		};
+		if (v.unknown) return refuse(`whose pi-dispatch-valkey-data is could not be read (${v.unknown}), so no Valkey is started on it`);
+		if (v.ours === false) return refuse(foreignVolumeLabelRefusal(v.owner));
+		// Adopted before (PR #475's round-cap re-review): the record in this folder names this very volume by its CreatedAt.
+		if (v.unlabelled && volumeRecordMatches(readVolumeRecord(cwd, fs), v)) {
+			volumeState = "recorded";
+			return true;
+		}
+		if (v.unlabelled && !servedByOurs) {
+			out("\n");
+			if (!/^y(es)?$/i.test(String((await prompt(adoptVolumeQuestion(deployment))) ?? "").trim())) return refuse(unadoptedVolumeRefusal());
+			// Whose queue it holds, read BEFORE any Valkey on it is published (round-cap re-review: a wrong `y` ran this
+			// deployment's Valkey on another's data for a second): a Valkey with no network loads it, and its marker is read
+			// through `docker exec`.
+			const check = await ownerPreCheck();
+			if (check.error) return refuse(`whose queue pi-dispatch-valkey-data holds could not be read before starting (${check.error}), so no Valkey is started on it`);
+			if (check.owner && !dirs.includes(check.owner)) return refuse(`${foreignMarkerRefusal(check.owner)}: read by a Valkey with no network, so no Valkey was published on it`);
+			recordVolume(v);
+			volumeState = "adopted";
+			return true;
+		}
+		// Served by this deployment's own container now (the upgrade restart), which attributes it: recorded too.
+		if (v.unlabelled && servedByOurs) recordVolume(v);
+		volumeState = v.absent ? "absent" : v.unlabelled ? "served" : "ours";
+		return true;
+	};
+	// The owner check itself: `valkeyOwnerCheckArgs` (no network, no port, no password), the marker read through
+	// `docker exec`, retried while the queue loads, and the container stopped and removed whatever it answered.
+	const ownerPreCheck = async () => {
+		out(`checking whose queue it holds first, with a Valkey that has no network:\n  docker ${valkeyOwnerCheckArgs(deployment).join(" ")}\n  docker ${OWNER_CHECK_EXEC.join(" ")}\n`);
+		if ((await runStreamed(spawn, "docker", valkeyOwnerCheckArgs(deployment), out)) !== 0) return { error: `its docker run failed (a leftover ${OWNER_CHECK_CONTAINER}? \`docker rm -f ${OWNER_CHECK_CONTAINER}\`)` };
+		try {
+			for (let i = 0; i < 40; i++) {
+				const a = ownerCheckAnswer(await runCmdQuery(spawn, "docker", OWNER_CHECK_EXEC));
+				if (!a.retry) return a;
+				await sleep(500);
+			}
+			return { error: "its Valkey did not answer within 20 s" };
+		} finally {
+			await runStreamed(spawn, "docker", ["stop", OWNER_CHECK_CONTAINER], out);
+			await runStreamed(spawn, "docker", ["rm", OWNER_CHECK_CONTAINER], out);
+		}
+	};
+	// The adoption's record (round-cap re-review): create-only, 0600, never over a different one.
+	const recordVolume = (v) => {
+		const path = join(cwd, VALKEY_VOLUME_RECORD);
+		// Nothing to record where docker gave no CreatedAt: the next `up` asks again.
+		if (typeof v.createdAt !== "string" || v.createdAt === "") return;
+		try {
+			if (fs.existsSync(path)) {
+				if (!volumeRecordMatches(readVolumeRecord(cwd, fs), v)) out(`⚠ ${path} names another pi-dispatch-valkey-data and is left as it is: this adoption is not recorded, so the next \`up\` asks again\n`);
+				return;
+			}
+			fs.writeFileSync(path, volumeRecordText(v), { mode: 0o600, flag: "wx" });
+			out(`✓ recorded the adopted volume (its CreatedAt) in ${path}, so a later \`up\` uses it without asking\n`);
+		} catch (err) {
+			out(`⚠ the adoption could not be recorded in ${path} (${err?.message ?? err}), so the next \`up\` asks again\n`);
+		}
+	};
+	// After every start on the volume: the queue's own `pi-dispatch:owner`, recorded where it is missing and checked where
+	// it is not. Another folder's stops what this pass just started, at once (`stop`), and fails up.
+	const ownerMarkerOk = async (stop) => {
+		const r = await claimValkeyOwner(`redis://127.0.0.1:${vport}`, deployment);
+		if (r.error) {
+			valkeyRefused = "marker";
+			out(`✗ Valkey was started, but its ${OWNER_MARKER_KEY} could not be recorded or read (${r.error}), so whose queue it holds is unconfirmed\n`);
+			summary.push(["valkey", `started, owner marker UNREAD: ${r.error}`]);
+			return false;
+		}
+		if (!dirs.includes(r.owner)) {
+			valkeyRefused = "volume";
+			const stopped = await stop();
+			out(`✗ ${foreignMarkerRefusal(r.owner)}: the Valkey this pass started on it was ${stopped ? "stopped again at once" : "NOT stopped (the stop failed): stop it now"}\n`);
+			summary.push(["valkey", `STOPPED: ${foreignMarkerRefusal(r.owner)}`]);
+			return false;
+		}
+		if (r.claimed) out(`✓ recorded ${OWNER_MARKER_KEY}=${deployment} in its queue\n`);
+		return true;
+	};
+	const stopRun = async () => (await runStreamed(spawn, "docker", VALKEY_STOP_ARGS, out)) === 0 && (await runStreamed(spawn, "docker", VALKEY_RM_ARGS, out)) === 0;
+	// A folder the setup wizard handed to compose (PR #475's review): its Valkey is compose's valkey, named by the folder's
+	// project and the override, published on VALKEY_URL's port through PI_VALKEY_PORT.
+	const handedOver = fs.existsSync(join(cwd, COMPOSE_VALKEY_OVERRIDE));
+	const project = composeProjectName(cwd);
+	const composeBase = composeArgs(handedOver ? { project, override: true } : {});
+	const composeEnv = { ...dockerEnv, [VALKEY_PORT_KEY]: String(vport) };
+	const ourName = handedOver ? `${project}-valkey-1` : "pi-dispatch-valkey";
+	const shownCompose = (args) => `${vport !== 6379 ? `${VALKEY_PORT_KEY}=${vport} ` : ""}docker ${quoteArgs(args)}`;
+	const composeNote = handedOver ? "" : ` (in a folder /dispatch setup laid out, with -p ${project} after \`compose\`)`;
+	// Issue #480: a compose line is a way to start Valkey later only where the folder holds the compose file (a clone, or
+	// a folder /dispatch setup copied it into). A folder init made has none, and there the way is this command again.
+	const laterValkey = () => (composeHere(cwd, fs) ? `start it later with \`${shownCompose([...composeBase, "up", "-d"])}\`${composeNote}` : "start it later by running `pi-dispatch up` again and accepting");
+	let existing = null;
+	if (dockerValkey.error) {
+		valkeyRefused = "url";
+		out(`✗ ${dockerValkey.error}\n`);
+		summary.push(["valkey", `NOT added: ${dockerValkey.error}`]);
+	} else if (dockerValkey.remote) {
+		out(`✓ VALKEY_URL names ${dockerValkey.remote}, not this host, so no Valkey is added here\n`);
+		summary.push(["valkey", "VALKEY_URL names another host, nothing added here"]);
+	} else if (await probeTcp("127.0.0.1", vport)) {
+		const who = await valkeyContainerOwner(ourName, { dirs, port: vport, query });
+		const ours = who.ours === true;
+		out(`✓ something is listening on ${vport}, assuming your Valkey${ours ? ` (it is the ${ourName} container)` : ""}\n`);
+		if (who.ours === false) out(`⚠ ${foreignContainerSentence(ourName, who.owner)}\n`);
+		// Issue #468: a Valkey there that answers a client sending NO password, while this deployment has one, was started
+		// before the password existed (the upgrade of a deployment that had none). Ours is offered a restart with it; one
+		// we did not start is named, with the compose command that recreates the compose-started one.
+		const open = dockerValkeyPassword ? (await probeValkeyAuth(`redis://127.0.0.1:${vport}`)) === "ok" : false;
+		const cost = "A job running right now is interrupted, and the worker and the receiver get NOAUTH until they are restarted: pause first if a job runs (pi-dispatch pause, wait for active jobs, then pi-dispatch resume after the restart)";
+		if (open && ours && handedOver) {
+			// The wizard handed this folder's Valkey to compose (PR #475's review): compose recreates it with the password,
+			// on the same volume, where `docker run` would start a second one beside it.
+			const recreate = [...composeBase, "up", "-d", "--force-recreate", "valkey"];
+			const accepted = (await volumeClear()) && (await volumeUsable({ servedByOurs: true })) ? await consent(`${ourName} answers without a password, and ${VALKEY_PASSWORD_KEY} is set in .env. up would recreate it with the password (compose stops it first, so Valkey writes its AOF out; the pi-dispatch-valkey-data volume, and the queue in it, is kept). ${cost}:`, [shownCompose(recreate)], { yes, out, prompt }) : null;
+			if (accepted === null) {
+				// Refused above (`volumeClear` said why): nothing was asked, so nothing was declined.
+			} else if (!accepted) {
+				out(`skipped: until it restarts with ${VALKEY_PASSWORD_KEY}, any local account can reach this queue\n`);
+				summary.push(["valkey", `${ourName} runs WITHOUT a password (declined the restart with it); \`pi-dispatch up\` again offers it`]);
+			} else {
+				const code = await runStreamed(spawn, "docker", recreate, out, { env: composeEnv });
+				out(code === 0 ? `✓ recreated ${ourName} with ${VALKEY_PASSWORD_KEY} (same volume). Restart the worker and the receiver now so they send it\n` : `✗ compose could not recreate its valkey (exit ${code}): its own output above says why\n`);
+				if (code === 0) await ownerMarkerOk(async () => (await runStreamed(spawn, "docker", [...composeBase, "stop", "valkey"], out, { env: composeEnv })) === 0);
+				summary.push(["valkey", code === 0 ? `recreated ${ourName} with ${VALKEY_PASSWORD_KEY} (volume kept); restart the worker and the receiver` : `recreate with the password FAILED (exit ${code}); see compose's output`]);
+			}
+		} else if (open && ours) {
+			const accepted = (await volumeClear()) && (await volumeUsable({ servedByOurs: true })) ? await consent(
+				`pi-dispatch-valkey answers without a password, and ${VALKEY_PASSWORD_KEY} is set in .env. up would restart it with the password (stopped first, so Valkey writes its AOF out; the pi-dispatch-valkey-data volume, and the queue in it, is kept). ${cost}:`,
+				[`docker ${VALKEY_STOP_ARGS.join(" ")}`, `docker ${VALKEY_RM_ARGS.join(" ")}`, `docker ${quoteArgs(VALKEY_RUN_ARGS)}`],
+				{ yes, out, prompt },
+			) : null;
+			if (accepted === null) {
+				// Refused above (`volumeClear` said why).
+			} else if (!accepted) {
+				out(`skipped: until it restarts with ${VALKEY_PASSWORD_KEY}, any local account can reach this queue\n`);
+				summary.push(["valkey", `pi-dispatch-valkey runs WITHOUT a password (declined the restart with it); \`pi-dispatch up\` again offers it`]);
+			} else if (await runStreamed(spawn, "docker", VALKEY_STOP_ARGS, out) !== 0 || await runStreamed(spawn, "docker", VALKEY_RM_ARGS, out) !== 0) {
+				out("✗ stopping or removing pi-dispatch-valkey failed: it runs as it was, without a password; doctor below will re-check\n");
+				summary.push(["valkey", "restart with the password FAILED at stop/rm; pi-dispatch-valkey still runs without one"]);
+			} else if (await runStreamed(spawn, "docker", VALKEY_RUN_ARGS, out, { env: dockerEnv }) !== 0) {
+				out("✗ docker run failed after pi-dispatch-valkey was removed: no Valkey runs now; its volume is kept. Re-run `pi-dispatch up`\n");
+				summary.push(["valkey", "restart with the password FAILED at docker run: NO Valkey runs now (the volume is kept); re-run `pi-dispatch up`"]);
+			} else if (await ownerMarkerOk(stopRun)) {
+				out(`✓ restarted Valkey with ${VALKEY_PASSWORD_KEY} (container pi-dispatch-valkey, same volume). Restart the worker and the receiver now so they send it: \`pi-dispatch service restart\` (and \`pi-dispatch service restart --receiver\`), or restart them however you run them\n`);
+				summary.push(["valkey", `restarted pi-dispatch-valkey with ${VALKEY_PASSWORD_KEY} (volume kept); restart the worker and the receiver`]);
+			}
+		} else if (open) {
+			out(`⚠ the Valkey on ${vport} answers without a password, and it is not a container up started, so up leaves it: restart it with ${VALKEY_PASSWORD_KEY} from .env${composeHere(cwd, fs) ? ` (compose: \`${shownCompose([...composeBase, "up", "-d"])}\`${composeNote}, which recreates it and keeps its volume)` : ""}\n`);
+			summary.push(["valkey", `port ${vport} has a listener that answers WITHOUT a password, left alone: restart it with ${VALKEY_PASSWORD_KEY}`]);
+		} else {
+			summary.push(["valkey", ours ? `container ${ourName} already running` : `port ${vport} already has a listener, left alone`]);
+		}
+	} else if (handedOver) {
+		// The wizard handed this folder's Valkey to compose (PR #475's review): up starts THAT one, compose's valkey on
+		// up's old volume, with the folder's project and the override, never a `docker run` of its own beside it (measured:
+		// up re-created pi-dispatch-valkey on the same volume, and the wizard's next compose run then failed to bind).
+		const start = [...composeBase, "up", "-d", "valkey"];
+		const accepted = (await volumeClear()) && (await volumeUsable()) ? await consent(`Nothing is listening on 127.0.0.1:${vport}. This folder's Valkey is compose's (${COMPOSE_VALKEY_OVERRIDE}, written by /dispatch setup), so up would start it:`, [shownCompose(start)], { yes, out, prompt }) : null;
+		if (accepted === null) {
+			// Refused above (`volumeClear` said why): nothing was asked, so nothing was declined.
+		} else if (!accepted) {
+			out(`skipped: start it later with \`${shownCompose(start)}\`\n`);
+			summary.push(["valkey", "skipped (declined): the queue needs it before `pi-dispatch worker` can drain"]);
+		} else {
+			const code = await runStreamed(spawn, "docker", start, out, { env: composeEnv });
+			if (code === 0 && !(await ownerMarkerOk(async () => (await runStreamed(spawn, "docker", [...composeBase, "stop", "valkey"], out, { env: composeEnv })) === 0))) {
+				// Said above; nothing more to add.
+			} else if (code === 0) {
+				out(`✓ started compose's valkey (project ${project}, the pi-dispatch-valkey-data volume, 127.0.0.1:${vport})\n`);
+				summary.push(["valkey", `started compose's valkey (project ${project}, volume pi-dispatch-valkey-data)`]);
+			} else {
+				// Reported, never swallowed: compose prints why (a port another container holds, most often), and up exits
+				// non-zero on it.
+				valkeyRefused = "compose";
+				out(`✗ compose could not start its valkey (exit ${code}): its own output above says why (another container on 127.0.0.1:${vport} is the usual one: \`docker ps\` shows which)\n`);
+				summary.push(["valkey", `compose's valkey FAILED to start (exit ${code}); see compose's output`]);
+			}
+		}
+	} else if ((existing = await valkeyContainerOwner("pi-dispatch-valkey", { dirs, port: vport, query })) && !existing.absent) {
+		// A pi-dispatch-valkey that does not answer this deployment's port: this deployment's, stopped (started as it is,
+		// never replaced), or another's, never touched (PR #475's review, round 3), or one docker could not describe.
+		if (existing.ours) {
+			out(`⚠ pi-dispatch-valkey is this deployment's and is not listening on ${vport}: \`docker start pi-dispatch-valkey\` starts it as it is\n`);
+			summary.push(["valkey", "pi-dispatch-valkey exists (this deployment's) and is not running; `docker start pi-dispatch-valkey`"]);
+		} else {
+			valkeyRefused = "volume";
+			const why = existing.unknown ? `whether pi-dispatch-valkey is this deployment's could not be read (${existing.unknown})` : foreignContainerSentence("pi-dispatch-valkey", existing.owner);
+			out(`✗ ${why}, and a second container of that name cannot be started beside it. Give this deployment a Valkey of its own (compose in this folder, which names its container and volume after the folder's project)\n`);
+			summary.push(["valkey", `NOT started: ${why}`]);
+		}
+	} else if ((await volumeClear()) && (await volumeUsable())) {
+		// The volume is created (labelled) only where it does not exist; an adopted or labelled one is used as it is.
+		const creates = volumeState === "absent";
+		const accepted = await consent(
+			`Nothing is listening on 127.0.0.1:${vport}. up would start Valkey (same semantics as deploy/docker-compose.yml)${volumeState === "adopted" ? " on the adopted pi-dispatch-valkey-data" : ""}:`,
+			[...(creates ? [`docker ${quoteArgs(VALKEY_VOLUME_ARGS)}`] : []), `docker ${quoteArgs(VALKEY_RUN_ARGS)}`],
+			{ yes, out, prompt },
+		);
+		if (!accepted) {
+			out(`skipped: ${laterValkey()}\n`);
+			summary.push(["valkey", "skipped (declined): the queue needs it before `pi-dispatch worker` can drain"]);
+		} else if (creates && await runStreamed(spawn, "docker", VALKEY_VOLUME_ARGS, out) !== 0) {
+			out("✗ docker volume create failed; continuing, doctor below will re-check Valkey\n");
+			summary.push(["valkey", composeHere(cwd, fs) ? `volume create FAILED; \`${shownCompose([...composeBase, "up", "-d"])}\` is the fallback` : "volume create FAILED; re-run `pi-dispatch up`"]);
+		} else if (await runStreamed(spawn, "docker", VALKEY_RUN_ARGS, out, { env: dockerEnv }) !== 0) {
+			out("✗ docker run failed; continuing, doctor below will re-check Valkey\n");
+			summary.push(["valkey", composeHere(cwd, fs) ? `container start FAILED; \`${shownCompose([...composeBase, "up", "-d"])}\` is the fallback` : "container start FAILED; re-run `pi-dispatch up`"]);
+		} else if (await ownerMarkerOk(stopRun)) {
+			out(`✓ started Valkey (container pi-dispatch-valkey, AOF on, bound to 127.0.0.1, ${dockerValkeyPassword ? `with ${VALKEY_PASSWORD_KEY} from .env` : "WITHOUT a password: .env sets none"})\n`);
+			summary.push(["valkey", "started container pi-dispatch-valkey (durable: --appendonly yes, restart unless-stopped)"]);
+		}
+	}
 	}
 
 	// (e2) the egress policy's proxy, and ONLY when the operator has already armed it. up never invents
@@ -206,19 +757,183 @@ export async function runUp(argv = [], deps = {}) {
 	// AFTER init, deliberately: init has just scaffolded egress-allowlist.conf, and starting a proxy whose
 	// allowlist file does not exist gets a directory created by docker where a file belonged and a squid
 	// that fails confusingly. If the file is still missing, this step declines itself and says which file.
-	if (egressArmedFn(env)) {
-		if ((await runCmd(spawn, "docker", ["inspect", "--format={{.State.Running}}", "pi-dispatch-egress-proxy"])) === 0) {
+	const proxyName = egressProxyName(venueEnv);
+	// (e1b) the folder's copy of the proxy's rules (issue #484), before the proxy step so that a proxy started, replaced
+	// or restarted below reads the refreshed file. Only where the shipped docker proxy mounts it: a proxy PI_EGRESS_PROXY
+	// names is the operator's, and the podman venue mounts an account-owned copy `service install` writes.
+	const confRefreshed = dockerUsed && egressArmedFn(venueEnv) && proxyName === DEFAULT_EGRESS_PROXY ? await proxyConfRefreshStep({ fs, cwd, out, prompt, summary, readPackagedConf, now, yes }) : false;
+	if (dockerUsed && egressArmedFn(venueEnv) && proxyName !== DEFAULT_EGRESS_PROXY) {
+		// PI_EGRESS_PROXY names the operator's own proxy (issue #430). This step used to look for, and offer to start, the
+		// shipped name whatever that key said, so it could report a proxy present that no job attaches to, or start one
+		// beside the one the worker actually uses. It now asks about the name the worker attaches by and starts nothing:
+		// that container is the operator's, and the shipped command below would not produce it.
+		// RUNNING, read off stdout alone, exactly as the podman path below (issue #453): `docker inspect` exits 0 for an
+		// exited container too, so the exit code called a stopped proxy "present" while every job was refused pre-spend.
+		// `.State.Status`, not `.State.Running` (issue #453): the status word is what names a paused or restarting container.
+		const inspect = await runCmdQuery(spawn, "docker", ["inspect", "--format={{.State.Status}}", proxyName]);
+		const status = inspect.code === 0 ? inspect.stdout.trim() : null;
+		if (status === "running") {
+			out(`\n✓ Egress proxy present (${proxyName}, named by PI_EGRESS_PROXY)\n`);
+			summary.push(["egress", `${proxyName} (PI_EGRESS_PROXY) present, left untouched`]);
+		} else if (inspect.code === 0) {
+			// It exists and is not running. Still the operator's container: reported, never started, for the reason above.
+			out(`\n✗ PI_EGRESS_PROXY names ${proxyName}, and that container exists but is not running (${status || "no status"}). up starts only the shipped ${DEFAULT_EGRESS_PROXY}, so start ${proxyName} yourself\n`);
+			summary.push(["egress", `${proxyName} (PI_EGRESS_PROXY) exists but is not running; every job is refused pre-spend until it runs`]);
+		} else {
+			out(`\n✗ PI_EGRESS_PROXY names ${proxyName}, and docker has no container of that name. up starts only the shipped ${DEFAULT_EGRESS_PROXY}, so start ${proxyName} yourself\n`);
+			summary.push(["egress", `${proxyName} (PI_EGRESS_PROXY) not found; every job is refused pre-spend until it runs`]);
+		}
+	} else if (dockerUsed && egressArmedFn(venueEnv)) {
+		// RUNNING and CURRENT, from one inspect (issue #453; `egress-proxy-state.mjs` says why each). Running is
+		// `.State.Status` "running". Current is the pinned image with its own entrypoint and command and THIS folder's two
+		// files mounted and nothing else: a container of the shipped name that differs is not this deployment's proxy,
+		// whether it is running or stopped. Mounts whose sources do not resolve on this host are UNKNOWN, never stale.
+		const inspect = await runCmdQuery(spawn, "docker", ["inspect", PROXY_STATE_FORMAT, DEFAULT_EGRESS_PROXY]);
+		const state = inspect.code === 0 ? parseProxyState(inspect.stdout) : null;
+		const judged = state ? shippedProxyDrift(state, { cwd, platform, realpath: (p) => (typeof fs.realpathSync === "function" ? fs.realpathSync(p) : p) }) : { drift: [], unknown: null };
+		const drift = judged.drift;
+		// The files a start or a recreate mounts. Both, not the allowlist alone: a missing egress-proxy.conf is bind-mounted
+		// as a directory the runtime creates in its place (measured, Docker Engine 29.8.1: the host path became a root-owned
+		// directory, and the create failed "not a directory: Are you trying to mount a directory onto a file", exit 127).
+		// A DIRECTORY at either path counts as missing too (PR #488's review): it is mounted where squid reads a file.
+		const fileProblem = (f) => (!fs.existsSync(join(cwd, f)) ? "is not here" : pathIsDirectory(fs, join(cwd, f)) ? "here is a directory, not a file" : null);
+		const missingFile = ["egress-allowlist.conf", "deploy/egress-proxy.conf"].find((f) => fileProblem(f) !== null);
+		const missingSaid = missingFile ? `${missingFile} ${fileProblem(missingFile)}` : "";
+		const noFile = missingFile ? (fileProblem(missingFile) === "is not here" ? `no ${missingFile} in this folder` : `${missingFile} in this folder is a directory`) : "";
+		// Whether the proxy's network is missing, filled by `egressNetworkLines` when an offer is about to be shown.
+		const network = { missing: false };
+		// STALE BY ITS IMAGE, ENTRYPOINT OR COMMAND (PR #456's final check): those are compared on every host, and a
+		// difference in any of them says the container is not the shipped proxy whatever its mounts hold, so an unknown
+		// mount is no reason to keep it. Docker Desktop reports every bind source as a path of its VM, so without this a
+		// proxy made from an older squid there was never replaced by `up`. HOW DESKTOP REPORTS `.Config.Image`, the
+		// entrypoint and the command is NOT MEASURED here (measured: Docker Engine 29.8.1, and Podman 4.9.3 and 5.8.1,
+		// the last with an image-id-created proxy reading as the pinned digest's spelling), so a Desktop spelling this
+		// does not expect would read stale and be offered, shown line for line and asked, never removed silently. An
+		// unknown mount still blocks a replace grounded on mounts alone.
+		const configStale = state ? shippedProxyDrift(state, { cwd, compareMounts: false }).drift.length > 0 : false;
+		const unjudged = Boolean(judged.unknown) && !configStale;
+		if (judged.unknown) out(`\n⚠ could not compare ${DEFAULT_EGRESS_PROXY}'s mounts on this host: ${judged.unknown}. Everything else about it is still judged, and up replaces it while one of its own two mounts is unknown only when its image, entrypoint or command shows it stale\n`);
+		if (inspect.code === 0 && !state) {
+			// It exists and its state could not be read: never started, never replaced, and never a `docker run` on a name
+			// that is taken.
+			out(`\n✗ ${DEFAULT_EGRESS_PROXY} exists, but its state could not be read from \`docker inspect\`, so up leaves it as it is; \`docker inspect ${DEFAULT_EGRESS_PROXY}\` shows it\n`);
+			summary.push(["egress", "proxy exists, state unreadable: left as it is"]);
+		} else if ((state?.status === "running" || state?.status === "paused") && drift.length === 0 && confRefreshed) {
+			// Issue #484: the rules were just refreshed under a running proxy, and squid reads them only at start. A RESTART,
+			// not `squid -k reconfigure`: the refresh renamed a new file over the old one, and a running container's bind
+			// mount still holds the old file (a file bind mount is of the inode; a start mounts the path again). Not the
+			// replace below either, which removes the container and with it every job network it is attached to; a restart
+			// keeps them. `--yes` never covers restarting a proxy jobs are using, as it never covers replacing one.
+			//
+			// A PAUSED current proxy takes this path too (PR #491's review): `unpause` alone resumes the same squid on the
+			// same mount, which still holds the old file, so it would run the old rules while `up` had just said they were
+			// replaced. It is unpaused and then restarted, two lines shown as one answer; unpausing first, rather than
+			// restarting a paused container, keeps the step off how each runtime stops a frozen one, which is not measured.
+			const paused = state.status === "paused";
+			const lines = paused ? [EGRESS_UNPAUSE_ARGS, EGRESS_RESTART_ARGS] : [EGRESS_RESTART_ARGS];
+			const shown = lines.map((a) => `docker ${a.join(" ")}`);
+			out(`\n${paused ? "⚠ Egress proxy is paused (pi-dispatch-egress-proxy), and holds" : "✓ Egress proxy present (pi-dispatch-egress-proxy), still running"} the rules it read at start\n`);
+			const attached = jobNetworksOf(state);
+			if (judged.unknown || missingFile) {
+				const why = judged.unknown ? "its mounts could not be compared on this host (above), so whether it mounts this folder's file is not known" : `${missingSaid}, and a restart would mount it as a directory`;
+				out(`not restarted: ${why}; \`${shown.join(" && ")}\` loads the refreshed rules once that is settled\n`);
+				summary.push(["egress", `proxy left ${state.status} on the rules it started with: not restarted, since ${why}`]);
+			} else {
+				if (yes && attached.length > 0) out("--yes does not cover restarting a proxy that jobs are using: answer below, or stop the worker and re-run\n");
+				if (
+					await consent(
+						`up would ${paused ? "unpause and then restart" : "restart"} it so squid reads the refreshed deploy/egress-proxy.conf${attached.length > 0 ? `. It is attached to ${attached.join(", ")}: those jobs lose their egress while it restarts` : ""}:`,
+						shown,
+						{ yes: yes && attached.length === 0, out, prompt },
+					)
+				) {
+					let failed = null;
+					for (const args of lines) {
+						if ((await runStreamed(spawn, "docker", args, out)) !== 0) {
+							failed = args[0];
+							break;
+						}
+					}
+					if (failed) {
+						out(`✗ could not ${failed} the egress proxy; continuing, doctor below will re-check it\n`);
+						summary.push(["egress", `${failed} FAILED after the rules refresh: see \`docker logs pi-dispatch-egress-proxy\``]);
+					} else {
+						summary.push(["egress", `${paused ? "unpaused and restarted" : "restarted"} pi-dispatch-egress-proxy on the refreshed rules`]);
+					}
+				} else {
+					out(`skipped: it ${paused ? "stays paused, and holds" : "runs"} the old rules until \`${shown.join(" && ")}\`\n`);
+					summary.push(["egress", `proxy left ${state.status} on the old rules (declined): \`${shown.join(" && ")}\` loads the refreshed ones`]);
+				}
+			}
+		} else if (state?.status === "running" && drift.length === 0) {
 			out("\n✓ Egress proxy already present (pi-dispatch-egress-proxy)\n");
-			summary.push(["egress", "proxy already present — left untouched"]);
-		} else if (!fs.existsSync(join(cwd, "egress-allowlist.conf"))) {
-			out("\n✗ the egress policy is on but egress-allowlist.conf is not here — not starting a proxy with no allowlist\n");
-			summary.push(["egress", "skipped — no egress-allowlist.conf in this folder; run `pi-dispatch init` here, then `up` again"]);
+			summary.push(["egress", judged.unknown ? "proxy already present, left untouched (its mounts could not be compared on this host)" : "proxy already present, left untouched"]);
+		} else if (state && drift.length > 0) {
+			// STALE, running or not: never started as it is. Its policy is not this deployment's, so the offer is to replace
+			// it with the shipped one, shown line for line. A running one may be carrying jobs: its job and sandbox networks
+			// are named, since removing it cuts each of them off mid-run.
+			out(`\n✗ ${DEFAULT_EGRESS_PROXY} exists (${state.status}) but is not this deployment's proxy: ${drift.join("; ")}\n`);
+			const attached = jobNetworksOf(state);
+			// Never removed on its mounts while one of its two own mounts is unknown (round-cap re-review): the other findings
+			// are said. Its image, entrypoint or command is ground enough (`configStale` above).
+			if (yes && attached.length > 0 && state.status === "running" && !unjudged && !missingFile) out("--yes does not cover replacing a proxy that jobs are using: answer below, or stop the worker and re-run\n");
+			if (unjudged) {
+				out(`not replaced: one of its own mounts could not be compared on this host (above), so up leaves it as it is; \`docker ${EGRESS_RM_ARGS.join(" ")}\` and \`pi-dispatch up\` replace it if you have checked it\n`);
+				summary.push(["egress", "stale proxy left as it is: one of its mounts could not be compared on this host"]);
+			} else if (missingFile) {
+				out(`✗ ${missingSaid}, so up cannot recreate it from this folder; run \`pi-dispatch init\` here (or \`up\` from the deployment folder), then \`up\` again\n`);
+				summary.push(["egress", `stale proxy left as it is: ${noFile} to recreate it from; its policy is not this deployment's`]);
+			} else if (
+				await consent(
+					`up would replace it with the shipped proxy (the same semantics as deploy/docker-compose.yml --profile egress)${attached.length > 0 ? `. It is attached to ${attached.join(", ")}: removing it cuts those jobs off from their egress mid-run, so stop the worker first (and let running jobs finish)` : ""}:`,
+					[`docker ${EGRESS_RM_ARGS.join(" ")}`, ...(await egressNetworkLines(spawn, network)), `docker ${quoteArgs(EGRESS_RUN_ARGS)}`],
+					// `--yes` does not cover cutting live jobs off (gate round 3): with a job network attached to a RUNNING
+					// proxy the lines are printed and a person must answer, so an unattended `up --yes` never does it.
+					{ yes: yes && !(attached.length > 0 && state.status === "running"), out, prompt },
+				)
+			) {
+				await runStreamed(spawn, "docker", EGRESS_RM_ARGS, out);
+				await ensureEgressNetwork(spawn, out, network);
+				if ((await runStreamed(spawn, "docker", EGRESS_RUN_ARGS, out)) !== 0) {
+					out("✗ could not start the egress proxy; continuing, doctor below will re-check it\n");
+					summary.push(["egress", "recreate failed: every job refuses pre-spend until it is up (costs no budget, runs nothing)"]);
+				} else {
+					summary.push(["egress", "replaced the stale pi-dispatch-egress-proxy with the shipped one"]);
+				}
+			} else {
+				out(`skipped: until it is replaced, jobs use a proxy whose policy is not this deployment's (\`docker ${EGRESS_RM_ARGS.join(" ")}\`, then \`pi-dispatch up\`)\n`);
+				summary.push(["egress", "stale proxy left as it is (declined): its policy is not this deployment's"]);
+			}
+		} else if (missingFile) {
+			out(`\n✗ the egress policy is on but ${missingSaid}, so no proxy is started without it\n`);
+			summary.push(["egress", `skipped: ${noFile}; run \`pi-dispatch init\` here (or \`up\` from the deployment folder), then \`up\` again`]);
+		} else if (state?.status === "restarting") {
+			// A crash loop: the restart policy is already starting it, and its squid keeps exiting. Nothing to start.
+			out(`\n✗ ${DEFAULT_EGRESS_PROXY} is restarting: its squid keeps exiting and its restart policy keeps bringing it back. \`docker logs ${DEFAULT_EGRESS_PROXY}\` says why; meanwhile each job is retried once, then failed\n`);
+			summary.push(["egress", "proxy crash-looping: see `docker logs pi-dispatch-egress-proxy`"]);
+		} else if (state) {
+			// Current, and stopped or paused. `docker run --name` would fail on the name conflict, so the SAME container is
+			// offered back: `unpause` for a paused one, else `start`, which is what `docker compose --profile egress up -d`
+			// does for a stopped container whose configuration is unchanged. It destroys nothing, and a compose-created
+			// container stays compose's.
+			const args = state.status === "paused" ? EGRESS_UNPAUSE_ARGS : EGRESS_START_ARGS;
+			if (await consent(`The egress policy is on (PI_EGRESS=0 opts out) and the allowlist proxy exists but is ${state.status}. up would ${args[0]} that same container (as deploy/docker-compose.yml --profile egress up -d does):`, [`docker ${args.join(" ")}`], { yes, out, prompt })) {
+				if ((await runStreamed(spawn, "docker", args, out)) !== 0) {
+					out(`✗ could not ${args[0]} the egress proxy; \`docker ${EGRESS_RM_ARGS.join(" ")}\` and re-run \`pi-dispatch up\` recreates it. Continuing; doctor below will re-check it\n`);
+					summary.push(["egress", `${args[0]} of the ${state.status} proxy failed; every job refuses pre-spend until it is up (costs no budget, runs nothing)`]);
+				} else {
+					summary.push(["egress", `${args[0] === "unpause" ? "unpaused" : "started"} the ${state.status} pi-dispatch-egress-proxy`]);
+				}
+			} else {
+				out(`skipped: ${args[0]} it later with \`docker ${args.join(" ")}\`\n`);
+				summary.push(["egress", "skipped (declined): every job is refused pre-spend until the proxy is up (PI_EGRESS=0 opts out)"]);
+			}
 		} else if (
-			await consent("The egress policy is on (PI_EGRESS=0 opts out) but the allowlist proxy is not running. up would start it (same semantics as deploy/docker-compose.yml --profile egress):", [`docker ${EGRESS_NETWORK_ARGS.join(" ")}`, `docker ${quoteArgs(EGRESS_RUN_ARGS)}`], { yes, out, prompt })
+			await consent("The egress policy is on (PI_EGRESS=0 opts out) but the allowlist proxy is not running. up would start it (same semantics as deploy/docker-compose.yml --profile egress):", [...(await egressNetworkLines(spawn, network)), `docker ${quoteArgs(EGRESS_RUN_ARGS)}`], { yes, out, prompt })
 		) {
-			// The network may already exist from a previous run; that is not a failure, so its code is not
-			// checked. The proxy is what matters and it is checked.
-			await runStreamed(spawn, "docker", EGRESS_NETWORK_ARGS, out);
+			// The network's create is not checked: one made between the ask and here is not a failure. The proxy is what
+			// matters and it is checked.
+			await ensureEgressNetwork(spawn, out, network);
 			if ((await runStreamed(spawn, "docker", EGRESS_RUN_ARGS, out)) !== 0) {
 				out("✗ could not start the egress proxy — continuing; doctor below will re-check it\n");
 				summary.push(["egress", "start failed — every job refuses pre-spend until it is up (costs no budget, runs nothing)"]);
@@ -226,22 +941,57 @@ export async function runUp(argv = [], deps = {}) {
 				summary.push(["egress", "started pi-dispatch-egress-proxy on pi-dispatch-egress-out"]);
 			}
 		} else {
-			out("skipped — start it later with `docker compose -f deploy/docker-compose.yml --profile egress up -d`\n");
+			out(`skipped: ${composeHere(cwd, fs) ? `start it later with \`${composeCommandFor(cwd, fs, ["--profile", "egress", "up", "-d"])}\`` : "start it later by running `pi-dispatch up` again and accepting"}\n`);
 			summary.push(["egress", "skipped (declined) — every job is refused pre-spend until the proxy is up (PI_EGRESS=0 opts out)"]);
 		}
 	}
 
+	// (e3) the podman venue's stack: Valkey and, while the policy is armed, the proxy, as Quadlet units through the SAME
+	// installer `pi-dispatch service install` uses (issue #430). After init for the reason (e2) gives: the proxy mounts
+	// the allowlist init scaffolds.
+	if (podmanReady) {
+		const stackState = { valkeyRefused: false };
+		await podmanStackStep({ env: venueEnv, valkeyKeys: valkeyKeys.env, state: stackState, venues, spawn, out, yes, prompt, summary, fs, probeTcp, lookup, interfaces, runSync, cwd, home, user: userName(), euid, newPassword, platform, templatesDir, readTemplate, mkdir, realpath });
+		valkeyRefused = stackState.valkeyRefused;
+	}
+
 	// (f) doctor — always, verbatim: up converges what it can, doctor is the judge of what remains
 	// (provider key, forge env, overlay …), and its verdict is up's exit code.
 	out("\ndoctor:\n");
 	runDoctorFn ??= (await import("./doctor.mjs")).runDoctor;
-	const doctorCode = await runDoctorFn(env, { out });
+	// Layered, per the note at step (e1): the lines just written configure the service and not this
+	// process, so an unlayered call would warn about exactly what `up` had converged a moment earlier.
+	//
+	// `env` WINS, and the filter is what makes that true rather than the spread order. `wrote` holds keys
+	// that were empty in the FILE, which is a different question from whether this shell sets them: an
+	// operator exporting `PI_SCOPED_LIMITS_FILE=/etc/pi/limits.json` with the key still commented in `.env`
+	// would otherwise have doctor read back the file `up` chose instead of the one their worker loads.
+	// SETS, not "sets to something usable", and the `.trim()` this dropped was hiding a refused boot from
+	// up's own verdict (issue #384). A shell that exports `PI_PAUSE_WINDOWS_FILE=   ` is a shell whose
+	// foreground worker reads three spaces, keeps them (`config.mjs` uses `??`, not `||`) and throws at
+	// `start.mjs` before it takes a job. Filling that key from `wrote` handed doctor a path the operator
+	// does not have set, so doctor judged a deployment nobody is running and `up` exited 0 on one that
+	// cannot start. Doctor now names the blank itself, which is the only line that tells the operator what
+	// to do about it. For the other two keys `up` writes, this hands doctor the truth rather than a default:
+	// `PI_LOGS_DIR=""` does resolve through `||` to what `up` wrote, but `PI_LOGS_DIR="   "` does NOT -- three
+	// spaces are truthy, so `config.mjs` keeps them and the worker really does use a directory named three
+	// spaces. Filling that key in from `wrote` made doctor judge a deployment the operator is not running,
+	// which is the same defect one key over.
+	const layered = { ...env };
+	for (const [key, value] of Object.entries(wrote)) {
+		if (typeof env[key] !== "string") layered[key] = value;
+	}
+	// The venue keys `.env` supplied (D2), by the same env-wins rule, so doctor judges the venue this pass drove.
+	for (const [key, value] of Object.entries(venue.fromFile)) {
+		if (typeof env[key] !== "string") layered[key] = value;
+	}
+	const doctorCode = await runDoctorFn(layered, { out });
 
 	// (g) the summary: what ran, what was skipped, what was already there — then the two commands
 	// that actually start work, so "up is green" flows straight into the first job.
 	out("\nup: summary\n");
 	for (const [name, note] of summary) {
-		out(`  ${name.padEnd(15)} ${note}\n`);
+		out(`  ${name.padEnd(21)} ${note}\n`);
 	}
 	out(`
 Next:
@@ -252,9 +1002,386 @@ Next:
   pi-dispatch run ./my-project --task "add type hints to utils.py"
       queue your first job from another terminal
 `);
+	// A worker run BY HAND reads only its shell, so on the podman venue it needs the list exported; the service reads
+	// `.env` itself. Printed only there, so every other deployment's closing text is unchanged.
+	if (venues.podmanUsed) {
+		out("  (podman venue: a worker started by hand reads only its shell, so export the same PI_BACKENDS there first, or run it as a service with `pi-dispatch service install`, which reads .env)\n");
+	}
+	// Issue #464: a Valkey this pass refused (another account's, or one no one could name) is a failed `up` whatever doctor
+	// says: a worker started now would take that queue's jobs, and an exit 0 read by a script or the wizard says ready.
+	if (valkeyRefused) {
+		// Worded per reason (gate round 2): an owner refusal and a URL the Quadlet Valkey cannot serve are different faults.
+		out(
+			valkeyRefused === "owner"
+				? "\nup: the Valkey VALKEY_URL reaches is not this account's (above); give this account its own port, or opt in with PI_VALKEY_SHARED=1 in .env, then re-run `pi-dispatch up`.\n"
+				: valkeyRefused === "password"
+					? `\nup: ${VALKEY_PASSWORD_KEY} in .env cannot be handed to Valkey (above); fix it, then re-run \`pi-dispatch up\`.\n`
+					: valkeyRefused === "compose"
+						? "\nup: compose could not start this folder's Valkey (above); free the port it names, then re-run `pi-dispatch up`.\n"
+						: valkeyRefused === "marker"
+							? `\nup: the Valkey up started could not be asked whose queue it holds (${OWNER_MARKER_KEY}, above); check it answers, then re-run \`pi-dispatch up\`.\n`
+							: valkeyRefused === "volume"
+							? "\nup: the Valkey container or volume named above is not this deployment's (or not attributed to it), and up never stops, removes, reuses or starts beside one; take the way out it names, then re-run `pi-dispatch up`.\n"
+							: "\nup: VALKEY_URL cannot be served as it is written (above); fix it in .env, then re-run `pi-dispatch up`.\n",
+		);
+		return doctorCode !== 0 ? doctorCode : 1;
+	}
 	return doctorCode;
 }
 
+/**
+ * The podman venue's gate: the same `podman info` read and the same ordered job-user rule the worker boots with
+ * (`decidePodmanJobUser`), so `up` cannot pass a host the worker then refuses, or refuse one it would run. Printed in
+ * the worker's own refusal words.
+ */
+async function podmanGate({ readPodmanInfo, platform, euid, egid, out }) {
+	let read;
+	try {
+		read = await readPodmanInfo();
+	} catch {
+		read = { answered: false, reason: "spawn-failed", transient: true };
+	}
+	const decision = decidePodmanJobUser({ platform, euid, egid, read });
+	if (decision.mode === "worker") {
+		out(`✓ rootless Podman answering (podman jobs run as ${decision.user}, with --userns=keep-id)\n`);
+		return { ok: true };
+	}
+	// The worker's boot-refusing causes stop `up` in the worker's own words. `up` is DELIBERATELY STRICTER than the
+	// worker on the rest (round 2, E7, which reverses round 1's D7): a podman info that timed out or that nothing could
+	// read is a per-job retry at the worker, but `up` is about to install units and run podman commands that have no
+	// timeout of their own, for a Podman it could not see. A wedged podman would hang the pass, and a REMOTE podman
+	// whose info merely timed out would get local Quadlet units. So only an answered, usable info continues.
+	if (decision.mode === "unmappable" && PODMAN_BOOT_REFUSING_CAUSES.has(decision.cause)) {
+		const why = podmanJobUserRefusal(decision);
+		out(`✗ podman venue not usable here\n    → ${why}\n`);
+		return { ok: false, why };
+	}
+	const why = `${decision.mode === "unmappable" ? podmanJobUserRefusal(decision) : `podman info did not answer (${decision.reason}).`} up stops here although the worker would only retry this per job: it will not install units for a Podman it could not see. Check that \`podman info --format json\` answers as this account, then re-run.`;
+	out(`✗ podman venue not answering\n    → ${why}\n`);
+	return { ok: false, why };
+}
+
+/** The default job image into this account's Podman store, mirroring the docker step (b) line for line. */
+async function podmanImageStep({ spawn, out, yes, prompt, summary }) {
+	if ((await runCmd(spawn, "podman", PODMAN_EXISTS_ARGS)) === 0) {
+		out(`✓ Job image present in this account's Podman store (${LOCAL_IMAGE})\n`);
+		summary.push(["podman job image", `already present (${LOCAL_IMAGE})`]);
+		return;
+	}
+	const accepted = await consent(
+		`The default job image (${LOCAL_IMAGE}) is not in this account's Podman store. up would run:`,
+		[`podman ${PULL_ARGS.join(" ")}`, `podman ${TAG_ARGS.join(" ")}`],
+		{ yes, out, prompt },
+	);
+	if (!accepted) {
+		out("skipped: pull it later with the two commands above\n");
+		summary.push(["podman job image", "skipped (declined): jobs run with --pull=never, so nothing fetches it later"]);
+	} else if ((await runStreamed(spawn, "podman", PULL_ARGS, out)) !== 0) {
+		out("✗ podman pull failed: continuing; doctor below will re-check the image\n");
+		summary.push(["podman job image", "pull FAILED: re-run `pi-dispatch up`, or pull by hand"]);
+	} else if ((await runStreamed(spawn, "podman", TAG_ARGS, out)) !== 0) {
+		out("✗ podman tag failed: continuing; doctor below will re-check the image\n");
+		summary.push(["podman job image", `pulled, but tagging as ${LOCAL_IMAGE} FAILED: re-run the tag command by hand`]);
+	} else {
+		out(`✓ pulled and tagged ${LOCAL_IMAGE} in this account's Podman store\n`);
+		summary.push(["podman job image", `pulled ${UPSTREAM_IMAGE} and tagged it ${LOCAL_IMAGE}`]);
+	}
+}
+
+/**
+ * The podman venue's stack step. Decides what is missing the way the docker steps do (a listener on 6379 is left
+ * alone, a proxy that exists is left alone), then plans the Quadlet files with `planStack`, shows `plan.actions`, and on
+ * consent hands those same objects to `applyStack`: what runs is literally what was shown.
+ */
+async function podmanStackStep({ env, valkeyKeys = {}, state = {}, venues, spawn, out, yes, prompt, summary, fs, probeTcp, lookup, interfaces, runSync, cwd, home, user, euid, templatesDir, readTemplate, mkdir, realpath, newPassword = newValkeyPassword, platform = "linux" }) {
+	const armed = egressArmedFn(env);
+	let includeValkey = false;
+	let valkeyPort = DEFAULT_VALKEY_PORT;
+	if (!venues.localUsed) {
+		// Issue #464: the rule `service install` applies (`decideValkey`), on VALKEY_URL and PI_VALKEY_SHARED as the
+		// service reads them (`deploymentValkeyEnv`): every address the URL reaches is judged, and a listener there is taken
+		// to be the Valkey only when it is this account's (or shared on purpose, opted in). Anything else is refused,
+		// nothing is added for it, and `up` exits non-zero.
+		const decided = await decideValkey({
+			venues,
+			url: valkeyKeys.VALKEY_URL,
+			installed: false,
+			probeTcp,
+			lookup,
+			interfaces,
+			euid,
+			user,
+			shared: valkeySharedOn(valkeyKeys[VALKEY_SHARED_KEY]),
+			subuids: readSubuidRanges({ user, euid, fs: { readFileSync: (p, enc) => (fs.readFileSync ?? readFileSync)(p, enc) }, run: runSync }),
+			fs: { readFileSync: (p, enc) => (fs.readFileSync ?? readFileSync)(p, enc) },
+			ownerName: (uid) => passwdNameFrom({ readFileSync: (p, enc) => (fs.readFileSync ?? readFileSync)(p, enc) }, uid),
+			envPath: join(cwd, ".env"),
+		});
+		valkeyPort = decided.port;
+		if (decided.error) {
+			state.valkeyRefused = "url";
+			out(`\n✗ ${decided.error}\n`);
+			summary.push(["valkey", `NOT added: ${decided.error}`]);
+		} else if (decided.refusal) {
+			state.valkeyRefused = "owner";
+			out(`\n✗ ${decided.refusal.text}\n`);
+			summary.push(["valkey", `NOT added and NOT adopted: ${decided.refusal.short}`]);
+		} else if (decided.include) {
+			includeValkey = true;
+		} else if (decided.remote) {
+			out(`\n✓ ${decided.notes[0]}\n`);
+			summary.push(["valkey", "VALKEY_URL names another host, nothing added here"]);
+		} else {
+			// "It is the pi-dispatch-valkey container" only when that container PUBLISHES this port: a container of that name
+			// on another port (a second deployment's) says nothing about who answers here.
+			const ps = await runCmdQuery(spawn, "podman", ["ps", "--filter", "name=^pi-dispatch-valkey$", "--format", "{{.Names}}|{{.Ports}}"]);
+			const ours = ps.code === 0 && ps.stdout.split("\n").some((l) => valkeyContainerPublishes(l, decided.port));
+			out(`\n✓ something is listening on ${decided.port}, assuming your Valkey${ours ? " (it is the pi-dispatch-valkey container, published there)" : ""}: ${decided.notes[0] ?? ""}\n`);
+			summary.push(["valkey", ours ? `container pi-dispatch-valkey already running on ${decided.port}` : `port ${decided.port} already has a listener, left alone`]);
+		}
+	}
+	// Issue #468: the password the Quadlet Valkey starts with, read from .env NOW (init, earlier in this pass, may have just
+	// written the file and a password into it): kept when set, generated when the Valkey this step adds is the
+	// deployment's own and it has none, written into .env only once the plan is accepted.
+	const envPath = join(cwd, ".env");
+	let valkeyPassword = null;
+	let pendingPassword = null;
+	if (includeValkey) {
+		let fileKeys = {};
+		let readError = null;
+		if (fs.existsSync(envPath)) {
+			try {
+				const read = readValkeyKeys(fs.readFileSync(envPath), { loader: "systemd", path: envPath });
+				if (read.error) readError = read.error;
+				else fileKeys = read.keys;
+			} catch (err) {
+				readError = `${envPath} could not be read (${err?.message ?? err})`;
+			}
+		}
+		const decided = readError ? { error: readError } : valkeyPasswordDecision({ ...valkeyKeys, ...fileKeys }, { envPath });
+		if (decided.error) {
+			state.valkeyRefused = "password";
+			out(`\n✗ ${decided.error}\n`);
+			summary.push(["valkey", `NOT added: ${decided.error}`]);
+			includeValkey = false;
+		} else {
+			if (decided.note) out(`\n⚠ ${decided.note}\n`);
+			if (decided.generate && fs.existsSync(envPath)) pendingPassword = newPassword();
+			else if (decided.generate) out(`\n⚠ no .env here, so the Valkey up adds has no password: run \`pi-dispatch init\` here, then \`pi-dispatch service install --force\`, which gives it one\n`);
+			valkeyPassword = decided.password ?? pendingPassword;
+		}
+	}
+	const components = stackComponents({ venues, env, includeValkey, armed, valkeyPort, valkeyPassword });
+	for (const note of components.notes) out(`\n⚠ ${note}\n`);
+	let keeperRestart = false;
+	if (components.proxy) {
+		// RUNNING, read off the output: `podman inspect` exits 0 for an EXITED container too and prints `false`
+		// (measured), so the exit code alone called a stopped hand-started proxy "present" and offered nothing, which is
+		// exactly the upgrade this step exists for. A stopped one is offered the unit, under the foreign-container rule.
+		// stdout ALONE (round 2, E2): podman's stderr warnings on an ordinary account would otherwise make `true` unequal.
+		// `.State.Status` (issue #453): Podman reports a paused container `paused` and one between restarts `stopped`
+		// (measured on 4.9.3 and 5.8.1), and only `running` carries a job's traffic.
+		const inspect = await runCmdQuery(spawn, "podman", ["inspect", "--format={{.State.Status}}", DEFAULT_EGRESS_PROXY]);
+		if (inspect.code === 0 && inspect.stdout.trim() === "running") {
+			out(`\n✓ Egress proxy already present under this account's Podman (${DEFAULT_EGRESS_PROXY})\n`);
+			summary.push(["egress (podman)", "proxy already present, left untouched"]);
+			components.proxy = false;
+		} else if (!fs.existsSync(join(cwd, "egress-allowlist.conf")) || pathIsDirectory(fs, join(cwd, "egress-allowlist.conf"))) {
+			out(`\n✗ the egress policy is on but egress-allowlist.conf ${pathIsDirectory(fs, join(cwd, "egress-allowlist.conf")) ? "here is a directory, not a file" : "is not here"}, not starting a proxy with no allowlist\n`);
+			summary.push(["egress (podman)", "skipped: no egress-allowlist.conf in this folder; run `pi-dispatch init` here, then `up` again"]);
+			components.proxy = false;
+		}
+	}
+	if (components.keeper) {
+		// The keeper (issue #458) under the proxy's rule: one that HOLDS is left alone, read off stdout as above, by the
+		// shared rule (`judgeNetnsKeeper`: running, bridge mode, on its own network; issue #463's gate found a keeper on
+		// `--network none` called "already running" here). Anything else is offered the unit, under the foreign-container
+		// rule, which is what stops a `--replace` over a container of that name that is not ours. It is offered with the
+		// allowlist missing too, since it mounts nothing and a proxy started later needs it just the same.
+		const inspect = await runCmdQuery(spawn, "podman", ["inspect", NETNS_KEEPER_FORMAT, NETNS_KEEPER]);
+		const keeper = judgeNetnsKeeper({ code: inspect.code, stdout: inspect.stdout });
+		if (keeper.holds) {
+			out(`\n✓ Rootless network keeper already running under this account's Podman on its own bridge network (${NETNS_KEEPER})\n`);
+			summary.push(["netns keeper (podman)", "already running, left untouched"]);
+			components.keeper = false;
+		} else if (keeper.exists) {
+			// There but not holding (paused, running off its bridge, exited): its unit, if the files are ours and unchanged,
+			// is RESTARTED, since `start` on a unit that is still active does nothing and "installed and started" would
+			// then be said over a keeper still not holding (PR #463 round 2). A container that is not ours stops at the
+			// foreign-container rule below, as before.
+			out(`\n⚠ ${NETNS_KEEPER} ${keeper.problem}: offering its unit, restarted\n`);
+			keeperRestart = true;
+		}
+	}
+	if (!components.valkey && !components.proxy && !components.keeper) return;
+	const plan = planStack({ components, templatesDir, deployDir: cwd, home, fs, readTemplate, restartUnits: keeperRestart ? [QUADLET_FILES.keeper.unit] : [] });
+	if (plan.error) {
+		out(`\n✗ ${plan.error}\n`);
+		summary.push(["podman stack", `NOT installed: ${plan.error}`]);
+		return;
+	}
+	const changed = plan.files.filter((f) => f.state === "changed");
+	if (changed.length > 0) {
+		// up has no --force, and a file someone edited is theirs until they say otherwise (init's contract).
+		out(`\n✗ ${changed.map((f) => f.path).join(", ")} differs from what this version renders, left untouched\n`);
+		summary.push(["podman stack", "NOT installed: a Quadlet file differs; `pi-dispatch service install --force` replaces it"]);
+		return;
+	}
+	// The shared installer's foreign-container rule (D3): a container of a unit's name that the unit does not own would
+	// be removed by the unit's `podman run --replace`. up has no --force, so it names both ways out and installs nothing.
+	// No user manager to talk to (`sudo -iu`, measured): said before anything is written (round 2, E8).
+	const bus = plan.actions.length > 0 ? userBusRefusal({ env, user, euid }) : null;
+	if (bus) {
+		out(`\n✗ ${bus}\n`);
+		summary.push(["podman stack", "NOT installed: no user manager reachable from this shell"]);
+		return;
+	}
+	// The manager's own XDG_RUNTIME_DIR and XDG_CONFIG_HOME (PR #463 round 3): service install's refusal, the same words.
+	const managerEnv = plan.actions.length > 0 ? managerEnvRefusal(await runCmdQuery(spawn, "systemctl", ["--user", "show-environment"]), { home, euid, user, realpath }) : null;
+	if (managerEnv) {
+		out(`\n✗ ${managerEnv}\n`);
+		summary.push(["podman stack", "NOT installed: the user manager's environment names another account's directories"]);
+		return;
+	}
+	const containers = await foreignContainers(plan, (cmd, args) => runCmdQuery(spawn, cmd, args));
+	if (containers.unknown.length > 0) {
+		const why = unknownContainerRefusal(containers.unknown);
+		out(`\n✗ ${why}\n`);
+		summary.push(["podman stack", "NOT installed: podman did not say whether the containers exist"]);
+		return;
+	}
+	const foreign = containers.found;
+	if (foreign.length > 0) {
+		const why = foreignContainerRefusal(foreign, { forceHint: "run `pi-dispatch service install --force`, which replaces it and says so" });
+		out(`\n✗ ${why}\n`);
+		summary.push(["podman stack", `NOT installed: ${foreign.map((f) => f.container).join(", ")} exists and is not the Quadlet unit's`]);
+		return;
+	}
+	const named = [components.valkey ? "Valkey" : null, components.proxy ? "the egress proxy" : null, components.keeper ? `the rootless network keeper (${NETNS_KEEPER}, which keeps the proxy's route out on Podman 4.x)` : null].filter(Boolean);
+	const parts = named.length > 1 ? `${named.slice(0, -1).join(", ")} and ${named.at(-1)}` : named[0];
+	const several = named.length > 1;
+	const accepted = await consent(
+		`${parts} ${several ? "are" : "is"} not running under this account's Podman. up would install ${several ? "them" : "it"} as Quadlet units in your user manager (the same installer \`pi-dispatch service install\` uses; systemd brings them back at boot while linger is on):`,
+		[...(pendingPassword ? [`generate ${VALKEY_PASSWORD_KEY} into ${envPath} (32 random bytes, hex; the value is not shown)`] : []), ...plan.actions.map(describeAction)],
+		{ yes, out, prompt },
+	);
+	const row = several ? "podman stack" : components.valkey ? "valkey" : components.proxy ? "egress (podman)" : "netns keeper (podman)";
+	if (!accepted) {
+		out("skipped: `pi-dispatch service install` installs the same units with the worker\n");
+		summary.push([row, `skipped (declined): ${components.valkey ? "the queue needs Valkey before `pi-dispatch worker` can drain" : components.proxy ? "every podman job is refused pre-spend until the proxy is up (PI_EGRESS=0 opts out)" : "on Podman 4.x the first egress job's teardown cuts the proxy's route out, and every later one gets 503"}`]);
+		return;
+	}
+	// The fs seam gains mkdir here only: up's own writes (`.env`) never needed one, and the Quadlet directory usually
+	// does not exist on a fresh account.
+	// Issue #464: every write journalled, as `service install` does. The plan writes every file before its first command
+	// (planStack), so a failed WRITE puts back every file this run wrote and names any it could not; a failed COMMAND
+	// leaves the files its units run from, named.
+	const journal = [];
+	const stackFs = { ...fs, mkdirSync: fs.mkdirSync ?? mkdir, unlinkSync: fs.unlinkSync ?? unlinkSync };
+	if (pendingPassword) {
+		// Issue #468: the password into .env before any stack file, journalled with what was there, so a failed write
+		// below puts .env back with the rest. Never over a value; the file narrowed to this account; the value unshown.
+		let previous = null;
+		try {
+			previous = fs.readFileSync(envPath);
+			if (!updateEnvFile(envPath, VALKEY_PASSWORD_KEY, pendingPassword, { fs, platform, narrow: true }).changed) throw new Error("the file already assigns it");
+		} catch (err) {
+			out(`✗ ${VALKEY_PASSWORD_KEY} could not be written into ${envPath} (${err?.message ?? err}), so nothing was installed. Continuing; doctor below will re-check\n`);
+			summary.push([row, `NOT installed: ${VALKEY_PASSWORD_KEY} could not be written into .env`]);
+			return;
+		}
+		journal.push({ path: envPath, existed: true, previous });
+		out(`✓ generated ${VALKEY_PASSWORD_KEY} into .env (value not shown; .env is now readable by this account only)\n`);
+	}
+	const applied = await applyStack(plan, { fs: stackFs, run: (cmd, args) => runStreamed(spawn, cmd, args, out), journal });
+	if (!applied.ok) {
+		if (!applied.ran) {
+			const rolled = describeRollBack(rollBackWrites(stackFs, journal));
+			out(`✗ ${applied.failed} failed (${applied.message ?? "write error"}), so nothing was installed: ${rolled}. Continuing; doctor below will re-check\n`);
+			summary.push([row, `install FAILED at: ${applied.failed}; ${rolled}`]);
+			return;
+		}
+		const remain = [...new Set(journal.map((e) => e.path))];
+		out(`✗ ${applied.failed} failed: continuing; doctor below will re-check. \`journalctl --user -u ${plan.start.join(" -u ")}\` has the details. Files this run wrote, which remain: ${remain.join(", ") || "none"}\n`);
+		summary.push([row, `install FAILED at: ${applied.failed}`]);
+		return;
+	}
+	const restarted = plan.restart ?? [];
+	const fresh = plan.start.filter((u) => !restarted.includes(u));
+	if (fresh.length > 0) out(`✓ started ${fresh.join(" ")}\n`);
+	if (restarted.length > 0) out(`✓ restarted ${restarted.join(" ")}\n`);
+	// `up` refuses a changed file above, so the one restart it makes is a keeper that was there and not holding.
+	summary.push([row, `installed as Quadlet units and ${restarted.length > 0 ? `${fresh.length > 0 ? `started (${fresh.join(", ")}) and ` : ""}restarted (${restarted.join(", ")})` : `started (${plan.start.join(", ")})`}`]);
+	// A keeper (re)started under a proxy that stays up, ours left running or the operator's own PI_EGRESS_PROXY, leaves
+	// that proxy for the operator to restart, named: the worker and doctor both ask for exactly that (PR #463 round 3).
+	const hint = keeperUnderRunningProxyHint(plan, egressProxyName(env), { keeperStarting: plan.start.includes(QUADLET_FILES.keeper.unit) });
+	if (hint) out(`⚠ ${hint}\n`);
+	out(lingerNote(await readLinger(user, (cmd, args) => runCmdCapture(spawn, cmd, args)), user));
+}
+
+/**
+ * Whether a `podman ps --format {{.Names}}|{{.Ports}}` line is the pi-dispatch-valkey container publishing host port
+ * `port` to its 6379 (issue #464). Ports read like `127.0.0.1:16468->6379/tcp` (measured, Podman 5.8.1 and 4.9.3), a
+ * list comma-separated.
+ */
+export function valkeyContainerPublishes(line, port) {
+	const [name, ports = ""] = String(line).trim().split("|");
+	if (name !== "pi-dispatch-valkey") return false;
+	return ports.split(",").some((p) => {
+		const m = /:(\d+)->6379\/tcp$/.exec(p.trim());
+		return m !== null && Number(m[1]) === port;
+	});
+}
+
+/**
+ * Issue #484: the folder's `deploy/egress-proxy.conf` against the installed package's copy. Nothing is said for an
+ * identical or an absent copy (the proxy step says what a missing file costs); a differing one is offered for
+ * replacement, shown and asked. Returns true when it was replaced.
+ *
+ * `--yes` DOES NOT COVER IT, and that is the one departure from up's consent rule ("--yes accepts them all"): every other
+ * action --yes accepts creates or starts something, or replaces a container this project made, while this replaces a
+ * FILE that reads the same whether an upgrade left it behind or the operator edited it on purpose, and nothing here can
+ * tell the two apart. So the lines are printed and a person answers, as for removing a proxy jobs are using. The old
+ * bytes are kept beside it either way (`replaceProxyConfCopy`), since an edit lost to a wrong "y" is still the
+ * operator's.
+ */
+async function proxyConfRefreshStep({ fs, cwd, out, prompt, summary, readPackagedConf, now, yes }) {
+	const rel = "deploy/egress-proxy.conf";
+	const path = join(cwd, rel);
+	// A directory there is the proxy step's to say (it starts nothing on one), so it is not read as a copy here.
+	if (pathIsDirectory(fs, path)) return false;
+	const judged = judgeProxyConfCopy({ path, read: (p) => fs.readFileSync(p, "utf8"), readPackaged: readPackagedConf });
+	if (judged.state === "absent" || judged.state === "same") return false;
+	if (judged.state !== "differs") {
+		const why = judged.state === "no-package" ? `the package's own copy (${PACKAGED_EGRESS_PROXY_CONF}) could not be read (${judged.error})` : `it could not be read (${judged.error})`;
+		out(`\n⚠ ${rel} was not compared with ${packageCopyName()}: ${why}\n`);
+		summary.push(["egress rules", `not compared: ${why}`]);
+		return false;
+	}
+	out(`\n⚠ ${rel} differs from ${packageCopyName()}: ${judged.summary}. An upgrade does not rewrite it, so it is either an older version's rules or an edit of your own (\`diff ${rel} ${PACKAGED_EGRESS_PROXY_CONF}\` shows which)\n`);
+	if (yes) out("--yes does not cover replacing a file that may hold your own edits: answer below\n");
+	const accepted = await consent(
+		`up would replace it with ${packageCopyName()}, keeping yours beside it:`,
+		[`cp ${rel} ${rel}.bak-<timestamp>`, `write ${PACKAGED_EGRESS_PROXY_CONF}'s content beside ${rel}, then rename it over ${rel}`],
+		{ yes: false, out, prompt },
+	);
+	if (!accepted) {
+		out(`skipped: ${rel} is left as it is; \`pi-dispatch up\` offers this again\n`);
+		summary.push(["egress rules", `${rel} differs from ${packageCopyName()}, left as it is (declined)`]);
+		return false;
+	}
+	const done = replaceProxyConfCopy({ path, text: judged.packaged, fs, now });
+	if (!done.ok) {
+		out(`✗ not replaced: ${done.reason}\n`);
+		summary.push(["egress rules", `NOT replaced: ${done.reason}`]);
+		return false;
+	}
+	const backup = `${rel}${done.backup.slice(path.length)}`;
+	out(`✓ replaced ${rel} with ${packageCopyName()}; yours is kept as ${backup}. squid reads it only at start, so a proxy already running or paused is offered a restart below\n`);
+	summary.push(["egress rules", `${rel} replaced with ${packageCopyName()} (the old one is ${backup})`]);
+	return true;
+}
+
 /**
  * Show the exact commands, then ask. Printing happens with or without `--yes`: consent is what the
  * flag waives, never visibility — every host mutation is on screen before it runs. The prompt
@@ -271,9 +1398,146 @@ async function consent(intro, commands, { yes, out, prompt }) {
 	return /^y(es)?$/i.test(String(answer ?? "").trim());
 }
 
-/** Re-join an argv array for display, quoting the args that contain spaces (e.g. "valkey-cli ping"). */
+/**
+ * Re-join an argv array for display, quoting the args that contain spaces (e.g. "valkey-cli ping"). An arg with a
+ * double quote or a `$` in it (issue #468: the Valkey start script) is shown in single quotes, which is how a shell
+ * would take it unchanged; none of those args has a single quote of its own.
+ */
 function quoteArgs(args) {
-	return args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ");
+	return args.map((a) => (/["$]/.test(a) ? `'${a}'` : a.includes(" ") ? `"${a}"` : a)).join(" ");
+}
+
+/**
+ * Issue #468: the password docker's Valkey starts with, from the deployment's `.env` (`dockerValkeyPasswordStep`): kept
+ * when set, generated into the file when the deployment runs its own Valkey on this host and has none, null otherwise.
+ * Said on screen and in the summary without the value.
+ */
+function dockerValkeyPasswordStep({ fs, envPath, platform, out, summary, newPassword }) {
+	if (!fs.existsSync(envPath)) {
+		summary.push([VALKEY_PASSWORD_KEY, "no .env here, skipped (set it wherever your env lives); the Valkey up starts then has no password"]);
+		return null;
+	}
+	const loader = platform === "linux" ? "systemd" : platform === "darwin" ? "shell" : "cmd";
+	let keys;
+	try {
+		const read = readValkeyKeys(fs.readFileSync(envPath), { loader, path: envPath });
+		if (read.error) throw new Error(read.error);
+		keys = read.keys;
+	} catch (err) {
+		out(`\n✗ ${VALKEY_PASSWORD_KEY}: ${err?.message ?? err}\n`);
+		summary.push([VALKEY_PASSWORD_KEY, `NOT decided: ${err?.message ?? err}`]);
+		return null;
+	}
+	const decided = valkeyPasswordDecision(keys, { envPath });
+	if (decided.error) {
+		out(`\n✗ ${decided.error}\n`);
+		summary.push([VALKEY_PASSWORD_KEY, `NOT usable: ${decided.error}`]);
+		return null;
+	}
+	if (decided.note) {
+		out(`\n⚠ ${decided.note}\n`);
+		summary.push([VALKEY_PASSWORD_KEY, decided.note]);
+		return null;
+	}
+	if (!decided.generate) {
+		summary.push([VALKEY_PASSWORD_KEY, "already set, left untouched (value not shown)"]);
+		return decided.password;
+	}
+	const password = newPassword();
+	try {
+		if (!updateEnvFile(envPath, VALKEY_PASSWORD_KEY, password, { fs, platform, narrow: true }).changed) throw new Error("the file already assigns it");
+	} catch (err) {
+		out(`\n✗ ${VALKEY_PASSWORD_KEY} could not be written: ${err?.message ?? err}\n`);
+		summary.push([VALKEY_PASSWORD_KEY, `NOT written: ${err?.message ?? err}. The Valkey up starts then has no password`]);
+		return null;
+	}
+	out(`\n✓ generated ${VALKEY_PASSWORD_KEY} into .env (32 random bytes, hex; value not shown; .env is now readable by this account only)\n`);
+	summary.push([VALKEY_PASSWORD_KEY, "generated into .env (value not shown; Valkey requires it, and every client sends it)"]);
+	return password;
+}
+
+/**
+ * PI_VALKEY_PORT in .env (PR #475's review, round 3): written where VALKEY_URL's port is not 6379 and .env names none,
+ * a differing value named and left alone (`valkeyPortEnvDecision`).
+ */
+function dockerValkeyPortStep({ fs, envPath, platform, port, out, summary }) {
+	if (!fs.existsSync(envPath)) return;
+	const loader = platform === "linux" ? "systemd" : platform === "darwin" ? "shell" : "cmd";
+	let decided;
+	try {
+		const found = readEnvAssignments(fs.readFileSync(envPath), [VALKEY_PORT_KEY], { loader })[VALKEY_PORT_KEY];
+		decided = valkeyPortEnvDecision(found === undefined ? undefined : (found.value ?? "?"), port, { envPath });
+		if (decided.write && !updateEnvFile(envPath, VALKEY_PORT_KEY, decided.write, { fs, platform }).changed) throw new Error("the file already assigns it");
+	} catch (err) {
+		out(`\n✗ ${VALKEY_PORT_KEY} could not be written: ${err?.message ?? err}\n`);
+		summary.push([VALKEY_PORT_KEY, `NOT written: ${err?.message ?? err}`]);
+		return;
+	}
+	if (decided.conflict) {
+		out(`\n⚠ ${decided.conflict}\n`);
+		summary.push([VALKEY_PORT_KEY, decided.conflict]);
+	} else if (decided.write) {
+		out(`\n✓ wrote ${VALKEY_PORT_KEY}=${port} into .env (VALKEY_URL's port), so compose in this folder publishes its Valkey there\n`);
+		summary.push([VALKEY_PORT_KEY, `written: ${port} (VALKEY_URL's port)`]);
+	}
+}
+
+/** Whether `path` is a directory, followed through a link; false where the seam cannot say (a test's fake fs). */
+function pathIsDirectory(fs, path) {
+	try {
+		return typeof fs.statSync === "function" && fs.statSync(path).isDirectory() === true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Whether this folder holds the compose file its compose lines name (issue #480: a folder init made does not). Every
+ * compose line `up` prints as a later or fallback step asks this first; the hand-over's own consented compose runs are
+ * reached only in a folder the wizard wrote the override into beside that file.
+ */
+function composeHere(cwd, fs) {
+	return fs.existsSync(join(cwd, COMPOSE_FILE));
+}
+
+/**
+ * The compose command a message names for this folder (PR #475's review): the folder's project and the hand-over
+ * override where the wizard wrote one, else the docs' plain command with the note a wizard folder needs.
+ */
+function composeCommandFor(cwd, fs, tail) {
+	const handedOver = fs.existsSync(join(cwd, COMPOSE_VALKEY_OVERRIDE));
+	const project = composeProjectName(cwd);
+	const args = [...composeArgs(handedOver ? { project, override: true } : {}), ...tail];
+	return `docker ${args.join(" ")}${handedOver ? "" : `\` (in a folder /dispatch setup laid out, with -p ${project} after \`compose`}`;
+}
+
+/**
+ * Where docker's Valkey is, from VALKEY_URL as the service reads it (`deploymentValkeyEnv`): `{ port, notes }`, with
+ * `remote` for another host (nothing is added for it) or `error` for a URL the Valkey `up` starts could not serve.
+ */
+function dockerValkeyWhere({ env, fs, envPath, platform }) {
+	const read = deploymentValkeyEnv({ env, fs, envPath, platform });
+	if (read.error) return { port: 6379, notes: [], error: `${read.error}. up judges the Valkey the service will use, so it adds none` };
+	const url = read.env.VALKEY_URL;
+	const target = valkeyTarget(url);
+	if (target.error) return { port: 6379, notes: read.notes, error: `VALKEY_URL: ${target.error}` };
+	if (!isLoopbackHost(target.host)) return { port: target.port, notes: read.notes, remote: target.host };
+	if (target.host.includes(":")) {
+		return { port: target.port, notes: read.notes, error: `VALKEY_URL's host is ${target.host}, and the Valkey up starts is published on 127.0.0.1 only, so the worker would not reach it. Write VALKEY_URL=redis://127.0.0.1:${target.port}` };
+	}
+	return { port: target.port, notes: read.notes };
+}
+
+/** `claimValkeyOwner` (connection.mjs) with the deployment's credential, as every client of the project gets it. */
+async function defaultClaimValkeyOwner(url, folder, { env, cwd }) {
+	const { claimValkeyOwner, valkeyClientContext } = await import("./connection.mjs");
+	return claimValkeyOwner(url, folder, { context: valkeyClientContext({ env, cwd }) });
+}
+
+/** Whether the Valkey at `url` answers a client that sends no password: its `valkeyAuthState`, through connection.mjs. */
+async function defaultProbeValkeyAuth(url, { env, cwd }) {
+	const { valkeyAuthState, valkeyClientContext } = await import("./connection.mjs");
+	return (await valkeyAuthState(url, { withoutPassword: true, context: valkeyClientContext({ env, cwd }) })).state;
 }
 
 /** Exit code of a spawned command; null when it could not launch (not on PATH) — mirrors doctor. */
@@ -295,11 +1559,13 @@ function runCmd(spawn, cmd, args) {
  * Run a CONSENTED command with its stdout+stderr streamed to `out` as it happens — a docker pull's
  * progress is the operator's confirmation that the thing they approved is the thing running.
  */
-function runStreamed(spawn, cmd, args, out) {
+function runStreamed(spawn, cmd, args, out, { env } = {}) {
 	return new Promise((resolve) => {
 		let child;
 		try {
-			child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+			// `env` only where a value must reach the command without being on its argv (issue #468: `docker run -e
+			// VALKEY_PASSWORD` reads it from here); otherwise the child inherits this process's, as before.
+			child = spawn(cmd, args, env ? { stdio: ["ignore", "pipe", "pipe"], env } : { stdio: ["ignore", "pipe", "pipe"] });
 		} catch {
 			resolve(null);
 			return;
@@ -311,6 +1577,54 @@ function runStreamed(spawn, cmd, args, out) {
 	});
 }
 
+/**
+ * Like runCmdCapture with the streams SEPARATE, for a podman query whose answer is stdout alone (round 2, E2): podman
+ * prints warnings on stderr on ordinary accounts, and a merged capture made `true` and our own label unequal.
+ */
+function runCmdQuery(spawn, cmd, args) {
+	return new Promise((resolve) => {
+		let child;
+		try {
+			child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+		} catch {
+			resolve({ 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", () => resolve({ code: null, stdout, stderr }));
+		child.on("close", (code) => resolve({ code, stdout, stderr }));
+	});
+}
+
+/**
+ * `docker network create pi-dispatch-egress-out` only where it does not exist (exec round 3): a recreate otherwise printed
+ * the daemon's "network name ... already used" every time. A quiet inspect first; its answer is never a failure, since the
+ * run that follows is what is checked.
+ *
+ * ASKED BEFORE THE CONSENT, and the create line shown only when the network is missing (PR #456's final check): `--yes`
+ * "runs exactly the lines shown", and the line it used to show, `... create pi-dispatch-egress-out   (only if it does
+ * not exist yet)`, was not a command anyone could run. The inspect is read-only, so it runs before the question; the
+ * create after it runs exactly when its line was shown.
+ */
+async function egressNetworkLines(spawn, network) {
+	network.missing = (await runCmdQuery(spawn, "docker", ["network", "inspect", EGRESS_NETWORK_ARGS[2]])).code !== 0;
+	return network.missing ? [`docker ${EGRESS_NETWORK_ARGS.join(" ")}`] : [];
+}
+/**
+ * The network the run needs, made at RUN time (PR #466 gate round 1): asked again after the answer, since it can be
+ * removed while the prompt waits, and then `docker run --network` fails "network not found" (measured). Created when it
+ * is missing then; when its create line was not shown, because it existed at the question, that is said before it runs.
+ * One that appeared meanwhile is left as it is.
+ */
+async function ensureEgressNetwork(spawn, out, network) {
+	if ((await runCmdQuery(spawn, "docker", ["network", "inspect", EGRESS_NETWORK_ARGS[2]])).code === 0) return;
+	if (!network.missing) out(`${EGRESS_NETWORK_ARGS[2]} was removed while the question waited, and the proxy's run needs it: \`docker ${EGRESS_NETWORK_ARGS.join(" ")}\`\n`);
+	await runStreamed(spawn, "docker", EGRESS_NETWORK_ARGS, out);
+}
+
 /** Like runCmd but with stdout+stderr captured, for read-only lookups (docker ps). */
 function runCmdCapture(spawn, cmd, args) {
 	return new Promise((resolve) => {