@edgehero/pi-dispatch 4.3.0 → 5.0.0

package/src/older-state.mjs

@@ -0,0 +1,249 @@
+/**
+ * State this build still meets in the shape, or at the place, an older release left it (issue #761): one finding each,
+ * which doctor prints as `state.older` and `up`'s summary repeats for the Valkey container.
+ *
+ * THE RULE for every later release: one that moves or reshapes a store and keeps the old shape readable registers a
+ * detector here, gated so that it retires itself (it fires only while the old shape is really there, and says nothing
+ * once it is gone), and adds a row to docs/upgrading.md. A detector fires on an EXACT older reference, never on
+ * something an operator chose (an image they picked, a file they edited, a path they set): a warning that cannot go
+ * away, or that argues with a deliberate choice, is one nobody reads.
+ *
+ * No data store has an older shape yet. Every versioned file and record this build reads, it also still writes:
+ * versions are stamped by need (DES-STORE-VERSION-WHEN-NEEDED), so a version 1 file or record is what this build writes
+ * too while nothing in it needs more, and job data's version 2 and the scoped limits' 3 are stamped only where a field
+ * needs them. The older LOCATIONS of issues #290 and #464 (the run history and the settings overlay under the OS temp
+ * dir, retained workspaces under the old shared jobs root) keep their own lines in doctor's `state` and `dirs` sections.
+ *
+ * What is here: the Valkey image older releases shipped, the floating `valkey/valkey:8`, which this release pins as
+ * `VALKEY_IMAGE` (valkey-auth.mjs says why). An upgrade rewrites none of the three places that keep it:
+ *   - a compose file in the deployment folder, which /dispatch setup copies create-only into `deploy/` (an earlier setup
+ *     copied it to the folder's top);
+ *   - the installed Quadlet unit, which only `service install --force` rewrites (`up` leaves a changed one as it is);
+ *   - the `pi-dispatch-valkey` container an older `up` started, which keeps its image until it is recreated.
+ *
+ * Pure but for two seams, and it never throws: `readFile(path)` gives a file's text (a throw, a missing file, is no
+ * finding), and `valkeyContainer()` gives `valkeyContainerOwner`'s verdict on the `pi-dispatch-valkey` container
+ * (valkey-auth.mjs; null, a throw or no seam is no finding), which `upValkeyContainerImage` judges with the folder's
+ * `handedOver`, and which also decides whether the compose file's fix recreates compose's valkey. A detector that cannot
+ * read must not say something false.
+ */
+import { join } from "node:path";
+import { COMPOSE_FILE, COMPOSE_VALKEY_OVERRIDE, VALKEY_IMAGE, VALKEY_VOLUME, composeArgs, composeProjectName } from "./valkey-auth.mjs";
+import { QUADLET_FILES, quadletDir } from "./podman-stack.mjs";
+
+/**
+ * Every Valkey image reference an older release shipped, as each place spelled it: compose and `up`'s `docker run` the
+ * short name, the Quadlet unit the fully qualified one. Matched EXACTLY, so `valkey/valkey:8.1`, `:8-alpine` and
+ * `:8@sha256:...` (each an operator's or this release's choice) never are. When `VALKEY_IMAGE` moves on, the value it
+ * leaves is added here, in both spellings; a test holds `VALKEY_IMAGE` out of this list.
+ */
+export const OLDER_VALKEY_IMAGES = Object.freeze(["valkey/valkey:8", "docker.io/valkey/valkey:8"]);
+
+/** The container `up` starts Valkey as (`valkeyDockerRunArgs`), the one `valkeyContainer` gives the verdict on. */
+export const VALKEY_CONTAINER = "pi-dispatch-valkey";
+
+/**
+ * The image of the Valkey container `owner` describes (`valkeyContainerOwner`'s verdict, valkey-auth.mjs), when `up`
+ * runs that container itself, else null. THE one rule `up`'s summary and doctor's `state.older` both judge the container
+ * by, so neither names a container the other leaves alone:
+ *   - it is provably this deployment's (`ours`: up's label naming this folder, compose's working dir here, or,
+ *     unlabelled, this deployment's VALKEY_URL port on 127.0.0.1). Another deployment's container, or one nothing ties
+ *     to this folder, is never stopped or removed from here, and the fix below does both;
+ *   - and the folder is not handed to compose (`handedOver` false: no `COMPOSE_VALKEY_OVERRIDE`). There compose runs the
+ *     Valkey and recreates it from the compose file, which its own detector judges, and `pi-dispatch up` starts compose's
+ *     valkey, never a container of its own.
+ * Anything else, an unknown or absent verdict and a hand-over fact that is not a boolean included, is null: a fix that
+ * could act on the wrong container is worse than no finding.
+ */
+export function upValkeyContainerImage(owner, { handedOver } = {}) {
+	if (!upRunsValkey(owner, { handedOver })) return null;
+	return typeof owner.image === "string" ? owner.image : null;
+}
+
+/**
+ * Whether this deployment's `up` runs its Valkey as that container, whatever its image: the first half of
+ * `upValkeyContainerImage`'s rule. Then compose does not run this deployment's Valkey, so the compose file's fix must
+ * not recreate compose's valkey, which would start a second, empty one beside the queue.
+ */
+function upRunsValkey(owner, { handedOver } = {}) {
+	return owner?.ours === true && handedOver === false;
+}
+
+/** The legacy place an earlier /dispatch setup copied the compose file to, relative to the deployment folder. */
+export const LEGACY_COMPOSE_FILE = "docker-compose.yml";
+
+// Said by every fix below, as `podman-stack.mjs` says it for a Valkey restart: the cost, and how to avoid it.
+const INTERRUPTS = "A job running right now is interrupted: pause first if one is (pi-dispatch pause, wait for active jobs, then pi-dispatch resume)";
+const PINS = `this release pins ${VALKEY_IMAGE}`;
+
+/** `ref` when it is exactly one of `OLDER_VALKEY_IMAGES` (surrounding whitespace aside), else null. */
+export function olderValkeyImage(ref) {
+	const s = typeof ref === "string" ? ref.trim() : "";
+	return OLDER_VALKEY_IMAGES.includes(s) ? s : null;
+}
+
+/**
+ * Every `image:` of the compose file's `valkey` service (the top-level `services.valkey` block), quotes and a trailing
+ * comment aside, in file order, or none. That service's only: another service on `valkey/valkey:8` (a cache an operator
+ * added beside the queue, say) is the operator's choice, and a finding about it is one no upgrade step clears. A line
+ * scan by indentation rather than a YAML parse, since the only question is which image the queue's Valkey names:
+ * `services:` at the top, `valkey:` one level under it, and `image:` one level under that, where a nested map's
+ * `image:`, a comment and a blank line are not it. A spelling the scan does not follow (a flow mapping, an anchor, a
+ * quoted key) is no finding, never a false one.
+ *
+ * A merge left unresolved in the service (git's conflict markers at column 0, which would otherwise end the block as a
+ * top-level key does) is read through: the marker lines count as blank and EVERY `image:` at the service's own level
+ * counts, so a conflict between `:8` and `:8.1` is a finding, whichever side holds the older line. Under git's diff3 and
+ * zdiff3 styles the merge base sits between a `|||||||` marker and the `=======`: it is neither side, so it counts as
+ * blank too, and an older line in the base alone is no finding. The markers are read inside the service only; elsewhere
+ * they still end the scan, as any top-level line does.
+ */
+function composeValkeyImages(text) {
+	const lines = String(text).split(/\r?\n/);
+	const depth = (line) => /^[ \t]*/.exec(line)[0].length;
+	const said = (line) => !/^\s*(?:#.*)?$/.test(line);
+	// git's markers: seven of one character at column 0, every one but `=======` followed by a name (a side, or the base).
+	const conflictMarker = (line) => /^(?:(?:<{7}|>{7}|\|{7})(?:[ \t].*)?|={7}[ \t]*)$/.test(line);
+	const baseMarker = (line) => /^\|{7}(?:[ \t].*)?$/.test(line);
+	const sidesMarker = (line) => /^={7}[ \t]*$/.test(line);
+	let i = lines.findIndex((line) => /^services:\s*(?:#.*)?$/.test(line));
+	if (i < 0) return [];
+	// The services, at the depth of the first one, until the next top-level key.
+	let services = null;
+	for (i += 1; i < lines.length; i++) {
+		if (!said(lines[i])) continue;
+		const d = depth(lines[i]);
+		if (d === 0) return [];
+		services ??= d;
+		if (d === services && /^\s*valkey:\s*(?:#.*)?$/.test(lines[i])) break;
+	}
+	// The valkey service's own keys, at the depth of its first one, until the next service.
+	const images = [];
+	let keys = null;
+	// Inside a conflict's merge base, from its `|||||||` to the `=======`.
+	let inBase = false;
+	for (i += 1; i < lines.length; i++) {
+		if (baseMarker(lines[i])) inBase = true;
+		else if (sidesMarker(lines[i])) inBase = false;
+		if (inBase || !said(lines[i]) || conflictMarker(lines[i])) continue;
+		const d = depth(lines[i]);
+		if (d <= services) break;
+		keys ??= d;
+		const m = d === keys ? /^\s*image:\s*(["']?)([^"'\s#]+)\1\s*(?:#.*)?$/.exec(lines[i]) : null;
+		if (m) images.push(m[2]);
+	}
+	return images;
+}
+
+/** The value of each `Image=` line of a unit file (systemd: a `#` or `;` line is a comment, the value is trimmed). */
+function quadletImages(text) {
+	const found = [];
+	for (const line of String(text).split(/\r?\n/)) {
+		const m = /^\s*Image\s*=\s*(.*?)\s*$/.exec(line);
+		if (m) found.push(m[1]);
+	}
+	return found;
+}
+
+/** A file's text through the seam, or null when it cannot be read (absent above all). */
+async function textOf(readFile, path) {
+	try {
+		const text = await readFile(path);
+		return text === null || text === undefined ? null : String(text);
+	} catch {
+		return null;
+	}
+}
+
+/** The verdict `valkeyContainer()` gives, synchronously or not, or null for no seam or one that throws. */
+async function verdictOf(valkeyContainer) {
+	if (typeof valkeyContainer !== "function") return null;
+	try {
+		return await valkeyContainer();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * The finding for the `pi-dispatch-valkey` container, or null: `upValkeyContainerImage` of the verdict
+ * `valkeyContainer()` gives and `handedOver`, held against the older images. Exported apart for `up`, which hands it
+ * the verdict of the inspect it already made and repeats this in its summary. `valkeyContainer` may answer
+ * synchronously or not.
+ */
+export async function olderValkeyContainerFinding({ valkeyContainer, handedOver } = {}) {
+	return containerFinding(await verdictOf(valkeyContainer), handedOver);
+}
+
+function containerFinding(owner, handedOver) {
+	const found = olderValkeyImage(upValkeyContainerImage(owner, { handedOver }));
+	if (!found) return null;
+	return {
+		store: "valkey-container",
+		label: `the ${VALKEY_CONTAINER} container runs ${found}, the floating tag an older \`pi-dispatch up\` started it with, and keeps it until it is recreated; ${PINS}`,
+		// stop, then rm, never `rm -f`: SIGTERM is what makes Valkey fsync its AOF and save a final snapshot before it exits
+		// (measured on 8.0.2 and 8.1.11), where `rm -f` kills it and can lose the last second of writes to the queue.
+		fix: `\`docker stop ${VALKEY_CONTAINER} && docker rm ${VALKEY_CONTAINER} && pi-dispatch up\` in the deployment folder starts ${VALKEY_IMAGE} on the same ${VALKEY_VOLUME} volume (stopped first, so Valkey writes its AOF out; the queue is kept). ${INTERRUPTS}`,
+	};
+}
+
+/** The first of a compose file's valkey images (`composeValkeyImages`) that is an older one, or null. */
+const olderComposeImage = (text) => composeValkeyImages(text).map(olderValkeyImage).find(Boolean) ?? null;
+
+/**
+ * Every finding for this deployment, in a fixed order: the folder's compose file, the earlier setup's copy at the
+ * folder's top, the installed Quadlet unit, the container. `cwd` is the deployment folder, `home` this account's home
+ * (where the Quadlet unit is installed); either missing skips its detectors. `handedOver` is whether the folder holds
+ * `COMPOSE_VALKEY_OVERRIDE`, as `up` reads it. The container's verdict is asked once, and decides the compose fix too:
+ * where this deployment's `up` runs the Valkey (`upRunsValkey`), the compose file only needs its line changed, since
+ * recreating compose's valkey would start a second, empty Valkey beside the queue. Where compose runs it, or the verdict
+ * cannot tell (no seam, a throw, a container that is not provably ours), the fix keeps the recreate.
+ */
+export async function olderStateFindings({ cwd, home, readFile, valkeyContainer, handedOver } = {}) {
+	const findings = [];
+	try {
+		const owner = await verdictOf(valkeyContainer);
+		if (typeof readFile === "function" && typeof cwd === "string" && cwd !== "") {
+			const path = join(cwd, COMPOSE_FILE);
+			const found = olderComposeImage((await textOf(readFile, path)) ?? "");
+			if (found) {
+				// The command /dispatch setup runs for this folder: its project, and the hand-over override where it wrote one.
+				const project = composeProjectName(cwd);
+				const override = (await textOf(readFile, join(cwd, COMPOSE_VALKEY_OVERRIDE))) !== null;
+				const line = `change that line to \`image: ${VALKEY_IMAGE}\` (the installed package's ${COMPOSE_FILE} has it)`;
+				findings.push({
+					store: "valkey-compose",
+					label: `${path} names ${found} for Valkey, the floating tag an older pi-dispatch shipped, which moves this host to a newer Valkey minor on its next pull; ${PINS}`,
+					fix: upRunsValkey(owner, { handedOver })
+						? `${line} and nothing more: this deployment's Valkey is the ${VALKEY_CONTAINER} container \`pi-dispatch up\` runs, not compose's, so recreating compose's valkey from this file would start a second, empty Valkey beside the queue`
+						: `${line}, then recreate Valkey from ${cwd} with \`docker ${composeArgs({ project, override }).join(" ")} up -d valkey\` (leave out \`-p ${project}\` if you run this file without it), which stops it first, so it writes its AOF out, and keeps its volume and the queue in it. ${INTERRUPTS}`,
+				});
+			}
+			const legacy = join(cwd, LEGACY_COMPOSE_FILE);
+			const old = olderComposeImage((await textOf(readFile, legacy)) ?? "");
+			if (old) {
+				findings.push({
+					store: "valkey-compose",
+					label: `${legacy} names ${old} for Valkey, the floating tag an older pi-dispatch shipped; ${PINS}`,
+					fix: `that file is an earlier /dispatch setup's copy, which setup no longer runs (${COMPOSE_FILE} is the one, and this copy's ../ paths reach the folder above ${cwd}): move any edits of yours there and remove it, or, if you still run it, change that line to \`image: ${VALKEY_IMAGE}\``,
+				});
+			}
+		}
+		if (typeof readFile === "function" && typeof home === "string" && home !== "") {
+			const path = join(quadletDir(home), QUADLET_FILES.valkey.file);
+			const found = quadletImages((await textOf(readFile, path)) ?? "").map(olderValkeyImage).find(Boolean);
+			if (found) {
+				findings.push({
+					store: "valkey-quadlet",
+					label: `${path} runs Valkey as ${found}, the floating tag an older pi-dispatch installed; this release pins docker.io/${VALKEY_IMAGE}`,
+					fix: `\`pi-dispatch service install --force\` in the deployment folder rewrites the unit and restarts ${QUADLET_FILES.valkey.unit} on the same ${VALKEY_VOLUME} volume (stopped first, so Valkey writes its AOF out; the queue is kept); \`pi-dispatch up\` leaves a changed unit file as it is. ${INTERRUPTS}`,
+				});
+			}
+		}
+		const container = containerFinding(owner, handedOver);
+		if (container) findings.push(container);
+	} catch {
+		// Nothing above throws by design (every read goes through a guarded seam); a finding already made still stands.
+	}
+	return findings;
+}

package/src/on-failure.mjs

@@ -11,11 +11,12 @@
  *     is the right event regardless).
  *   - **No verdict, no fault count, no profile table.** The hook changes NOTHING about the job: it runs
  *     after the outcome is decided, fire and forget, and a hook fault must never flip a result
- *     (CONST-RETRY-INFRA-ONLY). Its exit code is logged and unread -- OQ-027's residual, inherited.
+ *     (CONST-RETRY-INFRA-ONLY). Its exit code is logged and published for display only (#775).
  *   - **The reason is shape-guarded HERE, the single normalizing door.** `InfraRetry.reason` defaults to
  *     the whole message when no token was given, and messages carry things like a library's own words --
- *     so anything that does not look like a fixed token (`/^[a-z0-9-]{1,40}$/`) flattens to "infra"
- *     before it can become an argv element. Id-only argv is the contract
+ *     so anything that is not a record reason token (`RECORD_REASON_RE`, the run record's own rule, from
+ *     its leaf: so a reason the record keeps reaches the hook as itself, never as "infra") flattens to
+ *     "infra" before it can become an argv element. Id-only argv is the contract
  *     (`INT-ON-FAILURE-HOOK-CONTRACT`), and one guard at the spawn is worth ten at the call sites.
  *
  * What transfers unchanged: the executable resolved at CALL time (an operator who fixes the path
@@ -26,28 +27,31 @@
 
 import { realpathSync, statSync } from "node:fs";
 import { spawn } from "node:child_process";
+import { RECORD_REASON_RE } from "./record-reason.mjs";
 
 /** SIGTERM, then SIGKILL after this. secrets.mjs's grace, for its reason. */
 const KILL_GRACE_MS = 2000;
 
-/** A reason that may ride argv: a fixed lowercase token, never a message. */
-const REASON_SHAPE = /^[a-z0-9-]{1,40}$/;
-
 /**
  * Build the hook runner. Returns `fire({ jobId, outcome, reason })` -> void: spawns the operator's
  * command as `cmd <jobId> <outcome> <reason> <host>`, logs one `on_failure` line with the pinned key
  * set { jobId, code, detail }, and never throws, rejects, or delays anything.
  */
-export function makeOnFailure({ command, timeoutMs = 10_000, spawnFn = spawn, realExecutablePath = defaultRealExecutablePath, hostEnv = process.env, host = "", log = () => {} }) {
-	const note = (jobId, code, detail) => {
+export function makeOnFailure({ command, timeoutMs = 10_000, spawnFn = spawn, realExecutablePath = defaultRealExecutablePath, hostEnv = process.env, host = "", log = () => {}, publish = () => {} }) {
+	const note = (jobId, code, detail, outcome, reason) => {
 		try {
 			log("on_failure", { jobId, code, detail });
 		} catch {
 			// an injected sink that throws must not break the fire-and-forget contract
 		}
+		// The log's existing keys and the hook's return value stay unchanged. Independent guards mean a broken log
+		// sink does not silence the display, and a display fault cannot become a job retry or delay another hook.
+		try { void Promise.resolve(publish({ jobId, outcome, reason, detail, code })).catch(() => {}); } catch {}
 	};
 
 	return function fire({ jobId, outcome, reason }) {
+		const safeReason = typeof reason === "string" && RECORD_REASON_RE.test(reason) ? reason : "infra";
+		const finishNote = (code, detail) => note(typeof jobId === "string" ? jobId : null, code, detail, outcome, safeReason);
 		// Resolved at CALL time, not construction (wait-check's rule): realpath + the executable bit,
 		// answering the same question spawn will.
 		let path;
@@ -56,14 +60,14 @@ export function makeOnFailure({ command, timeoutMs = 10_000, spawnFn = spawn, re
 		} catch {
 			path = null;
 		}
-		if (!path) return note(typeof jobId === "string" ? jobId : null, null, "unresolvable");
+		if (!path) return finishNote(null, "unresolvable");
 
-		const safeReason = typeof reason === "string" && REASON_SHAPE.test(reason) ? reason : "infra";
+		// A reason rides argv only as a record reason token (the record's own rule), never as a message.
 		// Argv must be non-empty id-only strings, and none may start with a dash -- this is argv where a
 		// dash parses as a flag, and the option parser is the operator's. `host` may honestly be "".
 		const argv = [jobId, outcome, safeReason, host];
 		if (argv.slice(0, 3).some((a) => typeof a !== "string" || a === "") || argv.some((a) => typeof a === "string" && a.startsWith("-"))) {
-			return note(typeof jobId === "string" ? jobId : null, null, "argv-unusable");
+			return finishNote(null, "argv-unusable");
 		}
 
 		let child;
@@ -74,7 +78,7 @@ export function makeOnFailure({ command, timeoutMs = 10_000, spawnFn = spawn, re
 				shell: false,
 			});
 		} catch {
-			return note(jobId, null, "spawn");
+			return finishNote(null, "spawn");
 		}
 
 		let done = false;
@@ -84,7 +88,7 @@ export function makeOnFailure({ command, timeoutMs = 10_000, spawnFn = spawn, re
 			if (done) return;
 			done = true;
 			clearTimeout(timer);
-			note(jobId, code, detail);
+			finishNote(code, detail);
 		};
 		// The kill ladder: SIGTERM, and SIGKILL for a child that ignored it. The escalation timer is
 		// deliberately not cleared by finish -- it still has to land on a stubborn child -- and both

package/src/open-browser.mjs

@@ -1,5 +1,35 @@
 import { spawn as nodeSpawn } from "node:child_process";
 
+/**
+ * The opener's argv for `url` on `platform`. On win32 it is `rundll32 url.dll,FileProtocolHandler <url>`, the shell's
+ * own URL handler, and NOT `cmd /c start "" <url>` (what it was until issue #708): `cmd` re-parses its command line,
+ * so an unquoted `&` ends the command there (`start` opened the URL up to it and `cmd` ran the rest as a second
+ * command), and node quotes an argument only when it holds a space or a quote, which a URL never does. A login link
+ * (`login/code#<code>&next=/runs`) and a GitHub install URL both carry one. rundll32 is no shell: it hands the rest of
+ * its command line to the handler as it is, `&` and `#` included. Quoting the URL inside `start` was rejected because
+ * it relies on node's quoting rules and `cmd`'s together, and `^`-escaping because `cmd /c` and `start` each strip one
+ * level.
+ */
+export function openerArgv(url, platform = process.platform) {
+	if (platform === "darwin") return ["open", [url]];
+	if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+	return ["xdg-open", [url]];
+}
+
+/**
+ * Can a browser opened here be in front of the person at this terminal (issue #708)? Not over SSH (any of
+ * `SSH_CONNECTION`, `SSH_CLIENT` or `SSH_TTY` set: the browser would open on the remote host, or nowhere), and on
+ * Linux and the BSDs only with a display (`DISPLAY` or `WAYLAND_DISPLAY`: without one `xdg-open` falls back to a text
+ * browser or fails). macOS and Windows always have their desktop's opener. A false answer means the caller prints the
+ * URL and spawns nothing; the printed URL is the contract either way.
+ */
+export function isLocalBrowserSession({ env = process.env, platform = process.platform } = {}) {
+	const set = (k) => typeof env?.[k] === "string" && env[k] !== "";
+	if (set("SSH_CONNECTION") || set("SSH_CLIENT") || set("SSH_TTY")) return false;
+	if (platform === "darwin" || platform === "win32") return true;
+	return set("DISPLAY") || set("WAYLAND_DISPLAY");
+}
+
 /**
  * Best-effort platform browser opener. ALWAYS paired with the URL printed to the terminal -- a
  * headless or SSH'd operator has no opener that works, and the printed URL pasted into any browser
@@ -12,8 +42,7 @@ import { spawn as nodeSpawn } from "node:child_process";
  * without launching anything.
  */
 export function openBrowser(url, { spawn = nodeSpawn, platform = process.platform } = {}) {
-	const [cmd, args] =
-		platform === "darwin" ? ["open", [url]] : platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+	const [cmd, args] = openerArgv(url, platform);
 	try {
 		const child = spawn(cmd, args, { stdio: "ignore", detached: true });
 		child.on("error", () => {});

package/src/opener-cli.mjs

@@ -0,0 +1,135 @@
+/** An explicit import enrolls trusted Fleet mappings. A link never changes configuration. */
+import * as nodeFs from "node:fs";
+import { execFile as nodeExecFile, spawn as nodeSpawn } from "node:child_process";
+import { promisify } from "node:util";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { dirname, join, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import { parseSandboxOpenUrl } from "./opener-protocol.mjs";
+import { readSandboxHosts, sandboxCommand } from "./sandbox-hosts.mjs";
+import { spawnTerminal, terminalLaunch, windowsPowerShellEnv } from "./opener-terminal.mjs";
+import { trustedChain } from "./service-env.mjs";
+
+// env-internal XDG_CONFIG_HOME, HOME, USERPROFILE: the native handler belongs to the current account and uses its config directory.
+export function openerDirectory(env = process.env) { return join(env.XDG_CONFIG_HOME || join(env.HOME || env.USERPROFILE || homedir(), ".config"), "pi-dispatch", "opener"); }
+const apple = (value) => `"${String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+// Desktop-entry values unescape first, then Exec unquotes. Both layers need their own backslash.
+const desktop = (value) => `"${String(value).replaceAll("%", "%%").replace(/[\\"`$]/g, "\\$&").replaceAll("\\", "\\\\")}"`;
+
+export function openerRegistration({ platform, home, directory, nodePath, cliPath, dataHome = join(home, ".local", "share") }) {
+	if (platform === "darwin") {
+		const app = join(home, "Applications", "pi-dispatch Opener.app");
+		const source = `on open location theURL\n do shell script (quoted form of ${apple(nodePath)} & " " & quoted form of ${apple(cliPath)} & " opener handle " & quoted form of theURL)\nend open location\n`;
+		const plist = `<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict><key>CFBundleExecutable</key><string>applet</string><key>CFBundleIdentifier</key><string>com.pi-dispatch.opener</string><key>CFBundleName</key><string>pi-dispatch Opener</string><key>CFBundlePackageType</key><string>APPL</string><key>LSUIElement</key><true/><key>CFBundleURLTypes</key><array><dict><key>CFBundleTypeRole</key><string>Editor</string><key>CFBundleURLName</key><string>pi-dispatch sandbox</string><key>CFBundleURLSchemes</key><array><string>pi-dispatch-open</string></array></dict></array></dict></plist>\n`;
+		// osacompile signs its bundle. Our URL metadata changes its signed resources, so sign again after the
+		// plist write; registering a modified signature can compile cleanly and still refuse at native launch.
+		return { commands: [["/usr/bin/osacompile", ["-o", app, "-e", source]], ["/usr/bin/codesign", ["--force", "--sign", "-", app]], ["/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister", ["-f", app]]], between: { path: join(app, "Contents", "Info.plist"), content: plist }, directory: dirname(app) };
+	}
+	if (platform === "linux") {
+		if (nodePath.includes("=")) throw new Error("the desktop Exec format cannot name a Node executable whose path contains '='; use Copy or install Node at another path");
+		if (!dataHome.startsWith("/") || /[\x00-\x1f\x7f]/.test(dataHome)) throw new Error("XDG_DATA_HOME must be an absolute desktop data directory without control bytes");
+		const path = join(dataHome, "applications", "pi-dispatch-opener.desktop");
+		const content = `[Desktop Entry]\nType=Application\nName=pi-dispatch sandbox opener\nNoDisplay=true\nTerminal=false\nExec=${desktop(nodePath)} ${desktop(cliPath)} opener handle %u\nMimeType=x-scheme-handler/pi-dispatch-open;\n`;
+		return { files: [{ path, content }], commands: [["xdg-mime", ["default", "pi-dispatch-opener.desktop", "x-scheme-handler/pi-dispatch-open"]]], directory: dirname(path) };
+	}
+	if (platform === "win32") {
+		// HKCU registration requires no elevation. reg.exe takes values as argv, never through cmd.exe.
+		const key = "HKCU\\Software\\Classes\\pi-dispatch-open";
+		// ShellExecute expands percent placeholders in this registry template, even inside quoted paths.
+		// Escape only the fixed paths; the final %1 remains the single URI substitution.
+		const quoted = (value) => `"${String(value).replaceAll("%", "%%").replaceAll('"', '\\"')}"`;
+		return { commands: [["reg.exe", ["add", key, "/ve", "/d", "URL:pi-dispatch sandbox opener", "/f"]], ["reg.exe", ["add", key, "/v", "URL Protocol", "/d", "", "/f"]], ["reg.exe", ["add", `${key}\\shell\\open\\command`, "/ve", "/d", `${quoted(nodePath)} ${quoted(cliPath)} opener handle "%1"`, "/f"]]] };
+	}
+	throw new Error("this operating system has no supported opener installer; copy the sandbox command instead");
+}
+
+/** A blank line is the entire approval vocabulary. A pasted command, y, Escape or EOF never runs anything. */
+export async function promptSandboxCommand(command, { input = process.stdin, output = process.stdout, spawn = nodeSpawn, isTty = Boolean(input.isTTY && output.isTTY) } = {}) {
+	if (!isTty) return { refused: true, message: "the opener needs a real terminal; copy the command into your terminal instead" };
+	output.write(`\n${command.display}\n\nPress Enter to run this command, or type anything to cancel.\n`);
+	const accepted = await new Promise((resolveAnswer) => {
+		const lines = createInterface({ input, output, terminal: false });
+		let answered = false;
+		lines.once("line", (line) => { answered = true; lines.close(); resolveAnswer(line === ""); });
+		lines.once("close", () => { if (!answered) resolveAnswer(false); });
+	});
+	if (!accepted) return { cancelled: true, code: 0 };
+	const code = await new Promise((resolveCode, reject) => {
+		const child = spawn(command.argv[0], command.argv.slice(1), { stdio: "inherit" });
+		child.once("error", reject);
+		child.once("exit", (code) => resolveCode(code ?? 1));
+	});
+	return { code };
+}
+
+export async function runOpener(argv = [], { env = process.env, deps = {} } = {}) {
+	// env-internal HOME, USERPROFILE: the current account's home, for current-user native protocol registration.
+	const { fs = nodeFs, platform = process.platform, home = env.HOME || env.USERPROFILE || homedir(), nodePath = process.execPath, cliPath = fileURLToPath(new URL("./cli.mjs", import.meta.url)), out = (s) => process.stdout.write(s), err = (s) => process.stderr.write(s), execFile = promisify(nodeExecFile), terminal = null, showTerminal = spawnTerminal, prompt = promptSandboxCommand, uid = process.geteuid?.() } = deps;
+	const directory = openerDirectory(env);
+	const configPath = join(directory, "hosts.json");
+	try {
+		if (argv[0] === "install") {
+			if (argv.length !== 3 || argv[1] !== "--config") throw new Error("usage: pi-dispatch opener install --config <approved Fleet export.json>");
+			const source = readSandboxHosts(resolve(argv[2]), { fs, uid, allowMissing: false });
+			if (source.refusal) throw new Error(source.refusal);
+			if (!Object.keys(source.config.hosts).length) throw new Error("the approved Fleet export has no sandbox hosts");
+			fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+			const configStat = fs.lstatSync(directory);
+			if (!configStat.isDirectory() || configStat.isSymbolicLink() || (Number.isInteger(uid) && (configStat.uid !== uid || trustedChain(fs.realpathSync(directory), { fs, uid })))) throw new Error("the opener configuration folder must belong to this account, have a trusted parent and cannot be a link");
+			fs.chmodSync(directory, 0o700);
+			if (platform === "win32") {
+				// chmod does not express a Windows DACL. Protect the imported mapping using this account's SID,
+				// independently of a directory's inherited grants; the URL never supplies the principal or path.
+				const identity = await execFile("whoami.exe", ["/user", "/fo", "csv", "/nh"], { env, timeout: 10_000, maxBuffer: 64 * 1024 });
+				const sid = /S-1-\d+(?:-\d+)+/.exec(identity.stdout ?? "")?.[0];
+				if (!sid) throw new Error("the Windows account SID could not be resolved; the opener configuration was not imported");
+				// /grant:r replaces only this SID's grants. Reset first so a pre-existing explicit Everyone ACE is
+				// not retained beside it; removing inheritance then leaves only the grant below on this directory.
+				await execFile("icacls.exe", [directory, "/reset"], { env, timeout: 10_000, maxBuffer: 64 * 1024 });
+				await execFile("icacls.exe", [directory, "/inheritance:r", "/grant:r", `*${sid}:(OI)(CI)F`], { env, timeout: 10_000, maxBuffer: 64 * 1024 });
+			}
+			const temporary = join(directory, `import-${randomBytes(12).toString("hex")}.json`);
+			try {
+				fs.writeFileSync(temporary, JSON.stringify(source.config, null, 2) + "\n", { mode: 0o600, flag: "wx" });
+				fs.renameSync(temporary, configPath);
+			} finally { fs.rmSync(temporary, { force: true }); }
+			// env-internal XDG_DATA_HOME: xdg-mime and xdg-open look up desktop handlers in this same OS data directory.
+			const plan = openerRegistration({ platform, home, directory, nodePath, cliPath, dataHome: env.XDG_DATA_HOME || join(home, ".local", "share") });
+			if (plan.directory) {
+				fs.mkdirSync(plan.directory, { recursive: true, mode: 0o700 });
+				if (Number.isInteger(uid) && trustedChain(fs.realpathSync(plan.directory), { fs, uid })) throw new Error("the native handler directory is in a folder another account can change");
+			}
+			for (const file of plan.files ?? []) fs.writeFileSync(file.path, file.content, { mode: 0o600 });
+			for (let i = 0; i < plan.commands.length; i++) {
+				const [bin, args] = plan.commands[i];
+				// The MIME registration and the desktop entry must use the same XDG directories.
+				await execFile(bin, args, { env, timeout: 30_000, maxBuffer: 1024 * 1024 });
+				if (i === 0 && plan.between) fs.writeFileSync(plan.between.path, plan.between.content, { mode: 0o600 });
+			}
+			if (platform === "win32") {
+				// Windows requires SHCNE_ASSOCCHANGED for registered protocols too; writing HKCU alone can leave
+				// the Shell's old association cached until reboot. No URL or configurable text enters this script.
+				const notification = `Add-Type -Namespace PiDispatch -Name ShellChange -MemberDefinition '[System.Runtime.InteropServices.DllImport("shell32.dll")] public static extern void SHChangeNotify(int eventId, uint flags, System.IntPtr item1, System.IntPtr item2);'; [PiDispatch.ShellChange]::SHChangeNotify(0x08000000, 0x1000, [System.IntPtr]::Zero, [System.IntPtr]::Zero)`;
+				// env-internal SystemRoot: Windows' own PowerShell binary for its Shell association notification.
+				await execFile(win32.join(env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), ["-NoProfile", "-NonInteractive", "-Command", notification], { env: windowsPowerShellEnv(env), timeout: 30_000, maxBuffer: 64 * 1024 });
+			}
+			out("installed pi-dispatch-open for this account; commands wait for Enter in the terminal\n");
+			return 0;
+		}
+		if (!["handle", "prompt"].includes(argv[0]) || argv.length !== 2) throw new Error("usage: pi-dispatch opener install --config <file> (or handle <pi-dispatch-open://link>)");
+		const fields = parseSandboxOpenUrl(argv[1]);
+		const stored = readSandboxHosts(configPath, { fs, uid, allowMissing: false });
+		if (stored.refusal) throw new Error("the local opener has no usable approved configuration; run pi-dispatch opener install --config <Fleet export.json>");
+		const command = sandboxCommand(stored.config, fields);
+		if (argv[0] === "prompt") {
+			const result = await prompt(command);
+			if (result.refused) throw new Error(result.message);
+			return result.code ?? 0;
+		}
+		const plan = terminalLaunch({ platform, nodePath, cliPath, url: argv[1], directory: join(directory, "prompts"), env, fs, ...(terminal ? { terminal } : {}) });
+		await showTerminal(plan);
+		return 0;
+	} catch (error) { err(`opener: ${error.message}\n`); return 1; }
+}

package/src/opener-protocol.mjs

@@ -0,0 +1,27 @@
+/** Secret-free terminal handoff. No URL field is ever interpreted as a command or configuration. */
+import { WORKER_NAME_RE } from "./worker-name.mjs";
+
+export const SANDBOX_OPEN_VERBS = Object.freeze(["open", "attach"]);
+export const SANDBOX_OPEN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+export function sandboxOpenFields({ verb, id, host } = {}) {
+	if (!SANDBOX_OPEN_VERBS.includes(verb)) throw new Error("the opener verb must be open or attach");
+	if (typeof id !== "string" || !SANDBOX_OPEN_ID_RE.test(id)) throw new Error("the opener id is not a run or sandbox id");
+	if (typeof host !== "string" || !WORKER_NAME_RE.test(host) || /\.(?:json|log)$/i.test(host)) throw new Error("the opener host is not a worker name");
+	return { verb, id, host };
+}
+export function sandboxOpenUrl(fields) {
+	const { verb, id, host } = sandboxOpenFields(fields);
+	return `pi-dispatch-open://${verb}/${encodeURIComponent(id)}?host=${encodeURIComponent(host)}`;
+}
+export const buildSandboxOpenUrl = sandboxOpenUrl;
+export function parseSandboxOpenUrl(value) {
+	if (typeof value !== "string" || value.length > 1024) throw new Error("the opener link is invalid");
+	// Match the wire grammar before URL normalisation can hide a path traversal or a second decoding.
+	const match = /^pi-dispatch-open:\/\/(open|attach)\/([^/?#]+)\?host=([^&#]+)$/.exec(value);
+	if (!match) throw new Error("the opener link must name one open or attach verb, id and host");
+	let fields;
+	try { fields = sandboxOpenFields({ verb: match[1], id: decodeURIComponent(match[2]), host: decodeURIComponent(match[3]) }); }
+	catch (error) { throw new Error(error instanceof URIError ? "the opener link has invalid encoding" : error.message); }
+	if (sandboxOpenUrl(fields) !== value) throw new Error("the opener link is not canonical");
+	return fields;
+}