@mostra/cli 0.0.0-stage → 0.2.0

package/dist/run-BJaRnz-Q.js

@@ -0,0 +1,3824 @@
+import { a as catalogCodes, c as detectHarness, d as truthy, f as cliVersion, i as TelemetryEvent, l as buildEndpoint, m as packageRoot, n as startFlusher, o as durationBucket, p as fromSource, r as TelemetryStore, s as minute, u as decide } from "./flush-BCuWs0Zh.js";
+import { n as exitCodeFor, t as EXIT } from "./exit-CBIf8nAU.js";
+import { spawn } from "node:child_process";
+import { existsSync, lstatSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { ARTIFACT_PROGRESS, CLI_CLIENT_NAME, DEFAULT_DOCS_BASE, DEV_NOTIFY, FieldOp, HOST_PROTOCOL_REVISIONS, LineSplitter, MutationId, RpcError, RpcPeer, artifactCreateMethod, artifactGetMethod, artifactListMethod, artifactPublishMethod, artifactVerifyMethod, createDiagnostic, depsAddMethod, devStartMethod, devStopMethod, diagnosticCatalog, encodeLine, gcRunMethod, instanceCheckMethod, instanceStatusMethod, livePushMethod, mostraInitializeMethod, mostraShutdownMethod, resultsGetMethod, secretDeleteMethod, secretListMethod, secretSetMethod, stateGetMethod, statePatchMethod, viewDefaultMethod, viewLaunchMethod, viewRevokeMethod, viewRotateMethod, viewUrlMethod, waitMethod } from "@mostra/protocol";
+import { checkBrowser, checkFiles, enclosingBundle, readBundle, readSetup, resolveRuntime } from "@mostra/sdk";
+import { homedir, tmpdir } from "node:os";
+import { parseArgs } from "node:util";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline";
+import { createConnection } from "node:net";
+//#region src/command.ts
+/** Defines a command; the identity function, for types. */
+function defineCommand(command) {
+	return command;
+}
+/** The command path as one string: `daemon install`. */
+function commandName(command) {
+	return command.path.join(" ");
+}
+//#endregion
+//#region src/docs.ts
+/**
+* `mostra docs` (D140 item 17): the reference that ships with the CLI, by stable slug. The
+* diagnostic pages are keyed by code (`mostra docs MOSTRA_DEP_MISSING`, as hints say), beside the
+* CLI reference and the telemetry page. This index is the one source WP-15's `docs_search` and
+* WP-26's site read.
+*/
+/** Where the reference is: bundled in the build (`dist/reference`), or the repository's. */
+function referenceDir() {
+	const bundled = join(packageRoot(), "dist", "reference");
+	return !fromSource() && existsSync(bundled) ? bundled : join(packageRoot(), "..", "..", "docs", "reference");
+}
+function titleOf(file) {
+	const first = readFileSync(file, "utf8").split("\n").find((line) => line.startsWith("# "));
+	return first ? first.slice(2).trim() : "";
+}
+/** Every topic, the pages first and then the codes, sorted. */
+function docsIndex(dir = referenceDir()) {
+	const base = DEFAULT_DOCS_BASE.replace(/\/+$/, "");
+	const pages = [];
+	for (const topic of ["cli", "telemetry"]) {
+		const file = join(dir, `${topic}.md`);
+		if (existsSync(file)) pages.push({
+			topic,
+			title: titleOf(file),
+			url: `${base}/${topic}`,
+			file
+		});
+	}
+	const errorsDir = join(dir, "errors");
+	const errors = (existsSync(errorsDir) ? readdirSync(errorsDir).filter((name) => /^MOSTRA_[A-Z0-9_]+\.md$/.test(name)).sort() : []).map((name) => {
+		const code = name.slice(0, -3);
+		const file = join(errorsDir, name);
+		return {
+			topic: code,
+			title: titleOf(file),
+			url: `${base}/errors/${code}`,
+			file
+		};
+	});
+	return [...pages, ...errors];
+}
+/** The index as Markdown: what `mostra docs` prints without a topic. */
+function indexMarkdown(topics) {
+	const pages = topics.filter((topic) => !topic.topic.startsWith("MOSTRA_"));
+	const codes = topics.filter((topic) => topic.topic.startsWith("MOSTRA_"));
+	return [
+		"# Mostra reference",
+		"",
+		"Run `mostra docs <topic>` to read one. Diagnostic codes are topics too.",
+		"",
+		...pages.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
+		"",
+		"## Diagnostic codes",
+		"",
+		...codes.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
+		""
+	].join("\n");
+}
+/** The topics nearest an unknown one, for its usage error. */
+function nearestTopics(wanted, topics, count = 3) {
+	const target = wanted.toUpperCase();
+	return topics.map((topic) => {
+		const name = topic.topic.toUpperCase();
+		const contains = name.includes(target) || target.includes(name) ? 0 : 1;
+		return {
+			topic: topic.topic,
+			score: contains * 100 + distance(name, target)
+		};
+	}).sort((a, b) => a.score - b.score || (a.topic < b.topic ? -1 : 1)).slice(0, count).map((item) => item.topic);
+}
+/** Levenshtein distance. */
+function distance(a, b) {
+	const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i += 1) {
+		let previous = row[0];
+		row[0] = i;
+		for (let j = 1; j <= b.length; j += 1) {
+			const current = row[j];
+			row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+			previous = current;
+		}
+	}
+	return row[b.length];
+}
+//#endregion
+//#region src/home.ts
+/**
+* Where the CLI's things are: the home (D84's order), the runtime it starts, the home's settings
+* it reads, and the CLI's own config directory (D140 item 5). Resolving a path never touches the
+* file system; the runtime owns everything inside the home.
+*/
+const nonEmpty = (value) => value === void 0 || value === "" ? void 0 : value;
+/**
+* The home, in D84's order: `--home`, then `MOSTRA_HOME`, then the platform default (`~/.mostra`
+* on macOS, `${XDG_DATA_HOME:-~/.local/share}/mostra` on Linux), the same order the runtime uses.
+*/
+function resolveHome(options) {
+	const chosen = nonEmpty(options.home) ?? nonEmpty(options.env["MOSTRA_HOME"]);
+	if (chosen !== void 0) return resolve(options.cwd, chosen);
+	const user = nonEmpty(options.env["HOME"]) ?? homedir();
+	if ((options.platform ?? process.platform) === "darwin") return join(user, ".mostra");
+	const data = nonEmpty(options.env["XDG_DATA_HOME"]);
+	return join(data !== void 0 && isAbsolute(data) ? data : join(user, ".local", "share"), "mostra");
+}
+/**
+* The CLI's config directory (D140 item 5): `MOSTRA_CONFIG_DIR`, else
+* `${XDG_CONFIG_HOME:-~/.config}/mostra`, on both platforms. It holds telemetry's choice and
+* queue, per operating-system user, never per home.
+*/
+function configDir(env, cwd) {
+	const override = nonEmpty(env["MOSTRA_CONFIG_DIR"]);
+	if (override !== void 0) return resolve(cwd, override);
+	const xdg = nonEmpty(env["XDG_CONFIG_HOME"]);
+	const base = xdg !== void 0 && isAbsolute(xdg) ? xdg : join(nonEmpty(env["HOME"]) ?? homedir(), ".config");
+	return join(base, "mostra");
+}
+/**
+* The runtime the CLI starts (D85, RT-01), found as the SDK finds it: `MOSTRA_BUNDLE`,
+* `MOSTRA_RUNTIME_BIN`, the runtime bundle this CLI sits in, or a development checkout's built
+* runtime beside it. The bootstrap (`bootstrap.ts`) has already moved a CLI installed from npm
+* into its pinned bundle, so this never downloads. Throws the SDK's diagnostic when there is none.
+*/
+async function locateRuntime(env) {
+	const runtime = await resolveRuntime({ env });
+	return {
+		node: runtime.node,
+		entry: runtime.runtimeEntry
+	};
+}
+/**
+* Whether the CLI treats the home as a host's, which sends no telemetry (D140 item 4): a host
+* marked it, or its `config.json` can't be read as settings (fail closed). One rule for the
+* runner and for `mostra telemetry` (Opus review finding 6).
+*/
+function embeddedHome(marks) {
+	return marks.hostConfigured !== void 0 || marks.unreadable === true;
+}
+/**
+* The home's host mark, read from `config.json` without the instance, for commands that never
+* reach one. A file that can't be read as JSON counts as a host's home, so telemetry fails closed.
+*/
+function readHomeMarks(home) {
+	let text;
+	try {
+		text = readFileSync(join(home, "config.json"), "utf8");
+	} catch (error) {
+		return error.code === "ENOENT" ? {} : { unreadable: true };
+	}
+	try {
+		const mark = JSON.parse(text).hostConfigured;
+		if (mark === void 0) return {};
+		return typeof mark.client === "string" && typeof mark.at === "string" ? { hostConfigured: {
+			client: mark.client,
+			at: mark.at
+		} } : { unreadable: true };
+	} catch {
+		return { unreadable: true };
+	}
+}
+//#endregion
+//#region src/parse.ts
+/**
+* The command line, read against the command definitions (D140 item 13): the global flags, the
+* command path, its arguments and flags. Every failure is `MOSTRA_CLI_USAGE` or
+* `MOSTRA_CLI_UNKNOWN_COMMAND`, so `--json` mode reports it like any other error.
+*/
+/** The flags every command takes (INTERFACES §9). */
+const GLOBAL_FLAGS = [
+	{
+		name: "json",
+		kind: "boolean",
+		summary: "Print one JSON envelope on stdout (NDJSON for streams)."
+	},
+	{
+		name: "home",
+		kind: "string",
+		value: "<dir>",
+		summary: "Use this Mostra home instead of MOSTRA_HOME or the default."
+	},
+	{
+		name: "cwd",
+		kind: "string",
+		value: "<dir>",
+		summary: "Resolve relative paths from this directory."
+	},
+	{
+		name: "timeout",
+		kind: "duration",
+		value: "<d>",
+		summary: "Give up on the instance after this long (exit 4), such as 30s or 5m."
+	},
+	{
+		name: "help",
+		kind: "boolean",
+		summary: "Show this command's help; with --json, its definition."
+	}
+];
+/** A usage error. */
+function usage(message) {
+	return new RpcError(createDiagnostic("MOSTRA_CLI_USAGE", { message }));
+}
+const DURATION = /^([1-9][0-9]*)(ms|s|m|h|d)$/;
+const UNIT_MS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+/** A duration flag's milliseconds: `30s`, `5m`, `2h`, `7d`, `500ms`. */
+function durationMs(value) {
+	const match = DURATION.exec(value);
+	if (!match) throw usage(`"${value}" isn't a duration; use a number with ms, s, m, h or d, such as 30s.`);
+	return Number(match[1]) * UNIT_MS[match[2]];
+}
+/**
+* Reads the global flags wherever they stand, before the command is known: `--json` anywhere
+* before `--` makes even a usage error a JSON envelope (D140 item 16).
+*/
+function globalFlags(argv) {
+	const end = argv.indexOf("--");
+	const words = end === -1 ? argv : argv.slice(0, end);
+	const value = (name) => {
+		for (let index = 0; index < words.length; index += 1) {
+			const word = words[index];
+			if (word === `--${name}`) return words[index + 1];
+			if (word.startsWith(`--${name}=`)) return word.slice(name.length + 3);
+		}
+	};
+	const timeout = value("timeout");
+	let timeoutMs;
+	try {
+		timeoutMs = timeout === void 0 ? void 0 : durationMs(timeout);
+	} catch {
+		timeoutMs = void 0;
+	}
+	const home = value("home");
+	const cwd = value("cwd");
+	return {
+		json: words.includes("--json"),
+		...home !== void 0 ? { home } : {},
+		...cwd !== void 0 ? { cwd } : {},
+		...timeoutMs !== void 0 ? { timeoutMs } : {}
+	};
+}
+/** The command that names `words`' longest prefix. */
+function findCommand(commands, words) {
+	let best;
+	for (const command of commands) {
+		const { path } = command;
+		if (path.length <= words.length && path.every((word, index) => words[index] === word)) {
+			if (!best || path.length > best.used) best = {
+				command,
+				used: path.length
+			};
+		}
+	}
+	return best;
+}
+/** The first words of every command: the groups and the single-word commands. */
+function topWords(commands) {
+	return [...new Set(commands.map((command) => command.path[0]))].sort();
+}
+/** Parses the command line against the definitions. Throws a usage diagnostic. */
+function parseCommandLine(commands, argv) {
+	const bare = argv.filter((word) => word !== "--json");
+	if (bare.length === 1 && (bare[0] === "--version" || bare[0] === "-v")) return { kind: "version" };
+	const words = [];
+	const pathAt = [];
+	for (let index = 0; index < argv.length; index += 1) {
+		const word = argv[index];
+		if (word === "--json" || word === "--help" || word === "-h") continue;
+		if (word === "--home" || word === "--cwd" || word === "--timeout") {
+			index += 1;
+			continue;
+		}
+		if (/^--(home|cwd|timeout)=/.test(word)) continue;
+		if (word.startsWith("-")) break;
+		words.push(word);
+		pathAt.push(index);
+	}
+	const helpAsked = argv.includes("--help") || argv.includes("-h");
+	if (words.length === 0) {
+		if (helpAsked || argv.every((word) => word === "--json")) return { kind: "help" };
+		throw usage(`Name a command first; ${argv[0]} isn't one.`);
+	}
+	const found = findCommand(commands, words);
+	if (!found) {
+		const group = commands.filter((command) => command.path[0] === words[0]);
+		if (group.length > 0) {
+			if (helpAsked) return {
+				kind: "help",
+				group: words[0]
+			};
+			throw usage(`"mostra ${words[0]}" needs one of: ${group.map((command) => command.path.slice(1).join(" ")).join(", ")}.`);
+		}
+		throw new RpcError(createDiagnostic("MOSTRA_CLI_UNKNOWN_COMMAND", { message: `"${words[0]}" isn't a mostra command. The commands are: ${topWords(commands).join(", ")}.` }));
+	}
+	const { command } = found;
+	if (helpAsked) return {
+		kind: "help",
+		command
+	};
+	const used = new Set(pathAt.slice(0, found.used));
+	const rest = argv.filter((_, index) => !used.has(index));
+	const flagDefs = [...GLOBAL_FLAGS, ...command.flags ?? []];
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: [...rest],
+			allowPositionals: true,
+			strict: true,
+			options: Object.fromEntries(flagDefs.map((flag) => [flag.name, { type: flag.kind === "boolean" ? "boolean" : "string" }]))
+		});
+	} catch (error) {
+		throw usage(`${error.message.split(". To specify")[0]}. Run "mostra ${commandName(command)} --help".`);
+	}
+	const flags = {};
+	for (const flag of command.flags ?? []) {
+		const raw = parsed.values[flag.name];
+		if (raw === void 0) continue;
+		if (flag.kind === "boolean") {
+			flags[flag.name] = raw === true;
+			continue;
+		}
+		const text = String(raw);
+		if (flag.choices && !flag.choices.includes(text)) throw usage(`--${flag.name} takes one of ${flag.choices.join(", ")}; "${text}" isn't one.`);
+		if (flag.kind === "number") {
+			const number = Number(text);
+			if (!Number.isInteger(number) || number < 0) throw usage(`--${flag.name} takes a whole number; "${text}" isn't one.`);
+			flags[flag.name] = number;
+		} else if (flag.kind === "duration") {
+			durationMs(text);
+			flags[flag.name] = text;
+		} else if (flag.kind === "list") flags[flag.name] = text.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+		else flags[flag.name] = text;
+	}
+	const positionals = [...parsed.positionals];
+	const args = {};
+	for (const arg of command.args ?? []) {
+		if (arg.variadic) {
+			if (positionals.length === 0 && !arg.optional) throw usage(`"mostra ${commandName(command)}" needs <${arg.name}…>.`);
+			args[arg.name] = positionals.splice(0);
+			continue;
+		}
+		const value = positionals.shift();
+		if (value === void 0 && !arg.optional) throw usage(`"mostra ${commandName(command)}" needs <${arg.name}>.`);
+		args[arg.name] = value;
+	}
+	if (positionals.length > 0) throw usage(`"mostra ${commandName(command)}" takes no argument "${positionals[0]}". Run "mostra ${commandName(command)} --help".`);
+	if (typeof parsed.values["timeout"] === "string") durationMs(parsed.values["timeout"]);
+	return {
+		kind: "run",
+		command,
+		args,
+		flags
+	};
+}
+//#endregion
+//#region src/telemetry/zones.generated.ts
+/** The time zones where Mostra asks before sending telemetry (D140 item 10), matched as given. */
+const ASK_FIRST_ZONES = [
+	"Africa/Ceuta",
+	"America/Cayenne",
+	"America/Guadeloupe",
+	"America/Marigot",
+	"America/Martinique",
+	"Arctic/Longyearbyen",
+	"Asia/Famagusta",
+	"Asia/Nicosia",
+	"Atlantic/Azores",
+	"Atlantic/Canary",
+	"Atlantic/Faeroe",
+	"Atlantic/Faroe",
+	"Atlantic/Jan_Mayen",
+	"Atlantic/Madeira",
+	"Atlantic/Reykjavik",
+	"CET",
+	"EET",
+	"Eire",
+	"Etc/GMT",
+	"Etc/GMT+0",
+	"Etc/GMT+1",
+	"Etc/GMT+10",
+	"Etc/GMT+11",
+	"Etc/GMT+12",
+	"Etc/GMT+2",
+	"Etc/GMT+3",
+	"Etc/GMT+4",
+	"Etc/GMT+5",
+	"Etc/GMT+6",
+	"Etc/GMT+7",
+	"Etc/GMT+8",
+	"Etc/GMT+9",
+	"Etc/GMT-0",
+	"Etc/GMT-1",
+	"Etc/GMT-10",
+	"Etc/GMT-11",
+	"Etc/GMT-12",
+	"Etc/GMT-13",
+	"Etc/GMT-14",
+	"Etc/GMT-2",
+	"Etc/GMT-3",
+	"Etc/GMT-4",
+	"Etc/GMT-5",
+	"Etc/GMT-6",
+	"Etc/GMT-7",
+	"Etc/GMT-8",
+	"Etc/GMT-9",
+	"Etc/GMT0",
+	"Etc/Greenwich",
+	"Etc/UCT",
+	"Etc/UTC",
+	"Etc/Universal",
+	"Etc/Zulu",
+	"Europe/Amsterdam",
+	"Europe/Andorra",
+	"Europe/Athens",
+	"Europe/Belfast",
+	"Europe/Berlin",
+	"Europe/Bratislava",
+	"Europe/Brussels",
+	"Europe/Bucharest",
+	"Europe/Budapest",
+	"Europe/Busingen",
+	"Europe/Copenhagen",
+	"Europe/Dublin",
+	"Europe/Gibraltar",
+	"Europe/Guernsey",
+	"Europe/Helsinki",
+	"Europe/Isle_of_Man",
+	"Europe/Jersey",
+	"Europe/Lisbon",
+	"Europe/Ljubljana",
+	"Europe/London",
+	"Europe/Luxembourg",
+	"Europe/Madrid",
+	"Europe/Malta",
+	"Europe/Mariehamn",
+	"Europe/Monaco",
+	"Europe/Nicosia",
+	"Europe/Oslo",
+	"Europe/Paris",
+	"Europe/Prague",
+	"Europe/Riga",
+	"Europe/Rome",
+	"Europe/San_Marino",
+	"Europe/Sofia",
+	"Europe/Stockholm",
+	"Europe/Tallinn",
+	"Europe/Vaduz",
+	"Europe/Vatican",
+	"Europe/Vienna",
+	"Europe/Vilnius",
+	"Europe/Warsaw",
+	"Europe/Zagreb",
+	"Europe/Zurich",
+	"Factory",
+	"GB",
+	"GB-Eire",
+	"GMT",
+	"GMT+0",
+	"GMT-0",
+	"GMT0",
+	"Greenwich",
+	"Iceland",
+	"Indian/Mayotte",
+	"Indian/Reunion",
+	"MET",
+	"Poland",
+	"Portugal",
+	"UCT",
+	"UTC",
+	"Universal",
+	"WET",
+	"Zulu"
+];
+/** Every zone name tzdata 2026e knows; anything else is an unknown zone. */
+const KNOWN_ZONES = [
+	"Africa/Abidjan",
+	"Africa/Accra",
+	"Africa/Addis_Ababa",
+	"Africa/Algiers",
+	"Africa/Asmara",
+	"Africa/Asmera",
+	"Africa/Bamako",
+	"Africa/Bangui",
+	"Africa/Banjul",
+	"Africa/Bissau",
+	"Africa/Blantyre",
+	"Africa/Brazzaville",
+	"Africa/Bujumbura",
+	"Africa/Cairo",
+	"Africa/Casablanca",
+	"Africa/Ceuta",
+	"Africa/Conakry",
+	"Africa/Dakar",
+	"Africa/Dar_es_Salaam",
+	"Africa/Djibouti",
+	"Africa/Douala",
+	"Africa/El_Aaiun",
+	"Africa/Freetown",
+	"Africa/Gaborone",
+	"Africa/Harare",
+	"Africa/Johannesburg",
+	"Africa/Juba",
+	"Africa/Kampala",
+	"Africa/Khartoum",
+	"Africa/Kigali",
+	"Africa/Kinshasa",
+	"Africa/Lagos",
+	"Africa/Libreville",
+	"Africa/Lome",
+	"Africa/Luanda",
+	"Africa/Lubumbashi",
+	"Africa/Lusaka",
+	"Africa/Malabo",
+	"Africa/Maputo",
+	"Africa/Maseru",
+	"Africa/Mbabane",
+	"Africa/Mogadishu",
+	"Africa/Monrovia",
+	"Africa/Nairobi",
+	"Africa/Ndjamena",
+	"Africa/Niamey",
+	"Africa/Nouakchott",
+	"Africa/Ouagadougou",
+	"Africa/Porto-Novo",
+	"Africa/Sao_Tome",
+	"Africa/Timbuktu",
+	"Africa/Tripoli",
+	"Africa/Tunis",
+	"Africa/Windhoek",
+	"America/Adak",
+	"America/Anchorage",
+	"America/Anguilla",
+	"America/Antigua",
+	"America/Araguaina",
+	"America/Argentina/Buenos_Aires",
+	"America/Argentina/Catamarca",
+	"America/Argentina/ComodRivadavia",
+	"America/Argentina/Cordoba",
+	"America/Argentina/Jujuy",
+	"America/Argentina/La_Rioja",
+	"America/Argentina/Mendoza",
+	"America/Argentina/Rio_Gallegos",
+	"America/Argentina/Salta",
+	"America/Argentina/San_Juan",
+	"America/Argentina/San_Luis",
+	"America/Argentina/Tucuman",
+	"America/Argentina/Ushuaia",
+	"America/Aruba",
+	"America/Asuncion",
+	"America/Atikokan",
+	"America/Atka",
+	"America/Bahia",
+	"America/Bahia_Banderas",
+	"America/Barbados",
+	"America/Belem",
+	"America/Belize",
+	"America/Blanc-Sablon",
+	"America/Boa_Vista",
+	"America/Bogota",
+	"America/Boise",
+	"America/Buenos_Aires",
+	"America/Cambridge_Bay",
+	"America/Campo_Grande",
+	"America/Cancun",
+	"America/Caracas",
+	"America/Catamarca",
+	"America/Cayenne",
+	"America/Cayman",
+	"America/Chicago",
+	"America/Chihuahua",
+	"America/Ciudad_Juarez",
+	"America/Coral_Harbour",
+	"America/Cordoba",
+	"America/Costa_Rica",
+	"America/Coyhaique",
+	"America/Creston",
+	"America/Cuiaba",
+	"America/Curacao",
+	"America/Danmarkshavn",
+	"America/Dawson",
+	"America/Dawson_Creek",
+	"America/Denver",
+	"America/Detroit",
+	"America/Dominica",
+	"America/Edmonton",
+	"America/Eirunepe",
+	"America/El_Salvador",
+	"America/Ensenada",
+	"America/Fort_Nelson",
+	"America/Fort_Wayne",
+	"America/Fortaleza",
+	"America/Glace_Bay",
+	"America/Godthab",
+	"America/Goose_Bay",
+	"America/Grand_Turk",
+	"America/Grenada",
+	"America/Guadeloupe",
+	"America/Guatemala",
+	"America/Guayaquil",
+	"America/Guyana",
+	"America/Halifax",
+	"America/Havana",
+	"America/Hermosillo",
+	"America/Indiana/Indianapolis",
+	"America/Indiana/Knox",
+	"America/Indiana/Marengo",
+	"America/Indiana/Petersburg",
+	"America/Indiana/Tell_City",
+	"America/Indiana/Vevay",
+	"America/Indiana/Vincennes",
+	"America/Indiana/Winamac",
+	"America/Indianapolis",
+	"America/Inuvik",
+	"America/Iqaluit",
+	"America/Jamaica",
+	"America/Jujuy",
+	"America/Juneau",
+	"America/Kentucky/Louisville",
+	"America/Kentucky/Monticello",
+	"America/Knox_IN",
+	"America/Kralendijk",
+	"America/La_Paz",
+	"America/Lima",
+	"America/Los_Angeles",
+	"America/Louisville",
+	"America/Lower_Princes",
+	"America/Maceio",
+	"America/Managua",
+	"America/Manaus",
+	"America/Marigot",
+	"America/Martinique",
+	"America/Matamoros",
+	"America/Mazatlan",
+	"America/Mendoza",
+	"America/Menominee",
+	"America/Merida",
+	"America/Metlakatla",
+	"America/Mexico_City",
+	"America/Miquelon",
+	"America/Moncton",
+	"America/Monterrey",
+	"America/Montevideo",
+	"America/Montreal",
+	"America/Montserrat",
+	"America/Nassau",
+	"America/New_York",
+	"America/Nipigon",
+	"America/Nome",
+	"America/Noronha",
+	"America/North_Dakota/Beulah",
+	"America/North_Dakota/Center",
+	"America/North_Dakota/New_Salem",
+	"America/Nuuk",
+	"America/Ojinaga",
+	"America/Panama",
+	"America/Pangnirtung",
+	"America/Paramaribo",
+	"America/Phoenix",
+	"America/Port-au-Prince",
+	"America/Port_of_Spain",
+	"America/Porto_Acre",
+	"America/Porto_Velho",
+	"America/Puerto_Rico",
+	"America/Punta_Arenas",
+	"America/Rainy_River",
+	"America/Rankin_Inlet",
+	"America/Recife",
+	"America/Regina",
+	"America/Resolute",
+	"America/Rio_Branco",
+	"America/Rosario",
+	"America/Santa_Isabel",
+	"America/Santarem",
+	"America/Santiago",
+	"America/Santo_Domingo",
+	"America/Sao_Paulo",
+	"America/Scoresbysund",
+	"America/Shiprock",
+	"America/Sitka",
+	"America/St_Barthelemy",
+	"America/St_Johns",
+	"America/St_Kitts",
+	"America/St_Lucia",
+	"America/St_Thomas",
+	"America/St_Vincent",
+	"America/Swift_Current",
+	"America/Tegucigalpa",
+	"America/Thule",
+	"America/Thunder_Bay",
+	"America/Tijuana",
+	"America/Toronto",
+	"America/Tortola",
+	"America/Vancouver",
+	"America/Virgin",
+	"America/Whitehorse",
+	"America/Winnipeg",
+	"America/Yakutat",
+	"America/Yellowknife",
+	"Antarctica/Casey",
+	"Antarctica/Davis",
+	"Antarctica/DumontDUrville",
+	"Antarctica/Macquarie",
+	"Antarctica/Mawson",
+	"Antarctica/McMurdo",
+	"Antarctica/Palmer",
+	"Antarctica/Rothera",
+	"Antarctica/South_Pole",
+	"Antarctica/Syowa",
+	"Antarctica/Troll",
+	"Antarctica/Vostok",
+	"Arctic/Longyearbyen",
+	"Asia/Aden",
+	"Asia/Almaty",
+	"Asia/Amman",
+	"Asia/Anadyr",
+	"Asia/Aqtau",
+	"Asia/Aqtobe",
+	"Asia/Ashgabat",
+	"Asia/Ashkhabad",
+	"Asia/Atyrau",
+	"Asia/Baghdad",
+	"Asia/Bahrain",
+	"Asia/Baku",
+	"Asia/Bangkok",
+	"Asia/Barnaul",
+	"Asia/Beirut",
+	"Asia/Bishkek",
+	"Asia/Brunei",
+	"Asia/Calcutta",
+	"Asia/Chita",
+	"Asia/Choibalsan",
+	"Asia/Chongqing",
+	"Asia/Chungking",
+	"Asia/Colombo",
+	"Asia/Dacca",
+	"Asia/Damascus",
+	"Asia/Dhaka",
+	"Asia/Dili",
+	"Asia/Dubai",
+	"Asia/Dushanbe",
+	"Asia/Famagusta",
+	"Asia/Gaza",
+	"Asia/Harbin",
+	"Asia/Hebron",
+	"Asia/Ho_Chi_Minh",
+	"Asia/Hong_Kong",
+	"Asia/Hovd",
+	"Asia/Irkutsk",
+	"Asia/Istanbul",
+	"Asia/Jakarta",
+	"Asia/Jayapura",
+	"Asia/Jerusalem",
+	"Asia/Kabul",
+	"Asia/Kamchatka",
+	"Asia/Karachi",
+	"Asia/Kashgar",
+	"Asia/Kathmandu",
+	"Asia/Katmandu",
+	"Asia/Khandyga",
+	"Asia/Kolkata",
+	"Asia/Krasnoyarsk",
+	"Asia/Kuala_Lumpur",
+	"Asia/Kuching",
+	"Asia/Kuwait",
+	"Asia/Macao",
+	"Asia/Macau",
+	"Asia/Magadan",
+	"Asia/Makassar",
+	"Asia/Manila",
+	"Asia/Muscat",
+	"Asia/Nicosia",
+	"Asia/Novokuznetsk",
+	"Asia/Novosibirsk",
+	"Asia/Omsk",
+	"Asia/Oral",
+	"Asia/Phnom_Penh",
+	"Asia/Pontianak",
+	"Asia/Pyongyang",
+	"Asia/Qatar",
+	"Asia/Qostanay",
+	"Asia/Qyzylorda",
+	"Asia/Rangoon",
+	"Asia/Riyadh",
+	"Asia/Saigon",
+	"Asia/Sakhalin",
+	"Asia/Samarkand",
+	"Asia/Seoul",
+	"Asia/Shanghai",
+	"Asia/Singapore",
+	"Asia/Srednekolymsk",
+	"Asia/Taipei",
+	"Asia/Tashkent",
+	"Asia/Tbilisi",
+	"Asia/Tehran",
+	"Asia/Tel_Aviv",
+	"Asia/Thimbu",
+	"Asia/Thimphu",
+	"Asia/Tokyo",
+	"Asia/Tomsk",
+	"Asia/Ujung_Pandang",
+	"Asia/Ulaanbaatar",
+	"Asia/Ulan_Bator",
+	"Asia/Urumqi",
+	"Asia/Ust-Nera",
+	"Asia/Vientiane",
+	"Asia/Vladivostok",
+	"Asia/Yakutsk",
+	"Asia/Yangon",
+	"Asia/Yekaterinburg",
+	"Asia/Yerevan",
+	"Atlantic/Azores",
+	"Atlantic/Bermuda",
+	"Atlantic/Canary",
+	"Atlantic/Cape_Verde",
+	"Atlantic/Faeroe",
+	"Atlantic/Faroe",
+	"Atlantic/Jan_Mayen",
+	"Atlantic/Madeira",
+	"Atlantic/Reykjavik",
+	"Atlantic/South_Georgia",
+	"Atlantic/St_Helena",
+	"Atlantic/Stanley",
+	"Australia/ACT",
+	"Australia/Adelaide",
+	"Australia/Brisbane",
+	"Australia/Broken_Hill",
+	"Australia/Canberra",
+	"Australia/Currie",
+	"Australia/Darwin",
+	"Australia/Eucla",
+	"Australia/Hobart",
+	"Australia/LHI",
+	"Australia/Lindeman",
+	"Australia/Lord_Howe",
+	"Australia/Melbourne",
+	"Australia/NSW",
+	"Australia/North",
+	"Australia/Perth",
+	"Australia/Queensland",
+	"Australia/South",
+	"Australia/Sydney",
+	"Australia/Tasmania",
+	"Australia/Victoria",
+	"Australia/West",
+	"Australia/Yancowinna",
+	"Brazil/Acre",
+	"Brazil/DeNoronha",
+	"Brazil/East",
+	"Brazil/West",
+	"CET",
+	"Canada/Atlantic",
+	"Canada/Central",
+	"Canada/Eastern",
+	"Canada/Mountain",
+	"Canada/Newfoundland",
+	"Canada/Pacific",
+	"Canada/Saskatchewan",
+	"Canada/Yukon",
+	"Chile/Continental",
+	"Chile/EasterIsland",
+	"Cuba",
+	"EET",
+	"EST",
+	"Egypt",
+	"Eire",
+	"Etc/GMT",
+	"Etc/GMT+0",
+	"Etc/GMT+1",
+	"Etc/GMT+10",
+	"Etc/GMT+11",
+	"Etc/GMT+12",
+	"Etc/GMT+2",
+	"Etc/GMT+3",
+	"Etc/GMT+4",
+	"Etc/GMT+5",
+	"Etc/GMT+6",
+	"Etc/GMT+7",
+	"Etc/GMT+8",
+	"Etc/GMT+9",
+	"Etc/GMT-0",
+	"Etc/GMT-1",
+	"Etc/GMT-10",
+	"Etc/GMT-11",
+	"Etc/GMT-12",
+	"Etc/GMT-13",
+	"Etc/GMT-14",
+	"Etc/GMT-2",
+	"Etc/GMT-3",
+	"Etc/GMT-4",
+	"Etc/GMT-5",
+	"Etc/GMT-6",
+	"Etc/GMT-7",
+	"Etc/GMT-8",
+	"Etc/GMT-9",
+	"Etc/GMT0",
+	"Etc/Greenwich",
+	"Etc/UCT",
+	"Etc/UTC",
+	"Etc/Universal",
+	"Etc/Zulu",
+	"Europe/Amsterdam",
+	"Europe/Andorra",
+	"Europe/Astrakhan",
+	"Europe/Athens",
+	"Europe/Belfast",
+	"Europe/Belgrade",
+	"Europe/Berlin",
+	"Europe/Bratislava",
+	"Europe/Brussels",
+	"Europe/Bucharest",
+	"Europe/Budapest",
+	"Europe/Busingen",
+	"Europe/Chisinau",
+	"Europe/Copenhagen",
+	"Europe/Dublin",
+	"Europe/Gibraltar",
+	"Europe/Guernsey",
+	"Europe/Helsinki",
+	"Europe/Isle_of_Man",
+	"Europe/Istanbul",
+	"Europe/Jersey",
+	"Europe/Kaliningrad",
+	"Europe/Kiev",
+	"Europe/Kirov",
+	"Europe/Kyiv",
+	"Europe/Lisbon",
+	"Europe/Ljubljana",
+	"Europe/London",
+	"Europe/Luxembourg",
+	"Europe/Madrid",
+	"Europe/Malta",
+	"Europe/Mariehamn",
+	"Europe/Minsk",
+	"Europe/Monaco",
+	"Europe/Moscow",
+	"Europe/Nicosia",
+	"Europe/Oslo",
+	"Europe/Paris",
+	"Europe/Podgorica",
+	"Europe/Prague",
+	"Europe/Riga",
+	"Europe/Rome",
+	"Europe/Samara",
+	"Europe/San_Marino",
+	"Europe/Sarajevo",
+	"Europe/Saratov",
+	"Europe/Simferopol",
+	"Europe/Skopje",
+	"Europe/Sofia",
+	"Europe/Stockholm",
+	"Europe/Tallinn",
+	"Europe/Tirane",
+	"Europe/Tiraspol",
+	"Europe/Ulyanovsk",
+	"Europe/Uzhgorod",
+	"Europe/Vaduz",
+	"Europe/Vatican",
+	"Europe/Vienna",
+	"Europe/Vilnius",
+	"Europe/Volgograd",
+	"Europe/Warsaw",
+	"Europe/Zagreb",
+	"Europe/Zaporozhye",
+	"Europe/Zurich",
+	"Factory",
+	"GB",
+	"GB-Eire",
+	"GMT",
+	"GMT+0",
+	"GMT-0",
+	"GMT0",
+	"Greenwich",
+	"HST",
+	"Hongkong",
+	"Iceland",
+	"Indian/Antananarivo",
+	"Indian/Chagos",
+	"Indian/Christmas",
+	"Indian/Cocos",
+	"Indian/Comoro",
+	"Indian/Kerguelen",
+	"Indian/Mahe",
+	"Indian/Maldives",
+	"Indian/Mauritius",
+	"Indian/Mayotte",
+	"Indian/Reunion",
+	"Iran",
+	"Israel",
+	"Jamaica",
+	"Japan",
+	"Kwajalein",
+	"Libya",
+	"MET",
+	"MST",
+	"Mexico/BajaNorte",
+	"Mexico/BajaSur",
+	"Mexico/General",
+	"NZ",
+	"NZ-CHAT",
+	"Navajo",
+	"PRC",
+	"Pacific/Apia",
+	"Pacific/Auckland",
+	"Pacific/Bougainville",
+	"Pacific/Chatham",
+	"Pacific/Chuuk",
+	"Pacific/Easter",
+	"Pacific/Efate",
+	"Pacific/Enderbury",
+	"Pacific/Fakaofo",
+	"Pacific/Fiji",
+	"Pacific/Funafuti",
+	"Pacific/Galapagos",
+	"Pacific/Gambier",
+	"Pacific/Guadalcanal",
+	"Pacific/Guam",
+	"Pacific/Honolulu",
+	"Pacific/Johnston",
+	"Pacific/Kanton",
+	"Pacific/Kiritimati",
+	"Pacific/Kosrae",
+	"Pacific/Kwajalein",
+	"Pacific/Majuro",
+	"Pacific/Marquesas",
+	"Pacific/Midway",
+	"Pacific/Nauru",
+	"Pacific/Niue",
+	"Pacific/Norfolk",
+	"Pacific/Noumea",
+	"Pacific/Pago_Pago",
+	"Pacific/Palau",
+	"Pacific/Pitcairn",
+	"Pacific/Pohnpei",
+	"Pacific/Ponape",
+	"Pacific/Port_Moresby",
+	"Pacific/Rarotonga",
+	"Pacific/Saipan",
+	"Pacific/Samoa",
+	"Pacific/Tahiti",
+	"Pacific/Tarawa",
+	"Pacific/Tongatapu",
+	"Pacific/Truk",
+	"Pacific/Wake",
+	"Pacific/Wallis",
+	"Pacific/Yap",
+	"Poland",
+	"Portugal",
+	"ROC",
+	"ROK",
+	"Singapore",
+	"Turkey",
+	"UCT",
+	"US/Alaska",
+	"US/Aleutian",
+	"US/Arizona",
+	"US/Central",
+	"US/East-Indiana",
+	"US/Eastern",
+	"US/Hawaii",
+	"US/Indiana-Starke",
+	"US/Michigan",
+	"US/Mountain",
+	"US/Pacific",
+	"US/Samoa",
+	"UTC",
+	"Universal",
+	"W-SU",
+	"WET",
+	"Zulu"
+];
+//#endregion
+//#region src/telemetry/timezone.ts
+/**
+* Whether this machine's time zone asks first (D140 items 2 and 10). The zone is read here, on
+* this machine, and never sent. Every candidate name counts, as given: `TZ` (a leading `:`
+* removed), the target of `/etc/localtime`, and `Intl`'s zone. A machine asks first when any of
+* them is an ask-first zone, or none is a zone tzdata knows (missing, empty, `Etc/Unknown`, a
+* POSIX rule, a typo). Names are never canonicalized: tzdata links `Europe/Zagreb` to
+* `Europe/Belgrade` and `Indian/Reunion` to `Asia/Dubai`, and ICU builds differ in what they
+* resolve.
+*/
+const ASK_FIRST = new Set(ASK_FIRST_ZONES);
+const KNOWN = new Set(KNOWN_ZONES);
+/** The target of `/etc/localtime` after `zoneinfo/`, when it is a symbolic link. */
+function localtimeLink() {
+	try {
+		const target = readlinkSync("/etc/localtime");
+		const at = target.lastIndexOf("zoneinfo/");
+		return at === -1 ? void 0 : target.slice(at + 9);
+	} catch {
+		return;
+	}
+}
+function intlZone() {
+	try {
+		const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+		return typeof zone === "string" ? zone : void 0;
+	} catch {
+		return;
+	}
+}
+/** The candidate zone names, as given (empty and missing ones dropped). */
+function zoneCandidates(sources) {
+	const tz = sources.env["TZ"];
+	const fromTz = tz === void 0 ? void 0 : tz.startsWith(":") ? tz.slice(1) : tz;
+	const testLocaltime = sources.env["MOSTRA_TEST_LOCALTIME"];
+	return [
+		fromTz,
+		(sources.localtime ?? (testLocaltime !== void 0 ? () => testLocaltime === "" ? void 0 : testLocaltime : localtimeLink))(),
+		(sources.intl ?? intlZone)()
+	].filter((name) => typeof name === "string" && name.length > 0);
+}
+/** Whether telemetry asks first on this machine. */
+function asksFirst(sources) {
+	const candidates = zoneCandidates(sources);
+	if (candidates.some((name) => ASK_FIRST.has(name))) return true;
+	const tz = sources.env["TZ"];
+	if (tz !== void 0 && !KNOWN.has(tz.startsWith(":") ? tz.slice(1) : tz)) return true;
+	return !candidates.some((name) => KNOWN.has(name) && name !== "Etc/Unknown");
+}
+//#endregion
+//#region src/telemetry/words.ts
+/**
+* Telemetry's words to people (D140 item 11): the notice, the question, its answers and the
+* `status` lines, exactly as Mirza approved them (M28). `<docs>` is `DEFAULT_DOCS_BASE` (D37).
+*/
+const DOCS = `${DEFAULT_DOCS_BASE}/telemetry`;
+/** The notice where telemetry is on by default: stderr, once, before the first event. */
+const NOTICE_DEFAULT = `Mostra sends anonymous usage data to improve the CLI: the command, its
+outcome, the version, the platform, which agent ran it, and a random
+install ID. Never content, paths, tokens or personal data.
+Details: ${DOCS}
+Turn it off: mostra telemetry off, or set DO_NOT_TRACK=1.
+`;
+/** The question in the ask-first zones, when it may be asked. */
+const QUESTION = `Mostra can send anonymous usage data to improve the CLI: the command,
+its outcome, the version, the platform, which agent ran it, and a random
+install ID. Never content, paths, tokens or personal data.
+Details: ${DOCS}
+Send anonymous usage data? [y/N] `;
+/** The answers to the question. */
+const ANSWER = {
+	yes: "Telemetry is on. Turn it off any time: mostra telemetry off\n",
+	no: "Telemetry stays off. Turn it on any time: mostra telemetry on\n",
+	timeout: "No answer, so telemetry stays off. Turn it on any time: mostra telemetry on\n"
+};
+/** The notice in the ask-first zones when the question can't be asked: stderr, once. */
+const NOTICE_ASK_FIRST = `Mostra can send anonymous usage data to improve the CLI: the command,
+its outcome, the version, the platform, which agent ran it, and a random
+install ID. Never content, paths, tokens or personal data.
+Details: ${DOCS}
+Nothing is sent unless you run: mostra telemetry on
+An agent should ask its user before turning it on.
+`;
+/** `mostra telemetry on` and `off`. */
+const TURNED = {
+	on: "Telemetry is on. Turn it off any time: mostra telemetry off",
+	off: "Telemetry is off. Your install ID and any unsent events were deleted."
+};
+/** The first line of `mostra telemetry status`. */
+function statusLine(input) {
+	if (input.enabled) {
+		if (input.reason === "setting") return "Telemetry is on: you turned it on.";
+		if (input.reason === "variable") return "Telemetry is on: MOSTRA_TELEMETRY=1 is set.";
+		return "Telemetry is on by default here. Turn it off: mostra telemetry off";
+	}
+	switch (input.reason) {
+		case "setting": return "Telemetry is off: you turned it off.";
+		case "do-not-track": return "Telemetry is off: DO_NOT_TRACK is set.";
+		case "variable": return "Telemetry is off: MOSTRA_TELEMETRY=0 is set.";
+		case "variable-invalid": return "Telemetry is off: MOSTRA_TELEMETRY has a value Mostra doesn't recognize, so nothing is sent.";
+		case "embedded": return "Telemetry is off: a host configures this home, and hosts never send telemetry.";
+		case "no-collector": return "Telemetry is off: this build has no telemetry endpoint.";
+		case "unreadable": return `Telemetry is off: ${input.settingsFile} can't be read, so nothing is sent.`;
+		case "default": return "Telemetry is off until you turn it on: mostra telemetry on";
+	}
+}
+//#endregion
+//#region src/telemetry/index.ts
+/**
+* The standalone CLI's telemetry (D119, D140): the only code in Mostra that can send an event, and
+* only `@mostra/cli` may import it (a dependency-cruiser rule). The runner calls {@link begin}
+* before a command's work and {@link end} after it; everything else here is the decision, the
+* words, the schema, the store and the flusher.
+*/
+/** The catalog's codes: only these leave the machine in `error` and `codes`. */
+const CATALOG = new Set(Object.keys(diagnosticCatalog));
+/** Variables CI services set; any of them means `ci: true`, and the question is never asked. */
+const CI_MARKERS = [
+	"CI",
+	"CONTINUOUS_INTEGRATION",
+	"GITHUB_ACTIONS",
+	"GITLAB_CI",
+	"BUILDKITE",
+	"CIRCLECI",
+	"TRAVIS",
+	"TF_BUILD",
+	"JENKINS_URL",
+	"TEAMCITY_VERSION",
+	"BITBUCKET_BUILD_NUMBER",
+	"CODEBUILD_BUILD_ID"
+];
+/** Whether this process runs in CI. */
+function inCi(env) {
+	return CI_MARKERS.some((name) => truthy(env[name]));
+}
+/** How long the question waits for an answer. */
+const QUESTION_TIMEOUT_MS = 6e4;
+/** The current decision, for `telemetry status` and the session. */
+function currentDecision(options) {
+	return decide({
+		env: options.env,
+		buildEndpoint: options.buildEndpoint ?? buildEndpoint(),
+		embedded: options.embedded,
+		settings: options.store.read(),
+		askFirst: asksFirst({
+			...options.zones,
+			env: options.env
+		})
+	});
+}
+/** Starts one command's telemetry. */
+function telemetrySession(options) {
+	const now = options.now ?? Date.now;
+	const store = new TelemetryStore(options.configDir);
+	const pending = [];
+	const decision = (embedded) => currentDecision({
+		env: options.env,
+		store,
+		embedded,
+		...options.buildEndpoint !== void 0 ? { buildEndpoint: options.buildEndpoint } : {},
+		...options.zones !== void 0 ? { zones: options.zones } : {}
+	});
+	const shown = () => {
+		const read = store.read();
+		return read.ok && read.settings.noticeShownAt !== void 0;
+	};
+	/** Records that the notice was shown; `false` when the store can't be written. */
+	const markShown = () => store.update((current) => ({
+		...current,
+		noticeShownAt: new Date(now()).toISOString()
+	})) !== void 0;
+	const harness = detectHarness(options.env);
+	const ci = inCi(options.env);
+	return {
+		async begin() {
+			if (options.quiet) return true;
+			const current = decision(options.hostHome);
+			if (current.reason === "no-collector" || current.reason === "embedded") return true;
+			if (current.enabled) {
+				if (!shown() && markShown()) options.stderr(NOTICE_DEFAULT);
+				return true;
+			}
+			if (current.reason !== "default" || !current.askFirst) return true;
+			if (!(options.tty.stdin && options.tty.stderr && !options.json && !ci && harness === "none" && !options.readsStdin)) {
+				const read = store.read();
+				if (read.ok && read.settings.askFirstNoticeShownAt === void 0) {
+					if (store.update((settings) => ({
+						...settings,
+						askFirstNoticeShownAt: new Date(now()).toISOString()
+					})) !== void 0) options.stderr(NOTICE_ASK_FIRST);
+				}
+				return true;
+			}
+			const answer = await options.ask(QUESTION, QUESTION_TIMEOUT_MS);
+			const yes = typeof answer === "string" && /^\s*y(es)?\s*$/i.test(answer);
+			const stored = store.update((settings) => ({
+				...settings,
+				choice: yes ? "on" : "off",
+				noticeShownAt: new Date(now()).toISOString()
+			}));
+			options.stderr(stored === void 0 ? `${statusLine({
+				enabled: false,
+				reason: "unreadable",
+				askFirst: true,
+				settingsFile: store.settingsFile
+			})}\n` : yes ? ANSWER.yes : answer === void 0 ? ANSWER.timeout : ANSWER.no);
+			return answer !== "interrupt";
+		},
+		record(event) {
+			pending.push({
+				event: event.event,
+				fields: event.fields
+			});
+		},
+		end(outcome) {
+			if (options.quiet) return;
+			const current = decision(options.hostHome || outcome.hostInstance);
+			if (!current.enabled || current.consent === void 0 || !shown()) return;
+			const id = store.installId();
+			if (!id) return;
+			const common = {
+				schema: 1,
+				at: minute(new Date(now())),
+				installId: id.id,
+				version: cliVersion(),
+				os: process.platform === "darwin" ? "darwin" : "linux",
+				arch: process.arch,
+				node: Number(process.versions.node.split(".")[0]),
+				harness,
+				ci,
+				consent: current.consent
+			};
+			const events = [];
+			if (id.created) events.push({
+				...common,
+				event: "cli.first_run"
+			});
+			for (const item of pending) {
+				const fields = item.event === "verify.result" ? {
+					status: item.fields["status"],
+					...catalogCodes(item.fields["codes"] ?? [], CATALOG)
+				} : item.fields;
+				events.push({
+					...common,
+					...fields,
+					event: item.event
+				});
+			}
+			events.push({
+				...common,
+				event: "cli.command",
+				command: options.command,
+				exit: outcome.exit,
+				duration: durationBucket(outcome.durationMs),
+				json: options.json,
+				...outcome.error !== void 0 && CATALOG.has(outcome.error) ? { error: outcome.error } : {}
+			});
+			const lines = [];
+			for (const event of events) {
+				const parsed = TelemetryEvent.safeParse(event);
+				if (parsed.success) lines.push(JSON.stringify(parsed.data));
+			}
+			if (truthy(options.env["MOSTRA_TELEMETRY_DEBUG"])) {
+				for (const line of lines) options.stderr(`mostra telemetry (debug, not sent): ${line}\n`);
+				return;
+			}
+			store.append(lines, now());
+			if (options.flush !== false) startFlusher(store, options.env, now());
+		}
+	};
+}
+/** `mostra telemetry status`: the decision, the install ID and the queue. */
+function telemetryStatus(options) {
+	const store = new TelemetryStore(options.configDir);
+	const decided = currentDecision({
+		env: options.env,
+		store,
+		embedded: options.embedded
+	});
+	const homeBlocks = options.homeConfigUnreadable !== void 0 && decided.reason !== "no-collector";
+	const decision = homeBlocks ? {
+		...decided,
+		enabled: false,
+		reason: "unreadable"
+	} : decided;
+	const unreadableFile = homeBlocks ? options.homeConfigUnreadable : decision.reason === "unreadable" ? store.settingsFile : void 0;
+	const read = store.read();
+	const settings = read.ok ? read.settings : {};
+	const queued = read.ok ? store.queued(options.now ?? Date.now()).length : 0;
+	const status = {
+		enabled: decision.enabled,
+		reason: decision.reason,
+		askFirst: decision.askFirst,
+		...settings.installId !== void 0 ? { installId: settings.installId } : {},
+		...decision.endpoint !== void 0 ? { endpoint: decision.endpoint } : {},
+		queued,
+		...settings.noticeShownAt !== void 0 ? { noticeShownAt: settings.noticeShownAt } : {},
+		settingsFile: store.settingsFile,
+		...unreadableFile !== void 0 ? { unreadableFile } : {}
+	};
+	return {
+		status,
+		text: [
+			statusLine({
+				...decision,
+				settingsFile: unreadableFile ?? store.settingsFile
+			}),
+			...status.installId !== void 0 ? [`Install ID: ${status.installId}`] : [],
+			`Queued events: ${queued}`,
+			`Settings: ${store.settingsFile}`
+		].join("\n")
+	};
+}
+//#endregion
+//#region src/commands/shared.ts
+/**
+* What commands share: naming artifacts and sources on the command line, and reading JSON values.
+*/
+const ARTIFACT_ID = /^art_[0-9A-HJKMNP-TV-Z]{26}$/;
+/** An artifact named by its ID (`art_…`) or by a path, relative ones from `--cwd`. */
+function artifactRef(value, cwd) {
+	return ARTIFACT_ID.test(value) ? { artifactId: value } : { path: resolve(cwd, value) };
+}
+/** A source named the same way: a path, or the ID of an artifact (the path it was published from). */
+function sourceRef(value, cwd) {
+	return ARTIFACT_ID.test(value) ? { artifactId: value } : { path: resolve(cwd, value) };
+}
+/** A string argument the parser guaranteed. */
+function arg(context, name) {
+	const value = context.args[name];
+	if (typeof value !== "string") throw usage(`<${name}> is missing.`);
+	return value;
+}
+/** An optional string flag. */
+function flag(context, name) {
+	const value = context.flags[name];
+	return typeof value === "string" ? value : void 0;
+}
+/** Parses a JSON value given on the command line, in a file or on stdin. */
+function parseJson(text, where) {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		throw usage(`${where} isn't JSON: ${error.message}`);
+	}
+}
+/** Reads a JSON value from `--value`, `--file` or `--stdin`, exactly one of them. */
+async function jsonInput(context, valueFlag = "value") {
+	if ([
+		valueFlag,
+		"file",
+		"stdin"
+	].filter((name) => context.flags[name] !== void 0 && context.flags[name] !== false).length !== 1) throw usage(`Give the value with exactly one of --${valueFlag}, --file or --stdin.`);
+	if (context.flags["stdin"] === true) return parseJson(await context.readStdin(), "stdin");
+	const file = flag(context, "file");
+	if (file !== void 0) {
+		let text;
+		try {
+			text = readFileSync(resolve(context.cwd, file), "utf8");
+		} catch (error) {
+			throw usage(`--file ${file} can't be read (${error.code ?? "error"}).`);
+		}
+		return parseJson(text, file);
+	}
+	return parseJson(flag(context, valueFlag) ?? "", `--${valueFlag}`);
+}
+/** Indented JSON, for human output of structured results. */
+function pretty(value) {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+//#endregion
+//#region src/commands/admin.ts
+/**
+* Administration: `secret`, `list`, `status`, `daemon`, `host`, `gc`, `doctor`, `docs` and
+* `telemetry`. Each is a client of the host protocol or the runtime binary, never of the home's
+* files, except `doctor`, which reads what it needs to explain why an instance can't start.
+*/
+const artifactFlag = {
+	name: "artifact",
+	kind: "string",
+	value: "<path|id>",
+	summary: "The artifact's own secret, instead of one the whole home shares."
+};
+/** `mostra secret set <name>`. */
+const secretSetCommand = defineCommand({
+	path: ["secret", "set"],
+	summary: "Store a secret that server code reads with secret(name); the value comes from stdin and is never shown.",
+	args: [{
+		name: "name",
+		summary: "Letters, digits, _, . and -, starting with a letter or _."
+	}],
+	flags: [artifactFlag],
+	output: {
+		type: "SecretEntry",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "secret set MAIL_TOKEN --artifact ./inbox < token.txt",
+	readsStdin: true,
+	async run(context) {
+		let value = await context.readStdin();
+		if (value.endsWith("\n")) value = value.slice(0, value.endsWith("\r\n") ? -2 : -1);
+		if (value === "") throw usage("The secret's value comes from stdin, and stdin was empty.");
+		const artifact = flag(context, "artifact");
+		const entry = await context.call(secretSetMethod, {
+			name: arg(context, "name"),
+			value,
+			...artifact !== void 0 ? { artifact: artifactRef(artifact, context.cwd) } : {}
+		});
+		return {
+			result: entry,
+			human: `Stored ${entry.name} (${entry.scope})\n`
+		};
+	}
+});
+/** `mostra secret list`. */
+const secretListCommand = defineCommand({
+	path: ["secret", "list"],
+	summary: "List the secrets' names and scopes; values are never shown.",
+	flags: [artifactFlag],
+	output: {
+		type: "SecretListResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "secret list --artifact ./inbox",
+	async run(context) {
+		const artifact = flag(context, "artifact");
+		const result = await context.call(secretListMethod, { ...artifact !== void 0 ? { artifact: artifactRef(artifact, context.cwd) } : {} });
+		return {
+			result,
+			human: result.secrets.map((entry) => `${entry.name}  ${entry.scope}  ${entry.updatedAt}\n`).join("")
+		};
+	}
+});
+/** `mostra secret rm <name>`. */
+const secretRmCommand = defineCommand({
+	path: ["secret", "rm"],
+	summary: "Delete a secret.",
+	args: [{
+		name: "name",
+		summary: "The secret's name."
+	}],
+	flags: [artifactFlag],
+	output: {
+		type: "SecretDeleteResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "secret rm MAIL_TOKEN --artifact ./inbox",
+	async run(context) {
+		const artifact = flag(context, "artifact");
+		const result = await context.call(secretDeleteMethod, {
+			name: arg(context, "name"),
+			...artifact !== void 0 ? { artifact: artifactRef(artifact, context.cwd) } : {}
+		});
+		return {
+			result,
+			human: result.deleted ? "Deleted\n" : "No such secret\n"
+		};
+	}
+});
+/** `mostra list`. */
+const listCommand = defineCommand({
+	path: ["list"],
+	summary: "List the home's published artifacts.",
+	flags: [{
+		name: "family",
+		kind: "string",
+		value: "<family>",
+		summary: "Only artifacts of this family."
+	}],
+	output: {
+		type: "ArtifactListResult",
+		topic: "cli"
+	},
+	exits: [],
+	example: "list --family dashboard",
+	async run(context) {
+		const family = flag(context, "family");
+		const result = await context.call(artifactListMethod, { ...family !== void 0 ? { filter: { family } } : {} });
+		return {
+			result,
+			human: result.artifacts.map((artifact) => `${artifact.id}  v${artifact.latestVersion?.number ?? "-"}  ${artifact.title}${artifact.source ? `  ${artifact.source}` : ""}\n`).join("")
+		};
+	}
+});
+/** `mostra status [artifact]`. */
+const statusCommand = defineCommand({
+	path: ["status"],
+	summary: "Show the instance (processes, workers, deliveries) or one artifact (versions, policy, links).",
+	args: [{
+		name: "artifact",
+		summary: "An artifact: its source path or its ID.",
+		optional: true
+	}],
+	output: {
+		type: "InstanceStatusResult or ArtifactDetail",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "status ./sidebar-review",
+	async run(context) {
+		const artifact = context.args["artifact"];
+		if (typeof artifact === "string") {
+			const detail = await context.call(artifactGetMethod, { artifact: artifactRef(artifact, context.cwd) });
+			const versions = detail.versions.map((version) => `  v${version.number}  ${version.id}  ${version.publishedAt}${version.collected ? "  collected" : ""}\n`).join("");
+			return {
+				result: detail,
+				human: `${detail.id}  ${detail.title}\n${versions}`
+			};
+		}
+		const status = await context.call(instanceStatusMethod, {});
+		return {
+			result: status,
+			human: pretty(status)
+		};
+	}
+});
+/** The runtime's `service` command, as JSON. */
+async function service(context, action) {
+	const { stdout } = await context.runtime([
+		"service",
+		action,
+		"--home",
+		context.home,
+		...context.flags["no-start"] === true ? ["--no-start"] : []
+	]);
+	const line = stdout.split("\n").find((text) => text.trim().startsWith("{"));
+	let parsed = {};
+	try {
+		parsed = JSON.parse(line ?? "{}");
+	} catch {}
+	if (parsed.status === "ok" && parsed.service) return parsed.service;
+	throw new RpcError(parsed.diagnostic ?? createDiagnostic("MOSTRA_ENV_SERVICE_FAILED", { message: `mostra-runtime service ${action} gave no answer.` }));
+}
+const noStart = {
+	name: "no-start",
+	kind: "boolean",
+	summary: "Write or remove the service's file without asking launchd or systemd to load it."
+};
+/** `mostra daemon start`. */
+const daemonStartCommand = defineCommand({
+	path: ["daemon", "start"],
+	summary: "Start the home's daemon, or find the one already running.",
+	output: {
+		type: "DaemonStatus",
+		topic: "cli"
+	},
+	exits: [],
+	example: "daemon start",
+	async run(context) {
+		const summary = (await context.connection())?.summary;
+		return {
+			result: {
+				running: true,
+				...summary
+			},
+			human: `${summary?.started ? "Started" : "Running"}: pid ${summary?.pid}, ${summary?.socket}\n`
+		};
+	}
+});
+/** Stops the running daemon; resolves once its socket closed. */
+async function stopDaemon(context) {
+	const connection = await context.connection(false);
+	if (!connection) return { stopped: false };
+	const { pid } = connection.summary;
+	await context.call(mostraShutdownMethod, {});
+	await Promise.race([connection.closed, new Promise((done) => setTimeout(done, 15e3))]);
+	const deadline = Date.now() + 15e3;
+	while (existsSync(join(context.home, "instance.json")) && Date.now() < deadline) await new Promise((done) => setTimeout(done, 50));
+	return {
+		stopped: true,
+		pid
+	};
+}
+/** `mostra daemon stop`. */
+const daemonStopCommand = defineCommand({
+	path: ["daemon", "stop"],
+	summary: "Stop the home's daemon; open pages reconnect when it starts again.",
+	output: {
+		type: "DaemonStop",
+		topic: "cli"
+	},
+	exits: [],
+	example: "daemon stop",
+	async run(context) {
+		const result = await stopDaemon(context);
+		return {
+			result,
+			human: result.stopped ? `Stopped pid ${result.pid}\n` : "No daemon was running\n"
+		};
+	}
+});
+/** `mostra daemon restart`. */
+const daemonRestartCommand = defineCommand({
+	path: ["daemon", "restart"],
+	summary: "Stop the home's daemon and start it again, for instance after an update.",
+	output: {
+		type: "DaemonStatus",
+		topic: "cli"
+	},
+	exits: [],
+	example: "daemon restart",
+	async run(context) {
+		await stopDaemon(context);
+		const summary = (await context.connection())?.summary;
+		return {
+			result: {
+				running: true,
+				...summary
+			},
+			human: `Running: pid ${summary?.pid}\n`
+		};
+	}
+});
+/** `mostra daemon status`. */
+const daemonStatusCommand = defineCommand({
+	path: ["daemon", "status"],
+	summary: "Whether the home's daemon runs, when it would exit for lack of work, and its login service.",
+	output: {
+		type: "DaemonStatus",
+		topic: "cli"
+	},
+	exits: [],
+	example: "daemon status",
+	async run(context) {
+		const loginService = await service(context, "status");
+		const connection = await context.connection(false);
+		if (!connection) return {
+			result: {
+				running: false,
+				service: loginService
+			},
+			human: `Not running. Login service: ${loginService.installed ? "installed" : "not installed"}\n`
+		};
+		const status = await context.call(instanceStatusMethod, {});
+		return {
+			result: {
+				running: true,
+				...connection.summary,
+				status,
+				service: loginService
+			},
+			human: `Running: pid ${connection.summary.pid}${status.idleExitAt ? `, exits when idle at ${status.idleExitAt}` : ""}. Login service: ${loginService.installed ? "installed" : "not installed"}\n`
+		};
+	}
+});
+/** `mostra daemon install`. */
+const daemonInstallCommand = defineCommand({
+	path: ["daemon", "install"],
+	summary: "Run the home's daemon as a login service (launchd or systemd), so links answer at any hour.",
+	flags: [noStart],
+	output: {
+		type: "ServiceStatus",
+		topic: "cli"
+	},
+	exits: [],
+	example: "daemon install",
+	async run(context) {
+		const result = await service(context, "install");
+		return {
+			result,
+			human: `Installed ${result.name} (${result.file})\n`
+		};
+	}
+});
+/** `mostra daemon uninstall`. */
+const daemonUninstallCommand = defineCommand({
+	path: ["daemon", "uninstall"],
+	summary: "Remove the home's login service; the daemon then exits after 30 idle minutes.",
+	flags: [noStart],
+	output: {
+		type: "ServiceStatus",
+		topic: "cli"
+	},
+	exits: [],
+	example: "daemon uninstall",
+	async run(context) {
+		const result = await service(context, "uninstall");
+		return {
+			result,
+			human: `Removed ${result.name}\n`
+		};
+	}
+});
+/** `mostra host`. */
+const hostCommand = defineCommand({
+	path: ["host"],
+	summary: "Speak the host protocol on stdin and stdout, for a host that spawns Mostra; it sends no telemetry.",
+	flags: [{
+		name: "bind",
+		kind: "string",
+		value: "<address>",
+		summary: "Serve viewers on this address instead of 127.0.0.1."
+	}, {
+		name: "url-host",
+		kind: "string",
+		value: "<name>",
+		summary: "The host name links use; a wildcard --bind needs it."
+	}],
+	output: {
+		type: "the host protocol (INTERFACES §6)",
+		topic: "cli"
+	},
+	exits: [],
+	example: "host --home ~/.my-host/mostra",
+	local: true,
+	quiet: true,
+	readsStdin: true,
+	async run(context) {
+		const runtime = await locateRuntime(context.env);
+		const bind = flag(context, "bind");
+		const urlHost = flag(context, "url-host");
+		return {
+			result: void 0,
+			exit: await new Promise((resolve) => {
+				const child = spawn(runtime.node, [
+					runtime.entry,
+					"host",
+					"--home",
+					context.home,
+					...bind !== void 0 ? ["--bind", bind] : [],
+					...urlHost !== void 0 ? ["--url-host", urlHost] : []
+				], {
+					stdio: "inherit",
+					env: context.env
+				});
+				child.on("exit", (exit) => resolve(exit ?? EXIT.environment));
+				child.on("error", () => resolve(EXIT.environment));
+				for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => child.kill(signal));
+			}),
+			raw: true
+		};
+	}
+});
+/** `mostra gc`. */
+const gcCommand = defineCommand({
+	path: ["gc"],
+	summary: "Remove what nothing references: unreferenced versions' files, unused packages and caches.",
+	flags: [
+		{
+			name: "dry-run",
+			kind: "boolean",
+			summary: "List what a run would remove, and remove nothing."
+		},
+		{
+			name: "compact-events",
+			kind: "boolean",
+			summary: "Also replace events before --before with one summary per artifact."
+		},
+		{
+			name: "before",
+			kind: "string",
+			value: "<cursor>",
+			summary: "The cursor --compact-events compacts before."
+		}
+	],
+	output: {
+		type: "GcRunResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "gc --dry-run",
+	async run(context) {
+		const compact = context.flags["compact-events"] === true;
+		const before = flag(context, "before");
+		if (compact !== (before !== void 0)) throw usage("--compact-events and --before go together.");
+		if (before !== void 0 && !/^[0-9]+$/.test(before)) throw usage(`--before takes an event cursor; "${before}" isn't one.`);
+		const result = await context.call(gcRunMethod, {
+			...context.flags["dry-run"] === true ? { dryRun: true } : {},
+			...before !== void 0 ? { compactEvents: { before } } : {}
+		});
+		for (const warning of result.warnings ?? []) context.warn(warning);
+		return {
+			result,
+			human: `${[
+				`${result.dryRun ? "Would remove" : "Removed"} ${result.versions.length} versions' files, ${result.snapshots.count} snapshots, ${result.lockLayouts.count} lock layouts, ${result.storePackages.count} store packages and ${result.caches.count} cache entries (${result.bytes} bytes).`,
+				...result.versions.map((version) => `  ${version.artifactId} v${version.number} ${version.versionId}`),
+				...result.compacted ? [`Compacted ${result.compacted.removed} events.`] : []
+			].join("\n")}\n`
+		};
+	}
+});
+/** `mostra doctor`. */
+const doctorCommand = defineCommand({
+	path: ["doctor"],
+	summary: "Check the platform, the runtime, the home, its daemon and ledger, and the login service.",
+	flags: [{
+		name: "deep",
+		kind: "boolean",
+		summary: "Also hash every version against its recorded output digest."
+	}],
+	output: {
+		type: "DoctorResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "doctor",
+	async run(context) {
+		const checks = [];
+		const node = Number(process.versions.node.split(".")[0]);
+		checks.push(process.platform === "darwin" || process.platform === "linux" ? {
+			name: "platform",
+			status: "ok",
+			detail: `${process.platform} ${process.arch}, Node ${process.versions.node}`
+		} : {
+			name: "platform",
+			status: "error",
+			diagnostic: createDiagnostic("MOSTRA_PLATFORM_UNSUPPORTED", { message: `Mostra runs on macOS and Linux; this is ${process.platform}.` })
+		});
+		if (node < 24) checks.push({
+			name: "node",
+			status: "error",
+			diagnostic: createDiagnostic("MOSTRA_ENV_RUNTIME_MISSING", { message: `Mostra needs Node 24 or later; this is ${process.versions.node}.` })
+		});
+		try {
+			const runtime = await locateRuntime(context.env);
+			checks.push({
+				name: "runtime",
+				status: "ok",
+				detail: runtime.entry
+			});
+		} catch (error) {
+			checks.push({
+				name: "runtime",
+				status: "error",
+				diagnostic: error.diagnostic
+			});
+		}
+		checks.push(await bundleCheck(context.env, context.flags["deep"] === true));
+		checks.push(homeCheck(context.home));
+		let connection;
+		try {
+			connection = await context.connection();
+			checks.push({
+				name: "daemon",
+				status: "ok",
+				detail: `pid ${connection?.summary.pid}, ${connection?.summary.socket}`
+			});
+		} catch (error) {
+			const diagnostic = error instanceof RpcError ? error.diagnostic : void 0;
+			checks.push({
+				name: "daemon",
+				status: "error",
+				...diagnostic ? { diagnostic } : { detail: String(error) },
+				...diagnostic?.code === "MOSTRA_HOME_LEDGER_UNREADABLE" ? { detail: backups(context.home) } : {}
+			});
+		}
+		if (connection) {
+			if (connection.summary.version !== cliVersion()) checks.push({
+				name: "versions",
+				status: "warning",
+				detail: `The CLI is ${cliVersion()} and the daemon ${connection.summary.version}; run "mostra daemon restart" after an update.`
+			});
+			const instance = await context.call(instanceCheckMethod, context.flags["deep"] === true ? { deep: true } : {});
+			checks.push(...instance.checks.map((check) => ({ ...check })));
+			checks.push(await alwaysOnCheck(context));
+		}
+		const telemetry = telemetryStatus({
+			env: context.env,
+			configDir: context.configDir,
+			embedded: readHomeMarks(context.home).hostConfigured !== void 0 || connection?.summary.mode === "host"
+		});
+		checks.push({
+			name: "telemetry",
+			status: "ok",
+			detail: telemetry.text.split("\n")[0]
+		});
+		const firstError = checks.find((check) => check.status === "error");
+		const human = checks.map((check) => {
+			const mark = check.status === "ok" ? "ok  " : check.status === "warning" ? "warn" : "FAIL";
+			const what = check.diagnostic ? `${check.diagnostic.code}: ${check.diagnostic.message}` : check.detail ?? "";
+			const hint = check.diagnostic?.hint ? `\n        ${check.diagnostic.hint}` : "";
+			return `${mark}  ${check.name}${what ? `: ${what}` : ""}${hint}`;
+		}).join("\n");
+		return {
+			result: { checks },
+			human: `${human}\n`,
+			...firstError ? { exit: firstError.diagnostic ? exitCodeFor(firstError.diagnostic.code) : EXIT.environment } : {}
+		};
+	}
+});
+/**
+* The runtime bundle this CLI runs from (RT-01): set up and matching its files. Outside a bundle
+* (a development checkout, `MOSTRA_RUNTIME_BIN`) there is nothing to check. `--deep` hashes every
+* file against the bundle's file list and the browser against its pin, as setup does.
+*/
+async function bundleCheck(env, deep) {
+	const root = env["MOSTRA_BUNDLE"] || enclosingBundle();
+	if (!root) return {
+		name: "bundle",
+		status: "ok",
+		detail: "No runtime bundle: a development runtime."
+	};
+	try {
+		const bundle = await readBundle(root);
+		const label = `Mostra ${bundle.info.version} for ${bundle.info.platform} at ${root}`;
+		if (!await readSetup(bundle)) return {
+			name: "bundle",
+			status: "error",
+			diagnostic: createDiagnostic("MOSTRA_ENV_BUNDLE_UNAVAILABLE", { message: `The runtime bundle at ${root} isn't set up; run its bin/mostra-setup.` })
+		};
+		if (!deep) return {
+			name: "bundle",
+			status: "ok",
+			detail: label
+		};
+		await checkFiles(bundle);
+		const browser = await checkBrowser(bundle);
+		if (browser.length > 0) return {
+			name: "bundle",
+			status: "error",
+			diagnostic: createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: `The verify browser of the bundle at ${root} differs from its pin: ${browser.join("; ")}.` })
+		};
+		return {
+			name: "bundle",
+			status: "ok",
+			detail: `${label}; every file matches its SHA-256`
+		};
+	} catch (error) {
+		return {
+			name: "bundle",
+			status: "error",
+			diagnostic: error instanceof RpcError ? error.diagnostic : createDiagnostic("MOSTRA_ENV_BUNDLE_INVALID", { message: error.message })
+		};
+	}
+}
+/** The home: absent (it is made on first use), a directory the user owns, or not. */
+function homeCheck(home) {
+	let info;
+	try {
+		info = statSync(home);
+	} catch {
+		return {
+			name: "home",
+			status: "ok",
+			detail: `${home} (not created yet)`
+		};
+	}
+	if (!info.isDirectory() || process.getuid && info.uid !== process.getuid()) return {
+		name: "home",
+		status: "error",
+		diagnostic: createDiagnostic("MOSTRA_HOME_NOT_OWNED", { message: `Mostra can't use ${home}: another user owns it or it isn't a directory.` })
+	};
+	return {
+		name: "home",
+		status: "ok",
+		detail: home
+	};
+}
+/** The ledger's backups beside it, for a ledger that can't be opened (FAILURE_MODEL §3). */
+function backups(home) {
+	try {
+		const found = readdirSync(join(home, "store")).filter((name) => name.startsWith("ledger.sqlite.bak-"));
+		return found.length > 0 ? `Backups: ${found.map((name) => join(home, "store", name)).join(", ")}` : "No ledger backups.";
+	} catch {
+		return "No ledger backups.";
+	}
+}
+/**
+* LL-05's doctor half (D96, D63): artifacts with submission policy `none` are meant to answer at
+* any hour, which needs the home's login service.
+*/
+async function alwaysOnCheck(context) {
+	const { artifacts } = await context.call(artifactListMethod, {});
+	const longLived = artifacts.filter((artifact) => artifact.policy?.policy === "none");
+	if (longLived.length === 0) return {
+		name: "always-on",
+		status: "ok",
+		detail: "No artifact needs an always-on daemon."
+	};
+	const loginService = await service(context, "status");
+	if (loginService.installed) return {
+		name: "always-on",
+		status: "ok",
+		detail: `Login service ${loginService.name} keeps the daemon running.`
+	};
+	return {
+		name: "always-on",
+		status: "warning",
+		diagnostic: createDiagnostic("MOSTRA_HOME_NOT_ALWAYS_ON", { message: `${longLived.length} ${longLived.length === 1 ? "artifact has" : "artifacts have"} submission policy none (${longLived.map((artifact) => artifact.title).slice(0, 3).join(", ")}), and no login service keeps this home's daemon running.` })
+	};
+}
+/** `mostra docs [topic]`. */
+const docsCommand = defineCommand({
+	path: ["docs"],
+	summary: "Print Mostra's reference: the CLI, telemetry, and every diagnostic code's page.",
+	args: [{
+		name: "topic",
+		summary: "A topic or a diagnostic code. Default: the index.",
+		optional: true
+	}],
+	output: {
+		type: "DocsPage",
+		topic: "cli"
+	},
+	exits: [],
+	example: "docs MOSTRA_DEP_MISSING",
+	local: true,
+	quiet: true,
+	async run(context) {
+		const topics = docsIndex();
+		const wanted = context.args["topic"];
+		if (typeof wanted !== "string") {
+			const markdown = indexMarkdown(topics);
+			return {
+				result: {
+					topic: "index",
+					markdown,
+					url: topics[0]?.url.replace(/\/[^/]+$/, "") ?? "",
+					topics: topics.map(({ topic, title, url }) => ({
+						topic,
+						title,
+						url
+					}))
+				},
+				human: markdown
+			};
+		}
+		const found = topics.find((topic) => topic.topic === wanted || topic.topic === wanted.toUpperCase());
+		if (!found) throw usage(`No topic "${wanted}". The nearest: ${nearestTopics(wanted, topics).join(", ")}. Run "mostra docs" for the index.`);
+		const markdown = readFileSync(found.file, "utf8");
+		return {
+			result: {
+				topic: found.topic,
+				markdown,
+				url: found.url
+			},
+			human: markdown
+		};
+	}
+});
+/** `mostra telemetry status`. */
+const telemetryStatusCommand = defineCommand({
+	path: ["telemetry", "status"],
+	summary: "Whether the CLI sends anonymous usage data, and why.",
+	output: {
+		type: "TelemetryStatus",
+		topic: "telemetry"
+	},
+	exits: [],
+	example: "telemetry status",
+	local: true,
+	quiet: true,
+	async run(context) {
+		const { status, text } = telemetryStatus({
+			env: context.env,
+			configDir: context.configDir,
+			...homeTelemetry(context.home)
+		});
+		return {
+			result: status,
+			human: `${text}\n`
+		};
+	}
+});
+/** How the home bears on telemetry: a host's home, or one whose `config.json` can't be read. */
+function homeTelemetry(home) {
+	const marks = readHomeMarks(home);
+	return {
+		embedded: embeddedHome(marks) && marks.unreadable !== true,
+		...marks.unreadable === true ? { homeConfigUnreadable: join(home, "config.json") } : {}
+	};
+}
+/** The choice couldn't be recorded: nothing changed (Opus review finding 6). */
+function unwritable(store) {
+	return new RpcError(createDiagnostic("MOSTRA_CLI_CONFIG_UNWRITABLE", { message: `${store.settingsFile} can't be written, so the choice wasn't recorded and nothing changed.` }));
+}
+/** `mostra telemetry on`. */
+const telemetryOnCommand = defineCommand({
+	path: ["telemetry", "on"],
+	summary: "Send anonymous usage data from this CLI; the notice says what it contains.",
+	output: {
+		type: "TelemetryStatus",
+		topic: "telemetry"
+	},
+	exits: [EXIT.environment],
+	example: "telemetry on",
+	local: true,
+	quiet: true,
+	async run(context) {
+		const store = new TelemetryStore(context.configDir);
+		const read = store.read();
+		if (!(read.ok && read.settings.noticeShownAt !== void 0)) context.stderr(NOTICE_DEFAULT);
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		if ((store.update((current) => ({
+			...current,
+			choice: "on",
+			noticeShownAt: current.noticeShownAt ?? now
+		})) ?? store.locked(() => store.reset({
+			choice: "on",
+			noticeShownAt: now
+		}))) === void 0) throw unwritable(store);
+		const { status } = telemetryStatus({
+			env: context.env,
+			configDir: context.configDir,
+			...homeTelemetry(context.home)
+		});
+		return {
+			result: status,
+			human: `${TURNED.on}\n`
+		};
+	}
+});
+/** `mostra telemetry off`. */
+const telemetryOffCommand = defineCommand({
+	path: ["telemetry", "off"],
+	summary: "Stop sending usage data, and delete the install ID and any unsent events.",
+	output: {
+		type: "TelemetryStatus",
+		topic: "telemetry"
+	},
+	exits: [EXIT.environment],
+	example: "telemetry off",
+	local: true,
+	quiet: true,
+	async run(context) {
+		const store = new TelemetryStore(context.configDir);
+		if (!(store.turnOff() || store.locked(() => store.reset({ choice: "off" })) !== void 0)) throw unwritable(store);
+		const { status } = telemetryStatus({
+			env: context.env,
+			configDir: context.configDir,
+			...homeTelemetry(context.home)
+		});
+		return {
+			result: status,
+			human: `${TURNED.off}\n`
+		};
+	}
+});
+//#endregion
+//#region src/commands/authoring.ts
+/**
+* Authoring: `new`, `verify`, `publish` and `add`, thin clients of `artifact/create`,
+* `artifact/verify`, `artifact/publish` and `deps/add` (INTERFACES §6).
+*/
+/** `mostra new <dir>`. */
+const newCommand = defineCommand({
+	path: ["new"],
+	summary: "Create an artifact in an empty directory, with a generated ID.",
+	args: [{
+		name: "dir",
+		summary: "The directory to create it in; it must be empty or not exist."
+	}],
+	flags: [
+		{
+			name: "title",
+			kind: "string",
+			value: "<text>",
+			summary: "The artifact's title. Default: the directory's name."
+		},
+		{
+			name: "template",
+			kind: "string",
+			value: "<family>",
+			summary: "Start from a template (templates arrive in a later release)."
+		},
+		{
+			name: "request-id",
+			kind: "string",
+			value: "<id>",
+			summary: "Make a retry return the first attempt's result."
+		}
+	],
+	output: {
+		type: "ArtifactCreateResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "new ./sidebar-review --title 'Sidebar review'",
+	async run(context) {
+		const title = flag(context, "title");
+		const template = flag(context, "template");
+		const requestId = flag(context, "request-id");
+		const result = await context.call(artifactCreateMethod, {
+			dir: resolve(context.cwd, arg(context, "dir")),
+			...title !== void 0 ? { title } : {},
+			...template !== void 0 ? { template } : {},
+			...requestId !== void 0 ? { requestId } : {}
+		});
+		return {
+			result,
+			human: `Created ${result.artifactId} in ${result.dir}\n${result.files.map((file) => `  ${file}\n`).join("")}`
+		};
+	}
+});
+/** The verdict for people: the status, each diagnostic, the screenshots worth looking at. */
+function verdictText(verdict) {
+	const lines = [`verify: ${verdict.status}`];
+	for (const diagnostic of verdict.diagnostics) {
+		const where = diagnostic.location && "file" in diagnostic.location ? ` ${diagnostic.location.file}:${diagnostic.location.line}:${diagnostic.location.column}` : "";
+		const count = diagnostic.count !== void 0 && diagnostic.count > 1 ? ` (×${diagnostic.count})` : "";
+		lines.push(`  ${diagnostic.severity} ${diagnostic.code}${where}${count}: ${diagnostic.message}`);
+		if (diagnostic.hint) lines.push(`    ${diagnostic.hint}`);
+	}
+	for (const shot of verdict.screenshots.filter((screenshot) => screenshot.returned)) lines.push(`  screenshot ${shot.viewport}: ${shot.path}`);
+	return `${lines.join("\n")}\n`;
+}
+/** `mostra verify <path>`. */
+const verifyCommand = defineCommand({
+	path: ["verify"],
+	summary: "Build, render and check an artifact's source; one verdict, nothing published.",
+	args: [{
+		name: "path",
+		summary: "The artifact's source: a file, a directory, or its ID."
+	}],
+	flags: [{
+		name: "screenshots",
+		kind: "string",
+		value: "<when>",
+		choices: [
+			"on-failure",
+			"always",
+			"never"
+		],
+		default: "on-failure",
+		summary: "Which screenshots the verdict marks as worth looking at."
+	}],
+	output: {
+		type: "VerifyVerdict",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "verify ./sidebar-review",
+	async run(context) {
+		const connection = await context.connection();
+		const progressToken = randomUUID();
+		connection?.onNotification(ARTIFACT_PROGRESS, (params) => {
+			const { progressToken: token, stage } = params ?? {};
+			if (token === progressToken && typeof stage === "string") context.log(`verify: ${stage}`);
+		});
+		const screenshots = flag(context, "screenshots");
+		const verdict = await context.call(artifactVerifyMethod, {
+			source: sourceRef(arg(context, "path"), context.cwd),
+			progressToken,
+			...screenshots !== void 0 ? { screenshots } : {}
+		});
+		context.record({
+			event: "verify.result",
+			fields: {
+				status: verdict.status,
+				codes: verdict.diagnostics.map((diagnostic) => diagnostic.code)
+			}
+		});
+		return {
+			result: verdict,
+			human: verdictText(verdict),
+			...verdict.status === "fail" ? { exit: EXIT.failure } : {}
+		};
+	}
+});
+const POLICIES = {
+	once: {
+		policy: "once",
+		scope: "per-artifact"
+	},
+	"once-per-viewer": {
+		policy: "once",
+		scope: "per-viewer"
+	},
+	epochs: { policy: "epochs" },
+	none: { policy: "none" }
+};
+/** `mostra publish <path>`. */
+const publishCommand = defineCommand({
+	path: ["publish"],
+	summary: "Publish an artifact's source as a new immutable version, gated by verify, and print its link.",
+	args: [{
+		name: "path",
+		summary: "The artifact's source: a file, a directory, or its ID."
+	}],
+	flags: [
+		{
+			name: "force",
+			kind: "boolean",
+			summary: "Publish despite verify's errors and record their codes; never what didn't build."
+		},
+		{
+			name: "policy",
+			kind: "string",
+			value: "<policy>",
+			choices: Object.keys(POLICIES),
+			summary: "The submission policy to use, instead of the manifest's."
+		},
+		{
+			name: "request-id",
+			kind: "string",
+			value: "<id>",
+			summary: "Make a retry return the first attempt's receipt."
+		}
+	],
+	output: {
+		type: "PublishReceipt",
+		topic: "cli"
+	},
+	exits: [EXIT.failure, EXIT.conflict],
+	example: "publish ./sidebar-review",
+	async run(context) {
+		const policyName = flag(context, "policy");
+		const requestId = flag(context, "request-id");
+		const force = context.flags["force"] === true;
+		const receipt = await context.call(artifactPublishMethod, {
+			source: sourceRef(arg(context, "path"), context.cwd),
+			...force ? { force: true } : {},
+			...policyName !== void 0 ? { policy: POLICIES[policyName] } : {},
+			...requestId !== void 0 ? { requestId } : {}
+		});
+		context.record({
+			event: "publish.done",
+			fields: {
+				reused: receipt.reused,
+				forced: force
+			}
+		});
+		const forced = receipt.forcedDiagnostics !== void 0 && receipt.forcedDiagnostics.length > 0 ? `Forced past: ${receipt.forcedDiagnostics.join(", ")}\n` : "";
+		return {
+			result: receipt,
+			human: `${receipt.reused ? "Already published" : "Published"} version ${receipt.version} (${receipt.versionId}) of ${receipt.artifactId}\n${forced}${receipt.url ?? ""}\n`
+		};
+	}
+});
+/** `mostra add <package…>`. */
+const addCommand = defineCommand({
+	path: ["add"],
+	summary: "Add npm packages to an artifact's lockfile at exact versions, installing them into the home's store.",
+	args: [{
+		name: "package",
+		summary: "npm specs: name, name@version, name@range or name@tag.",
+		variadic: true
+	}],
+	flags: [{
+		name: "artifact",
+		kind: "string",
+		value: "<path|id>",
+		summary: "The artifact. Default: the one in the current directory."
+	}, {
+		name: "request-id",
+		kind: "string",
+		value: "<id>",
+		summary: "Make a retry return the first attempt's result."
+	}],
+	output: {
+		type: "DepsAddResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "add recharts@3 --artifact ./dashboard",
+	async run(context) {
+		const packages = context.args["package"];
+		if (!Array.isArray(packages) || packages.length === 0) throw usage("\"mostra add\" needs <package…>.");
+		const requestId = flag(context, "request-id");
+		const result = await context.call(depsAddMethod, {
+			artifact: sourceRef(flag(context, "artifact") ?? ".", context.cwd),
+			packages,
+			...requestId !== void 0 ? { requestId } : {}
+		});
+		return {
+			result,
+			human: result.packages.map((added) => `${added.name}@${added.version}${added.warm ? " (warm set)" : ""}\n`).join("")
+		};
+	}
+});
+//#endregion
+//#region src/commands/dev.ts
+/**
+* `mostra dev` (VR-08, D140 item 12): a development preview of unpublished source with hot
+* reload, until Ctrl-C. It prints the preview's link and then what happens in the session (built,
+* reloaded, server restarted, submissions with their Results, diagnostics) as a stream: NDJSON
+* envelopes with `--json`, lines otherwise. Viewers never reach a preview; it isn't a version.
+*/
+/** One event's line without `--json`. */
+function line(event) {
+	const files = event.files && event.files.length > 0 ? `: ${event.files.join(", ")}` : "";
+	switch (event.kind) {
+		case "built": return `Updated${files}\n`;
+		case "reloaded": return `Reloaded${files}\n`;
+		case "server-restarted": return `Server code restarted${files}\n`;
+		case "submission": return `Submission recorded (not delivered):\n${JSON.stringify(event.results, null, 2)}\n`;
+		case "diagnostics": return `${(event.diagnostics ?? []).map((diagnostic) => `${diagnostic.code}: ${diagnostic.message}`).join("\n")}\n`;
+	}
+}
+const devCommand = defineCommand({
+	path: ["dev"],
+	summary: "Preview an artifact's unpublished source with hot reload, until Ctrl-C; viewers never see it.",
+	args: [{
+		name: "path",
+		summary: "The artifact's source: a file, a directory, or its ID."
+	}],
+	flags: [{
+		name: "port",
+		kind: "number",
+		value: "<port>",
+		summary: "The preview's port on 127.0.0.1; default one the system picks."
+	}],
+	output: {
+		type: "DevStartResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure, EXIT.environment],
+	example: "dev ./sidebar-review",
+	streams: true,
+	async run(context) {
+		const connection = await context.connection();
+		let sessionId;
+		const early = [];
+		const show = (event) => {
+			if (event.kind === "diagnostics") for (const diagnostic of event.diagnostics ?? []) context.warn(diagnostic);
+			context.emit(event, line(event));
+		};
+		connection?.onNotification(DEV_NOTIFY, (params) => {
+			const event = params;
+			if (sessionId === void 0) early.push(event);
+			else if (event.sessionId === sessionId) show(event);
+		});
+		const portFlag = context.flags["port"];
+		const started = await context.call(devStartMethod, {
+			source: sourceRef(arg(context, "path"), context.cwd),
+			...typeof portFlag === "number" ? { port: portFlag } : {}
+		});
+		sessionId = started.sessionId;
+		context.emit({
+			kind: "started",
+			...started
+		}, `Development preview, not published: ${started.url}\nPress Ctrl-C to stop.\n`);
+		for (const event of early.splice(0)) if (event.sessionId === sessionId) show(event);
+		let stop = () => {};
+		const ended = await new Promise((done) => {
+			stop = () => done("signal");
+			process.once("SIGINT", stop);
+			process.once("SIGTERM", stop);
+			connection?.closed.then(() => done("closed"));
+		});
+		process.off("SIGINT", stop);
+		process.off("SIGTERM", stop);
+		if (ended === "closed") throw new RpcError(createDiagnostic("MOSTRA_HOST_CONNECTION_CLOSED", {
+			message: "The instance ended the development preview (it stopped or restarted).",
+			hint: "Run mostra dev again."
+		}));
+		await context.call(devStopMethod, { sessionId }).catch(() => void 0);
+		return {
+			result: {
+				sessionId,
+				stopped: "signal"
+			},
+			human: "Stopped.\n"
+		};
+	}
+});
+//#endregion
+//#region src/commands/interaction.ts
+/**
+* Interaction: `wait`, `results`, `push` and `state get|set|patch`, thin clients of `wait`,
+* `results/get`, `live/push` and `state/*` (INTERFACES §6, D101). `wait` ends with exit 5 when it
+* times out (`still_waiting`), and a write that meets a conflict with exit 6.
+*/
+/** The longest one `wait` request may ask for (INTERFACES §6: 2^31 − 1 ms). */
+const MAX_WAIT_MS = 2 ** 31 - 1;
+/** `mostra wait <artifact>`. */
+const waitCommand = defineCommand({
+	path: ["wait"],
+	summary: "Block until an artifact's submission, signal, state change or event; still_waiting on timeout.",
+	args: [{
+		name: "artifact",
+		summary: "The artifact: its source path or its ID."
+	}],
+	flags: [
+		{
+			name: "until",
+			kind: "string",
+			value: "<condition>",
+			summary: "submitted, signal:<name>, state:<fieldId> or event:<type>."
+		},
+		{
+			name: "after",
+			kind: "string",
+			value: "<cursor>",
+			summary: "Wait for what comes after this cursor. Default: the latest publish."
+		},
+		{
+			name: "timeout",
+			kind: "duration",
+			value: "<d>",
+			summary: "Stop waiting after this long, with still_waiting and exit 5. Default: no limit."
+		}
+	],
+	output: {
+		type: "WaitResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure, EXIT.stillWaiting],
+	example: "wait ./sidebar-review --until submitted --timeout 30m",
+	async run(context) {
+		const until = flag(context, "until");
+		if (until === void 0) throw usage("\"mostra wait\" needs --until, such as --until submitted.");
+		const timeout = flag(context, "timeout");
+		const deadline = timeout === void 0 ? void 0 : Date.now() + durationMs(timeout);
+		const artifact = artifactRef(arg(context, "artifact"), context.cwd);
+		let after = flag(context, "after");
+		for (;;) {
+			const remaining = deadline === void 0 ? MAX_WAIT_MS : Math.max(0, deadline - Date.now());
+			const result = await context.call(waitMethod, {
+				artifact,
+				until,
+				timeoutMs: Math.min(remaining, MAX_WAIT_MS),
+				...after !== void 0 ? { after } : {}
+			});
+			if (result.status === "satisfied") return {
+				result,
+				human: `${result.event.type} at cursor ${result.cursor}\n`
+			};
+			if (deadline === void 0) {
+				after = result.cursor;
+				continue;
+			}
+			return {
+				result,
+				human: `still waiting; resume with --after ${result.cursor}\n`,
+				exit: EXIT.stillWaiting
+			};
+		}
+	}
+});
+/** `mostra results <artifact>`. */
+const resultsCommand = defineCommand({
+	path: ["results"],
+	summary: "Print an artifact's submission in full: answers, state, choices, comments, actions and signals.",
+	args: [{
+		name: "artifact",
+		summary: "The artifact: its source path or its ID."
+	}],
+	flags: [{
+		name: "submission",
+		kind: "string",
+		value: "<id>",
+		summary: "This submission instead of the latest."
+	}, {
+		name: "format",
+		kind: "string",
+		value: "<format>",
+		choices: ["md", "json"],
+		summary: "Markdown or JSON. Default: Markdown, or JSON with --json."
+	}],
+	output: {
+		type: "Results",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "results ./sidebar-review",
+	async run(context) {
+		const format = flag(context, "format") ?? (context.json ? "json" : "md");
+		const submission = flag(context, "submission");
+		const result = await context.call(resultsGetMethod, {
+			artifact: artifactRef(arg(context, "artifact"), context.cwd),
+			format,
+			...submission !== void 0 ? { submission } : {}
+		});
+		const markdown = typeof result === "object" && result !== null && "markdown" in result ? result.markdown : void 0;
+		return {
+			result,
+			human: markdown !== void 0 ? `${markdown.trimEnd()}\n` : pretty(result)
+		};
+	}
+});
+/** `mostra push <artifact> <key>`. */
+const pushCommand = defineCommand({
+	path: ["push"],
+	summary: "Push a value into an artifact's live source; pages showing it update at once.",
+	args: [{
+		name: "artifact",
+		summary: "The artifact: its source path or its ID."
+	}, {
+		name: "key",
+		summary: "The live source's key: its export name in live.ts, or a new one."
+	}],
+	flags: [
+		{
+			name: "value",
+			kind: "string",
+			value: "<json>",
+			summary: "The value, as JSON."
+		},
+		{
+			name: "file",
+			kind: "string",
+			value: "<path>",
+			summary: "Read the value from a JSON file."
+		},
+		{
+			name: "stdin",
+			kind: "boolean",
+			summary: "Read the value from stdin."
+		},
+		{
+			name: "append",
+			kind: "boolean",
+			summary: "Add the value to the source's ring instead of replacing it."
+		},
+		{
+			name: "request-id",
+			kind: "string",
+			value: "<id>",
+			summary: "Make a retry return the first attempt's revision."
+		}
+	],
+	output: {
+		type: "LivePushResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: `push ./dashboard prices --value '{"btc": 64000}'`,
+	readsStdin: (flags) => flags["stdin"] === true,
+	async run(context) {
+		const value = await jsonInput(context);
+		const requestId = flag(context, "request-id");
+		const result = await context.call(livePushMethod, {
+			artifact: artifactRef(arg(context, "artifact"), context.cwd),
+			key: arg(context, "key"),
+			value,
+			...context.flags["append"] === true ? { mode: "append" } : {},
+			...requestId !== void 0 ? { requestId } : {}
+		});
+		return {
+			result,
+			human: `revision ${result.revision}\n`
+		};
+	}
+});
+const writeFlags = [
+	{
+		name: "base",
+		kind: "string",
+		value: "<revision>",
+		summary: "Write only if the fields are unchanged since this revision; else a conflict (exit 6)."
+	},
+	{
+		name: "as",
+		kind: "string",
+		value: "<actor>",
+		choices: ["agent", "host"],
+		default: "agent",
+		summary: "Who the change is attributed to."
+	},
+	{
+		name: "mutation-id",
+		kind: "string",
+		value: "<mut_…>",
+		summary: "Make a retry return the first attempt's result."
+	}
+];
+/** `mostra state get <artifact> [ids…]`. */
+const stateGetCommand = defineCommand({
+	path: ["state", "get"],
+	summary: "Read an artifact's state: the fields every viewer shares, with their revisions.",
+	args: [{
+		name: "artifact",
+		summary: "The artifact: its source path or its ID."
+	}, {
+		name: "id",
+		summary: "Only these field IDs.",
+		optional: true,
+		variadic: true
+	}],
+	output: {
+		type: "StateGetResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure],
+	example: "state get ./tasks priorities",
+	async run(context) {
+		const ids = context.args["id"];
+		const result = await context.call(stateGetMethod, {
+			artifact: artifactRef(arg(context, "artifact"), context.cwd),
+			...ids !== void 0 && ids.length > 0 ? { ids: [...ids] } : {}
+		});
+		return {
+			result,
+			human: pretty(result)
+		};
+	}
+});
+/** Sends one state mutation; a conflict ends with exit 6. */
+async function patch(context, ops) {
+	const base = flag(context, "base");
+	const as = flag(context, "as") ?? "agent";
+	const result = await context.call(statePatchMethod, {
+		artifact: artifactRef(arg(context, "artifact"), context.cwd),
+		ops,
+		mutationId: flag(context, "mutation-id") ?? MutationId.create(),
+		as,
+		...base !== void 0 ? { baseRevision: base } : {}
+	});
+	const conflicted = result.conflicts.length > 0;
+	return {
+		result,
+		human: conflicted ? `conflict on ${result.conflicts.map((conflict) => conflict.id).join(", ")}; revision ${result.revision}\n` : `revision ${result.revision}\n`,
+		...conflicted ? { exit: EXIT.conflict } : {}
+	};
+}
+/** `mostra state set <artifact> <id> <json>`. */
+const stateSetCommand = defineCommand({
+	path: ["state", "set"],
+	summary: "Set one field of an artifact's state; viewers see it at once.",
+	args: [
+		{
+			name: "artifact",
+			summary: "The artifact: its source path or its ID."
+		},
+		{
+			name: "id",
+			summary: "The field ID."
+		},
+		{
+			name: "value",
+			summary: "The value, as JSON."
+		}
+	],
+	flags: writeFlags,
+	output: {
+		type: "StatePatchResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure, EXIT.conflict],
+	example: `state set ./tasks priorities '["Ship the CLI"]'`,
+	async run(context) {
+		return patch(context, [{
+			id: arg(context, "id"),
+			value: parseJson(arg(context, "value"), "<value>")
+		}]);
+	}
+});
+/** `mostra state patch <artifact>`. */
+const statePatchCommand = defineCommand({
+	path: ["state", "patch"],
+	summary: "Change several fields of an artifact's state in one revision: [{ id, value } | { id, delete: true }].",
+	args: [{
+		name: "artifact",
+		summary: "The artifact: its source path or its ID."
+	}],
+	flags: [
+		{
+			name: "ops",
+			kind: "string",
+			value: "<json>",
+			summary: "The operations, as JSON."
+		},
+		{
+			name: "file",
+			kind: "string",
+			value: "<path>",
+			summary: "Read the operations from a JSON file."
+		},
+		{
+			name: "stdin",
+			kind: "boolean",
+			summary: "Read the operations from stdin."
+		},
+		...writeFlags
+	],
+	output: {
+		type: "StatePatchResult",
+		topic: "cli"
+	},
+	exits: [EXIT.failure, EXIT.conflict],
+	example: `state patch ./tasks --file ops.json`,
+	readsStdin: (flags) => flags["stdin"] === true,
+	async run(context) {
+		const ops = await jsonInput(context, "ops");
+		const parsed = FieldOp.array().safeParse(ops);
+		if (!parsed.success || parsed.data.length === 0) throw usage("The operations must be a non-empty JSON array of { id, value } or { id, delete: true }.");
+		return patch(context, parsed.data);
+	}
+});
+//#endregion
+//#region src/browser.ts
+/**
+* Opening a browser on a launch URL without putting it on a command line (D140 item 15, Opus
+* review finding 4). A program's arguments are readable by every local user (`ps`,
+* `/proc/<pid>/cmdline`), so the opener gets the path of a page that redirects to the launch URL,
+* written mode 0600 in a fresh directory of mode 0700, as Jupyter's server does for its token.
+* The launch ticket in the page is single-use and lives a minute, so a page left behind is
+* harmless; each launch removes the ones older than that.
+*/
+/** The prefix of the directories launch pages live in. */
+const PREFIX = "mostra-open-";
+/** A launch page older than this holds a ticket that expired: it goes on the next launch. */
+const STALE_MS = 12e4;
+/** Escapes text for an HTML attribute or element. */
+const html = (text) => text.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+/** The page that sends the browser on to `url`. */
+function launchPage(url) {
+	const script = JSON.stringify(url).replaceAll("<", "\\u003c");
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<meta http-equiv="refresh" content="0;url=${html(url)}">
+<title>Opening Mostra</title>
+<script>location.replace(${script});<\/script>
+</head>
+<body>
+<p>Opening the artifact. If nothing happens, <a href="${html(url)}">open it here</a>.</p>
+</body>
+</html>
+`;
+}
+/** Removes launch pages of earlier launches that are this user's and older than a minute or two. */
+function sweep(base, now) {
+	const uid = process.getuid?.();
+	let names;
+	try {
+		names = readdirSync(base);
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		if (!name.startsWith(PREFIX)) continue;
+		const dir = join(base, name);
+		try {
+			const stats = lstatSync(dir);
+			if (!stats.isDirectory() || uid !== void 0 && stats.uid !== uid) continue;
+			if (now - stats.mtimeMs < STALE_MS) continue;
+			rmSync(dir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	}
+}
+/** Writes the launch page for `url`; its path. */
+function writeLaunchPage(url, base = tmpdir(), now = Date.now()) {
+	sweep(base, now);
+	const dir = mkdtempSync(join(base, PREFIX));
+	const file = join(dir, "open.html");
+	writeFileSync(file, launchPage(url), {
+		mode: 384,
+		flag: "wx"
+	});
+	return file;
+}
+/**
+* Splits a command the way a shell would split plain words and quotes, without running one:
+* `firefox --new-window %s` or `"/Applications/My Browser" %s`.
+*/
+function splitCommand(command) {
+	const words = [];
+	let word = "";
+	let inWord = false;
+	let quote;
+	for (let index = 0; index < command.length; index += 1) {
+		const char = command[index];
+		if (quote) {
+			if (char === quote) quote = void 0;
+			else if (char === "\\" && quote === "\"" && index + 1 < command.length) {
+				index += 1;
+				word += command[index];
+			} else word += char;
+			continue;
+		}
+		if (char === "\"" || char === "'") {
+			quote = char;
+			inWord = true;
+		} else if (char === "\\" && index + 1 < command.length) {
+			index += 1;
+			word += command[index];
+			inWord = true;
+		} else if (/\s/.test(char)) {
+			if (inWord) words.push(word);
+			word = "";
+			inWord = false;
+		} else {
+			word += char;
+			inWord = true;
+		}
+	}
+	if (inWord) words.push(word);
+	return words;
+}
+/**
+* The commands that may open `target`, in order: each entry of `$BROWSER` (separated by `:`, its
+* `%s` replaced by the target, else the target appended, `%%` a literal `%`, as `xdg-open` and
+* Python's `webbrowser` read it), else the platform's opener.
+*/
+function browserCommands(target, env, platform = process.platform) {
+	const chosen = env["BROWSER"];
+	const entries = chosen !== void 0 && chosen.trim() !== "" ? chosen.split(":").filter((entry) => entry.trim() !== "") : [platform === "darwin" ? "open" : "xdg-open"];
+	const commands = [];
+	for (const entry of entries) {
+		const words = splitCommand(entry);
+		if (words.length === 0) continue;
+		let substituted = false;
+		const argv = words.map((word) => word.replaceAll(/%%|%s/g, (match) => {
+			if (match === "%%") return "%";
+			substituted = true;
+			return target;
+		}));
+		commands.push(substituted ? argv : [...argv, target]);
+	}
+	return commands;
+}
+/** Starts one command, detached; whether it started (its program was found and could run). */
+function start(argv) {
+	const [program, ...args] = argv;
+	if (program === void 0) return Promise.resolve(false);
+	return new Promise((resolve) => {
+		try {
+			const child = spawn(program, args, {
+				detached: true,
+				stdio: "ignore"
+			});
+			child.once("spawn", () => {
+				child.unref();
+				resolve(true);
+			});
+			child.once("error", () => resolve(false));
+		} catch {
+			resolve(false);
+		}
+	});
+}
+/** Opens `url` in a browser through a launch page; whether a browser command started. */
+async function openInBrowser(url, env) {
+	let page;
+	try {
+		page = writeLaunchPage(url);
+	} catch {
+		return false;
+	}
+	for (const command of browserCommands(page, env)) if (await start(command)) return true;
+	return false;
+}
+//#endregion
+//#region src/commands/viewing.ts
+/**
+* `mostra open`: the artifact's link on stdout, and a browser opened on a one-time launch URL that
+* never carries the link's secret (D140 item 15), handed over in a page, never on a command line
+* (`browser.ts`). A client of `view/default`, `view/url`,
+* `view/rotate`, `view/revoke` and `view/launch`.
+*/
+/** Whether this session can show a browser: not over SSH without a display. */
+function hasDisplay(env, platform = process.platform) {
+	const ssh = env["SSH_CONNECTION"] !== void 0 || env["SSH_TTY"] !== void 0;
+	if (platform === "darwin") return !ssh;
+	return env["DISPLAY"] !== void 0 || env["WAYLAND_DISPLAY"] !== void 0;
+}
+/** Whether `open` should launch a browser: a terminal without `--json`, or `--browser`. */
+function wantsBrowser(context) {
+	if (context.flags["no-browser"] === true) return false;
+	if (context.flags["browser"] === true) return true;
+	return context.tty.stdout && !context.json && hasDisplay(context.env);
+}
+/** The link, opened in a browser when wanted. */
+async function show(context, link) {
+	let opened = false;
+	if (wantsBrowser(context)) opened = await openInBrowser((await context.call(viewLaunchMethod, { tokenId: link.tokenId })).url, context.env);
+	return {
+		result: {
+			...link,
+			opened
+		},
+		human: `${link.url}\n`
+	};
+}
+//#endregion
+//#region src/commands/index.ts
+/** The commands, in help's order: the authoring loop first. */
+const COMMANDS = [
+	newCommand,
+	devCommand,
+	verifyCommand,
+	publishCommand,
+	defineCommand({
+		path: ["open"],
+		summary: "Print an artifact's capability link and open it in a browser; or mint, rotate or revoke a link.",
+		args: [{
+			name: "artifact",
+			summary: "The artifact: its source path or its ID."
+		}],
+		flags: [
+			{
+				name: "new",
+				kind: "boolean",
+				summary: "Mint a separate link instead of the artifact's default one."
+			},
+			{
+				name: "version",
+				kind: "string",
+				value: "<n|id>",
+				summary: "A new link that opens only this version."
+			},
+			{
+				name: "scope",
+				kind: "list",
+				value: "<a,b>",
+				summary: "A new link's scopes: view, draft, submit, review, signal, action:*. Default: all."
+			},
+			{
+				name: "ttl",
+				kind: "duration",
+				value: "<d>",
+				summary: "A new link that expires after this long, such as 24h."
+			},
+			{
+				name: "viewer",
+				kind: "string",
+				value: "<ref>",
+				summary: "A new link that acts for this person, by your own stable key for them."
+			},
+			{
+				name: "viewer-name",
+				kind: "string",
+				value: "<name>",
+				summary: "The display name of --viewer."
+			},
+			{
+				name: "rotate",
+				kind: "string",
+				value: "<tokenId>",
+				summary: "Replace this link with a new one; the old one stops working."
+			},
+			{
+				name: "revoke",
+				kind: "string",
+				value: "<tokenId>",
+				summary: "Stop this link from working."
+			},
+			{
+				name: "browser",
+				kind: "boolean",
+				summary: "Open a browser even without a terminal."
+			},
+			{
+				name: "no-browser",
+				kind: "boolean",
+				summary: "Only print the link."
+			},
+			{
+				name: "request-id",
+				kind: "string",
+				value: "<id>",
+				summary: "Make a retried --new return the same link."
+			}
+		],
+		output: {
+			type: "CapabilityLink",
+			topic: "cli"
+		},
+		exits: [EXIT.failure],
+		example: "open ./sidebar-review",
+		async run(context) {
+			const artifact = artifactRef(arg(context, "artifact"), context.cwd);
+			const revoke = flag(context, "revoke");
+			const rotate = flag(context, "rotate");
+			if (revoke !== void 0 && rotate !== void 0) throw usage("Give --rotate or --revoke, not both.");
+			if (revoke !== void 0) {
+				await context.call(viewRevokeMethod, { tokenId: revoke });
+				return {
+					result: {
+						tokenId: revoke,
+						revoked: true
+					},
+					human: `Revoked ${revoke}\n`
+				};
+			}
+			if (rotate !== void 0) return show(context, await context.call(viewRotateMethod, { tokenId: rotate }));
+			const version = flag(context, "version");
+			const scopes = context.flags["scope"];
+			const ttl = flag(context, "ttl");
+			const viewerRef = flag(context, "viewer");
+			const viewerName = flag(context, "viewer-name");
+			const requestId = flag(context, "request-id");
+			if (viewerName !== void 0 && viewerRef === void 0) throw usage("--viewer-name needs --viewer.");
+			if (!(context.flags["new"] === true || version !== void 0 || scopes !== void 0 || ttl !== void 0 || viewerRef !== void 0)) return show(context, await context.call(viewDefaultMethod, { artifact }));
+			return show(context, await context.call(viewUrlMethod, {
+				artifact,
+				...version !== void 0 ? { version: /^[0-9]+$/.test(version) ? Number(version) : version } : {},
+				...scopes !== void 0 ? { scopes } : {},
+				...ttl !== void 0 ? { ttl } : {},
+				...viewerRef !== void 0 ? { viewer: {
+					ref: viewerRef,
+					...viewerName !== void 0 ? { name: viewerName } : {}
+				} } : {},
+				...requestId !== void 0 ? { requestId } : {}
+			}));
+		}
+	}),
+	waitCommand,
+	resultsCommand,
+	stateGetCommand,
+	stateSetCommand,
+	statePatchCommand,
+	pushCommand,
+	addCommand,
+	secretSetCommand,
+	secretListCommand,
+	secretRmCommand,
+	listCommand,
+	statusCommand,
+	daemonStartCommand,
+	daemonStopCommand,
+	daemonRestartCommand,
+	daemonStatusCommand,
+	daemonInstallCommand,
+	daemonUninstallCommand,
+	hostCommand,
+	docsCommand,
+	doctorCommand,
+	gcCommand,
+	telemetryStatusCommand,
+	telemetryOnCommand,
+	telemetryOffCommand
+];
+//#endregion
+//#region src/help.ts
+/**
+* Help, generated from the command definitions (D140 items 8 and 16): `--help` for people,
+* `--help --json` for agents (the definition itself), and `docs/reference/cli.md`, which CI
+* checks is current. The wording lives in the definitions; this module only lays it out.
+*/
+const EXIT_MEANING = {
+	[EXIT.ok]: "success",
+	[EXIT.failure]: "artifact failure (verify failed, publish refused, the artifact's state refused the request)",
+	[EXIT.usage]: "usage error",
+	[EXIT.environment]: "environment error (no runtime, browser or socket; the home; an unsupported platform)",
+	[EXIT.timeout]: "timeout (--timeout passed)",
+	[EXIT.stillWaiting]: "still waiting (the wait timed out; the result says where to resume)",
+	[EXIT.conflict]: "conflict (already submitted, a compare-and-set mismatch, a reused request ID)"
+};
+/** The usage line: `mostra open <artifact> [flags]`. */
+function usageLine(command) {
+	const args = (command.args ?? []).map((arg) => {
+		const name = arg.variadic ? `<${arg.name}…>` : `<${arg.name}>`;
+		return arg.optional ? `[${name}]` : name;
+	});
+	return [
+		"mostra",
+		...command.path,
+		...args,
+		...(command.flags ?? []).length > 0 ? ["[flags]"] : []
+	].join(" ");
+}
+function flagLine(flag) {
+	const name = `--${flag.name}${flag.kind === "boolean" ? "" : ` ${flag.value ?? `<${flag.kind}>`}`}`;
+	const choices = flag.choices ? ` (${flag.choices.join(", ")})` : "";
+	const fallback = flag.default !== void 0 ? ` Default: ${flag.default}.` : "";
+	return `  ${name.padEnd(28)} ${flag.summary}${choices}${fallback}`;
+}
+/** Commands that run until their connection or Ctrl-C ends them: `--timeout` doesn't bound them. */
+const UNBOUNDED = /* @__PURE__ */ new Set(["host", "dev"]);
+/**
+* The global flags a command doesn't define again (`wait --timeout` is the wait's own); a command
+* `--timeout` doesn't bound has no `--timeout`.
+*/
+function globalFlagsOf(command) {
+	const own = new Set((command.flags ?? []).map((flag) => flag.name));
+	if (UNBOUNDED.has(command.path[0] ?? "")) own.add("timeout");
+	return GLOBAL_FLAGS.filter((flag) => !own.has(flag.name));
+}
+/** Every exit code a command can end with, sorted: `--timeout` can end any it bounds with 4. */
+function exitCodes(command) {
+	const bounded = !UNBOUNDED.has(command.path[0] ?? "") && command.path[0] !== "wait";
+	return [.../* @__PURE__ */ new Set([
+		EXIT.ok,
+		...command.exits,
+		EXIT.usage,
+		EXIT.environment,
+		...bounded ? [EXIT.timeout] : []
+	])].sort((a, b) => a - b);
+}
+/** One command's help, for people. */
+function commandHelp(command) {
+	const lines = [
+		command.summary,
+		"",
+		"Usage:",
+		`  ${usageLine(command)}`
+	];
+	if ((command.args ?? []).length > 0) {
+		lines.push("", "Arguments:");
+		for (const arg of command.args ?? []) lines.push(`  ${`<${arg.name}>`.padEnd(28)} ${arg.summary}`);
+	}
+	if ((command.flags ?? []).length > 0) {
+		lines.push("", "Flags:");
+		for (const flag of command.flags ?? []) lines.push(flagLine(flag));
+	}
+	lines.push("", "Global flags:");
+	for (const flag of globalFlagsOf(command)) lines.push(flagLine(flag));
+	lines.push("", `Output: ${command.output.type} (mostra docs ${command.output.topic})`);
+	lines.push("", "Exit codes:");
+	for (const code of exitCodes(command)) lines.push(`  ${code}  ${EXIT_MEANING[code] ?? ""}`);
+	lines.push("", "Example:", `  mostra ${command.example}`, "");
+	return lines.join("\n");
+}
+/** A group's help (`mostra daemon --help`): its commands. */
+function groupHelp(commands, group) {
+	const members = commands.filter((command) => command.path[0] === group);
+	return [
+		`mostra ${group}: ${members.length} commands.`,
+		"",
+		...members.map((command) => `  ${commandName(command).padEnd(22)} ${command.summary}`),
+		"",
+		`Run "mostra ${group} <command> --help" for one of them.`,
+		""
+	].join("\n");
+}
+/** The top-level help: every command. */
+function topHelp(commands) {
+	return [
+		"Mostra, the agent artifact runtime: write ordinary React, verify it, publish it, share the link, wait for answers.",
+		"",
+		"Usage:",
+		"  mostra <command> [arguments] [flags]",
+		"",
+		"Commands:",
+		...commands.map((command) => `  ${commandName(command).padEnd(22)} ${command.summary}`),
+		"",
+		"Global flags:",
+		...GLOBAL_FLAGS.map(flagLine),
+		"",
+		"Run \"mostra <command> --help\" for a command, and \"mostra docs\" for the reference.",
+		""
+	].join("\n");
+}
+/** One command's machine-readable definition (`--help --json`). */
+function commandDefinition(command) {
+	return {
+		command: commandName(command),
+		summary: command.summary,
+		usage: usageLine(command),
+		args: (command.args ?? []).map((arg) => ({
+			name: arg.name,
+			summary: arg.summary,
+			optional: arg.optional === true,
+			variadic: arg.variadic === true
+		})),
+		flags: [...command.flags ?? [], ...globalFlagsOf(command)].map((flag) => ({
+			name: flag.name,
+			type: flag.kind,
+			summary: flag.summary,
+			...flag.choices ? { choices: flag.choices } : {},
+			...flag.default !== void 0 ? { default: flag.default } : {},
+			global: GLOBAL_FLAGS.includes(flag)
+		})),
+		output: command.output,
+		exitCodes: exitCodes(command).map((code) => ({
+			code,
+			meaning: EXIT_MEANING[code] ?? ""
+		})),
+		stdin: typeof command.readsStdin === "function" ? "sometimes" : command.readsStdin === true,
+		streams: command.streams === true,
+		example: `mostra ${command.example}`
+	};
+}
+/** `docs/reference/cli.md`: every command's help as one page. */
+function referenceMarkdown(commands) {
+	const sections = commands.map((command) => `## mostra ${commandName(command)}\n\n\`\`\`text\n${commandHelp(command).trimEnd()}\n\`\`\`\n`);
+	return [
+		"# The mostra CLI",
+		"",
+		"<!-- Generated from the command definitions in packages/cli/src/commands/. Don't edit; run `pnpm fix`. -->",
+		"",
+		"Every command takes `--json`, which prints one envelope on stdout: `{ \"ok\": true, \"result\", \"instance\", \"warnings\" }` or `{ \"ok\": false, \"error\", \"warnings\" }`. Streaming commands print one envelope per line, the last one carrying `result` or `error`. Logs and progress go to stderr. Without a terminal, or with `--json`, no command asks a question.",
+		"",
+		`Commands: ${topWords(commands).map((word) => `\`${word}\``).join(", ")}.`,
+		"",
+		...sections
+	].join("\n");
+}
+//#endregion
+//#region src/client.ts
+/**
+* The CLI's connection to its home's instance (D45, D81, INTERFACES §9): it attaches to the
+* daemon recorded in `instance.json`, or starts one (`mostra-runtime daemon`, which itself
+* attaches when another starter won), and opens a session as `mostra-cli`. The SDK (WP-11) does
+* the same few steps over the same protocol.
+*/
+/** How long one attempt to reach a recorded socket waits. */
+const ATTACH_TIMEOUT_MS = 5e3;
+/** How long a daemon this command starts may take to say where it listens. */
+const START_TIMEOUT_MS = 3e4;
+/**
+* Opens a session with the home's instance, starting its daemon when none runs. Returns
+* `undefined` when `autostart` is false and no instance runs. Throws the start's diagnostic when
+* the daemon can't start (`MOSTRA_HOME_LOCKED`, `MOSTRA_PLATFORM_UNSUPPORTED` …).
+*/
+async function connect(options) {
+	const recorded = readSocket(options.home);
+	if (recorded !== void 0) {
+		const session = await open(recorded, options, false).catch(() => void 0);
+		if (session) return session;
+	}
+	if (options.autostart === false) return void 0;
+	options.onStarting?.(true);
+	let started;
+	try {
+		started = await startDaemon(options);
+	} finally {
+		options.onStarting?.(false);
+	}
+	return open(started.socket, options, started.status === "started");
+}
+/** The socket `instance.json` records (D81), if the file exists and reads. */
+function readSocket(home) {
+	try {
+		const record = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
+		return typeof record.socket === "string" ? record.socket : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Starts the home's daemon, detached from this process, and reads the one line it prints: where
+* it listens, or why it couldn't start. A daemon another starter won prints `attached` and exits.
+*/
+async function startDaemon(options) {
+	const deadlineAt = Date.now() + START_TIMEOUT_MS;
+	const timedOut = () => new RpcError(createDiagnostic("MOSTRA_HOST_TIMEOUT", { message: `The home's daemon didn't start within ${formatDuration(START_TIMEOUT_MS)}.` }));
+	const runtime = await locateRuntime(options.env);
+	if (Date.now() >= deadlineAt) throw timedOut();
+	const args = [
+		runtime.entry,
+		"daemon",
+		"--home",
+		options.home
+	];
+	return new Promise((resolve, reject) => {
+		const child = spawn(runtime.node, args, {
+			detached: true,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			env: {
+				...process.env,
+				...options.env
+			}
+		});
+		const splitter = new LineSplitter();
+		let settled = false;
+		const finish = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			child.stdout?.removeAllListeners("data");
+			child.stdout?.destroy();
+			child.unref();
+			outcome();
+		};
+		const timer = setTimeout(() => finish(() => reject(timedOut())), Math.max(0, deadlineAt - Date.now()));
+		child.on("error", (error) => finish(() => reject(new RpcError(createDiagnostic("MOSTRA_ENV_RUNTIME_MISSING", { message: `The runtime couldn't be started: ${error.message}` })))));
+		child.on("close", (code) => finish(() => reject(new RpcError(createDiagnostic("MOSTRA_HOST_CONNECTION_CLOSED", { message: `The home's daemon exited (${code ?? "signal"}) before it said where it listens.` })))));
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk) => {
+			for (const line of splitter.push(chunk)) {
+				let parsed;
+				try {
+					parsed = JSON.parse(line);
+				} catch {
+					continue;
+				}
+				finish(() => {
+					if (parsed.status === "failed") reject(new RpcError(parsed.diagnostic ?? createDiagnostic("MOSTRA_HOST_INTERNAL_ERROR", { message: "The home's daemon failed to start." })));
+					else resolve(parsed);
+				});
+				return;
+			}
+		});
+	});
+}
+async function open(socketPath, options, started) {
+	const socket = await new Promise((resolve, reject) => {
+		const connection = createConnection(socketPath);
+		const timer = setTimeout(() => {
+			connection.destroy();
+			reject(closed(socketPath, "timed out"));
+		}, ATTACH_TIMEOUT_MS);
+		connection.once("error", (error) => {
+			clearTimeout(timer);
+			reject(closed(socketPath, error.code ?? "failed"));
+		});
+		connection.once("connect", () => {
+			clearTimeout(timer);
+			resolve(connection);
+		});
+	});
+	const handlers = /* @__PURE__ */ new Map();
+	const peer = new RpcPeer({
+		send: (message) => {
+			if (!socket.destroyed) socket.write(encodeLine(message));
+		},
+		onNotification: (method, params) => handlers.get(method)?.(params)
+	});
+	let markClosed = () => {};
+	const closedPromise = new Promise((done) => {
+		markClosed = done;
+	});
+	const splitter = new LineSplitter();
+	socket.setEncoding("utf8");
+	socket.on("data", (chunk) => {
+		for (const line of splitter.push(chunk)) peer.receiveLine(line);
+	});
+	const end = () => {
+		peer.close();
+		markClosed();
+	};
+	socket.on("close", end);
+	socket.on("error", () => socket.destroy());
+	let result;
+	try {
+		result = await peer.call(mostraInitializeMethod, {
+			client: {
+				name: CLI_CLIENT_NAME,
+				version: cliVersion()
+			},
+			revisions: [...HOST_PROTOCOL_REVISIONS],
+			capabilities: { notifications: [ARTIFACT_PROGRESS, DEV_NOTIFY] },
+			ports: [],
+			home: { path: options.home }
+		}, { timeoutMs: ATTACH_TIMEOUT_MS });
+	} catch (error) {
+		socket.destroy();
+		throw error;
+	}
+	return {
+		summary: {
+			home: result.instance.home,
+			socket: socketPath,
+			pid: result.instance.pid,
+			mode: result.instance.mode,
+			version: result.instance.version,
+			started
+		},
+		warnings: result.warnings,
+		call: (method, params, timeoutMs) => peer.call(method, params, timeoutMs !== void 0 ? { timeoutMs } : {}),
+		onNotification: (method, handler) => {
+			handlers.set(method, handler);
+		},
+		closed: closedPromise,
+		close: () => {
+			peer.close();
+			socket.end();
+			socket.destroy();
+		}
+	};
+}
+function closed(path, why) {
+	return new RpcError(createDiagnostic("MOSTRA_HOST_CONNECTION_CLOSED", { message: `Couldn't reach the instance at ${path} (${why}).` }));
+}
+/** A limit as people write it: `250 ms`, `5 s`, `1.5 s`. */
+function formatDuration(ms) {
+	if (ms < 1e3) return `${ms} ms`;
+	const seconds = ms / 1e3;
+	return `${Number.isInteger(seconds) ? seconds : seconds.toFixed(1)} s`;
+}
+//#endregion
+//#region src/run.ts
+/**
+* The runner (INTERFACES §9, D140 item 16): reads the command line, runs one command, and owns
+* everything commands share. stdout carries exactly one JSON value in `--json` mode (one per line
+* for a stream), whatever happens, usage errors and crashes included; logs, progress and warnings
+* go to stderr; the exit code comes from one table; telemetry's notice or question comes before
+* the command's work and its events after it.
+*/
+/** The diagnostic an exception is, for the envelope: its own, or an internal error. */
+function diagnosticOf(error) {
+	if (error instanceof RpcError) return error.diagnostic;
+	return createDiagnostic("MOSTRA_HOST_INTERNAL_ERROR", { message: `mostra failed unexpectedly: ${error instanceof Error ? error.message : String(error)}` });
+}
+/** A diagnostic for people, on stderr. */
+function describe(diagnostic) {
+	const hint = diagnostic.hint ? `\n  ${diagnostic.hint}` : "";
+	const fix = diagnostic.fix?.kind === "command" && diagnostic.fix.command ? `\n  Run: ${diagnostic.fix.command}` : "";
+	return `${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}${hint}${fix}\n  ${diagnostic.docs}\n`;
+}
+/** Reads the whole of stdin. */
+function readAll(stream) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+		stream.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		stream.on("error", reject);
+	});
+}
+/** Asks one question on stderr, read from stdin: the answer, `undefined` after the timeout, or Ctrl-C. */
+function ask(io, question, timeoutMs) {
+	return new Promise((resolve) => {
+		const rl = createInterface({
+			input: io.stdin,
+			output: process.stderr,
+			terminal: true
+		});
+		let done = false;
+		const finish = (answer) => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			rl.close();
+			resolve(answer);
+		};
+		const timer = setTimeout(() => {
+			io.stderr("\n");
+			finish(void 0);
+		}, timeoutMs);
+		rl.on("SIGINT", () => {
+			io.stderr("\n");
+			finish("interrupt");
+		});
+		rl.on("close", () => finish(""));
+		rl.question(question, (answer) => finish(answer));
+	});
+}
+/** Runs one command line and returns its exit code. */
+async function run(io) {
+	const started = Date.now();
+	const global = globalFlags(io.argv);
+	const json = global.json;
+	const warnings = [];
+	let summary;
+	let connection;
+	let streamed = false;
+	const writeJson = (value) => io.stdout(`${JSON.stringify(value)}\n`);
+	const fail = (diagnostic) => {
+		if (json) writeJson({
+			ok: false,
+			error: diagnostic,
+			...summary && !streamed ? { instance: summary } : {},
+			warnings
+		});
+		else io.stderr(describe(diagnostic));
+		return exitCodeFor(diagnostic.code);
+	};
+	const platform = io.platform ?? process.platform;
+	if (platform !== "darwin" && platform !== "linux") return fail(createDiagnostic("MOSTRA_PLATFORM_UNSUPPORTED", { message: `Mostra runs on macOS and Linux; this is ${platform}.` }));
+	let parsed;
+	try {
+		parsed = parseCommandLine(COMMANDS, io.argv);
+	} catch (error) {
+		return fail(diagnosticOf(error));
+	}
+	if (parsed.kind === "version") {
+		if (json) writeJson({
+			ok: true,
+			result: { version: cliVersion() },
+			warnings
+		});
+		else io.stdout(`${cliVersion()}\n`);
+		return EXIT.ok;
+	}
+	if (parsed.kind === "help") {
+		if (json) writeJson({
+			ok: true,
+			result: parsed.command ? commandDefinition(parsed.command) : { commands: COMMANDS.filter((command) => !parsed.group || command.path[0] === parsed.group).map(commandDefinition) },
+			warnings
+		});
+		else io.stdout(parsed.command ? commandHelp(parsed.command) : parsed.group ? groupHelp(COMMANDS, parsed.group) : topHelp(COMMANDS));
+		return EXIT.ok;
+	}
+	const { command } = parsed;
+	if (global.timeoutMs !== void 0 && UNBOUNDED.has(command.path[0] ?? "")) return fail(createDiagnostic("MOSTRA_CLI_USAGE", { message: `mostra ${commandName(command)} runs until Ctrl-C or its connection ends, so --timeout doesn't apply to it.` }));
+	const timeoutMs = command.path[0] === "wait" ? void 0 : global.timeoutMs;
+	const cwd = global.cwd !== void 0 ? resolve(io.cwd, global.cwd) : io.cwd;
+	const home = resolveHome({
+		home: global.home,
+		env: io.env,
+		cwd,
+		platform
+	});
+	const config = configDir(io.env, cwd);
+	const marks = readHomeMarks(home);
+	const readsStdin = typeof command.readsStdin === "function" ? command.readsStdin(parsed.flags) : command.readsStdin === true;
+	const telemetry = telemetrySession({
+		env: io.env,
+		configDir: config,
+		command: commandName(command),
+		json,
+		tty: io.tty,
+		readsStdin,
+		quiet: command.quiet === true,
+		hostHome: embeddedHome(marks),
+		stderr: io.stderr,
+		ask: (question, timeoutMs) => ask(io, question, timeoutMs)
+	});
+	let connectionClosed = false;
+	let startingDaemon = false;
+	const getConnection = async (autostart = true) => {
+		if (connection && !connectionClosed) return connection;
+		connectionClosed = false;
+		const opened = await connect({
+			home,
+			env: io.env,
+			autostart,
+			onStarting: (starting) => {
+				startingDaemon = starting;
+			}
+		});
+		if (!opened) return void 0;
+		connection = opened;
+		opened.closed.then(() => {
+			if (connection === opened) connectionClosed = true;
+		});
+		summary = opened.summary;
+		for (const warning of opened.warnings) {
+			warnings.push(warning);
+			io.stderr(describe(warning));
+		}
+		return opened;
+	};
+	const context = {
+		args: parsed.args,
+		flags: parsed.flags,
+		cwd,
+		json,
+		timeoutMs,
+		env: io.env,
+		tty: io.tty,
+		home,
+		configDir: config,
+		stdout: io.stdout,
+		stderr: io.stderr,
+		async call(method, params) {
+			const session = await getConnection();
+			if (!session) throw new RpcError(createDiagnostic("MOSTRA_HOST_CONNECTION_CLOSED", { message: "No instance runs for this home." }));
+			const remaining = timeoutMs === void 0 ? void 0 : Math.max(1, timeoutMs - (Date.now() - started));
+			return session.call(method, params, remaining);
+		},
+		connection: getConnection,
+		readStdin: () => readAll(io.stdin),
+		log: (line) => io.stderr(`${line}\n`),
+		emit(event, human) {
+			if (json) {
+				writeJson({
+					ok: true,
+					event,
+					...summary && !streamed ? { instance: summary } : {}
+				});
+				streamed = true;
+			} else if (human !== void 0) io.stdout(human);
+		},
+		warn(diagnostic) {
+			warnings.push(diagnostic);
+			io.stderr(describe(diagnostic));
+		},
+		record: (event) => telemetry.record(event),
+		runtime: (args, stdio = "pipe") => runRuntime(io, args, stdio)
+	};
+	let exit;
+	let error;
+	try {
+		if (!await telemetry.begin().catch(() => true)) return 130;
+		const outcome = await withTimeout(command, context, timeoutMs, () => startingDaemon);
+		exit = outcome.exit ?? EXIT.ok;
+		if (outcome.raw) return exit;
+		if (json) writeJson({
+			ok: true,
+			result: outcome.result ?? null,
+			...summary && !streamed && command.local !== true ? { instance: summary } : {},
+			warnings
+		});
+		else io.stdout(outcome.human ?? `${JSON.stringify(outcome.result, null, 2)}\n`);
+	} catch (caught) {
+		const diagnostic = diagnosticOf(caught);
+		error = diagnostic.code;
+		exit = fail(diagnostic);
+	} finally {
+		connection?.close();
+	}
+	try {
+		telemetry.end({
+			exit,
+			durationMs: Date.now() - started,
+			hostInstance: summary?.mode === "host",
+			...error !== void 0 ? { error } : {}
+		});
+	} catch {}
+	return exit;
+}
+/**
+* Runs a command, bounded by `--timeout` (exit 4 with `MOSTRA_HOST_TIMEOUT`). `host` and `dev` run
+* until their connection or Ctrl-C ends them, so `--timeout` bounds neither.
+*/
+async function withTimeout(command, context, timeoutMs, startingDaemon) {
+	if (timeoutMs === void 0 || command.path[0] === "host" || command.path[0] === "dev") return command.run(context);
+	let timer;
+	try {
+		return await Promise.race([command.run(context), new Promise((_, reject) => {
+			timer = setTimeout(() => reject(new RpcError(createDiagnostic("MOSTRA_HOST_TIMEOUT", { message: startingDaemon() ? `The home's daemon didn't start within ${timeoutMs} ms (--timeout).` : `mostra ${commandName(command)} didn't finish within --timeout (${timeoutMs} ms); what it asked for may still take effect.` }))), timeoutMs);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** Runs `mostra-runtime …` and collects its stdout. */
+async function runRuntime(io, args, stdio) {
+	const runtime = await locateRuntime(io.env);
+	return new Promise((resolve) => {
+		const child = spawn(runtime.node, [runtime.entry, ...args], {
+			stdio: stdio === "inherit" ? "inherit" : [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			env: io.env
+		});
+		let stdout = "";
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk) => io.stderr(chunk));
+		child.on("error", () => resolve({
+			code: EXIT.environment,
+			stdout
+		}));
+		child.on("close", (code) => resolve({
+			code: code ?? EXIT.environment,
+			stdout
+		}));
+	});
+}
+//#endregion
+export { COMMANDS as a, referenceMarkdown as i, commandDefinition as n, commandHelp as r, run as t };
+
+//# sourceMappingURL=run-BJaRnz-Q.js.map