@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/src/service.mjs

@@ -23,6 +23,9 @@
  *                   package's own exported entry, wherever npm (or the workspace symlink) put it.
  *                   null when the package is not installed — receiver renders refuse loudly instead
  *                   of writing a unit that would crash-loop at boot.
+ *   - consoleEntry  the admin package's bin, dist/console.mjs (issue #708, resolveConsoleEntry): the
+ *                   same resolution, else the `pi-dispatch-console` a global install put on PATH. null
+ *                   refuses the console renders, for the receiver's reason.
  *
  * Scope doctrine:
  *   - User-level by default, everywhere. macOS REFUSES root outright (a LaunchAgent is per-user, and a
@@ -36,24 +39,31 @@
  *     from the cross-scope check (a second receiver is pointless, not destructive) but still refuse
  *     same-scope duplicates.
  *
- * `restart --drain` composes the README's manual ritual (pause → poll active → restart → resume) with
- * the same VALKEY_URL-only queue connection as cli.mjs's pause/resume: the drain must work even when
- * the rest of the config is broken.
+ * `restart --drain` composes the README's manual ritual (pause → poll active → restart → resume) over this
+ * host's queues (issue #804): the shared one and, when the deployment declares PI_WORKER_NAME, the host's own,
+ * which is where its cron, chained and manual runs wait. It reads VALKEY_URL and PI_WORKER_NAME alone, as cli.mjs's
+ * verbs read them, so the drain works even when the rest of the config is broken. It is not the fleet's pause: a
+ * peer's own queue is neither paused nor waited for.
  */
 import { spawn as nodeSpawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
+import { accessSync, constants as fsConstants, existsSync, mkdirSync, readFileSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { lookup as dnsLookup } from "node:dns/promises";
 import { connect as netConnect } from "node:net";
 import { homedir, networkInterfaces, tmpdir, userInfo } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { parseBackendList, venuesOf } from "./backends.mjs";
+import { openshellSetupOf, parseBackendList, venuesOf } from "./backends.mjs";
+import { OPENSHELL_BREW_INSTALL, OPENSHELL_GATEWAY_UNIT, OPENSHELL_NO_WINDOWS } from "./openshell-cli.mjs";
 import { sharedShellIgnored } from "./deployment-venue.mjs";
 import { egressArmed, egressProxyName } from "./egress.mjs";
 import { ENV_WRITER_FS, updateEnvFile } from "./env-file.mjs";
+import { operatorCount, readTokensFile, tokensFilePath } from "./console-tokens.mjs";
+import { resolveSetupWorkerEntry, setupCachePath } from "./setup-host-entry.mjs";
+import { cliDeploymentEnv, deploymentServiceEnv } from "./service-env.mjs";
+import * as nodeFs from "node:fs";
 import { MODEL_ENDPOINTS_INCLUDE_NAME } from "./model-endpoints.mjs";
-import { VALKEY_HEALTH_SCRIPT, VALKEY_PASSWORD_KEY, VALKEY_START_SCRIPT, dollarsDoubled, newValkeyPassword, valkeyPasswordDecision } from "./valkey-auth.mjs";
+import { VALKEY_HEALTH_SCRIPT, VALKEY_IMAGE, VALKEY_PASSWORD_KEY, VALKEY_START_SCRIPT, dollarsDoubled, newValkeyPassword, valkeyPasswordDecision } from "./valkey-auth.mjs";
 import { ALL_QUADLET_FILES, ALLOWLIST_PLACEHOLDER, MODEL_ENDPOINTS_PLACEHOLDER, NETNS_KEEPER, NETNS_KEEPER_FORMAT, judgeNetnsKeeper, keeperUnderRunningProxyHint, managerEnvRefusal, PROXY_CONF_PLACEHOLDER, QUADLET_FILES, applyStack, decideValkey, describeAction, passwdNameFrom, readSubuidRanges, readValkeyKeys, valkeySharedOn, VALKEY_SHARED_KEY, describeRollBack, journalWrite, rollBackWrites, foreignContainerRefusal, foreignContainers, lingerNote, planStack, proxyConfCopyPath, proxyRestartWarning, quadletDir, readLinger, readStackKeys, stackComponents, unknownContainerRefusal, userBusRefusal, valkeyEnvPath, valkeyPasswordRestartWarning, workerUnitDeps } from "./podman-stack.mjs";
 
 /** This command's default fs seam: its own calls, and every call the `.env` writer makes (`ENV_WRITER_FS`, issue #522). */
@@ -80,6 +90,70 @@ function resolveReceiverStart() {
 	}
 }
 
+/** The admin package, whose bin is the console (`pi-dispatch-console` -> ./dist/console.mjs, in its published `files`). */
+export const CONSOLE_PACKAGE = "@edgehero/pi-dispatch-admin";
+
+/**
+ * The console's entry point (issue #708): the admin package's dist/console.mjs as module resolution finds it from here,
+ * else the real path of the `pi-dispatch-console` on this shell's PATH. null when neither exists.
+ *
+ * Two lookups because the admin package is NOT a dependency of this one: it is a pi extension an operator installs
+ * with `pi install` or `npm i -g`. Resolution from here finds it when it sits in the same node_modules tree as this
+ * worker (both global, or both in the deployment folder); the PATH lookup covers the rest. The package has no
+ * `exports` map, so the subpath resolves as a plain file, and `import.meta.resolve` does not check that the file
+ * exists (measured on node 23.5: a checkout without `node admin/build.mjs` resolves to a dist/ that is not there),
+ * hence the existence check.
+ *
+ * The PATH hit is accepted only when its real path IS the package's file: it ends in dist/console.mjs and the
+ * package.json two levels up names this package (round 1 review of #708). npm's bin is a symlink to exactly that file,
+ * but pnpm and Volta put a SHIM on PATH (a shell script, or a binary that picks a version at run time), and a unit that
+ * ran `node <shim>` would crash at every start. The real path, not the PATH name, because a service manager's PATH is
+ * not this shell's and launchd's cannot see an nvm or Homebrew prefix at all. `findOnPath` reads only absolute POSIX
+ * directories, so on Windows this lookup does not run and resolution is the only way (`refuseMissingConsole` says so).
+ */
+export function resolveConsoleEntry({ findBin, realpath, exists = existsSync, readFile = (p) => readFileSync(p, "utf8"), resolveModule = (specifier) => import.meta.resolve(specifier) }) {
+	try {
+		const resolved = fileURLToPath(resolveModule(`${CONSOLE_PACKAGE}/dist/console.mjs`));
+		if (exists(resolved)) return resolved;
+	} catch {}
+	const found = findBin("pi-dispatch-console");
+	if (!found) return null;
+	try {
+		const real = realpath(found);
+		const dist = dirname(real);
+		if (basename(real) !== "console.mjs" || basename(dist) !== "dist") return null;
+		const pkg = JSON.parse(readFile(join(dirname(dist), "package.json")));
+		return pkg?.name === CONSOLE_PACKAGE ? real : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The console tokens file the SERVICE's console reads for the deployment in `deployDir` (issue #708): PI_CONSOLE_TOKENS_FILE
+ * from the deployment `.env` (through the reader the console itself uses), else console-tokens.json there. Never this
+ * shell's export: the unit inherits no shell, loads no EnvironmentFile and its wrapper sources no `.env`, so `serve`
+ * finds only the file's value. One helper for `service install --console` and `up`'s next step, so the two cannot
+ * name different files.
+ */
+export function consoleTokensPathFor(deployDir, platform) {
+	const { env } = deploymentServiceEnv({ env: {}, dir: deployDir, keys: ["PI_CONSOLE_TOKENS_FILE"], platform, fs: nodeFs });
+	return tokensFilePath(env, deployDir);
+}
+
+/**
+ * How many operator tokens the console this unit starts would find (issue #708): `{ path, operators }` or
+ * `{ path, refusal }`. The tokens file is where `serve --deployment <deployDir>` looks: PI_CONSOLE_TOKENS_FILE as the
+ * SERVICE sees it (the deployment `.env`, through the reader the console itself uses), never this shell's export,
+ * which the unit does not inherit. Read with the real filesystem on purpose: `readTokensFile` judges the file the way
+ * `serve` does (owner-only, regular, no symlink), and a fake that answered differently would prove nothing.
+ */
+export function readConsoleOperators(deployDir, platform) {
+	const path = consoleTokensPathFor(deployDir, platform);
+	const read = readTokensFile({ path });
+	return read.refusal ? { path, refusal: read.refusal } : { path, operators: operatorCount(read.file) };
+}
+
 /**
  * The whole substitution surface, template by template. The render replaces ONLY these literals (plus
  * the scope-dependent `User=` / `WantedBy=` rewrites called out below); the pin test in
@@ -89,7 +163,8 @@ function resolveReceiverStart() {
 // The two worker-template literals a podman render rewrites (issue #430), spelled once for the pin table and the render.
 const WORKER_DESCRIPTION = "Description=pi-dispatch worker (drains the job queue on the host; launches job containers via docker)";
 const WORKER_VALKEY_COMMENT = "# Valkey must be reachable (on this host, `pi-dispatch up` in the deployment folder starts it), but it is a separate\n# unit/container -- not ordered here since it may be remote.\n";
-
+// The template's ordering line, which an openshell render on Podman alone rewrites without docker.service (issue #707).
+const WORKER_AFTER = "After=network-online.target docker.service";
 export const TEMPLATE_PINS = {
 	"worker.service": [
 		"ExecStart=/usr/bin/node worker/src/cli.mjs worker", // the WHOLE line → `<execPath> <cliPath> worker` (cli.mjs sits beside this module in src/ in both layouts)
@@ -100,6 +175,7 @@ export const TEMPLATE_PINS = {
 		"\nWants=network-online.target\n", // the anchor the podman venue's Wants=/After= on its Quadlet units go after (issue #430), user scope only
 		"Description=pi-dispatch worker (drains the job queue on the host; launches job containers via docker)", // → names rootless podman on a podman deployment (issue #430)
 		"# Valkey must be reachable (on this host, `pi-dispatch up` in the deployment folder starts it), but it is a separate\n# unit/container -- not ordered here since it may be remote.\n", // → says it IS ordered, when the Quadlet Valkey is installed
+		"After=network-online.target docker.service", // → without docker.service on an openshell deployment whose engine is podman and that blesses no `local` (issue #707); the openshell gateway's Wants=/After= go at the \nWants= anchor above
 		// Byte-for-byte survivors — semantics the render must not lose:
 		"RestartPreventExitStatus=2", // EXIT_POLICY is never restarted (a retry loop is a bill)
 		"StartLimitIntervalSec=60",
@@ -123,8 +199,21 @@ export const TEMPLATE_PINS = {
 		"KillSignal=SIGTERM",
 		"TimeoutStopSec=30",
 	],
+	// Issue #708: the console, the receiver's shape. Its ExecStart names the console package's entry and the deployment
+	// (`serve --deployment`), so the folder is in the line twice and the WHOLE line is replaced, as for the other two.
+	"console.service": [
+		"ExecStart=/usr/bin/node /usr/lib/node_modules/@edgehero/pi-dispatch-admin/dist/console.mjs serve --deployment /opt/pi-dispatch", // the WHOLE line → `<execPath> <consoleEntry> serve --deployment <deployDir>`
+		"WorkingDirectory=/opt/pi-dispatch",
+		"\nUser=pi\n",
+		"WantedBy=multi-user.target",
+		"RestartPreventExitStatus=2", // serve's refusals (no operator token, the lock held, an unusable listen) exit 2, and the next start would refuse the same way
+		"StartLimitIntervalSec=60",
+		"StartLimitBurst=5",
+		"KillSignal=SIGTERM",
+		"TimeoutStopSec=30",
+	],
 	"com.pi-dispatch.worker.plist": [
-		"<string>com.pi-dispatch.worker</string>", // → com.pi-dispatch.receiver for --receiver
+		"<string>com.pi-dispatch.worker</string>", // → com.pi-dispatch.receiver for --receiver, com.pi-dispatch.console for --console
 		"<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>", // → the PACKAGE's wrapper copy, followed by the exec argv (<node> <script> …) the wrapper now runs verbatim
 		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>", // → the deployment folder (load-bearing: the wrapper sources ./.env there); also the anchor for the PATH injection below
 		"<string>/opt/pi-dispatch/logs/worker.out.log</string>", // → <deployDir>/logs/… (install creates the dir; launchd will not)
@@ -149,14 +238,18 @@ export const TEMPLATE_PINS = {
 	// they read back (`--env-setup`, issue #209 — the plist's EnvironmentVariables dict on macOS, nssm's
 	// AppEnvironmentExtra on Windows), and a rename on one side with silence on the other would produce
 	// a unit that starts fine and ignores the operator's secrets manager.
-	"worker-env-wrapper.sh": ["PI_ENV_SETUP"],
-	"worker-env-wrapper.cmd": ["PI_ENV_SETUP"],
+	// Since issue #708 also PI_WRAPPER_NO_DOTENV, which the console's plist and nssm entry set and the wrappers test
+	// before they load ./.env: the same rename hazard, and here a rename would hand the console every worker secret.
+	"worker-env-wrapper.sh": ["PI_ENV_SETUP", "PI_WRAPPER_NO_DOTENV"],
+	"worker-env-wrapper.cmd": ["PI_ENV_SETUP", "PI_WRAPPER_NO_DOTENV"],
 	// The podman venue's stack as Quadlet units (issue #430, podman-stack.mjs). Three are copied verbatim, so what is
 	// pinned is what the worker and the installer rely on by NAME: the container and network names the worker attaches
 	// by, the unit names the worker unit Wants=, the loopback-only port, and an explicit Network= in every .container
 	// (a containers.conf `netns = "host"` would otherwise put it in the host namespace, measured).
 	"pi-dispatch-valkey.network": ["NetworkName=pi-dispatch-valkey"],
 	"pi-dispatch-valkey.container": [
+		// Issue #761: the pinned Valkey, fully qualified for Podman's short-name rule, from the one constant.
+		`Image=docker.io/${VALKEY_IMAGE}`,
 		"ContainerName=pi-dispatch-valkey",
 		"Network=pi-dispatch-valkey.network",
 		"PublishPort=127.0.0.1:6379:6379",
@@ -222,7 +315,7 @@ export const TEMPLATE_PINS = {
  * composed form quotes.
  */
 const ENV_SETUP_REFUSALS = {
-	linux: { re: /['"$\\\x00-\x1f\x7f]/, why: "the path lands inside a single-quoted systemd Exec word, and systemd expands $VAR there whatever the quoting" },
+	linux: { re: /['"$%\\\x00-\x1f\x7f]/, why: "the path lands inside a single-quoted systemd Exec word, and systemd expands $VAR and %-specifiers there whatever the quoting" },
 	darwin: { re: /[<>&"\x00-\x1f\x7f]/, why: "the launchd unit is a plist, and the path lands in an XML <string>" },
 	win32: { re: /[%"\x00-\x1f\x7f]/, why: "cmd expands %VAR% when the wrapper runs the script" },
 };
@@ -278,6 +371,23 @@ const ENV_SETUP_READERS = {
 	},
 };
 
+/**
+ * `text` as XML character data: `&`, `<` and `>` only, `&` first. No string this render writes lands in an attribute,
+ * so `'` and `"` need no entity, and leaving them literal keeps every plist that held one byte-identical to before
+ * (final review of #708). `>` is escaped although character data allows it, so a path can never write `-->`.
+ */
+function xmlText(text) {
+	return String(text).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/**
+ * The reverse, for what readUnitSeam reads back out of a plist: the three entities `xmlText` writes plus the two it does
+ * not (a hand-edited plist may carry them). `&amp;` last, so `&amp;lt;` stays `&lt;`.
+ */
+function xmlUntext(text) {
+	return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+
 /**
  * What an installed unit records: the configured `--env-setup` path and the deployment folder it
  * serves. Both null for a unit rendered without the flag, which is every unit that predates issue #209
@@ -294,7 +404,12 @@ export function readUnitSeam(text, platform) {
 	// capture already ends exactly where the renderer's delimiter does, and a path is allowed to hold a
 	// space anywhere in it. An empty value means the same as no value at all.
 	const clip = (v) => (v === null ? null : v.replace(/\r$/, "") || null);
-	return { setup: clip(grab(readers.setup)), deployDir: clip(grab(readers.deployDir)) };
+	// The folder as the renderer escaped it (round 1 review of #708): `%` doubled in a systemd unit (WorkingDirectory=
+	// expands specifiers), XML entities in a plist. Undone here so a folder holding either still reads as itself.
+	const folder = clip(grab(readers.deployDir));
+	const deployDir = folder === null ? null : platform === "linux" ? folder.replace(/%%/g, "%") : platform === "darwin" ? xmlUntext(folder) : folder;
+	const setup = clip(grab(readers.setup));
+	return { setup: setup !== null && platform === "darwin" ? xmlUntext(setup) : setup, deployDir };
 }
 
 /**
@@ -312,7 +427,7 @@ export function readUnitUser(text, platform) {
 
 const SUBCOMMANDS = new Set(["render", "install", "uninstall", "status", "start", "stop", "restart"]);
 
-const SERVICE_USAGE = `pi-dispatch service — run the worker (or --receiver) as an OS service, rendered for THIS host
+const SERVICE_USAGE = `pi-dispatch service — run the worker (or --receiver, or --console) as an OS service, rendered for THIS host
 
   pi-dispatch service render                the unit(s) with this host's real node + repo paths
   pi-dispatch service install [--force]     write + enable the user-level unit
@@ -320,10 +435,14 @@ const SERVICE_USAGE = `pi-dispatch service — run the worker (or --receiver) as
   pi-dispatch service uninstall             stop, disable and remove the installed unit
   pi-dispatch service status                which unit exists in which scope, and whether it is active
   pi-dispatch service start|stop            thin launchctl / systemctl --user / nssm wrappers
-  pi-dispatch service restart [--drain]     restart; --drain pauses the queue, waits for active jobs
-                                            to finish, restarts, resumes  [--drain-timeout <s>, default 600]
+  pi-dispatch service restart [--drain]     restart; --drain pauses this host's queues (the shared one, and
+                                            its own when PI_WORKER_NAME is set), waits for their active jobs to
+                                            finish, restarts, resumes the ones it paused  [--drain-timeout <s>, default 600]
 
   flags: --receiver          the webhook receiver instead of the worker
+         --console           the operator console (pi-dispatch-console serve) instead of the worker;
+                             install needs an operator token (pi-dispatch-console token add)
+         --host-setup        render|install --console: grant bounded local setup, Linux/macOS user scope
          --user | --system   linux scope (default --user; --system never executes root commands)
          --force             replace an existing unit in the same scope
          --print             also print the rendered unit before installing
@@ -343,6 +462,10 @@ export async function runService(argv = [], deps = {}) {
 		// Injectable so tests can render as if from an npm install without installing anything.
 		moduleDir = MODULE_DIR,
 		resolveReceiver = resolveReceiverStart,
+		// Issue #708: the console package's entry (see resolveConsoleEntry); a test injects a path or null.
+		resolveConsole = null,
+		// Issue #708: the operator tokens the console unit would start with (see readConsoleOperators).
+		consoleOperators = readConsoleOperators,
 		home = homedir(),
 		// env-internal USER: whose account a rendered unit runs as, taken from the login already running
 		// this command. An operator changes it by running the command as someone else, not by declaring it.
@@ -354,7 +477,9 @@ export async function runService(argv = [], deps = {}) {
 		err = (s) => process.stderr.write(s),
 		sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
 		now = () => Date.now(),
-		queue = null, // test seam; production builds one lazily in doRestart from VALKEY_URL
+		// Test seam: `(name) => queue`, one handle per queue the drain covers. Production builds them lazily in doRestart
+		// from VALKEY_URL.
+		queueFor = null,
 		// Is anything on 127.0.0.1:6379? Asked only on a podman deployment, to decide whether the Quadlet Valkey is
 		// wanted (issue #430); the same plain TCP connect `up` uses, for up's reason. Issue #464: asked of every address
 		// VALKEY_URL's host resolves to (`lookup`, as the worker's client resolves it), and `interfaces` says which of
@@ -368,6 +493,9 @@ export async function runService(argv = [], deps = {}) {
 		realpath = (p) => realpathSync(p),
 		// Issue #468: how a new Valkey password is made (a test's seam; 32 random bytes, hex, never shown).
 		newPassword = newValkeyPassword,
+		// Issue #707: where this shell finds a CLI by name (its PATH, the first executable file), for the plist's PATH.
+		// env-internal PATH: this shell's own search path, read only to find the openshell CLI's directory for the plist.
+		findBin = (name) => findOnPath(name, env.PATH),
 	} = deps;
 
 	let values, positionals;
@@ -377,6 +505,8 @@ export async function runService(argv = [], deps = {}) {
 			allowPositionals: true,
 			options: {
 				receiver: { type: "boolean", default: false },
+				console: { type: "boolean", default: false },
+				"host-setup": { type: "boolean", default: false },
 				user: { type: "boolean", default: false },
 				system: { type: "boolean", default: false },
 				force: { type: "boolean", default: false },
@@ -396,9 +526,17 @@ export async function runService(argv = [], deps = {}) {
 		return cmd ? 1 : 0; // bare `service` is a usage view, an unknown subcommand is an error
 	}
 	if (values.user && values.system) return fail(err, "--user and --system are mutually exclusive");
+	// One component per invocation: every subcommand addresses exactly one unit, and guessing which of two was meant
+	// would install, stop or remove the other one.
+	if (values.receiver && values.console) return fail(err, "--receiver and --console are mutually exclusive: each names one service; run the command once for each");
+	if (values["host-setup"] && (!values.console || !["render", "install"].includes(cmd) || values.system || !["linux", "darwin"].includes(platform))) return fail(err, "--host-setup is only for render/install --console in a Linux or macOS user service");
 	if (platform === "darwin" && values.system) {
-		return fail(err, "macOS is user-scope only (a LaunchAgent): Docker Desktop lives in the login session, so a system daemon would wait on a docker socket that only exists once you log in. Drop --system.");
+		// The Docker Desktop reason is the worker's; the console and the receiver start no container (round 1 review of #708).
+		return fail(err, values.console || values.receiver ? "macOS is user-scope only here (a LaunchAgent, in your login session, where this command installs every unit). Drop --system." : "macOS is user-scope only (a LaunchAgent): Docker Desktop lives in the login session, so a system daemon would wait on a docker socket that only exists once you log in. Drop --system.");
 	}
+	// `--drain` pauses the QUEUES and waits for their jobs, which only the worker runs (round 1 review of #708): on the
+	// receiver or the console it would pause every job for a restart that drains nothing.
+	if (values.drain && (values.console || values.receiver)) return fail(err, "--drain applies to the worker alone (it pauses the queues and waits for their running jobs); restart the receiver or the console without it");
 	if (platform === "win32" && (values.user || values.system)) {
 		return fail(err, "Windows services via nssm are machine-scoped; --user/--system do not apply here");
 	}
@@ -420,6 +558,9 @@ export async function runService(argv = [], deps = {}) {
 		// Resolved only when asked for: worker-only invocations must not care whether the receiver
 		// package exists here at all.
 		receiverStart: values.receiver ? resolveReceiver() : null,
+		// Issue #708: the same rule for the console, resolved only for --console.
+		consoleEntry: values.console ? (resolveConsole ?? (() => resolveConsoleEntry({ findBin, realpath })))() : null,
+		consoleOperators,
 		home,
 		user,
 		tmp,
@@ -429,16 +570,21 @@ export async function runService(argv = [], deps = {}) {
 		err,
 		sleep,
 		now,
-		queue,
+		queueFor,
 		probeTcp,
 		lookup,
 		interfaces,
 		runSync,
 		realpath,
 		newPassword,
-		which: values.receiver ? "receiver" : "worker",
+		findBin,
+		which: values.receiver ? "receiver" : values.console ? "console" : "worker",
 		scope: platform === "linux" && values.system ? "system" : "user",
 		force: values.force,
+		// The terminal bootstrap reuses this exact planner for an existing granted console.
+		// This dependency is internal; no environment variable or start flag grants authority.
+		hostSetup: values["host-setup"] || (values.console && deps.setupConsoleGrant === true),
+		setupExpected: deps.setupExpected,
 		// The operator's env-setup script, or null for the shipped default. Null is load-bearing: with no
 		// seam configured every render below is byte-identical to what it produced before issue #209.
 		envSetup: null,
@@ -455,7 +601,13 @@ export async function runService(argv = [], deps = {}) {
 		if (resolved.error) return fail(err, resolved.error);
 		ctx.envSetup = resolved.path;
 	}
+	if (ctx.hostSetup && (!(deps.setupEntry ?? resolveSetupWorkerEntry)().entry || setupCachePath(ctx.consoleEntry))) return fail(err, "--host-setup needs durable installed worker and console entries, never npm execution-cache paths");
 
+	if (deps.setupPlan === true) return setupServicePlan(ctx, cmd);
+	if (deps.setupExpected !== undefined) {
+		const current = await setupServicePlan(ctx, cmd);
+		if (JSON.stringify(current) !== JSON.stringify(deps.setupExpected)) return fail(err, "the setup service plan changed before dispatch; preview it again");
+	}
 	switch (cmd) {
 		case "render":
 			return doRender(ctx);
@@ -476,6 +628,107 @@ export async function runService(argv = [], deps = {}) {
 	}
 }
 
+/**
+ * The services this command installs, by `ctx.which`. Each has ONE systemd template, and the launchd and nssm forms are
+ * derived from the worker's (the receiver's precedent): the same KeepAlive/ExitTimeOut shape and the same AppExit pair,
+ * which is what keeps every component's exit 2 a stop rather than a restart loop.
+ *
+ *   template      the deploy/ file renderLinuxUnit reads (a TEMPLATE_PINS key)
+ *   templateExec  that template's ExecStart line, replaced WHOLE by execArgvFor's argv
+ */
+const COMPONENTS = Object.freeze(["worker", "receiver", "console"]);
+const COMPONENT_TEMPLATES = Object.freeze({
+	worker: { template: "worker.service", templateExec: "ExecStart=/usr/bin/node worker/src/cli.mjs worker" },
+	receiver: { template: "receiver.service", templateExec: "ExecStart=/usr/bin/node receiver/src/start.mjs" },
+	console: { template: "console.service", templateExec: "ExecStart=/usr/bin/node /usr/lib/node_modules/@edgehero/pi-dispatch-admin/dist/console.mjs serve --deployment /opt/pi-dispatch" },
+});
+
+/**
+ * The command a unit runs, for every service manager: the systemd ExecStart, the argv the launchd wrapper execs and
+ * nssm's AppParameters. One function because there were three copies of it, one per manager, and a component added
+ * to two of them would install a unit on the third that runs the worker. Absolute node, absolute script: nothing here
+ * depends on a PATH or a working directory. The console names its deployment itself (`serve --deployment`), so it
+ * reads THIS deployment's `.env` and tokens even where the manager's working directory were not honoured.
+ */
+function execArgvFor(ctx) {
+	if (ctx.which === "receiver") return [ctx.execPath, ctx.receiverStart];
+	if (ctx.which === "console") return [ctx.execPath, ctx.consoleEntry, "serve", "--deployment", ctx.deployDir, ...(ctx.hostSetup ? ["--host-setup"] : [])];
+	return [ctx.execPath, ctx.cliPath, "worker"];
+}
+
+/** The browser's planner uses the installer's own render and stack plan, never a second unit template (#774). */
+export async function planServiceSetup(argv, deps = {}) {
+	return runService(argv, { ...deps, setupPlan: true, out: () => {}, err: () => {} });
+}
+
+async function setupServicePlan(ctx, operation) {
+	const no = (reason) => ({ refusal: reason });
+	if (!["linux", "darwin"].includes(ctx.platform) || ctx.scope !== "user" || (ctx.platform === "darwin" && ctx.euid === 0)) return no("unsupported");
+	if (ctx.which === "receiver" && !ctx.receiverStart) return no("missing-receiver");
+	if (ctx.which === "console" && !ctx.consoleEntry) return no("unsafe-entry");
+	if (renderRefusal(ctx) !== null) return no("unsafe-deployment");
+	const paths = unitPaths(ctx);
+	if (ctx.which === "worker" && paths.otherScopeWorkerPaths.some((p) => ctx.fs.existsSync(p))) return no("foreign-service");
+	const venue = deploymentVenue(ctx);
+	if (venue.error) return no("unsafe-deployment");
+	let stack = null;
+	if (ctx.platform === "linux" && ctx.which === "worker") {
+		stack = await stackFor(ctx, venue, { readKeeper: true });
+		if (stack?.error || stack?.valkeyRefusal || stack?.pendingPassword || (stack?.plan.restart?.length ?? 0) > 0 || (stack?.plan.clientsRestarted?.length ?? 0) > 0 || stack?.plan.files.some((f) => f.state === "changed")) return no("unsafe-dependencies");
+		if (stack) {
+			const foreign = await foreignContainers(stack.plan, (cmd, args) => runQuery(ctx, cmd, args));
+			if (foreign.found.length || foreign.unknown.length) return no("unsafe-dependencies");
+		}
+	}
+	const text = ctx.platform === "linux" ? renderLinuxUnit(ctx, stack?.plan.start ?? [], venue.venues ?? null, venue.openshell) : renderPlist(ctx, { pathDirs: openshellPathDirs(ctx, venue) });
+	let before = null;
+	if (ctx.fs.existsSync(paths.installPath)) {
+		try {
+			const st = ctx.fs.lstatSync?.(paths.installPath);
+			if (st && (st.isSymbolicLink() || !st.isFile() || st.uid !== ctx.euid || (st.mode & 0o022))) return no("foreign-service");
+			before = ctx.fs.readFileSync(paths.installPath, "utf8");
+		} catch { return no("foreign-service"); }
+		// A hand-edited unit can launch anything this account can launch; it is not a setup-owned service.
+		if (before !== text) return no("foreign-service");
+	}
+	if (operation === "install" && before !== null) return no("service-exists");
+	if (operation !== "install" && before === null) return no("missing-service");
+	let active = false;
+	let loaded = false;
+	if (ctx.platform === "linux") {
+		const manager = await runQuery(ctx, "systemctl", ["--user", "show-environment"]);
+		if (manager.code !== 0 || managerEnvRefusal(manager, { home: ctx.home, euid: ctx.euid, user: ctx.user, realpath: ctx.realpath })) return no("manager-unavailable");
+		const status = await runQuery(ctx, "systemctl", ["--user", "show", "--property=LoadState,ActiveState,FragmentPath,DropInPaths,WorkingDirectory,ExecStart", paths.name]);
+		if (status.code !== 0) return no("manager-unavailable");
+		const properties = Object.fromEntries(String(status.stdout).split("\n").map((line) => { const at = line.indexOf("="); return [line.slice(0, at), line.slice(at + 1)]; }));
+		if (before !== null) {
+			try {
+				if (properties.LoadState !== "loaded" || !properties.FragmentPath || ctx.realpath(properties.FragmentPath) !== ctx.realpath(paths.installPath) || properties.DropInPaths !== "" || !properties.WorkingDirectory || ctx.realpath(properties.WorkingDirectory) !== ctx.realpath(ctx.deployDir)) return no("foreign-service");
+				const argv = /(?:^|[ ;])argv\[\]=([^;]*);/.exec(properties.ExecStart ?? "")?.[1]?.trim();
+				if (argv !== execArgvFor(ctx).join(" ")) return no("foreign-service");
+			} catch { return no("foreign-service"); }
+		} else if (properties.LoadState && properties.LoadState !== "not-found") return no("foreign-service");
+		loaded = properties.LoadState === "loaded";
+		active = /^ActiveState=active$/m.test(status.stdout);
+	} else {
+		const manager = await runQuery(ctx, "launchctl", ["print", `gui/${ctx.euid}`]);
+		if (manager.code !== 0) return no("manager-unavailable");
+		const status = await runQuery(ctx, "launchctl", ["print", `gui/${ctx.euid}/${paths.name}`]);
+		loaded = status.code === 0;
+		if (loaded) {
+			try {
+				const source = /^\s*path = (.+)$/m.exec(status.stdout)?.[1];
+				const directory = /^\s*working directory = (.+)$/m.exec(status.stdout)?.[1];
+				const argumentsText = /arguments = \{\s*\n([\s\S]*?)\n\s*\}/.exec(status.stdout)?.[1];
+				const argv = argumentsText?.split("\n").map((line) => line.trim()).filter(Boolean);
+				if (!before || !source || ctx.realpath(source) !== ctx.realpath(paths.installPath) || !directory || ctx.realpath(directory) !== ctx.realpath(ctx.deployDir) || JSON.stringify(argv) !== JSON.stringify(["/bin/sh", ctx.wrapperSh, ...execArgvFor(ctx)])) return no("foreign-service");
+			} catch { return no("foreign-service"); }
+		}
+		active = status.code === 0 && /state = running/.test(status.stdout);
+	}
+	return { operation, which: ctx.which, path: paths.installPath, text, before, active, loaded, stack: stack?.plan ?? null, effects: [...(operation === "install" ? [`write-${ctx.which}-unit`] : []), `${operation === "install" ? "start" : operation}-${ctx.which}`, ...(stack?.plan.files.some((f) => f.state === "new") ? ["write-stack-files"] : []), ...(stack?.plan.start ?? []).flatMap((unit) => unit.includes("valkey") ? ["start-valkey"] : unit.includes("proxy") ? ["start-proxy"] : unit.includes("keeper") ? ["start-keeper"] : [])] };
+}
+
 /**
  * Where each unit lives (or is looked for) per platform. `otherScopeWorkerPaths` exists only to
  * enforce DES-CONCURRENCY-3 at install time — those locations are READ, never written. On Linux the
@@ -513,7 +766,8 @@ function unitPaths(ctx) {
 }
 
 /**
- * Every unit FILE this tool could have installed on this host: both daemons, both scopes, plus the
+ * Every unit FILE this tool could have installed on this host: every component (the worker, the receiver and, since
+ * issue #708, the console), both scopes, plus the
  * `worker.service` name the README's manual `sudo cp` instructions produce (doStatus already counts
  * that one as a real worker unit, so a preflight reading units must too). Derived from unitPaths
  * rather than restated, so the two cannot disagree about where a unit lives.
@@ -523,7 +777,7 @@ function unitPaths(ctx) {
 export function installedUnitPaths(platform, home) {
 	if (platform !== "linux" && platform !== "darwin") return [];
 	const found = [];
-	for (const which of ["worker", "receiver"]) {
+	for (const which of COMPONENTS) {
 		const paths = unitPaths({ platform, home, which, scope: "user" });
 		found.push({ which, scope: "user", path: platform === "linux" ? paths.userPath : paths.installPath });
 		found.push({ which, scope: "system", path: paths.systemPath });
@@ -532,6 +786,21 @@ export function installedUnitPaths(platform, home) {
 	return found;
 }
 
+/**
+ * The console unit FILE installed for the deployment in `cwd` (issue #708), or null: one of `installedUnitPaths`'
+ * console entries whose WorkingDirectory (`readUnitSeam`) is this folder. Shared by doctor and `up`, so the two agree
+ * on whether a console service exists. Always null on win32, where the service is nssm's and is asked by name.
+ */
+export function installedConsoleUnitPath({ platform, home, cwd, fileExists = existsSync, readUnit = (path) => readFileSync(path, "utf8") }) {
+	for (const { path, which } of installedUnitPaths(platform, home)) {
+		if (which !== "console" || !fileExists(path)) continue;
+		try {
+			if (readUnitSeam(readUnit(path), platform).deployDir === cwd) return path;
+		} catch {}
+	}
+	return null;
+}
+
 function readTemplate(ctx, name) {
 	return ctx.fs.readFileSync(join(ctx.templatesDir, name), "utf8");
 }
@@ -552,7 +821,10 @@ function subDeployDir(ctx, text) {
 	// Function replacement, here and everywhere below a computed path is the REPLACEMENT: String.replace
 	// and replaceAll both read `$&` and its relatives out of a replacement STRING, so a deployment folder
 	// holding one would splice itself into the unit. A function replacement is taken literally.
-	return text.replaceAll("/opt/pi-dispatch", () => ctx.deployDir);
+	// `%` doubled (round 1 review of #708): WorkingDirectory= and EnvironmentFile= expand systemd specifiers, so a
+	// folder named `a%hb` would run in `a<home>b`. readUnitSeam undoes it. Linux units only: the plist has its own
+	// escaping (xmlText), and nssm takes the folder as an argv word.
+	return text.replaceAll("/opt/pi-dispatch", () => ctx.deployDir.replace(/%/g, "%%"));
 }
 
 /**
@@ -578,6 +850,68 @@ function refuseMissingReceiver(ctx) {
 	);
 }
 
+/**
+ * The console refusals (issue #708), shared by render and install as the receiver's is: the console package's entry
+ * not found, so a unit would name a file that is not there.
+ */
+function refuseMissingConsole(ctx) {
+	// Worded per platform (round 1 review of #708): `findOnPath` reads no Windows directory, so there it did not look.
+	const looked =
+		ctx.platform === "win32"
+			? `${CONSOLE_PACKAGE}/dist/console.mjs does not resolve from this worker's install (on Windows that is the only place looked: the PATH lookup does not run there)`
+			: `neither does ${CONSOLE_PACKAGE}/dist/console.mjs resolve from this worker's install, nor is a \`pi-dispatch-console\` on this shell's PATH that is that package's own file (a pnpm or Volta shim is not)`;
+	return fail(
+		ctx.err,
+		`the operator console is not installed where this command can find it: ${looked}. Install it in the same place as this worker, so it resolves from here: npm install -g ${CONSOLE_PACKAGE} when the worker is installed globally, or npm install ${CONSOLE_PACKAGE} in the folder whose node_modules holds this worker (an admin package installed anywhere else is not found), then re-run`,
+	);
+}
+
+/**
+ * Paths a unit cannot carry (round 1 review of #708), refused before anything is rendered, on every component: a control
+ * character in the deployment folder (it would end or corrupt the unit line, the XML or the nssm property), surrounding
+ * whitespace on Linux (systemd strips it from WorkingDirectory=, so the unit would run in another folder), and on
+ * Windows a command word holding a character cmd reads (the wrapper runs its argv as `%*`, where `"` cannot be
+ * quoted and `&`, `|`, `<`, `>`, `^` and `%` outside quotes change the command). Everything else is quoted or escaped
+ * per form: systemdWord, xmlText, nssm's argv. null when the render can go ahead.
+ */
+function renderRefusal(ctx) {
+	const shown = (c) => (c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f ? `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}` : c);
+	const control = /[\x00-\x1f\x7f]/.exec(ctx.deployDir);
+	if (control) return fail(ctx.err, `the deployment folder ${JSON.stringify(ctx.deployDir)} holds ${JSON.stringify(shown(control[0]))}, a control character no service unit can carry; run this from a folder without one`);
+	if (ctx.platform === "linux" && ctx.deployDir !== ctx.deployDir.trim()) return fail(ctx.err, `the deployment folder ${JSON.stringify(ctx.deployDir)} starts or ends with whitespace, which systemd strips from WorkingDirectory=, so the unit would run in another folder; rename it`);
+	// NOT refused (final review of #708): a `--` in the folder, which the plist template also names inside XML comments.
+	// plutil accepts it there, and `xmlText` escapes `>`, so a folder can never write the `-->` that would end one;
+	// refusing it broke worker installs that had always worked in a folder like ~/my--deploy.
+	if (ctx.platform === "win32") {
+		for (const word of execArgvFor(ctx)) {
+			const bad = /["%&|<>^\x00-\x1f\x7f]/.exec(word);
+			if (bad) return fail(ctx.err, `${JSON.stringify(word)} holds ${JSON.stringify(shown(bad[0]))}, which the service's wrapper cannot pass to the command it runs (cmd reads it); move it to a path without one`);
+		}
+	}
+	return null;
+}
+
+/**
+ * Install only: a console unit started with no operator token in its tokens file would exit 2 on every start (`serve`
+ * refuses, so nobody could change anything from it), and RestartPreventExitStatus=2 would then leave it stopped. An
+ * install that "succeeds" into a service that never runs is the silent no-op this project refuses, so it is refused
+ * here, with the fix. A tokens file that cannot be used at all (missing, too open, invalid) is refused the same way and
+ * with its own sentence. `render` does not refuse: it writes nothing, and the unit it shows is right once a token exists.
+ */
+function refuseConsoleWithoutOperator(ctx) {
+	let found;
+	try {
+		found = ctx.consoleOperators(ctx.deployDir, ctx.platform);
+	} catch (err) {
+		return fail(ctx.err, `the console's tokens file could not be read (${err?.message ?? err}), so the console would refuse to start; nothing was installed`);
+	}
+	if (found.refusal) return fail(ctx.err, `${found.refusal}. The console refuses to start without it, so nothing was installed`);
+	if (found.operators === 0) {
+		return fail(ctx.err, `${found.path} holds no operator token, so \`pi-dispatch-console serve\` would refuse to start (exit 2) and the unit would stay stopped. Add one first: pi-dispatch-console token add --name <you> --role operator --deployment ${ctx.deployDir}`);
+	}
+	return null;
+}
+
 /**
  * The systemd form of the env-setup seam. Three pieces, each load-bearing:
  *
@@ -600,8 +934,29 @@ function refuseMissingReceiver(ctx) {
  * whole script as one word, and a worker exiting 2 under it reports ExecMainStatus=2 with NRestarts=0.
  */
 function composeEnvSetupExec(setup, argv) {
-	const command = argv.map((a) => `"${a}"`).join(" ");
-	return `/bin/sh -c 'set -a; . "${setup}" || exit 1; set +a; exec ${command}'`;
+	// The argv inside the script, in sh's double quotes, as it always was, while every word is one that form carries
+	// as itself. Otherwise (round 1 review of #708: a deployment folder in the console's argv may hold a space, a `'`,
+	// a `$` or a `%`) the argv goes AFTER the script as its own systemd words (`systemdWord`), and the script runs
+	// `exec "$@"` (written `$$@`: systemd turns `$$` into `$` whatever the quoting), so nothing typed into a path is
+	// ever shell text. The prefix readUnitSeam reads is the same in both forms.
+	if (argv.every((a) => !/['"$`\\%\x00-\x1f\x7f]/.test(a))) {
+		const command = argv.map((a) => `"${a}"`).join(" ");
+		return `/bin/sh -c 'set -a; . "${setup}" || exit 1; set +a; exec ${command}'`;
+	}
+	return `/bin/sh -c 'set -a; . "${setup}" || exit 1; set +a; exec "$$@"' sh ${argv.map(systemdWord).join(" ")}`;
+}
+
+/**
+ * One word of a systemd Exec line (systemd.service(5), "Command lines"; systemd.unit(5), "Specifiers"): as it is when it
+ * holds only characters systemd reads literally, else in double quotes with `\\` and `"` escaped, `%` written `%%` (a
+ * specifier) and `$` written `$$` (variable expansion, which happens inside quotes too). Round 1 review of #708: the
+ * console's argv carries the deployment folder, and an unquoted one split at a space and expanded `%h` and `$HOME`.
+ * Every path a render held before is a bare word, so those units are byte-identical. A control character cannot be
+ * written on one unit line at all; `renderRefusal` refuses it before anything is rendered.
+ */
+export function systemdWord(word) {
+	if (/^[A-Za-z0-9_@+=:,./-]+$/.test(word)) return word;
+	return `"${word.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%").replace(/\$/g, "$$$$")}"`;
 }
 
 /**
@@ -609,16 +964,14 @@ function composeEnvSetupExec(setup, argv) {
  * known literals (see TEMPLATE_PINS); everything else — RestartPreventExitStatus=2, the StartLimit
  * crash-loop bound, KillSignal, TimeoutStopSec — passes through byte-for-byte.
  */
-function renderLinuxUnit(ctx, stackUnits = [], venues = null) {
-	const template = ctx.which === "receiver" ? "receiver.service" : "worker.service";
+function renderLinuxUnit(ctx, stackUnits = [], venues = null, openshell = null) {
+	const { template, templateExec: templateLine } = COMPONENT_TEMPLATES[ctx.which];
 	// The ExecStart line is replaced WHOLE, not path-by-path: the template's script path is relative
 	// to a repo-root WorkingDirectory that only a checkout has. The rendered unit points at absolute
 	// entries that exist in both layouts — cliPath beside this module; the receiver package's ./start
-	// export — so ExecStart works no matter what WorkingDirectory is.
-	const argv = ctx.which === "receiver" ? [ctx.execPath, ctx.receiverStart] : [ctx.execPath, ctx.cliPath, "worker"];
-	const templateLine =
-		ctx.which === "receiver" ? "ExecStart=/usr/bin/node receiver/src/start.mjs" : "ExecStart=/usr/bin/node worker/src/cli.mjs worker";
-	const execStart = `ExecStart=${ctx.envSetup ? composeEnvSetupExec(ctx.envSetup, argv) : argv.join(" ")}`;
+	// export; the console package's dist/console.mjs — so ExecStart works no matter what WorkingDirectory is.
+	const argv = execArgvFor(ctx);
+	const execStart = `ExecStart=${ctx.envSetup ? composeEnvSetupExec(ctx.envSetup, argv) : argv.map(systemdWord).join(" ")}`;
 	// The banner outranks the template's own "TEMPLATE/UNTESTED EXAMPLE — set the PLACEHOLDERs" header,
 	// which renders through below (the no-markers design keeps templates byte-usable, so their prose
 	// survives): a reader of the rendered unit should know the placeholders are already substituted.
@@ -649,16 +1002,29 @@ function renderLinuxUnit(ctx, stackUnits = [], venues = null) {
 		unit = unit.replace("WantedBy=multi-user.target", "WantedBy=default.target");
 		// The podman venue's Quadlet units (issue #430), which live in this same user manager, so the worker can be
 		// ordered after them. Nothing is added when there are none, which keeps every other render byte-identical.
-		const deps = workerUnitDeps(stackUnits);
-		if (deps) unit = unit.replace("\nWants=network-online.target\n", () => `\nWants=network-online.target\n${deps}`);
+		const deps = workerUnitDeps(stackUnits, venues?.podmanUsed || !openshell?.used ? {} : { forWhat: "the openshell venue's Valkey on Podman (issue #707)" });
+		// Issue #707: the openshell venues' gateway is the `openshell-gateway` USER unit OpenShell's package ships, in this
+		// same user manager, so the worker pulls it in at boot. `Wants=`, never `Requires=`, for workerUnitDeps' reason: a
+		// gateway that fails to start must not stop the worker, whose boot says why (and whose other venues still run).
+		// NO `After=`, the obvious companion, REJECTED (review round 1 of #715, measured with `systemd-analyze --user verify
+		// default.target`): the 0.1.4 deb's unit has `After=default.target` and `WantedBy=default.target`, and the worker is
+		// WantedBy default.target too, so default.target -> worker -> gateway -> default.target is an ordering cycle, and
+		// systemd breaks it by deleting the worker's start job. Unordered is safe: a gateway down at boot is only logged
+		// (`openshell_gateway_down_at_boot`), and every job reads it again before it spends.
+		const gatewayDeps = openshell?.used ? `# Added by \`pi-dispatch service install\` for the openshell venue (issue #707): the gateway's own user unit, pulled\n# in but NOT ordered (its unit is After=default.target, so an After= here is an ordering cycle).\nWants=${OPENSHELL_GATEWAY_UNIT}\n` : "";
+		if (deps || gatewayDeps) unit = unit.replace("\nWants=network-online.target\n", () => `\nWants=network-online.target\n${deps}${gatewayDeps}`);
 		// The template's own words, made true for a podman deployment (round 2 nit): its Description says jobs launch
-		// via docker, and its comment says Valkey is not ordered here. Both anchors are TEMPLATE_PINS.
-		if (venues?.podmanUsed) {
-			const runtime = venues.localUsed ? "docker and rootless podman" : "rootless podman";
+		// via docker, and its comment says Valkey is not ordered here. Both anchors are TEMPLATE_PINS. Issue #707: and for
+		// an openshell one, whose jobs run in the gateway's sandboxes on its engine.
+		if (venues?.podmanUsed || openshell?.used) {
+			const runtimes = [venues?.localUsed ? "docker" : null, venues?.podmanUsed ? "rootless podman" : null, openshell?.used ? `an OpenShell gateway on ${openshell.engine}` : null].filter(Boolean);
+			const runtime = runtimes.length > 1 ? `${runtimes.slice(0, -1).join(", ")} and ${runtimes.at(-1)}` : runtimes[0];
 			unit = unit.replace(WORKER_DESCRIPTION, () => `Description=pi-dispatch worker (drains the job queue on the host; launches job containers via ${runtime})`);
 			if (stackUnits.includes(QUADLET_FILES.valkey.unit)) {
-				unit = unit.replace(WORKER_VALKEY_COMMENT, () => "# Valkey is the podman venue's Quadlet unit in this same user manager, so the worker is ordered after it\n# (the Wants=/After= lines `pi-dispatch service install` added below).\n");
+				unit = unit.replace(WORKER_VALKEY_COMMENT, () => (venues?.podmanUsed ? "# Valkey is the podman venue's Quadlet unit in this same user manager, so the worker is ordered after it\n# (the Wants=/After= lines `pi-dispatch service install` added below).\n" : "# Valkey is a Quadlet unit in this same user manager (the openshell venue's engine is Podman), so the worker is\n# ordered after it (the Wants=/After= lines `pi-dispatch service install` added below).\n"));
 			}
+			// Nothing of this deployment runs on docker: no `local` venue, and the gateway's engine is Podman.
+			if (openshell?.used && openshell.engine === "podman" && !venues?.localUsed) unit = unit.replace(WORKER_AFTER, () => "After=network-online.target");
 		}
 	} else {
 		unit = unit.replace(/^User=pi$/m, () => `User=${ctx.user}`);
@@ -675,31 +1041,36 @@ function renderLinuxUnit(ctx, stackUnits = [], venues = null) {
  * the wrapper's conversion to a clean 0 is exactly what KeepAlive/SuccessfulExit=false reads as
  * "leave it stopped" -- launchd's only way to spell RestartPreventExitStatus=2.
  */
-function renderPlist(ctx) {
+function renderPlist(ctx, { pathDirs = [] } = {}) {
 	// Substituted before anything composed goes in (subDeployDir): the two anchors below are therefore
 	// written in their post-substitution form, and PI_ENV_SETUP can no longer be rewritten into a path
 	// the operator never typed. Only subDeployDir here — the template's /usr/bin/node is example prose.
-	let plist = subDeployDir(ctx, readTemplate(ctx, "com.pi-dispatch.worker.plist"));
+	// Every string this render puts into the XML is escaped (`xmlText`, round 1 review of #708): a deployment folder
+	// or a package path holding `&` or `<` produced a plist launchd refuses to load. No-op for every other path, so
+	// those renders are byte-identical to before.
+	let plist = readTemplate(ctx, "com.pi-dispatch.worker.plist").replaceAll("/opt/pi-dispatch", () => xmlText(ctx.deployDir));
 	// One wrapper, two daemons: the exec argv IS the difference now. The wrapper sources ./.env in the
 	// unit's WorkingDirectory and runs exactly these arguments — no `receiver` selector flag, no paths
 	// guessed inside the wrapper (issue #96: the wrapper's self-relative guess broke under npm install).
-	const execArgv = ctx.which === "receiver" ? [ctx.execPath, ctx.receiverStart] : [ctx.execPath, ctx.cliPath, "worker"];
-	if (ctx.which === "receiver") {
+	const execArgv = execArgvFor(ctx);
+	if (ctx.which !== "worker") {
+		// The console (issue #708) is derived exactly as the receiver is: `serve`'s refusals exit 2, which the wrapper
+		// turns into the clean exit KeepAlive leaves stopped.
 		plist = plist
-			.replace("<string>com.pi-dispatch.worker</string>", "<string>com.pi-dispatch.receiver</string>")
-			.replaceAll("worker.out.log", "receiver.out.log")
-			.replaceAll("worker.err.log", "receiver.err.log");
+			.replace("<string>com.pi-dispatch.worker</string>", () => `<string>com.pi-dispatch.${ctx.which}</string>`)
+			.replaceAll("worker.out.log", () => `${ctx.which}.out.log`)
+			.replaceAll("worker.err.log", () => `${ctx.which}.err.log`);
 	}
 	// The template's two-element ProgramArguments (sh + wrapper) becomes sh + the PACKAGE's wrapper +
 	// the command: absolute node, absolute script. The wrapper path is module-relative (templatesDir),
 	// so it exists in a checkout AND under node_modules — unlike the old repo-root guess.
 	plist = plist.replace(
-		`<string>${ctx.deployDir}/deploy/worker-env-wrapper.sh</string>`,
+		`<string>${xmlText(ctx.deployDir)}/deploy/worker-env-wrapper.sh</string>`,
 		() =>
 			[
-				`<string>${ctx.wrapperSh}</string>`,
-				"<!-- the command the wrapper execs after sourcing ./.env in WorkingDirectory - absolute paths, nothing guessed -->",
-				...execArgv.map((a) => `<string>${a}</string>`),
+				`<string>${xmlText(ctx.wrapperSh)}</string>`,
+				ctx.which === "console" ? "<!-- the command the wrapper execs in WorkingDirectory (it sources no .env for the console: PI_WRAPPER_NO_DOTENV below) - absolute paths, nothing guessed -->" : "<!-- the command the wrapper execs after sourcing ./.env in WorkingDirectory - absolute paths, nothing guessed -->",
+				...execArgv.map((a) => `<string>${xmlText(a)}</string>`),
 			].join("\n\t\t"),
 	);
 	// launchd's default PATH is /usr/bin:/bin — an nvm or Homebrew node is invisible to it. The exec
@@ -709,7 +1080,19 @@ function renderPlist(ctx) {
 	// no-EnvironmentVariables stance is about credentials, which still live only in .env.
 	// The dict is built as a list so the seam below can extend it without a second anchor. Everything
 	// in it is a PATH; nothing in it is a credential, which is what keeps this file committable.
-	const envEntries = ["\t\t<key>PATH</key>", `\t\t<string>${dirname(ctx.execPath)}:/usr/bin:/bin:/usr/sbin:/sbin</string>`];
+	// Issue #707: and the directories of the CLIs a venue spawns by name (the openshell CLI, resolved from this shell's
+	// PATH at install time), which launchd's PATH cannot see either: a Homebrew `openshell` is in /opt/homebrew/bin.
+	// With none, the line is byte-identical to the one before (review round 1 of #715), node in /usr/bin included.
+	const fixed = ["/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+	const extra = [...new Set(pathDirs)].filter((d) => d !== dirname(ctx.execPath) && !fixed.includes(d));
+	const envEntries = ["\t\t<key>PATH</key>", `\t\t<string>${xmlText([dirname(ctx.execPath), ...extra, ...fixed].join(":"))}</string>`];
+	if (ctx.which === "console") {
+		// Issue #708 (round 1 review): the console reads the deployment's .env itself (`serve --deployment`), only its own
+		// keys and only from a file no other account can change, so the wrapper must not source the whole file into its
+		// environment (every worker secret, each read as this "shell's" and so winning over the file). The wrapper tests
+		// this before its load; PI_ENV_SETUP below still runs when configured.
+		envEntries.push("\t\t<key>PI_WRAPPER_NO_DOTENV</key>", "\t\t<string>1</string>");
+	}
 	if (ctx.envSetup) {
 		// launchd has no EnvironmentFile and no shell in front of ProgramArguments, so the seam is a
 		// VARIABLE the wrapper reads rather than a composed command line: nothing here has to be quoted
@@ -718,10 +1101,10 @@ function renderPlist(ctx) {
 		envEntries.push(
 			"\t\t<!-- `pi-dispatch service --env-setup`: worker-env-wrapper.sh sources this file after ./.env.\n\t\t     A path, not a credential. Re-render to change it. -->",
 			"\t\t<key>PI_ENV_SETUP</key>",
-			`\t\t<string>${ctx.envSetup}</string>`,
+			`\t\t<string>${xmlText(ctx.envSetup)}</string>`,
 		);
 	}
-	const workingDir = `<key>WorkingDirectory</key>\n\t<string>${ctx.deployDir}</string>`;
+	const workingDir = `<key>WorkingDirectory</key>\n\t<string>${xmlText(ctx.deployDir)}</string>`;
 	plist = plist.replace(
 		workingDir,
 		() =>
@@ -744,7 +1127,7 @@ function renderPlist(ctx) {
 function nssmSequence(ctx) {
 	const service = `pi-dispatch-${ctx.which}`;
 	const logDir = `${ctx.deployDir}\\logs`;
-	const execArgv = ctx.which === "receiver" ? [ctx.execPath, ctx.receiverStart] : [ctx.execPath, ctx.cliPath, "worker"];
+	const execArgv = execArgvFor(ctx);
 	return {
 		service,
 		commands: [
@@ -753,7 +1136,9 @@ function nssmSequence(ctx) {
 			// Same seam as the plist's EnvironmentVariables dict, for the same reason: nssm takes a
 			// NAME=VALUE with no shell between it and the wrapper, so the path needs no quoting and
 			// AppParameters stays byte-identical to the default render.
-			...(ctx.envSetup ? [["set", service, "AppEnvironmentExtra", `PI_ENV_SETUP=${ctx.envSetup}`]] : []),
+			// The console's PI_WRAPPER_NO_DOTENV (issue #708) travels the same way, in the same one property (nssm takes
+			// several NAME=VALUE words there).
+			...(ctx.envSetup || ctx.which === "console" ? [["set", service, "AppEnvironmentExtra", ...(ctx.envSetup ? [`PI_ENV_SETUP=${ctx.envSetup}`] : []), ...(ctx.which === "console" ? ["PI_WRAPPER_NO_DOTENV=1"] : [])]] : []),
 			["set", service, "AppStdout", `${logDir}\\${ctx.which}.out.log`],
 			["set", service, "AppStderr", `${logDir}\\${ctx.which}.err.log`],
 			["set", service, "AppStopMethodConsole", "15000"],
@@ -779,8 +1164,10 @@ function nssmSequence(ctx) {
  * splits it) and a file it cannot read there is not a refusal: refusing an install over a key that could change
  * nothing about it would be a refusal with no remedy.
  */
-function podmanVenue(ctx) {
-	if (ctx.which !== "worker") return { used: false };
+const NO_OPENSHELL = Object.freeze(openshellSetupOf(null));
+
+function deploymentVenue(ctx) {
+	if (ctx.which !== "worker") return { used: false, openshell: NO_OPENSHELL };
 	const envPath = join(ctx.deployDir, ".env");
 	const linux = ctx.platform === "linux";
 	let fileKeys = {};
@@ -790,18 +1177,18 @@ function podmanVenue(ctx) {
 			// Bytes, not text: `readStackKeys` checks what systemd refuses to load before it decodes (issue #447).
 			text = ctx.fs.readFileSync(envPath);
 		} catch (err) {
-			if (!linux) return { used: false };
+			if (!linux) return { used: false, openshell: NO_OPENSHELL };
 			return { error: `cannot read ${envPath} to learn whether this deployment runs the podman venue: ${err?.message}` };
 		}
 		const loader = linux ? "systemd" : ctx.platform === "darwin" ? "shell" : "cmd";
 		const read = readStackKeys(text, { loader, path: envPath });
-		if (read.error) return linux ? { error: read.error } : { used: false };
+		if (read.error) return linux ? { error: read.error } : { used: false, openshell: NO_OPENSHELL };
 		fileKeys = read.keys;
 		// Issue #464: where the worker's queue is, and whether a Valkey another uid holds may be it (PI_VALKEY_SHARED), as
 		// the service reads them, for the Valkey rule (`decideValkey`). A line the loaders read differently is refused,
 		// naming what in it is the problem, rather than guessed at.
 		const valkey = readValkeyKeys(text, { loader, path: envPath });
-		if (valkey.error) return linux ? { error: valkey.error } : { used: false };
+		if (valkey.error) return linux ? { error: valkey.error } : { used: false, openshell: NO_OPENSHELL };
 		fileKeys = { ...fileKeys, ...valkey.keys };
 	}
 	// Refused here, unlike doctor's venuesOf, which reads an unparseable list as `local`: doctor then reports the parse,
@@ -809,11 +1196,15 @@ function podmanVenue(ctx) {
 	try {
 		parseBackendList(fileKeys.PI_BACKENDS);
 	} catch (err) {
-		return linux ? { error: `${envPath}: ${err.message}` } : { used: false };
+		return linux ? { error: `${envPath}: ${err.message}` } : { used: false, openshell: NO_OPENSHELL };
 	}
 	const venues = venuesOf(fileKeys);
-	if (!venues.podmanUsed) return { used: false };
-	return { used: true, venues, env: fileKeys };
+	// Issue #707: the openshell venues' setup by the one rule `up` follows (`openshellSetupOf`): which engine, and whether
+	// this deployment's Valkey is a Quadlet unit on it. An engine the worker refuses at boot is refused here too, on Linux,
+	// rather than installing a unit that starts into that refusal.
+	const openshell = openshellSetupOf(venues, fileKeys);
+	if (openshell.engineError && linux) return { error: `${envPath}: ${openshell.engineError}` };
+	return { used: venues.podmanUsed, venues, env: fileKeys, openshell };
 }
 
 /**
@@ -823,6 +1214,18 @@ function podmanVenue(ctx) {
  * the worker would race its own queue at every boot; and installing them means writing into a user's config from a
  * command whose system-scope doctrine is to write nothing. User scope with linger does both properly.
  */
+/**
+ * The refusal for an openshell venue in SYSTEM scope (issue #707), as podman's: the gateway is the `openshell-gateway` USER
+ * unit, which a system unit cannot order itself after, and the CLI the worker drives keeps its gateway registration under
+ * that user's own config directory, which a system unit's environment does not point at.
+ */
+function refuseOpenshellSystemScope(ctx) {
+	return fail(
+		ctx.err,
+		`PI_BACKENDS in ${join(ctx.deployDir, ".env")} lists an openshell venue, and its gateway runs as ${OPENSHELL_GATEWAY_UNIT}, a unit of the worker account's OWN user manager, which a system unit cannot order itself after; the openshell CLI also keeps its gateway registration under that account's home. Install in user scope (drop --system) with linger on:  sudo loginctl enable-linger ${ctx.user}`,
+	);
+}
+
 function refusePodmanSystemScope(ctx) {
 	return fail(
 		ctx.err,
@@ -836,10 +1239,11 @@ function refusePodmanSystemScope(ctx) {
  * `up` starts what is not running, while an install also keeps (and orders the worker after) a Valkey unit an
  * earlier run already installed, even though that Valkey is now the thing listening.
  */
-async function podmanStackFor(ctx, venue, { readKeeper = false } = {}) {
+async function podmanStackFor(ctx, venue, { readKeeper = false, egress = true } = {}) {
 	let armed;
 	try {
-		armed = egressArmed(venue.env);
+		// `egress: false` (issue #707): the openshell venue's Valkey alone, with no proxy and no keeper, whatever PI_EGRESS says.
+		armed = egress ? egressArmed(venue.env) : false;
 	} catch (err) {
 		return { error: `${join(ctx.deployDir, ".env")}: ${err.message}` };
 	}
@@ -910,12 +1314,17 @@ async function podmanStackFor(ctx, venue, { readKeeper = false } = {}) {
 
 async function doRender(ctx) {
 	if (ctx.which === "receiver" && !ctx.receiverStart) return refuseMissingReceiver(ctx);
+	if (ctx.which === "console" && !ctx.consoleEntry) return refuseMissingConsole(ctx);
+	const unrenderable = renderRefusal(ctx);
+	if (unrenderable !== null) return unrenderable;
 	const paths = unitPaths(ctx);
 	if (ctx.platform === "darwin") {
 		ctx.out(`# → ${paths.installPath}\n`);
-		ctx.out(renderPlist(ctx));
+		ctx.out(renderPlist(ctx, { pathDirs: openshellPathDirs(ctx, deploymentVenue(ctx)) }));
 		ctx.out(
-			"\n# note: ProgramArguments runs the package's worker-env-wrapper.sh, which sources ./.env in the\n# WorkingDirectory above and then runs the argv that follows it — launchd has no EnvironmentFile.\n# The wrapper also converts a policy refusal (exit 2, EXIT_POLICY) into a clean exit, so KeepAlive\n# never relaunch-loops a refusal into a provider bill.\n",
+			ctx.which === "console"
+				? "\n# note: ProgramArguments runs the package's worker-env-wrapper.sh, which (PI_WRAPPER_NO_DOTENV=1) sources NO\n# .env for the console: `serve --deployment` reads the console's own keys from it. The wrapper converts serve's\n# refusal (exit 2) into a clean exit, so KeepAlive leaves it stopped instead of relaunching it.\n"
+				: "\n# note: ProgramArguments runs the package's worker-env-wrapper.sh, which sources ./.env in the\n# WorkingDirectory above and then runs the argv that follows it — launchd has no EnvironmentFile.\n# The wrapper also converts a policy refusal (exit 2, EXIT_POLICY) into a clean exit, so KeepAlive\n# never relaunch-loops a refusal into a provider bill.\n",
 		);
 		if (ctx.envSetup) {
 			ctx.out(
@@ -925,16 +1334,14 @@ async function doRender(ctx) {
 		return 0;
 	}
 	if (ctx.platform === "linux") {
-		const venue = podmanVenue(ctx);
+		const venue = deploymentVenue(ctx);
 		if (venue.error) return fail(ctx.err, venue.error);
-		let stack = null;
-		if (venue.used) {
-			if (ctx.scope === "system") return refusePodmanSystemScope(ctx);
-			stack = await podmanStackFor(ctx, venue);
-			if (stack.error) return fail(ctx.err, stack.error);
-		}
+		if (ctx.scope === "system" && venue.used) return refusePodmanSystemScope(ctx);
+		if (ctx.scope === "system" && venue.openshell.used) return refuseOpenshellSystemScope(ctx);
+		const stack = await stackFor(ctx, venue);
+		if (stack?.error) return fail(ctx.err, stack.error);
 		ctx.out(`# → ${paths.installPath}\n`);
-		ctx.out(renderLinuxUnit(ctx, stack?.plan.start ?? [], stack?.venues ?? null));
+		ctx.out(renderLinuxUnit(ctx, stack?.plan.start ?? [], venue.venues ?? null, venue.openshell));
 		// The proxy's rules copy is named, not printed (round 3 nit): it is the package's egress-proxy.conf verbatim, and
 		// 4.7 KB of squid configuration under a "Quadlet" heading read as a unit file.
 		for (const f of stack?.plan.files ?? []) {
@@ -956,6 +1363,13 @@ async function doRender(ctx) {
 
 async function doInstall(ctx) {
 	if (ctx.which === "receiver" && !ctx.receiverStart) return refuseMissingReceiver(ctx);
+	if (ctx.which === "console" && !ctx.consoleEntry) return refuseMissingConsole(ctx);
+	const unrenderable = renderRefusal(ctx);
+	if (unrenderable !== null) return unrenderable;
+	if (ctx.which === "console") {
+		const refused = refuseConsoleWithoutOperator(ctx);
+		if (refused !== null) return refused;
+	}
 	const paths = unitPaths(ctx);
 
 	// THE refusal, worker only: one worker per docker daemon (DES-CONCURRENCY-3). The worker's boot
@@ -973,30 +1387,56 @@ async function doInstall(ctx) {
 		}
 	}
 
-	const venue = podmanVenue(ctx);
+	const venue = deploymentVenue(ctx);
 	if (venue.error) return fail(ctx.err, venue.error);
+	// Issue #707: no OpenShell gateway exists for Windows (the pinned release's assets were checked), so a worker unit for
+	// this deployment would start into a venue that cannot run here. Refused before anything is written.
+	if (ctx.platform === "win32" && venue.openshell.used) return fail(ctx.err, OPENSHELL_NO_WINDOWS);
 	if (ctx.platform === "darwin" || ctx.platform === "win32") {
-		const code = ctx.platform === "darwin" ? await installDarwin(ctx, paths) : await installWindows(ctx);
+		const code = ctx.platform === "darwin" ? await installDarwin(ctx, paths, venue) : await installWindows(ctx);
 		// Said, never silently skipped: the venue refuses every host that is not Linux (podman-platform), so there is
 		// no stack to install here, and a deployment listing it should know why nothing about Podman happened.
 		if (code === 0 && venue.used) ctx.out("note: PI_BACKENDS lists podman, and the podman venue runs only on Linux (it refuses this host as podman-platform), so no podman stack was installed here\n");
 		return code;
 	}
-	if (ctx.scope === "system") return venue.used ? refusePodmanSystemScope(ctx) : installLinuxSystem(ctx, paths);
-	let stack = null;
+	if (ctx.scope === "system") return venue.used ? refusePodmanSystemScope(ctx) : venue.openshell.used ? refuseOpenshellSystemScope(ctx) : installLinuxSystem(ctx, paths);
 	let foreign = [];
-	if (venue.used) {
-		stack = await podmanStackFor(ctx, venue, { readKeeper: true });
+	const stack = await stackFor(ctx, venue, { readKeeper: true });
+	if (stack) {
 		if (stack.error) return fail(ctx.err, stack.error);
 		// Every stack refusal first, the unit's own among them, so installLinuxUser's unit check never fires alone.
 		const refused = await stackRefusal(ctx, paths, stack);
 		if (refused.error) return fail(ctx.err, refused.error);
 		foreign = refused.foreign;
 	}
-	return installLinuxUser(ctx, paths, stack, foreign);
+	return installLinuxUser(ctx, paths, stack, foreign, venue);
+}
+
+/**
+ * The Quadlet stack this deployment's worker unit is installed with, or null: the podman venue's (Valkey, the proxy and
+ * the keeper, by their own rules), or, for an openshell venue on Podman that no `local` or `podman` venue decides the
+ * queue for, its Valkey alone (issue #707, `openshellSetupOf`'s `valkeyEngine`), with no proxy and no keeper.
+ */
+async function stackFor(ctx, venue, opts = {}) {
+	if (venue.used) return podmanStackFor(ctx, venue, opts);
+	if (venue.openshell?.valkeyEngine === "podman") return podmanStackFor(ctx, venue, { ...opts, egress: false });
+	return null;
+}
+
+/**
+ * The directory of the `openshell` CLI as this shell finds it (issue #707), for the plist's PATH: launchd's own PATH
+ * cannot see a Homebrew install, and the worker spawns the CLI by name. Empty where no openshell venue is blessed, or
+ * where it is not found (then `installDarwin` says so).
+ */
+function openshellPathDirs(ctx, venue) {
+	if (!venue?.openshell?.used) return [];
+	const found = ctx.findBin("openshell");
+	// A directory the plist cannot carry as written (review round 1 of #715): `&`, `<`, `>`, `"` or a control byte would
+	// break or change the XML, the refusal `--env-setup` makes for the same file. Left out, and said by installDarwin.
+	return found && !ENV_SETUP_REFUSALS.darwin.re.test(dirname(found)) ? [dirname(found)] : [];
 }
 
-async function installDarwin(ctx, paths) {
+async function installDarwin(ctx, paths, venue = null) {
 	// Root refusal (the svc.sh darwin precedent): sudo would bootstrap into ROOT's gui domain and
 	// write root's LaunchAgents — a unit the operator's own session neither sees nor controls, running
 	// outside the login session that owns Docker Desktop.
@@ -1023,7 +1463,7 @@ async function installDarwin(ctx, paths) {
 		// launchd creates the StandardOutPath FILES but not their parent directory: without this the job
 		// spawns and dies with its error unwritable. Done at install, not render: render stays read-only.
 		ctx.fs.mkdirSync(join(ctx.deployDir, "logs"), { recursive: true });
-		journalWrite(ctx.fs, journal, paths.installPath, renderPlist(ctx));
+		journalWrite(ctx.fs, journal, paths.installPath, renderPlist(ctx, { pathDirs: openshellPathDirs(ctx, venue) }));
 	} catch (err) {
 		return fail(ctx.err, `could not write ${paths.installPath} (${err?.message ?? err}), so nothing was installed: ${describeRollBack(rollBackWrites(ctx.fs, journal))}`);
 	}
@@ -1035,9 +1475,20 @@ async function installDarwin(ctx, paths) {
 	if (enable !== 0) return fail(ctx.err, `launchctl enable gui/${ctx.euid}/${paths.name} failed (exit ${enable})`);
 	ctx.out(`installed ${paths.name} → ${paths.installPath} (bootstrapped into gui/${ctx.euid}; RunAtLoad starts it now and on login)\n`);
 	// The honest note: no pretending a LaunchAgent is a boot daemon. It is the right fit anyway.
+	// The Docker Desktop reason is the worker's (issue #708): the console starts no container, and telling its operator
+	// about a docker socket would explain a choice by a fact that does not apply to it.
 	ctx.out(
-		"note: a LaunchAgent is LOGIN-scoped — it runs while you are logged in, not from boot. That is the honest fit here: Docker Desktop is itself login-scoped, so a boot-time daemon would only wait on a docker socket that appears at login anyway.\n",
+		ctx.which === "console"
+			? "note: a LaunchAgent is LOGIN-scoped — it runs while you are logged in, not from boot, which is when a browser on this Mac can reach it.\n"
+			: "note: a LaunchAgent is LOGIN-scoped — it runs while you are logged in, not from boot. That is the honest fit here: Docker Desktop is itself login-scoped, so a boot-time daemon would only wait on a docker socket that appears at login anyway.\n",
 	);
+	// Issue #707: the openshell venue's gateway, which a LaunchAgent cannot order itself after; Homebrew's service runs it
+	// in the same login session. And the CLI the worker spawns by name, whose directory is now on the plist's PATH.
+	if (venue?.openshell?.used) {
+		const found = ctx.findBin("openshell");
+		if (found && ENV_SETUP_REFUSALS.darwin.re.test(dirname(found))) ctx.out(`⚠ the openshell venue: this shell finds \`openshell\` in ${JSON.stringify(dirname(found))}, which the plist cannot carry (${ENV_SETUP_REFUSALS.darwin.why}), so its PATH does not name it and the worker will not find the CLI. Install it somewhere without those characters, then re-run with --force\n`);
+		else ctx.out(found ? `note: the openshell venue: the plist's PATH carries ${dirname(found)}, where this shell finds \`openshell\`. Keep its gateway running in this login session: \`brew services start openshell\` (the service of OpenShell's release formula, \`${OPENSHELL_BREW_INSTALL}\`; homebrew-core's formula defines none)\n` : `⚠ the openshell venue: \`openshell\` is not on this shell's PATH, so the plist's PATH carries no directory for it and the worker will not find the CLI. Install OpenShell's release formula (\`${OPENSHELL_BREW_INSTALL}\`), then re-run with --force; its service keeps the gateway running in this login session: \`brew services start openshell\`\n`);
+	}
 	return 0;
 }
 
@@ -1091,7 +1542,7 @@ async function stackRefusal(ctx, paths, stack) {
 	return { foreign };
 }
 
-async function installLinuxUser(ctx, paths, stack = null, foreign = []) {
+async function installLinuxUser(ctx, paths, stack = null, foreign = [], venue = null) {
 	if (ctx.fs.existsSync(paths.installPath) && !ctx.force) {
 		return fail(ctx.err, `${paths.installPath} already exists — pass --force to replace it (same non-clobber contract as init)`);
 	}
@@ -1104,7 +1555,7 @@ async function installLinuxUser(ctx, paths, stack = null, foreign = []) {
 	const writeUnit = () => {
 		try {
 			ctx.fs.mkdirSync(dirname(paths.installPath), { recursive: true });
-			journalWrite(ctx.fs, journal, paths.installPath, renderLinuxUnit(ctx, stack?.plan.start ?? [], stack?.venues ?? null));
+			journalWrite(ctx.fs, journal, paths.installPath, renderLinuxUnit(ctx, stack?.plan.start ?? [], venue?.venues ?? stack?.venues ?? null, venue?.openshell ?? null));
 			return { ok: true };
 		} catch (err) {
 			return { ok: false, failed: `write ${paths.installPath}`, code: null, message: err?.message };
@@ -1130,7 +1581,7 @@ async function installLinuxUser(ctx, paths, stack = null, foreign = []) {
 		if (passwordWarning) ctx.out(`⚠ ${passwordWarning}\n`);
 		if (stack.plan.actions.length > 0) {
 			// Shown, then done: the same lines `up` asks consent for, carried out by the same function.
-			ctx.out(`podman venue (PI_BACKENDS in .env): its stack, as Quadlet units in ${stack.plan.dir}:\n`);
+			ctx.out(`${venue?.used === false ? "openshell venue on Podman (PI_BACKENDS and PI_OPENSHELL_ENGINE in .env): its Valkey" : "podman venue (PI_BACKENDS in .env): its stack"}, as Quadlet units in ${stack.plan.dir}:\n`);
 			for (const action of stack.plan.actions) ctx.out(`  ${describeAction(action)}\n`);
 			const applied = await applyStack(stack.plan, { fs: ctx.fs, run: (cmd, args) => run(ctx, cmd, args), journal, beforeRuns: writeUnit });
 			if (!applied.ok) {
@@ -1162,6 +1613,7 @@ async function installLinuxUser(ctx, paths, stack = null, foreign = []) {
 		return fail(ctx.err, `systemctl --user enable --now ${paths.name} failed (exit ${enable}); the unit is written at ${paths.installPath}; \`systemctl --user status ${paths.name}\` has the details (files this run wrote, which remain: ${writtenList()})`);
 	}
 	ctx.out(`installed ${paths.name} → ${paths.installPath} (enabled and started in your user manager)\n`);
+	if (venue?.openshell?.used) ctx.out(`${paths.name} Wants= ${OPENSHELL_GATEWAY_UNIT} (not After=, whose ordering would be a cycle through default.target), the OpenShell gateway's own user unit (\`systemctl --user enable --now ${OPENSHELL_GATEWAY_UNIT}\` starts it at boot too)\n`);
 	if (stack) {
 		// Said as it happened: `start` on a unit already active is a no-op, so a unit whose file this run replaced was
 		// RESTARTED (planStack), and the line names which is which rather than calling everything "started".
@@ -1482,6 +1934,10 @@ async function startStop(ctx, verb) {
 	}
 	let code;
 	if (ctx.platform === "darwin") {
+		if (verb === "start" && ctx.setupExpected?.loaded === false) {
+			const loaded = await run(ctx, "launchctl", ["bootstrap", `gui/${ctx.euid}`, paths.installPath]);
+			if (loaded !== 0) return fail(ctx.err, "the previewed LaunchAgent could not be loaded");
+		}
 		code =
 			verb === "start"
 				? await run(ctx, "launchctl", ["kickstart", `gui/${ctx.euid}/${paths.name}`])
@@ -1507,9 +1963,28 @@ async function doRestart(ctx, values) {
 	if (!Number.isFinite(timeoutS) || timeoutS <= 0) {
 		return fail(ctx.err, `--drain-timeout must be a positive number of seconds, got: ${values["drain-timeout"]}`);
 	}
-	let queue = ctx.queue;
+	// Which queues (issue #804): the ones this host's worker drains, as `createWorker` builds them, the shared queue and,
+	// when the deployment declares PI_WORKER_NAME, `pi-jobs@<name>`. The shared queue alone let the restart go ahead while
+	// a cron, chained or manual run from the host queue still ran, and the stop aborted it. The name is read as
+	// `pi-dispatch run` reads it, this shell's else the deployment `.env`'s, and a disagreement or a line the service's
+	// loader may read differently refuses: guessing would drain a queue the worker does not run, or miss the one it does.
+	const deployment = cliDeploymentEnv(ctx.env, ["PI_WORKER_NAME"], { cwd: ctx.deployDir, platform: ctx.platform, readFile: (p) => ctx.fs.readFileSync(p) });
+	if (deployment.problem) return fail(ctx.err, `${deployment.problem}. Nothing was paused.`);
+	// Lazy, as below: `service` subcommands that never touch the queue must not load bullmq/ioredis.
+	const { QUEUE, hostQueueName } = await import("./queue.mjs");
+	let names = [QUEUE];
+	if (deployment.env.PI_WORKER_NAME) {
+		// The worker's own rule (`workerName`), so a name it refuses at boot is refused here, never drained as typed.
+		const { workerName } = await import("./config.mjs");
+		try {
+			names = [QUEUE, hostQueueName(workerName(deployment.env))];
+		} catch (error) {
+			return fail(ctx.err, `${error.message}. Nothing was paused.`);
+		}
+	}
+	let queueFor = ctx.queueFor;
 	let url;
-	if (!queue) {
+	if (!queueFor) {
 		// VALKEY_URL only, exactly like cli.mjs's pause/resume: the drain must work even when the rest
 		// of the config (forge auth …) is broken, and failFast keeps a down Valkey an error in seconds
 		// instead of a hung restart. Lazy imports for the same reason cli.mjs uses them: `service`
@@ -1518,54 +1993,111 @@ async function doRestart(ctx, values) {
 		const { cliValkeyUrl, parseConnection } = await import("./connection.mjs");
 		url = cliValkeyUrl(ctx.env, { cwd: ctx.deployDir, warn: (line) => ctx.err(line) });
 		const { makeQueue } = await import("./queue.mjs");
-		queue = makeQueue(parseConnection(url, { failFast: true }));
-	}
+		queueFor = (name) => makeQueue(parseConnection(url, { failFast: true }), { name });
+	}
+	const queues = [];
+	// The queues THIS drain paused and has not resumed yet. Only these are resumed at the end: a queue an operator paused
+	// before the drain (`pi-dispatch pause`, say) stays paused after it, where the drain used to resume it regardless.
+	const held = [];
+	// The queues paused before this drain, which it leaves as it found them.
+	const kept = [];
+	const and = (list) => list.join(" and ");
+	const keptWords = () => `${and(kept)} ${kept.length === 1 ? "was" : "were"} paused before the drain and ${kept.length === 1 ? "stays" : "stay"} paused`;
+	// The words an operator acts on, naming the queues this drain left paused.
+	const staysPaused = (list) => (list.length === 1 ? `the queue ${list[0]} STAYS PAUSED` : `each queue (${list.join(", ")}) STAYS PAUSED`);
+	// The way back from a drain that stopped short. `pi-dispatch resume` is the deployment's resume and takes every queue
+	// at once, so the advice says so: told only to run it, an operator would also resume a queue paused before the drain,
+	// which the drain itself leaves as it found it.
+	const resumeNote = () => `\`pi-dispatch resume\` resumes every queue of the deployment${kept.length > 0 ? ` (${and(kept)} too, though ${kept.length === 1 ? "it was" : "they were"} paused before the drain)` : ""}`;
+	// `then` is what the operator does first. With nothing paused by this drain there is nothing of its own to resume.
+	const leftPaused = (then) => (held.length > 0 ? `${staysPaused(held)}; ${then}, then resume: ${resumeNote()}` : `this drain paused no queue (${keptWords()}); ${then}`);
 	try {
-		await queue.pause();
-		ctx.out("paused — no new jobs will start; waiting for active jobs to finish\n");
+		// One queue at a time, each opened only once the one before it answered, and INSIDE the try, so `finally` closes
+		// every handle opened (a throw while opening the second cannot leak the first). Opening them all first left the
+		// second still connecting when the first could not reach Valkey, and closing a BullMQ queue mid-connect makes it
+		// emit an `error` nothing listens for: an unhandled rejection printed after the right message.
+		const before = [];
+		for (const name of names) {
+			const q = queueFor(name);
+			queues.push(q);
+			before.push((await q.isPaused()) === true);
+		}
+		kept.push(...names.filter((_, i) => before[i]));
+		for (const [i, q] of queues.entries()) {
+			if (before[i]) continue;
+			await q.pause();
+			held.push(names[i]);
+		}
+		if (kept.length === 0) ctx.out(`paused ${and(held)}: no new jobs will start; waiting for their active jobs to finish\n`);
+		else ctx.out(`${held.length > 0 ? `paused ${and(held)}; ` : ""}${keptWords()}: no new jobs will start; waiting for the active jobs on ${and(names)} to finish\n`);
 		const deadline = ctx.now() + timeoutS * 1000;
-		let { active = 0 } = await queue.getJobCounts("active");
+		// Every queue's active count, summed: a job running from either one is a job the restart would abort.
+		const activeNow = async () => {
+			const per = await Promise.all(queues.map((q) => q.getJobCounts("active").then((c) => Number(c?.active ?? 0))));
+			return { active: per.reduce((a, b) => a + b, 0), shown: names.length > 1 ? ` (${names.map((n, i) => `${n} ${per[i]}`).join(", ")})` : "" };
+		};
+		let { active, shown } = await activeNow();
 		while (active > 0) {
 			if (ctx.now() >= deadline) {
 				// Deliberately NO resume and NO restart: a job is still running. Restarting would abort
 				// it; resuming would feed new jobs toward a restart that is still owed. Paused is the
 				// safe durable state (it survives the restart the operator will now do by hand).
-				ctx.out(
-					`drain timed out after ${timeoutS}s with ${active} job(s) still active — NOT restarting.\nThe queue STAYS PAUSED so the running job can finish undisturbed. Investigate (pi-dispatch status), then restart and \`pi-dispatch resume\` yourself.\n`,
-				);
+				const stays = held.length > 0 ? `${staysPaused(held)} so the running job can finish undisturbed. Investigate (pi-dispatch status), then restart and resume yourself: ${resumeNote()}.` : `this drain paused no queue (${keptWords()}). Investigate (pi-dispatch status), then restart yourself.`;
+				ctx.out(`drain timed out after ${timeoutS}s with ${active} job(s) still active${shown}: NOT restarting.\n${stays[0].toUpperCase()}${stays.slice(1)}\n`);
 				return 1;
 			}
-			ctx.out(`  ${active} active — waiting\n`);
+			ctx.out(`  ${active} active${shown}, waiting\n`);
 			await ctx.sleep(2000);
-			({ active = 0 } = await queue.getJobCounts("active"));
+			({ active, shown } = await activeNow());
 		}
 		// A HELD job is neither active nor waiting, so the loop above has just reported a drained queue with
 		// however many jobs still parked on `run.waitFor` (issue #230). They are safe -- a hold spends
 		// nothing, survives a restart and reserves no slot -- but the operator is upgrading, and those jobs
 		// will wake against the new version. Said plainly rather than left to be discovered, which is what
 		// this command would otherwise be doing: reporting a drained queue it cannot see all of.
-		const delayed = await queue.getJobCounts("delayed").then((c) => Number(c?.delayed ?? 0), () => 0);
+		const delayed = (await Promise.all(queues.map((q) => q.getJobCounts("delayed").then((c) => Number(c?.delayed ?? 0), () => 0)))).reduce((a, b) => a + b, 0);
 		if (delayed > 0) {
 			ctx.out(`note: ${delayed} job(s) sit in the delayed set (cron next-occurrences, retry backoff, quiet hours, scope/host deferrals, or jobs held on run.waitFor). None is active, so none blocked this drain; they will wake against the new version.\n`);
 		}
 		const stopped = await doStop(ctx);
 		if (stopped !== 0) {
-			ctx.out("restart did not happen — the queue STAYS PAUSED; fix the service, then `pi-dispatch resume`.\n");
+			ctx.out(`restart did not happen: ${leftPaused("fix the service")}.\n`);
 			return 1;
 		}
 		const started = await doStart(ctx);
 		if (started !== 0) {
-			ctx.out("the service did not come back — the queue STAYS PAUSED; fix the service, then `pi-dispatch resume`.\n");
+			ctx.out(`the service did not come back: ${leftPaused("fix the service")}.\n`);
 			return 1;
 		}
-		await queue.resume();
-		ctx.out("resumed — drained restart complete\n");
+		const ours = [...held];
+		for (const name of ours) {
+			await queues[names.indexOf(name)].resume();
+			held.shift();
+		}
+		ctx.out(`${ours.length > 0 ? `resumed ${and(ours)}: ` : ""}drained restart complete${kept.length > 0 ? `; ${keptWords()}` : ""}\n`);
 		return 0;
 	} catch (error) {
-		return fail(ctx.err, `could not reach Valkey: ${(await import("./valkey-auth.mjs")).valkeyDownHint(url)}\n  ${error.message}`);
+		// Name what this drain left paused: a failure after the first pause (the second pause refused, Valkey gone mid-wait,
+		// a resume refused partway) leaves the deployment half switched, and "could not reach Valkey" alone reads as
+		// "nothing happened".
+		const left = held.length > 0 ? `${leftPaused("wait until Valkey answers")}.` : "Nothing was paused.";
+		return fail(ctx.err, `could not reach Valkey: ${(await import("./valkey-auth.mjs")).valkeyDownHint(url)}\n  ${error.message}\n  ${left}`);
 	} finally {
-		await queue.close().catch(() => {});
+		for (const q of queues) await q.close().catch(() => {});
+	}
+}
+
+/** The first executable regular file named `name` in a PATH string, or null (issue #707's lookup seam's default). */
+export function findOnPath(name, path, { access = (p) => accessSync(p, fsConstants.X_OK), isFile = (p) => statSync(p).isFile() } = {}) {
+	for (const dir of String(path ?? "").split(delimiter)) {
+		if (dir === "" || !dir.startsWith("/")) continue;
+		const candidate = join(dir, name);
+		try {
+			access(candidate);
+			if (isFile(candidate)) return candidate;
+		} catch {}
 	}
+	return null;
 }
 
 function fail(err, message) {