@edgehero/pi-dispatch 5.0.0 → 5.1.0

package/src/console-open.mjs

@@ -0,0 +1,99 @@
+/**
+ * `pi-dispatch console`: get me into the console (issue #849). One command to remember, whatever state things are in.
+ *
+ * The work is split by who owns what. This side owns the service: is the console answering, and if not, can it be started. The admin's
+ * `pi-dispatch-console open` owns the credential: which operator, the audit row, the one-time code and the browser. So a code is minted
+ * only by the package that has always minted one.
+ *
+ * It starts a service that is already installed and stopped, because that is what someone typing this wants, and starting one is not a
+ * new grant: the unit exists because they installed it. It never installs one, which is `up --console`'s decision and asks first.
+ */
+import * as nodeFs from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { attachedCommand, commandsHere, waitForConsole } from "./console-bootstrap.mjs";
+import { makeConsoleAudit } from "./console-audit.mjs";
+import { consoleProbeTarget, probeConsole } from "./console-probe.mjs";
+import { logsDirPath } from "./config.mjs";
+import { findOnPath, installedConsoleUnitPath, resolveConsoleEntry, runService } from "./service.mjs";
+import { deploymentServiceEnv } from "./service-env.mjs";
+import { consoleTokensPathFor } from "./service.mjs";
+import { readTokensFile, tokenNames } from "./console-tokens.mjs";
+
+const SHELL = Object.freeze({ name: "shell", role: "shell", session: null });
+
+const USAGE = "usage: pi-dispatch console [--name <name>] [--next /setup] [--port <n>] [--deployment <dir>]\n";
+
+export async function runConsoleOpen(argv, deps = {}) {
+	const fs = deps.fs ?? nodeFs;
+	const env = deps.env ?? process.env;
+	const platform = deps.platform ?? process.platform;
+	const uid = deps.euid ?? process.geteuid?.();
+	const home = deps.home ?? homedir();
+	const out = deps.out ?? ((text) => process.stdout.write(text));
+	const refuse = (text) => { out(`pi-dispatch console: ${text}\n`); return 2; };
+	// Strict, as the console's own command is: a misread flag here would start a service or sign in the wrong person.
+	let values;
+	try { ({ values } = parseArgs({ args: argv, options: { deployment: { type: "string" }, name: { type: "string" }, next: { type: "string" }, port: { type: "string" }, help: { type: "boolean", short: "h" } } })); }
+	catch (e) { return refuse(`${e?.message ?? "the arguments could not be read"}; run pi-dispatch console --help`); }
+	if (values.help) { out(USAGE); return 0; }
+	// Free refusals first: a typo must not start a service and write a row before anyone finds out.
+	if (values.deployment === "") return refuse("--deployment needs a folder.");
+	if (values.next !== undefined && values.next !== "/setup") return refuse("--next must be /setup.");
+	if (values.port !== undefined && !(/^\d{1,5}$/.test(values.port) && Number(values.port) >= 1 && Number(values.port) <= 65535)) return refuse("--port must be a port number (1 to 65535).");
+	const realpath = fs.realpathSync;
+	const from = realpath(deps.cwd ?? process.cwd());
+	let dir;
+	try { dir = realpath(resolve(from, values.deployment ?? ".")); }
+	catch { return refuse("that deployment folder does not exist."); }
+	const here = commandsHere(dir, fs, { from });
+	if (!fs.existsSync(join(dir, ".env"))) return refuse(values.deployment === undefined ? "this folder is not a deployment. Run this from your deployment folder, or pass --deployment <dir>." : "that folder is not a deployment: it has no .env.");
+	// Read whatever `--name` says: a file the admin would refuse, or a choice it could not make, is known now, before a service starts.
+	let tokens = null;
+	try { tokens = (deps.readTokens ?? readTokensFile)({ path: (deps.consoleTokensPath ?? consoleTokensPathFor)(dir, platform), fs, uid }); } catch { /* the admin's own read says what is wrong */ }
+	if (tokens?.refusal) return refuse(`the console tokens file cannot be used: ${tokens.refusal}. Run ${here.worker} doctor.`);
+	if (tokens?.file) {
+		// `tokenNames`: an entry kept for a role this build does not know is no missing name, and the admin explains it (issue #761).
+		if (values.name !== undefined && !tokenNames(tokens.file).includes(values.name)) return refuse(`there is no token named "${values.name}" in this deployment.`);
+		const operators = tokens.file.tokens.filter((entry) => entry.role === "operator").length;
+		if (values.name === undefined && operators !== 1) return refuse(operators === 0 ? `there is no operator token yet. Run ${here.worker} up --console.` : `there are ${operators} operator tokens, so name one with --name <name>.`);
+	}
+	// env-internal PATH: find the installed admin binary, as `up --console` does.
+	const consoleEntry = (deps.resolveConsole ?? (() => resolveConsoleEntry({ findBin: (name) => findOnPath(name, env.PATH), realpath })))();
+	if (!consoleEntry) return refuse(`the console package is not installed here. Run ${here.worker} up --console in your deployment folder to set it up.`);
+
+	// PI_LOGS_DIR too: the service start's row and the sign-in's row must land in one audit chain.
+	const shellConsoleKeys = Object.keys(env).filter((key) => key.startsWith("PI_CONSOLE_") || key === "PI_LOGS_DIR");
+	const read = deploymentServiceEnv({ env: {}, dir, keys: [...new Set(["PI_CONSOLE_LISTEN", "PI_LOGS_DIR", ...shellConsoleKeys])], fs, uid, platform });
+	if (read.untrusted || (read.unreadable && read.unreadable !== "ENOENT")) return refuse(`this deployment's .env is unsafe or cannot be read. Run ${here.worker} doctor in this folder.`);
+	// The admin's `open` reads this shell's values first; the probe and the service read the file. Two answers would put the link, or the
+	// code, somewhere the running console never looks.
+	if (shellConsoleKeys.some((key) => env[key] !== read.env[key])) return refuse("console settings in this shell differ from the deployment's .env. Unset them here.");
+	const target = consoleProbeTarget(read.env.PI_CONSOLE_LISTEN);
+	if (target.unknown) return refuse("the console has no concrete local address (PI_CONSOLE_LISTEN), so no link could reach it.");
+
+	const probe = deps.probeConsole ?? probeConsole;
+	if ((await probe(read.env)).state !== "running") {
+		// This deployment's own unit, never just any console unit on the account: another's could carry a `--host-setup` grant.
+		if ((deps.consoleUnit ?? installedConsoleUnitPath)({ platform, home, cwd: dir }) === null) return refuse(`the console is not running, and no service for this deployment is installed. Run ${here.worker} up --console to set it up, or ${here.console} serve to run it in this terminal.`);
+		out("The console is not running. Starting its service.\n");
+		const audit = deps.audit ?? makeConsoleAudit({ logsDir: resolve(dir, logsDirPath(read.env)), fs, now: deps.now ?? Date.now });
+		const row = { actor: SHELL, action: "write", kind: "setup-console-start", target: "console", outcome: "ok" };
+		try { audit.append(row); } catch { return refuse(`the audit log could not be written, so the console service was not started. Run ${here.worker} doctor.`); }
+		const started = await (deps.runServiceFn ?? runService)(["start", "--console"], { cwd: dir, env, platform, euid: uid, home, fs, resolveConsole: () => consoleEntry });
+		if (started !== 0) {
+			try { audit.append({ ...row, outcome: "failed", reason: "console-start-refused" }); } catch { /* the refusal below is what the person must see */ }
+			return refuse(`the console service did not start. ${here.worker} service status --console says why.`);
+		}
+		const ready = await waitForConsole(read.env, { probe, now: deps.now ?? Date.now, ms: deps.consoleWaitMs ?? 15_000, ...(deps.sleep ? { sleep: deps.sleep } : {}) });
+		if (!ready) return refuse(`the console service started but did not answer in time. ${here.worker} service status --console says why.`);
+	}
+
+	const passed = [];
+	for (const flag of ["name", "next", "port"]) if (values[flag] !== undefined) passed.push(`--${flag}`, values[flag]);
+	// A unix socket has no port of its own; 4790 is the local end of the tunnel the printed `ssh -L` line sets up.
+	if (target.kind === "unix" && values.port === undefined) passed.push("--port", "4790");
+	const code = await (deps.consoleOpen ?? attachedCommand)(process.execPath, [consoleEntry, "open", "--deployment", dir, ...passed], { cwd: dir, env });
+	return typeof code === "number" ? code : refuse("the console command could not be started.");
+}

package/src/doctor.mjs

@@ -134,6 +134,7 @@ import { DOLLAR_ENV_NAMES, DOLLAR_SETTING_KEYS, checkDollarInvariant, effectiveC
 import { cronPlacement, envelopeJobPaths } from "./schedules.mjs";
 import { envelopeDigest, envelopeInsideJobPaths, loadEnvelopeChecked } from "./envelope.mjs";
 import { keptTokens, operatorCount, readTokensFile, tokensFilePath } from "./console-tokens.mjs";
+import { consoleDevicesDir, devicesState } from "./console-devices.mjs";
 import { RUN_MIRROR_MAX_RUNS_DEFAULT, RUN_MIRROR_MAX_RUNS_MAX, RUN_MIRROR_MAX_RUNS_MIN, runMirrorMaxRunsOf } from "./retention.mjs";
 import { verifyConsoleAudit } from "./console-audit.mjs";
 import { OTHER } from "./priorities.mjs";
@@ -5552,6 +5553,16 @@ export function consoleChecks(env, { cwd = process.cwd(), fs = nodeFs, uid = pro
 		} else if (operators > 0) {
 			checks.push({ ok: true, label: `console: tokens file ${shownPath} is owner-only and outside every job folder (${operators} operator${operators === 1 ? "" : "s"}, ${viewers} viewer${viewers === 1 ? "" : "s"})` });
 		}
+		// Issue #849: the remembered devices, which sit beside the tokens file and are as sensitive as it is about who may sign in.
+		const devicesDir = consoleDevicesDir(path);
+		const devices = devicesState({ dir: devicesDir, fs, uid, platform });
+		if (devices.problem) {
+			checks.push({ ok: false, label: "console: the remembered-device folder cannot be used, so a remembered browser must sign in again", fix: escapeControls(devices.problem) });
+		} else if (!devices.absent) {
+			const devicesInside = consoleTokensInsideJobPaths(devicesDir, env, { cwd, fs, folders, skillsDirs, realpath, directory: true });
+			if (devicesInside.problem) checks.push({ ok: false, label: `console: the remembered-device folder ${quotedShown(devicesDir)} ${devicesInside.problem}`, fix: devicesInside.fix });
+			if (devices.unreadable > 0) checks.push({ ok: false, label: `console: ${devices.unreadable} remembered-device record${devices.unreadable === 1 ? "" : "s"} in ${quotedShown(devicesDir)} cannot be read, and those browsers must sign in again`, fix: `if a newer pi-dispatch wrote ${devices.unreadable === 1 ? "it" : "them"}, upgrade this host; otherwise remove the file${devices.unreadable === 1 ? "" : "s"} whose name${devices.unreadable === 1 ? " starts" : "s start"} with ${devices.unreadableIds.slice(0, 5).join(", ")} from that folder` });
+		}
 		const kept = keptTokens(read.file).length;
 		if (kept > 0) {
 			const said = kept === 1 ? "1 token carries a role this pi-dispatch does not know, so a console of this release signs it in nowhere" : `${kept} tokens carry a role this pi-dispatch does not know, so a console of this release signs them in nowhere`;
@@ -5567,6 +5578,11 @@ export function consoleChecks(env, { cwd = process.cwd(), fs = nodeFs, uid = pro
 	} else {
 		checks.push({ ok: true, label: `console: listens on ${escapeControls(listen.shown)}` });
 	}
+	// Only on an address that really is not loopback: PI_CONSOLE_BIND_PUBLIC=1 alone changes nothing about where a loopback console's cookies travel.
+	if (bindPublic && !listen.refusal && !listen.loopback) {
+		const devices = devicesState({ dir: consoleDevicesDir(path), fs, uid, platform });
+		if (devices.live > 0) checks.push({ ok: false, warn: true, label: `console: ${devices.live} remembered device${devices.live === 1 ? "" : "s"} on a console that listens on a non-loopback address, where cookies cross the network in plain HTTP`, fix: "listen on a loopback address and reach the console through a tunnel, or put it behind a proxy that terminates TLS" });
+	}
 	if (bindPublic) {
 		checks.push({ ok: false, warn: true, label: "console: PI_CONSOLE_BIND_PUBLIC=1 lets the console listen on a non-loopback address, where tokens and session cookies cross the network in plain HTTP", fix: "keep it only behind a TLS proxy on a network you trust; otherwise unset PI_CONSOLE_BIND_PUBLIC, listen on 127.0.0.1, [::1] or a unix: socket, and reach it with ssh -L" });
 	}
@@ -5653,17 +5669,19 @@ export async function consoleServiceChecks(env, seams = {}) {
  * relative run root is skipped here (the envelope refuses one; the console has no such rule to borrow), and a path
  * that cannot be judged is said, not passed.
  */
-function consoleTokensInsideJobPaths(path, env, { cwd, fs, folders, skillsDirs, realpath }) {
+function consoleTokensInsideJobPaths(path, env, { cwd, fs, folders, skillsDirs, realpath, directory = false }) {
 	const fix = "move the tokens file out of every local trigger's run.folder and run.skillsDir, every PI_DISPATCH_RUN_ROOTS root and PI_GLOBAL_PI_DIR, and point PI_CONSOLE_TOKENS_FILE at its new path";
 	try {
 		const st = fs.statSync(path);
-		if (st.nlink > 1) return { problem: `has ${st.nlink} hard links: another name of the file could sit inside a folder a job can see, so keep exactly one`, fix: `remove the other names (\`find / -samefile ${path}\` lists them)` };
+		// A folder always has more than one link (its own name, `.`, and each child's `..`), so the count says nothing about one.
+		if (!directory && st.nlink > 1) return { problem: `has ${st.nlink} hard links: another name of the file could sit inside a folder a job can see, so keep exactly one`, fix: `remove the other names (\`find / -samefile ${path}\` lists them)` };
 		const real = realpath(path);
 		const runRoots = delimitedList(env.PI_DISPATCH_RUN_ROOTS).filter((r) => isAbsolute(r));
 		const globalPiDir = typeof env.PI_GLOBAL_PI_DIR === "string" && env.PI_GLOBAL_PI_DIR !== "" ? env.PI_GLOBAL_PI_DIR : null;
 		// PWD comes from the process environment inside the check, as on doctor's envelope load (`loadEnvelopeChecked`).
-		const inside = envelopeInsideJobPaths(real, { cronFolders: folders, runRoots, skillsDirs, globalPiDir }, { cwd });
+		const inside = envelopeInsideJobPaths(real, { cronFolders: folders, runRoots, skillsDirs, globalPiDir }, { cwd, directory });
 		if (inside === null) return {};
+		if (directory) return { problem: `lies inside a folder a job container can see (${quotedShown(inside.path)}): a job there could plant a remembered device`, fix: "move the tokens file and this folder out of every folder a job can see, point PI_CONSOLE_TOKENS_FILE at the new path, and remove the old folder" };
 		const what = { "cron-folder": "a local trigger's run.folder", "run-root": "a PI_DISPATCH_RUN_ROOTS root", "skills-dir": "a trigger's run.skillsDir", "global-pi-dir": "PI_GLOBAL_PI_DIR" }[inside.kind] ?? inside.kind;
 		return { problem: `lies inside ${what} (${quotedShown(inside.path)}), which a job container can see: a job there could read the token hashes or add a token of its own`, fix };
 	} catch (err) {

package/src/envelope.mjs

@@ -290,7 +290,7 @@ function jobPathCandidates(path, cwd, env, statSync) {
  * to write instead, when there is one. The FILE must exist (the check runs with a successful load) and must have one
  * link: a hard link elsewhere is the same file under a name this check cannot see, and it could sit in a job path.
  */
-function canonicalEnvelopePath(path, realpath, statSync) {
+function canonicalEnvelopePath(path, realpath, statSync, directory = false) {
 	const text = String(path);
 	if (!isAbsolute(text)) throw configError(`the envelope path ${JSON.stringify(text)} must be absolute: write its canonical path, with no symlink, "." or ".." in it`);
 	let real;
@@ -304,6 +304,8 @@ function canonicalEnvelopePath(path, realpath, statSync) {
 	}
 	const stat = statSync(text, { bigint: true });
 	// Before the link count: a directory's nlink counts its subdirectories, so "has 3 hard links" would misname it.
+	// `directory`: the console's device store is a folder, judged by the same identity rules. A folder has no link count to speak of.
+	if (directory && stat.isDirectory()) return text;
 	if (!stat.isFile()) {
 		throw configError(`the envelope path ${JSON.stringify(text)} is not a regular file; point it at the envelope file itself`);
 	}
@@ -366,8 +368,8 @@ export function fileIdentity(stat) {
  * relative, and when a path cannot be read for a reason other than its absence. `realpathSync`, `statSync`, `cwd` and
  * `env` are injectable for tests.
  */
-export function envelopeInsideJobPaths(envelopePath, { cronFolders = [], runRoots = [], skillsDirs = [], globalPiDir = null } = {}, { realpathSync = fsRealpathSync.native, statSync = fsStatSync, cwd = process.cwd(), env = process.env } = {}) {
-	const real = canonicalEnvelopePath(envelopePath, realpathSync, statSync);
+export function envelopeInsideJobPaths(envelopePath, { cronFolders = [], runRoots = [], skillsDirs = [], globalPiDir = null } = {}, { realpathSync = fsRealpathSync.native, statSync = fsStatSync, cwd = process.cwd(), env = process.env, directory = false } = {}) {
+	const real = canonicalEnvelopePath(envelopePath, realpathSync, statSync, directory);
 	// A relative run root is refused under an envelope, as `PI_GLOBAL_PI_DIR` and `run.skillsDir` already must be
 	// absolute: the worker would judge it against its own working directory, while the admin's `dispatch_run` resolves
 	// it in the operator's pi process, so the two could mean different folders.

package/src/mcp-config.mjs

@@ -17,7 +17,9 @@
  * name or password. pi's own resolver would run a value starting with `!` and expand bare `$NAME`; the job resolves
  * the references itself, never pi.
  *
- * Accepted is a subset of pi 1.1.0's schema (core/mcp-servers.js `validateMcpServerConfig`), strict on keys: a key
+ * Accepted is a subset of pi 1.1.0's schema (core/mcp-servers.js `validateMcpServerConfig`; since 1.5.2 pi-mcp's
+ * dist/config.js checks the fields MCP clients share and core/mcp-servers.js adds exposure and `auth`, accepting the
+ * same entries as before), strict on keys: a key
  * pi-dispatch does not know is refused, so a key a later pi adds is read before a job relies on it. Refused outright:
  * `auth` and `oauth` (a credential flow the container cannot finish, and a token file it must not hold), `cwd` (a job
  * runs its servers in the checkout), and the legacy `sse` type, which pi refuses too. `allowPackageRunner` is

package/src/models-json.mjs

@@ -154,6 +154,8 @@ const SamplingParams = T.rec(T.unknown());
 const SamplingParamsByThinkingLevel = T.obj({ off: opt(SamplingParams), minimal: opt(SamplingParams), low: opt(SamplingParams), medium: opt(SamplingParams), high: opt(SamplingParams), xhigh: opt(SamplingParams), max: opt(SamplingParams) });
 const KwargValue = T.union(T.str(), T.num(), T.bool(), T.nul(), T.obj({ $var: req(T.union(T.lit("thinking.enabled"), T.lit("thinking.effort"), T.lit("thinking.budget"))), omitWhenOff: opt(T.bool()) }));
 const affinity = T.union(T.lit("openai"), T.lit("openai-nosession"), T.lit("openrouter"));
+// pi 1.5.2: the prompt_cache_key switch, the same three values in the completions, responses and generic schemas.
+const cacheKeyMode = T.union(T.lit("auto"), T.lit("enabled"), T.lit("disabled"));
 const costRates = { input: req(T.num()), output: req(T.num()), cacheRead: req(T.num()), cacheWrite: req(T.num()) };
 const ModelCostTier = T.obj({ inputTokensAbove: req(T.num()), ...costRates });
 const ModelCost = T.obj({ ...costRates, tiers: opt(T.arr(ModelCostTier)) });
@@ -164,7 +166,8 @@ const ImageResize = T.obj({ maxWidth: opt(posInt), maxHeight: opt(posInt), maxBy
 const ModelInputLimits = T.obj({ maxRequestBytes: opt(posInt), images: opt(T.obj({ resize: opt(ImageResize), maxPerMessage: opt(posInt), maxPerRequest: opt(posInt) })) });
 // compat-schema.js's ProviderCompatSchema: the merged properties of the OpenAI completions, OpenAI responses, Anthropic
 // messages, Bedrock, Mistral and System One schemas. A key two of them share takes pi's generic override, which for every shared
-// key here is the same type as each api's own (a boolean, or the three-way affinity format), so the superset is exact.
+// key here is the same type as each api's own (a boolean, the three-way affinity format, or 1.5.2's three-way
+// promptCacheKeyMode), so the superset is exact.
 const bool = opt(T.bool());
 const ProviderCompat = T.obj({
 	// OpenAI completions
@@ -176,6 +179,8 @@ const ProviderCompat = T.obj({
 	maxTokensField: opt(T.union(T.lit("max_completion_tokens"), T.lit("max_tokens"))),
 	requiresToolResultName: bool,
 	requiresAssistantAfterToolResult: bool,
+	requiresNonNullAssistantContent: bool,
+	requiresToolsWithToolHistory: bool,
 	requiresThinkingAsText: bool,
 	requiresReasoningContentOnAssistantMessages: bool,
 	thinkingFormat: opt(T.union(...["openai", "openrouter", "deepseek", "together", "baseten", "zai", "qwen", "chat-template", "qwen-chat-template", "string-thinking", "ant-ling"].map((x) => T.lit(x)))),
@@ -193,6 +198,7 @@ const ProviderCompat = T.obj({
 	cacheControlFormat: opt(T.lit("anthropic")),
 	sendSessionAffinityHeaders: bool,
 	sessionAffinityFormat: opt(affinity),
+	promptCacheKeyMode: opt(cacheKeyMode),
 	supportsLongCacheRetention: bool,
 	vllmPriority: opt(T.num()),
 	// OpenAI responses
@@ -209,6 +215,7 @@ const ProviderCompat = T.obj({
 	supportsStrictTools: bool,
 	supportsMidConvoEffort: bool,
 	supportsMidConvoToolChanges: bool,
+	supportsMessageThreads: bool,
 	// System One classifier image transport, checked before pi reads the overlay.
 	imageInput: opt(T.union(T.lit("assets"), T.lit("images"), T.lit("state-image-urls"))),
 	sendImageOptInHeader: bool,

package/src/setup-host-entry.mjs

@@ -4,7 +4,10 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export function setupCachePath(path) {
-	return /(?:^|[/\\])(?:_npx|_cacache|npm-cache|\.cache)(?:[/\\]|$)/.test(String(path));
+	// pnpm's, yarn's and bun's temporary stores are as disposable as npm's own. Matched by their whole shape, because a folder someone named
+	// `dlx` is an ordinary folder.
+	const text = String(path);
+	return /(?:^|[/\\])(?:_npx|_cacache|npm-cache|\.cache)(?:[/\\]|$)/.test(text) || /(?:^|[/\\])pnpm[/\\]dlx(?:[/\\]|$)/.test(text) || /(?:^|[/\\])xfs-[^/\\]+[/\\]dlx-\d+(?:[/\\]|$)/.test(text) || /(?:^|[/\\])bunx-\d+-[^/\\]+(?:[/\\]|$)/.test(text) || /(?:^|[/\\])\.yarn[/\\]berry[/\\]cache(?:[/\\]|$)/.test(text);
 }
 export function trustedSetupFile(entry, { uid = process.geteuid?.(), realpath = realpathSync, stat = statSync } = {}) {
 	try {

package/src/up.mjs

@@ -1155,7 +1155,9 @@ export async function runUp(argv = [], deps = {}) {
 	for (const [name, note] of summary) {
 		out(`  ${name.padEnd(21)} ${note}\n`);
 	}
-	out(`
+	// `up --console` goes on to /setup, whose checklist is the next step, and these bare commands are not on a local install's PATH.
+	const nextOut = deps.skipNextSteps ? () => {} : out;
+	nextOut(`
 Next:
   edit ${envPath}
       set ANTHROPIC_API_KEY (or your provider's key) — already logged into pi? leave it blank
@@ -1167,7 +1169,7 @@ Next:
 	// 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");
+		nextOut("  (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 #708: the console as a service, offered only where it could start (an operator token exists): without one,
 	// `service install --console` refuses, and a "Next:" line that leads to a refusal is not a next step.
@@ -1175,10 +1177,10 @@ Next:
 	try {
 		consoleReady = consoleOperators(cwd) > 0 && !consoleUnitInstalled(cwd);
 	} catch {}
-	if (consoleReady) out("  pi-dispatch service install --console\n      keep the operator console running as a service (open it with /dispatch console)\n");
+	if (consoleReady) nextOut("  pi-dispatch service install --console\n      keep the operator console running as a service (open it with /dispatch console)\n");
 	// Issue #707: the openshell venues' own next step, said only where one is blessed.
 	if (openshell.used) {
-		out(`  pi-dispatch service install\n      the worker as a ${platform === "darwin" ? "LaunchAgent (the gateway runs in this login session: `brew services start openshell`, the service of OpenShell's release formula, keeps it there)" : `user service that pulls in the gateway's own unit (${OPENSHELL_GATEWAY_UNIT})`}; then \`pi-dispatch doctor\` reads the gateway, its engine and the image back. A worker started by hand reads only its shell, so export the same PI_BACKENDS (and PI_OPENSHELL_ENGINE) there first\n`);
+		nextOut(`  pi-dispatch service install\n      the worker as a ${platform === "darwin" ? "LaunchAgent (the gateway runs in this login session: `brew services start openshell`, the service of OpenShell's release formula, keeps it there)" : `user service that pulls in the gateway's own unit (${OPENSHELL_GATEWAY_UNIT})`}; then \`pi-dispatch doctor\` reads the gateway, its engine and the image back. A worker started by hand reads only its shell, so export the same PI_BACKENDS (and PI_OPENSHELL_ENGINE) there first\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.