@treeport/treeport 0.4.0 → 0.6.1

package/dist/update-qVp7yL5D.js

@@ -0,0 +1,2716 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { spawn } from "node:child_process";
+import crypto from "node:crypto";
+import fsSync, { constants } from "node:fs";
+import os from "node:os";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region src/duration.ts
+const DURATION_UNITS = /* @__PURE__ */ new Map([
+	["ms", 1],
+	["s", 1e3],
+	["m", 6e4],
+	["h", 36e5]
+]);
+const MAX_DURATION_MS = 2147483647;
+function parseDurationMs(value) {
+	const match = /^(\d+)(ms|s|m|h)$/.exec(value);
+	if (!match) throw new Error("Timeout must be a positive duration such as 500ms, 30s, 5m, or 1h");
+	const amount = Number(match[1]);
+	const multiplier = DURATION_UNITS.get(match[2] ?? "");
+	if (multiplier === void 0) throw new Error("Timeout has an unsupported duration unit");
+	const timeoutMs = amount * multiplier;
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_DURATION_MS) throw new Error("Timeout must be between 1ms and 2147483647ms");
+	return timeoutMs;
+}
+//#endregion
+//#region src/server/core/loopback.ts
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+	"127.0.0.1",
+	"::1",
+	"localhost"
+]);
+function isLoopbackHost(host) {
+	return LOOPBACK_HOSTS.has(host.trim().toLowerCase());
+}
+function assertLoopbackHost(host) {
+	if (isLoopbackHost(host)) return;
+	throw new Error("Treeport supports only loopback listeners. Run `treeport start --host 127.0.0.1`, then use `treeport remote enable` for private remote access.");
+}
+//#endregion
+//#region src/cli/lifecycle.ts
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 8733;
+function listenerUrl(host, port) {
+	return `http://${host.includes(":") && !host.startsWith("[") ? `[${host}]` : host}:${port}`;
+}
+function expandHome(value) {
+	return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+function localPaths(env = process.env) {
+	const defaultDataDir = env.XDG_DATA_HOME ? path.join(expandHome(env.XDG_DATA_HOME), "treeport") : process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support", "treeport") : path.join(os.homedir(), ".local", "share", "treeport");
+	const dataDir = path.resolve(expandHome(env.TREEPORT_DATA_DIR?.trim() || defaultDataDir));
+	const runtimeDir = path.resolve(expandHome(env.TREEPORT_RUNTIME_DIR?.trim() || (env.XDG_RUNTIME_DIR ? path.join(env.XDG_RUNTIME_DIR, "treeport") : path.join(os.tmpdir(), `treeport-${process.getuid?.() ?? "user"}`))));
+	return {
+		dataDir,
+		runtimeDir,
+		preferencesPath: path.join(dataDir, "config.json"),
+		statePath: path.join(runtimeDir, "daemon.json"),
+		lockPath: path.join(dataDir, "daemon.lock"),
+		logPath: path.join(dataDir, "logs", "daemon.log")
+	};
+}
+async function readJson$1(filePath, schema) {
+	return fs.readFile(filePath, "utf8").then((value) => schema.parse(JSON.parse(value))).catch(() => null);
+}
+const preferencesSchema = z.looseObject({
+	host: z.string().optional(),
+	port: z.number().optional(),
+	remote: z.strictObject({
+		port: z.number(),
+		target: z.string()
+	}).optional()
+});
+const daemonRecordSchema = z.strictObject({
+	pid: z.number(),
+	instanceId: z.string(),
+	version: z.string(),
+	apiUrl: z.string(),
+	dataDir: z.string(),
+	startedAt: z.string(),
+	installationMethod: z.string(),
+	daemonLifecycle: z.enum([
+		"treeport",
+		"service",
+		"external"
+	])
+});
+const healthRecordSchema = z.strictObject({
+	ok: z.literal(true),
+	version: z.string(),
+	protocolVersion: z.number(),
+	hostname: z.string().optional(),
+	pid: z.number(),
+	instanceId: z.string().nullable(),
+	installationMethod: z.string(),
+	daemonLifecycle: z.enum([
+		"treeport",
+		"service",
+		"external"
+	]),
+	url: z.string()
+});
+async function preferences(env = process.env) {
+	return await readJson$1(localPaths(env).preferencesPath, preferencesSchema) ?? {};
+}
+async function savePreferences(value) {
+	const paths = localPaths();
+	await fs.mkdir(paths.dataDir, {
+		recursive: true,
+		mode: 448
+	});
+	const temporaryPath = `${paths.preferencesPath}.${process.pid}.tmp`;
+	await fs.writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 384 });
+	await fs.rename(temporaryPath, paths.preferencesPath);
+}
+async function resolveLocalApiUrl(env = process.env) {
+	const explicit = env.TREEPORT_API_URL?.trim();
+	const managedApiUrl = env.TREEPORT_MANAGED_API_URL?.trim();
+	const daemonRecordPath = env.TREEPORT_DAEMON_RECORD?.trim();
+	if (explicit && explicit !== managedApiUrl) return explicit.replace(/\/$/, "");
+	if (managedApiUrl && daemonRecordPath) {
+		const record = await readJson$1(path.resolve(expandHome(daemonRecordPath)), daemonRecordSchema);
+		if (record) return record.apiUrl.replace(/\/$/, "");
+	}
+	if (explicit) return explicit.replace(/\/$/, "");
+	const saved = await preferences(env);
+	return listenerUrl(env.TREEPORT_HOST?.trim() || env.HOST?.trim() || saved.host || DEFAULT_HOST, Number.parseInt(env.TREEPORT_PORT?.trim() || env.PORT?.trim() || String(saved.port ?? DEFAULT_PORT), 10));
+}
+async function resolvePackagePath(...segments) {
+	const candidates = [
+		fileURLToPath(new URL("../", import.meta.url)),
+		fileURLToPath(new URL("../../../", import.meta.url)),
+		fileURLToPath(new URL("../../", import.meta.url))
+	];
+	for (const candidate of candidates) if (await fs.access(path.join(candidate, "package.json")).then(() => true).catch(() => false)) return path.join(candidate, ...segments);
+	throw new Error("Could not locate the Treeport package directory");
+}
+async function treeportVersion() {
+	return (await readJson$1(await resolvePackagePath("package.json"), z.looseObject({ version: z.string().optional() })))?.version ?? "development";
+}
+function processExists$1(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+async function daemonHealth(apiUrl, timeoutMs = 1500) {
+	const signal = AbortSignal.timeout(timeoutMs);
+	return fetch(`${apiUrl}/api/health`, { signal }).then(async (response) => {
+		if (!response.ok) return null;
+		const result = healthRecordSchema.safeParse(await response.json());
+		return result.success ? result.data : null;
+	}).catch(() => null);
+}
+function matchesOwnership(state, observed) {
+	return observed.pid === state.pid && observed.instanceId === state.instanceId && path.resolve(state.dataDir) === localPaths().dataDir;
+}
+async function readState() {
+	return readJson$1(localPaths().statePath, daemonRecordSchema);
+}
+async function removeStaleState(state) {
+	const paths = localPaths();
+	for (const filePath of [paths.statePath, paths.lockPath]) if ((await readJson$1(filePath, z.looseObject({ instanceId: z.string() })))?.instanceId === state.instanceId) await fs.rm(filePath, { force: true });
+}
+async function stopOwned(state) {
+	if (!processExists$1(state.pid)) {
+		await removeStaleState(state);
+		return;
+	}
+	const observed = await daemonHealth(state.apiUrl);
+	if (!observed || !matchesOwnership(state, observed)) throw new Error(`Refusing to stop PID ${state.pid}: Treeport could not verify ownership. Check ${localPaths().statePath}.`);
+	process.kill(state.pid, "SIGTERM");
+	const deadline = Date.now() + 7e3;
+	while (Date.now() < deadline) {
+		if (!processExists$1(state.pid)) {
+			await removeStaleState(state);
+			return;
+		}
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	throw new Error(`Treeport did not stop within 7 seconds. See ${localPaths().logPath}.`);
+}
+async function executableCheck(executable, args) {
+	return new Promise((resolve) => {
+		const child = spawn(executable, args, { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		let output = "";
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => {
+			output += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			output += chunk;
+		});
+		child.once("error", (error) => resolve({
+			ok: false,
+			detail: error.message
+		}));
+		child.once("close", (code) => resolve({
+			ok: code === 0,
+			detail: output.trim() || `exited with status ${code ?? 1}`
+		}));
+	});
+}
+const tailscaleStatusResponseSchema = z.looseObject({
+	BackendState: z.string().optional(),
+	Self: z.looseObject({ DNSName: z.string().optional() }).optional()
+});
+const tailscaleServeConfigurationSchema = z.lazy(() => z.looseObject({
+	TCP: z.record(z.string(), z.looseObject({})).optional(),
+	Foreground: z.record(z.string(), tailscaleServeConfigurationSchema).optional(),
+	Web: z.record(z.string(), z.looseObject({ Handlers: z.record(z.string(), z.looseObject({ Proxy: z.string().optional() })).optional() })).optional()
+}));
+async function tailscale(args) {
+	return new Promise((resolve, reject) => {
+		const child = spawn("tailscale", args, { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		let stdout = "";
+		let stderr = "";
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => reject(/* @__PURE__ */ new Error(error.code === "ENOENT" ? "Tailscale is required for remote access. Install it from https://tailscale.com/download, run `tailscale up`, then retry." : `Could not run Tailscale: ${error.message}`)));
+		child.once("close", (code) => {
+			if (code === 0) {
+				resolve(stdout);
+				return;
+			}
+			const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+			reject(/* @__PURE__ */ new Error(`Tailscale ${args[0]} failed${detail ? `: ${detail}` : ` (status ${code ?? 1})`}`));
+		});
+	});
+}
+function tailscaleJson(value, command, schema) {
+	const result = schema.safeParse(JSON.parse(value));
+	if (!result.success) throw new Error(`Tailscale ${command} returned an invalid JSON response`);
+	return result.data;
+}
+function remotePreference(value) {
+	if (value.remote === void 0) return null;
+	if (!Number.isInteger(value.remote.port) || value.remote.port < 1 || value.remote.port > 65535 || !value.remote.target) throw new Error("Treeport remote access preferences are invalid");
+	return value.remote;
+}
+function localProxyTarget(apiUrl) {
+	if (!URL.canParse(apiUrl)) throw new Error("Treeport remote access requires a loopback daemon URL");
+	const url = new URL(apiUrl);
+	if (url.protocol !== "http:" || ![
+		"127.0.0.1",
+		"localhost",
+		"::1",
+		"[::1]"
+	].includes(url.hostname)) throw new Error("Treeport remote access requires a loopback daemon. Run `treeport start --host 127.0.0.1`, then try again.");
+	return `http://${url.host}`;
+}
+function portIsServed(config, port) {
+	const tcp = config.TCP;
+	if (tcp && Object.hasOwn(tcp, String(port))) return true;
+	return Object.values(config.Foreground ?? {}).some((value) => portIsServed(value, port));
+}
+function rootProxyForPort(config, port) {
+	for (const [hostPort, server] of Object.entries(config.Web ?? {})) {
+		if (!hostPort.endsWith(`:${port}`)) continue;
+		const proxy = server.Handlers?.["/"]?.Proxy;
+		if (proxy !== void 0) return proxy;
+	}
+	return null;
+}
+function proxyMatches(actual, expected) {
+	return actual !== null && expected !== void 0 && actual.replace(/\/$/, "") === expected.replace(/\/$/, "");
+}
+async function tailscaleServeConfig() {
+	return tailscaleJson(await tailscale([
+		"serve",
+		"status",
+		"--json"
+	]), "serve status", tailscaleServeConfigurationSchema);
+}
+async function tailscaleRemoteUrl(port) {
+	const status = tailscaleJson(await tailscale(["status", "--json"]), "status", tailscaleStatusResponseSchema);
+	if (status.BackendState !== "Running") throw new Error("Tailscale is not connected. Run `tailscale up` then try again.");
+	const dnsName = status.Self?.DNSName;
+	if (!dnsName?.trim()) throw new Error("Tailscale did not report a DNS name. Enable MagicDNS, then try again.");
+	return `https://${dnsName.trim().replace(/\.$/, "")}${port === 443 ? "" : `:${port}`}`;
+}
+async function enableTailscaleRemote(options) {
+	if (options.port !== void 0 && (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535)) throw new Error("--port must be an integer between 1 and 65535");
+	const saved = await preferences();
+	const remote = remotePreference(saved);
+	const port = options.port ?? remote?.port ?? DEFAULT_PORT;
+	if (remote && remote.port !== port) throw new Error(`Treeport remote access is already configured on port ${remote.port}. Run \`treeport remote disable\` before choosing another port.`);
+	const expectedTarget = localProxyTarget((await daemonStatus()).state?.apiUrl ?? await resolveLocalApiUrl());
+	const [url, config] = await Promise.all([tailscaleRemoteUrl(port), tailscaleServeConfig()]);
+	const existingTarget = rootProxyForPort(config, port);
+	if ((portIsServed(config, port) || existingTarget !== null) && !proxyMatches(existingTarget, expectedTarget) && !proxyMatches(existingTarget, remote?.target)) throw new Error(`Tailscale Serve already uses port ${port}. Choose another port with \`treeport remote enable --port <port>\`.`);
+	const target = localProxyTarget((options.daemon ?? await daemonUp({})).apiUrl);
+	const alreadyEnabled = proxyMatches(existingTarget, target);
+	if (!alreadyEnabled) await tailscale([
+		"serve",
+		"--bg",
+		`--https=${port}`,
+		target
+	]);
+	await savePreferences({
+		...saved,
+		remote: {
+			port,
+			target
+		}
+	});
+	return {
+		alreadyEnabled,
+		port,
+		url
+	};
+}
+async function tailscaleRemoteStatus() {
+	const remote = remotePreference(await preferences());
+	if (!remote) return {
+		configured: false,
+		active: false,
+		port: null,
+		url: null
+	};
+	const [url, config] = await Promise.all([tailscaleRemoteUrl(remote.port), tailscaleServeConfig()]);
+	return {
+		configured: true,
+		active: proxyMatches(rootProxyForPort(config, remote.port), remote.target),
+		port: remote.port,
+		url
+	};
+}
+async function disableTailscaleRemote() {
+	const saved = await preferences();
+	const remote = remotePreference(saved);
+	if (!remote) return {
+		wasEnabled: false,
+		changedTailscale: false
+	};
+	if (proxyMatches(rootProxyForPort(await tailscaleServeConfig(), remote.port), remote.target)) {
+		await tailscale([
+			"serve",
+			`--https=${remote.port}`,
+			"off"
+		]);
+		delete saved.remote;
+		await savePreferences(saved);
+		return {
+			wasEnabled: true,
+			changedTailscale: true
+		};
+	}
+	delete saved.remote;
+	await savePreferences(saved);
+	return {
+		wasEnabled: false,
+		changedTailscale: false
+	};
+}
+async function runDoctor() {
+	const paths = localPaths();
+	const gitPath = process.env.TREEPORT_GIT_PATH?.trim() || "git";
+	const tmuxPath = process.env.TREEPORT_TMUX_PATH?.trim() || "tmux";
+	const [git, tmux] = await Promise.all([executableCheck(gitPath, ["--version"]), executableCheck(tmuxPath, ["-V"])]);
+	const tmuxMatch = /tmux\s+(\d+)\.(\d+)/i.exec(tmux.detail);
+	const tmuxSupported = Boolean(tmux.ok && tmuxMatch && (Number(tmuxMatch[1]) > 3 || Number(tmuxMatch[1]) === 3 && Number(tmuxMatch[2]) >= 2));
+	const checkDirectory = (directoryPath) => fs.mkdir(directoryPath, {
+		recursive: true,
+		mode: 448
+	}).then(() => ({
+		ok: true,
+		detail: directoryPath
+	})).catch((error) => ({
+		ok: false,
+		detail: `${directoryPath}: ${error instanceof Error ? error.message : String(error)}`
+	}));
+	const [dataDirectory, runtimeDirectory] = await Promise.all([checkDirectory(paths.dataDir), checkDirectory(paths.runtimeDir)]);
+	return [
+		{
+			name: "Node",
+			ok: true,
+			detail: process.version
+		},
+		{
+			name: "Git",
+			...git
+		},
+		{
+			name: "tmux",
+			ok: tmuxSupported,
+			detail: tmuxSupported ? tmux.detail : `${tmux.detail}. Treeport requires tmux 3.2 or newer.`
+		},
+		{
+			name: "Data directory",
+			...dataDirectory
+		},
+		{
+			name: "Runtime directory",
+			...runtimeDirectory
+		}
+	];
+}
+async function daemonStatus() {
+	const state = await readState();
+	if (!state) return {
+		running: false,
+		state: null,
+		health: null,
+		verified: false
+	};
+	if (!processExists$1(state.pid)) {
+		await removeStaleState(state);
+		return {
+			running: false,
+			state: null,
+			health: null,
+			verified: false
+		};
+	}
+	const observed = await daemonHealth(state.apiUrl);
+	return {
+		running: Boolean(observed),
+		state,
+		health: observed,
+		verified: Boolean(observed && matchesOwnership(state, observed))
+	};
+}
+async function daemonUp(options) {
+	if (options.port !== void 0 && (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535)) throw new Error("--port must be an integer between 1 and 65535");
+	const paths = localPaths();
+	const saved = await preferences();
+	const next = {
+		...saved,
+		host: options.host?.trim() || saved.host || DEFAULT_HOST,
+		port: options.port ?? saved.port ?? DEFAULT_PORT
+	};
+	const host = options.host?.trim() || process.env.TREEPORT_HOST?.trim() || process.env.HOST?.trim() || next.host;
+	assertLoopbackHost(host);
+	if (options.host !== void 0 || options.port !== void 0) await savePreferences(next);
+	const port = Number.parseInt(options.port === void 0 ? process.env.TREEPORT_PORT?.trim() || process.env.PORT?.trim() || String(next.port) : String(options.port), 10);
+	const apiUrl = options.host !== void 0 || options.port !== void 0 ? listenerUrl(host, port) : process.env.TREEPORT_API_URL?.trim() || listenerUrl(host, port);
+	const currentVersion = await treeportVersion();
+	const existing = await daemonStatus();
+	if (existing.state) {
+		if (!existing.running || !existing.verified) throw new Error(`Treeport PID ${existing.state.pid} is running but ownership or health could not be verified. See ${paths.logPath}.`);
+		if (existing.health?.version === currentVersion && existing.state.apiUrl === apiUrl) return {
+			alreadyRunning: true,
+			apiUrl: existing.state.apiUrl,
+			pid: existing.state.pid
+		};
+		await stopOwned(existing.state);
+	}
+	const failedChecks = (await runDoctor()).filter((check) => !check.ok);
+	if (failedChecks.length) throw new Error(failedChecks.map((check) => `${check.name}: ${check.detail}`).join("\n"));
+	const serverEntry = await resolvePackagePath("dist", "node", "server", "index.js");
+	const webDist = await resolvePackagePath("dist", "web");
+	await fs.access(serverEntry);
+	await fs.mkdir(path.dirname(paths.logPath), {
+		recursive: true,
+		mode: 448
+	});
+	if (await fs.stat(paths.logPath).then((value) => value.size).catch(() => 0) > 5 * 1024 * 1024) {
+		await fs.rm(`${paths.logPath}.1`, { force: true });
+		await fs.rename(paths.logPath, `${paths.logPath}.1`);
+	}
+	const instanceId = crypto.randomUUID();
+	const childEnvironment = {
+		...process.env,
+		TREEPORT_HOST: host,
+		TREEPORT_PORT: String(port),
+		TREEPORT_API_URL: apiUrl,
+		TREEPORT_DATA_DIR: paths.dataDir,
+		TREEPORT_RUNTIME_DIR: paths.runtimeDir,
+		TREEPORT_APP_VERSION: currentVersion,
+		TREEPORT_INSTANCE_ID: instanceId,
+		TREEPORT_INSTALLATION_METHOD: process.env.TREEPORT_INSTALLATION_METHOD?.trim() || "npm",
+		TREEPORT_DAEMON_LIFECYCLE: "treeport",
+		TREEPORT_WEB_DIST: webDist
+	};
+	if (options.foreground) {
+		console.log(`Treeport will listen on ${apiUrl}`);
+		const child = spawn(process.execPath, [serverEntry], {
+			env: childEnvironment,
+			stdio: "inherit"
+		});
+		const code = await new Promise((resolve, reject) => {
+			child.once("error", reject);
+			child.once("close", (value) => resolve(value ?? 1));
+		});
+		if (code !== 0) throw new Error(`Treeport exited with status ${code}`);
+		return {
+			alreadyRunning: false,
+			apiUrl,
+			pid: child.pid ?? 0
+		};
+	}
+	const log = fsSync.openSync(paths.logPath, "a", 384);
+	const child = spawn(process.execPath, [serverEntry], {
+		env: childEnvironment,
+		detached: true,
+		stdio: [
+			"ignore",
+			log,
+			log
+		]
+	});
+	child.unref();
+	fsSync.closeSync(log);
+	const deadline = Date.now() + 15e3;
+	while (Date.now() < deadline) {
+		const observed = await daemonHealth(apiUrl, 500);
+		if (observed && observed.pid === child.pid && observed.instanceId === instanceId && observed.version === currentVersion) return {
+			alreadyRunning: false,
+			apiUrl,
+			pid: child.pid ?? observed.pid
+		};
+		if (child.pid && !processExists$1(child.pid)) break;
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	const recentLog = await fs.readFile(paths.logPath, "utf8").then((value) => value.split("\n").slice(-20).join("\n").trim()).catch(() => "");
+	throw new Error(`Treeport did not become ready at ${apiUrl}. See ${paths.logPath}.${recentLog ? `\n\n${recentLog}` : ""}`);
+}
+async function daemonDown() {
+	const state = await readState();
+	if (!state) return { wasRunning: false };
+	await stopOwned(state);
+	return { wasRunning: true };
+}
+async function readDaemonLogs(lines = 100) {
+	return (await fs.readFile(localPaths().logPath, "utf8").catch((error) => {
+		if (error.code === "ENOENT") return "";
+		throw error;
+	})).split("\n").slice(-lines - 1).join("\n");
+}
+//#endregion
+//#region src/cli/service.ts
+const serviceRecordSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	manager: z.enum(["launchd", "systemd"]),
+	mode: z.enum(["user", "headless"]).optional(),
+	platform: z.string(),
+	uid: z.number().int().nonnegative(),
+	gid: z.number().int().nonnegative(),
+	username: z.string().min(1),
+	group: z.string().min(1),
+	home: z.string().min(1),
+	dataDir: z.string().min(1),
+	runtimeDir: z.string().min(1),
+	logPath: z.string().min(1),
+	apiUrl: z.string().min(1),
+	cliEntrypoint: z.string().min(1),
+	runtimeExecutable: z.string().min(1).nullable().default(null),
+	runtimeEntrypoint: z.string().min(1).nullable().default(null),
+	installationMethod: z.string().min(1),
+	definitionName: z.string().min(1),
+	definitionPath: z.string().min(1),
+	definitionHash: z.string().length(64),
+	environmentHash: z.string().length(64),
+	environment: z.record(z.string(), z.string()),
+	requestedState: z.enum(["running", "stopped"]),
+	pendingAdministratorRequestId: z.string().nullable(),
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+const administratorRequestSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	id: z.string().uuid(),
+	operation: z.enum([
+		"enable",
+		"start",
+		"stop",
+		"disable"
+	]),
+	createdAt: z.string(),
+	expiresAt: z.string(),
+	uid: z.number().int().nonnegative(),
+	gid: z.number().int().nonnegative(),
+	username: z.string().min(1),
+	group: z.string().min(1),
+	home: z.string().min(1),
+	serviceRecordPath: z.string().min(1),
+	runnerPath: z.string().min(1),
+	definitionName: z.string().min(1),
+	definitionPath: z.string().min(1),
+	stagedDefinitionPath: z.string().min(1),
+	definitionHash: z.string().length(64),
+	apiUrl: z.string().min(1),
+	cliEntrypoint: z.string().min(1),
+	runtimeExecutable: z.string().min(1),
+	runtimeEntrypoint: z.string().min(1)
+});
+function managerForPlatform(platform = process.platform) {
+	return platform === "darwin" ? "launchd" : platform === "linux" ? "systemd" : null;
+}
+function servicePaths(env = process.env) {
+	const paths = localPaths(env);
+	const directory = path.join(paths.dataDir, "service");
+	return {
+		directory,
+		recordPath: path.join(directory, "service.json"),
+		runnerPath: path.join(directory, "run"),
+		requestsDirectory: path.join(directory, "requests"),
+		stagedDefinitionPath: path.join(directory, "treeport.plist")
+	};
+}
+function launchdLocation(input) {
+	const name = `app.treeport.daemon.${input.uid}`;
+	const domain = input.mode === "headless" ? "system" : `gui/${input.uid}`;
+	return {
+		name,
+		path: input.mode === "headless" ? `/Library/LaunchDaemons/${name}.plist` : path.join(input.home, "Library", "LaunchAgents", `${name}.plist`),
+		domain,
+		target: `${domain}/${name}`
+	};
+}
+function userLaunchdCommands(input) {
+	if (input.operation === "enable") return {
+		bootout: ["bootout", input.location.target],
+		enable: ["enable", input.location.target],
+		activate: [
+			"bootstrap",
+			input.location.domain,
+			input.definitionPath
+		]
+	};
+	if (input.operation === "start") return {
+		bootout: null,
+		enable: ["enable", input.location.target],
+		activate: input.active ? [
+			"kickstart",
+			"-k",
+			input.location.target
+		] : [
+			"bootstrap",
+			input.location.domain,
+			input.definitionPath
+		]
+	};
+	return {
+		bootout: ["bootout", input.location.target],
+		enable: null,
+		activate: null
+	};
+}
+async function readJson(filePath, schema) {
+	return fs.readFile(filePath, "utf8").then((value) => schema.parse(JSON.parse(value))).catch(() => null);
+}
+async function writeJson$2(filePath, value) {
+	await fs.mkdir(path.dirname(filePath), {
+		recursive: true,
+		mode: 448
+	});
+	const temporaryPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	await fs.writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 384 });
+	await fs.rename(temporaryPath, filePath);
+}
+function fingerprint(value) {
+	const parsed = z.string().safeParse(value);
+	const source = parsed.success ? parsed.data : JSON.stringify(Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right))));
+	return crypto.createHash("sha256").update(source).digest("hex");
+}
+function xml(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+}
+function shellQuote$1(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function createAdministratorCommand(input) {
+	return `sudo ${shellQuote$1(input.runtimeExecutable)} ${shellQuote$1(input.runtimeEntrypoint)} service apply --request ${shellQuote$1(input.requestPath)}`;
+}
+function systemdValue(value) {
+	return value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("%", "%%").replaceAll("\n", "\\n");
+}
+function createLaunchdDefinition(input) {
+	return {
+		label: input.label,
+		mode: input.mode,
+		programArguments: [input.runnerPath],
+		username: input.mode === "headless" ? input.username : null,
+		group: input.mode === "headless" ? input.group : null,
+		environment: input.environment,
+		workingDirectory: input.home,
+		standardOutPath: input.logPath,
+		standardErrorPath: input.logPath,
+		keepAlive: true,
+		processType: "Background",
+		throttleInterval: 10,
+		exitTimeOut: 10,
+		abandonProcessGroup: true,
+		umask: 63
+	};
+}
+function serializeLaunchdDefinition(definition) {
+	const environment = Object.entries(definition.environment).sort(([left], [right]) => left.localeCompare(right)).map(([name, value]) => `      <key>${xml(name)}</key>\n      <string>${xml(value)}</string>`).join("\n");
+	const argumentsXml = definition.programArguments.map((argument) => `      <string>${xml(argument)}</string>`).join("\n");
+	const account = definition.username && definition.group ? `    <key>UserName</key>\n    <string>${xml(definition.username)}</string>\n    <key>GroupName</key>\n    <string>${xml(definition.group)}</string>\n` : "";
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${xml(definition.label)}</string>
+    <key>ProgramArguments</key>
+    <array>
+${argumentsXml}
+    </array>
+${account}    <key>EnvironmentVariables</key>
+    <dict>
+${environment}
+    </dict>
+    <key>WorkingDirectory</key>
+    <string>${xml(definition.workingDirectory)}</string>
+    <key>StandardOutPath</key>
+    <string>${xml(definition.standardOutPath)}</string>
+    <key>StandardErrorPath</key>
+    <string>${xml(definition.standardErrorPath)}</string>
+    <key>KeepAlive</key>
+    <true/>
+    <key>ProcessType</key>
+    <string>${definition.processType}</string>
+    <key>ThrottleInterval</key>
+    <integer>${definition.throttleInterval}</integer>
+    <key>ExitTimeOut</key>
+    <integer>${definition.exitTimeOut}</integer>
+    <key>AbandonProcessGroup</key>
+    <true/>
+    <key>Umask</key>
+    <integer>${definition.umask}</integer>
+  </dict>
+</plist>
+`;
+}
+function createSystemdDefinition(input) {
+	return {
+		description: "Treeport daemon",
+		execStart: input.runnerPath,
+		environment: input.environment,
+		restart: "always",
+		restartSeconds: 5,
+		timeoutStopSeconds: 10,
+		killMode: "process",
+		wantedBy: "default.target"
+	};
+}
+function serializeSystemdDefinition(definition) {
+	const environment = Object.entries(definition.environment).sort(([left], [right]) => left.localeCompare(right)).map(([name, value]) => `Environment="${systemdValue(name)}=${systemdValue(value)}"`).join("\n");
+	return `[Unit]
+Description=${definition.description}
+
+[Service]
+Type=simple
+ExecStart="${systemdValue(definition.execStart)}"
+${environment}
+Restart=${definition.restart}
+RestartSec=${definition.restartSeconds}
+TimeoutStopSec=${definition.timeoutStopSeconds}
+KillMode=${definition.killMode}
+
+[Install]
+WantedBy=${definition.wantedBy}
+`;
+}
+async function runCommand$1(executable, args, environment = process.env) {
+	return new Promise((resolve) => {
+		const child = spawn(executable, args, {
+			env: environment,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (value) => {
+			stdout += value;
+		});
+		child.stderr.on("data", (value) => {
+			stderr += value;
+		});
+		child.once("error", (error) => {
+			resolve({
+				code: 127,
+				stdout,
+				stderr: error.message
+			});
+		});
+		child.once("close", (code) => {
+			resolve({
+				code: code ?? 1,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+function commandError(command, result) {
+	const detail = [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join("\n");
+	return /* @__PURE__ */ new Error(`${command} failed${detail ? `: ${detail}` : ` with status ${result.code}`}`);
+}
+async function executablePath(name) {
+	const candidates = name === "launchctl" ? ["/bin/launchctl", "/usr/bin/launchctl"] : [`/usr/bin/${name}`, `/bin/${name}`];
+	for (const candidate of candidates) if (await fs.access(candidate, constants.X_OK).then(() => true).catch(() => false)) return candidate;
+	return name;
+}
+async function primaryGroup(username) {
+	const result = await runCommand$1(await executablePath("id"), ["-gn", username]);
+	if (result.code !== 0 || !result.stdout.trim()) throw commandError("id -gn", result);
+	return result.stdout.trim();
+}
+function currentEntrypoint() {
+	const value = process.env.TREEPORT_CLI_ENTRYPOINT?.trim() || process.argv[1]?.trim();
+	return value ? path.resolve(value) : null;
+}
+async function ensureEntrypoint() {
+	const entrypoint = currentEntrypoint();
+	if (!entrypoint) throw new Error("Treeport could not identify a stable CLI entrypoint. Install Treeport with npm, then retry.");
+	await fs.access(entrypoint, constants.X_OK).catch(() => {
+		throw new Error(`Treeport cannot execute its stable CLI entrypoint at ${entrypoint}. Reinstall Treeport, then retry.`);
+	});
+	const [actual, expected] = await Promise.all([fs.realpath(entrypoint), fs.realpath(await resolvePackagePath("bin", "treeport.mjs"))]);
+	if (actual !== expected) {
+		const prefix = path.dirname(path.dirname(entrypoint));
+		const managedEntrypoint = path.join(prefix, "lib", "treeport", "current", "lib", "node_modules", "@treeport", "treeport", "bin", "treeport.mjs");
+		const [source, managed] = await Promise.all([fs.readFile(entrypoint, "utf8").catch(() => ""), fs.realpath(managedEntrypoint).catch(() => null)]);
+		if (!source.includes("TREEPORT_MANAGED_LAUNCHER=1") || managed !== expected) throw new Error(`The current CLI entrypoint is not the installed Treeport npm bin: ${entrypoint}`);
+	}
+	return entrypoint;
+}
+async function currentAdministratorRuntime() {
+	const invokedEntrypoint = process.argv[1]?.trim();
+	if (!invokedEntrypoint) throw new Error("Treeport could not identify its Node entrypoint.");
+	const runtimeEntrypoint = path.resolve(invokedEntrypoint);
+	const [runtimeExecutable, actualEntrypoint, packageBinEntrypoint, packageCliEntrypoint] = await Promise.all([
+		fs.realpath(process.execPath),
+		fs.realpath(runtimeEntrypoint),
+		fs.realpath(await resolvePackagePath("bin", "treeport.mjs")),
+		fs.realpath(await resolvePackagePath("dist", "node", "cli", "index.js"))
+	]);
+	if (actualEntrypoint !== packageBinEntrypoint && actualEntrypoint !== packageCliEntrypoint) throw new Error(`Treeport cannot use an unrecognized package entrypoint for administrator commands: ${runtimeEntrypoint}`);
+	await Promise.all([fs.access(runtimeExecutable, constants.X_OK), fs.access(runtimeEntrypoint, constants.R_OK)]);
+	return {
+		runtimeExecutable,
+		runtimeEntrypoint
+	};
+}
+function cacheDirectory(home, env) {
+	const configured = env.TREEPORT_CACHE_DIR?.trim();
+	if (configured) return path.resolve(configured.replace(/^~(?=\/|$)/, home));
+	if (env.XDG_CACHE_HOME?.trim()) return path.join(path.resolve(env.XDG_CACHE_HOME.replace(/^~(?=\/|$)/, home)), "treeport");
+	return process.platform === "darwin" ? path.join(home, "Library", "Caches", "treeport") : path.join(home, ".cache", "treeport");
+}
+function createServiceEnvironment(input) {
+	const env = input.env ?? process.env;
+	const url = new URL(input.apiUrl);
+	assertLoopbackHost(url.hostname);
+	const result = {
+		HOME: input.user.homedir,
+		USER: input.user.username,
+		LOGNAME: input.user.username,
+		PATH: env.PATH?.trim() || "/usr/local/bin:/usr/bin:/bin",
+		TREEPORT_HOST: url.hostname,
+		TREEPORT_PORT: url.port || "80",
+		TREEPORT_API_URL: input.apiUrl,
+		TREEPORT_DATA_DIR: input.paths.dataDir,
+		TREEPORT_RUNTIME_DIR: input.paths.runtimeDir,
+		TREEPORT_CACHE_DIR: cacheDirectory(input.user.homedir, env),
+		TREEPORT_DATABASE_PATH: env.TREEPORT_DATABASE_PATH?.trim() || path.join(input.paths.dataDir, "treeport.db"),
+		TREEPORT_SHELL: env.TREEPORT_SHELL?.trim() || env.SHELL?.trim() || "/bin/sh",
+		TREEPORT_TMUX_PATH: env.TREEPORT_TMUX_PATH?.trim() || "tmux",
+		TREEPORT_GIT_PATH: env.TREEPORT_GIT_PATH?.trim() || "git",
+		TREEPORT_GH_PATH: env.TREEPORT_GH_PATH?.trim() || "gh",
+		TREEPORT_DAEMON_LIFECYCLE: "service",
+		TREEPORT_INSTALLATION_METHOD: input.installationMethod,
+		TREEPORT_SERVICE_RECORD: input.recordPath
+	};
+	for (const [name, value] of Object.entries(env)) if (value !== void 0 && (name === "LANG" || name === "LC_ALL" || name.startsWith("LC_"))) result[name] = value;
+	return result;
+}
+function definitionForRecord(record) {
+	if (record.manager === "launchd") return serializeLaunchdDefinition(createLaunchdDefinition({
+		label: record.definitionName,
+		mode: record.mode,
+		runnerPath: servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).runnerPath,
+		username: record.username,
+		group: record.group,
+		environment: record.environment,
+		home: record.home,
+		logPath: record.logPath
+	}));
+	return serializeSystemdDefinition(createSystemdDefinition({
+		runnerPath: servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).runnerPath,
+		environment: record.environment
+	}));
+}
+function runnerSource(record) {
+	return `#!/bin/sh
+set -u
+entrypoint=${shellQuote$1(record.cliEntrypoint)}
+record=${shellQuote$1(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).recordPath)}
+log=${shellQuote$1(record.logPath)}
+reported=0
+while [ ! -x "$entrypoint" ]; do
+  if [ "$reported" -eq 0 ]; then
+    mkdir -p "$(dirname "$log")"
+    printf '%s Treeport service cannot start because %s is missing. Reinstall Treeport, then run treeport service enable or treeport service disable.\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$entrypoint" >> "$log"
+    reported=1
+  fi
+  sleep 60
+done
+export TREEPORT_SERVICE_RECORD="$record"
+exec "$entrypoint" service run
+`;
+}
+function storedServiceMode(input) {
+	return input.mode ?? (input.manager === "launchd" ? "headless" : "user");
+}
+async function readServiceRecord(recordPath) {
+	const record = await readJson(recordPath, serviceRecordSchema);
+	if (!record) return null;
+	return {
+		...record,
+		mode: storedServiceMode(record)
+	};
+}
+async function currentRecord() {
+	return readServiceRecord(servicePaths().recordPath);
+}
+async function saveRecord(record) {
+	await writeJson$2(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).recordPath, record);
+}
+async function managerState(record) {
+	if (record.manager === "launchd") {
+		const launchctl = await executablePath("launchctl");
+		const location = launchdLocation({
+			uid: record.uid,
+			home: record.home,
+			mode: record.mode
+		});
+		const [active, disabled, definitionExists] = await Promise.all([
+			runCommand$1(launchctl, ["print", location.target]),
+			runCommand$1(launchctl, ["print-disabled", location.domain]),
+			fs.access(record.definitionPath).then(() => true).catch(() => false)
+		]);
+		return {
+			active: active.code === 0,
+			enabled: definitionExists && !disabled.stdout.includes(`"${record.definitionName}" => true`),
+			lingering: true,
+			managerIssue: null
+		};
+	}
+	const systemctl = await executablePath("systemctl");
+	const [active, enabled, linger] = await Promise.all([
+		runCommand$1(systemctl, [
+			"--user",
+			"is-active",
+			record.definitionName
+		]),
+		runCommand$1(systemctl, [
+			"--user",
+			"is-enabled",
+			record.definitionName
+		]),
+		runCommand$1(await executablePath("loginctl"), [
+			"show-user",
+			record.username,
+			"-p",
+			"Linger",
+			"--value"
+		])
+	]);
+	return {
+		active: active.code === 0 && active.stdout.trim() === "active",
+		enabled: enabled.code === 0 && enabled.stdout.trim() === "enabled",
+		lingering: linger.code === 0 && linger.stdout.trim() === "yes",
+		managerIssue: active.code === 127 || active.stderr.includes("Failed to connect to bus") || active.stderr.includes("No medium found") ? "The systemd user manager is not available." : linger.code === 127 ? "loginctl is not available." : null
+	};
+}
+function administratorCommand(record) {
+	const requestId = record.pendingAdministratorRequestId;
+	if (!requestId || !record.runtimeExecutable || !record.runtimeEntrypoint) return null;
+	const requestPath = path.join(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).requestsDirectory, `${requestId}.json`);
+	return createAdministratorCommand({
+		runtimeExecutable: record.runtimeExecutable,
+		runtimeEntrypoint: record.runtimeEntrypoint,
+		requestPath
+	});
+}
+async function untrackedDefinition() {
+	const manager = managerForPlatform();
+	if (!manager) return null;
+	const user = os.userInfo();
+	if (manager === "launchd") {
+		for (const mode of ["headless", "user"]) {
+			const location = launchdLocation({
+				uid: user.uid,
+				home: user.homedir,
+				mode
+			});
+			if (await fs.access(location.path).then(() => true).catch(() => false)) return {
+				manager,
+				mode,
+				...location
+			};
+		}
+		return null;
+	}
+	const name = "treeport.service";
+	const definitionPath = path.join(process.env.XDG_CONFIG_HOME?.trim() || path.join(user.homedir, ".config"), "systemd", "user", name);
+	return await fs.access(definitionPath).then(() => true).catch(() => false) ? {
+		manager,
+		mode: "user",
+		name,
+		path: definitionPath,
+		target: name
+	} : null;
+}
+async function serviceInstalled() {
+	return await currentRecord() !== null || await untrackedDefinition() !== null;
+}
+async function serviceStatus() {
+	const manager = managerForPlatform();
+	const record = await currentRecord();
+	if (!manager) return {
+		supported: false,
+		manager: null,
+		mode: null,
+		state: "disabled",
+		installed: false,
+		enabledAtBoot: false,
+		active: false,
+		healthy: false,
+		rebootReady: false,
+		definitionMatches: false,
+		environmentMatches: false,
+		entrypointMatches: false,
+		requestedState: null,
+		definitionPath: null,
+		entrypoint: null,
+		daemon: null,
+		issues: [`Treeport service mode does not support ${process.platform}.`],
+		recoveryCommands: [],
+		administratorCommand: null
+	};
+	if (!record) {
+		const untracked = await untrackedDefinition();
+		if (!untracked) return {
+			supported: true,
+			manager,
+			mode: null,
+			state: "disabled",
+			installed: false,
+			enabledAtBoot: false,
+			active: false,
+			healthy: false,
+			rebootReady: false,
+			definitionMatches: false,
+			environmentMatches: false,
+			entrypointMatches: false,
+			requestedState: null,
+			definitionPath: null,
+			entrypoint: null,
+			daemon: null,
+			issues: [],
+			recoveryCommands: ["treeport service enable"],
+			administratorCommand: null
+		};
+		const active = untracked.manager === "launchd" ? await runCommand$1(await executablePath("launchctl"), ["print", untracked.target]) : await runCommand$1(await executablePath("systemctl"), [
+			"--user",
+			"is-active",
+			untracked.name
+		]);
+		return {
+			supported: true,
+			manager,
+			mode: untracked.mode,
+			state: "stale",
+			installed: true,
+			enabledAtBoot: untracked.mode === "headless",
+			active: active.code === 0,
+			healthy: false,
+			rebootReady: false,
+			definitionMatches: false,
+			environmentMatches: false,
+			entrypointMatches: false,
+			requestedState: null,
+			definitionPath: untracked.path,
+			entrypoint: null,
+			daemon: null,
+			issues: [`A Treeport ${untracked.mode === "headless" ? "advanced headless " : ""}service definition exists at ${untracked.path}, but its service record is missing. Restore the original Treeport data directory before you manage it.${untracked.mode === "headless" ? " An administrator must approve removal of the system definition." : ""}`],
+			recoveryCommands: [],
+			administratorCommand: null
+		};
+	}
+	const paths = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
+	const [managerStatus, definitionContent, entrypointExists, daemon] = await Promise.all([
+		managerState(record),
+		fs.readFile(record.definitionPath, "utf8").catch(() => ""),
+		fs.access(record.cliEntrypoint, constants.X_OK).then(() => true).catch(() => false),
+		daemonStatus()
+	]);
+	const definitionPresent = definitionContent !== "";
+	const definitionMatches = definitionPresent && fingerprint(definitionContent) === record.definitionHash;
+	const invokedEntrypoint = currentEntrypoint();
+	const entrypointMatches = Boolean(entrypointExists && (invokedEntrypoint === null || path.resolve(invokedEntrypoint) === path.resolve(record.cliEntrypoint)));
+	const environmentMatches = fingerprint(createServiceEnvironment({
+		user: {
+			uid: record.uid,
+			gid: record.gid,
+			username: record.username,
+			homedir: record.home,
+			shell: record.environment.TREEPORT_SHELL ?? null
+		},
+		paths: localPaths({
+			TREEPORT_DATA_DIR: record.dataDir,
+			TREEPORT_RUNTIME_DIR: record.runtimeDir
+		}),
+		apiUrl: record.apiUrl,
+		recordPath: paths.recordPath,
+		installationMethod: record.installationMethod
+	})) === record.environmentHash;
+	const healthy = Boolean(daemon.verified && daemon.health?.daemonLifecycle === "service" && daemon.state?.daemonLifecycle === "service" && path.resolve(daemon.state.dataDir) === path.resolve(record.dataDir));
+	const installed = managerStatus.enabled;
+	const enabledAtBoot = installed && (record.manager === "launchd" ? record.mode === "headless" : managerStatus.lingering);
+	const rebootReady = enabledAtBoot;
+	const pendingCommand = administratorCommand(record) ?? (record.manager === "systemd" && managerStatus.enabled && !managerStatus.lingering ? `sudo loginctl enable-linger ${record.username}` : null);
+	const issues = [];
+	const recoveryCommands = [];
+	const repairCommand = record.manager === "launchd" && record.mode === "headless" ? "treeport service enable --headless" : "treeport service enable";
+	if (record.manager !== manager) issues.push(`The service record uses ${record.manager}, but this host requires ${manager}.`);
+	if (!definitionMatches && !record.pendingAdministratorRequestId) {
+		issues.push(definitionPresent ? `The service definition at ${record.definitionPath} was changed.` : `The service definition is missing at ${record.definitionPath}.`);
+		recoveryCommands.push(repairCommand);
+	}
+	if (definitionMatches && !installed && !record.pendingAdministratorRequestId) {
+		issues.push(record.manager === "launchd" && record.mode === "user" ? "The service definition is not enabled for startup after login." : "The service definition is not enabled for startup after reboot.");
+		recoveryCommands.push(repairCommand);
+	}
+	if (!entrypointMatches) {
+		issues.push(`The service CLI entrypoint is unavailable or moved: ${record.cliEntrypoint}`);
+		recoveryCommands.push(repairCommand);
+	}
+	if (!environmentMatches) {
+		issues.push("The service environment differs from the current Treeport environment.");
+		recoveryCommands.push(repairCommand);
+	}
+	if (record.manager === "systemd" && installed && !managerStatus.lingering) {
+		issues.push(`User lingering is disabled for ${record.username}.`);
+		recoveryCommands.push(`sudo loginctl enable-linger ${record.username}`);
+	}
+	if (managerStatus.managerIssue) issues.push(managerStatus.managerIssue);
+	if (installed && record.requestedState === "running" && !healthy && !record.pendingAdministratorRequestId) {
+		issues.push("The supervised Treeport daemon is not healthy.");
+		recoveryCommands.push("treeport start");
+	}
+	const stale = record.manager !== manager || !definitionMatches || !environmentMatches || !entrypointMatches || definitionPresent && !installed || managerStatus.managerIssue !== null;
+	const state = record.pendingAdministratorRequestId || record.manager === "systemd" && installed && !managerStatus.lingering ? "action_required" : stale ? "stale" : healthy ? "healthy" : installed && record.requestedState === "stopped" ? "stopped" : installed && managerStatus.active ? "starting" : installed ? "unhealthy" : "disabled";
+	return {
+		supported: true,
+		manager,
+		mode: record.mode,
+		state,
+		installed,
+		enabledAtBoot,
+		active: managerStatus.active,
+		healthy,
+		rebootReady,
+		definitionMatches,
+		environmentMatches,
+		entrypointMatches,
+		requestedState: record.requestedState,
+		definitionPath: record.definitionPath,
+		entrypoint: record.cliEntrypoint,
+		daemon,
+		issues,
+		recoveryCommands: [...new Set(recoveryCommands)],
+		administratorCommand: pendingCommand
+	};
+}
+async function prepareRecord(requestedMode) {
+	if (process.getuid?.() === 0) throw new Error("Run `treeport service enable` as the user who will run Treeport, not as root.");
+	const manager = managerForPlatform();
+	if (!manager) throw new Error(`Treeport service mode supports macOS launchd and Linux systemd; found ${process.platform}.`);
+	const explicitApiUrl = process.env.TREEPORT_API_URL?.trim();
+	if (explicitApiUrl) assertLoopbackHost(new URL(explicitApiUrl).hostname);
+	if (manager !== "launchd" && requestedMode === "headless") throw new Error("The `--headless` option is only available for the advanced macOS LaunchDaemon mode.");
+	const mode = manager === "launchd" ? requestedMode : "user";
+	const user = os.userInfo();
+	const paths = localPaths();
+	const locations = servicePaths();
+	const apiUrl = await resolveLocalApiUrl();
+	const listener = new URL(apiUrl);
+	if (listener.protocol !== "http:") throw new Error("Treeport service mode requires a local HTTP loopback URL.");
+	assertLoopbackHost(listener.hostname);
+	const [cliEntrypoint, administratorRuntime] = await Promise.all([ensureEntrypoint(), manager === "launchd" && mode === "headless" ? currentAdministratorRuntime() : Promise.resolve(null)]);
+	const group = await primaryGroup(user.username);
+	const launchd = manager === "launchd" ? launchdLocation({
+		uid: user.uid,
+		home: user.homedir,
+		mode
+	}) : null;
+	const definitionName = launchd?.name ?? "treeport.service";
+	const definitionPath = launchd?.path ?? path.join(process.env.XDG_CONFIG_HOME?.trim() || path.join(user.homedir, ".config"), "systemd", "user", definitionName);
+	const environment = createServiceEnvironment({
+		user,
+		paths,
+		apiUrl,
+		recordPath: locations.recordPath,
+		installationMethod: "npm"
+	});
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const previous = await currentRecord();
+	const untracked = previous ? null : await untrackedDefinition();
+	if (untracked) throw new Error(`A Treeport ${untracked.mode === "headless" ? "advanced headless " : ""}service definition already exists at ${untracked.path}. Restore its original Treeport data directory before you manage or remove it.`);
+	if (previous && path.resolve(previous.dataDir) !== paths.dataDir) throw new Error(`Treeport service mode already uses ${previous.dataDir}. Disable it before enabling ${paths.dataDir}.`);
+	if (previous && previous.mode !== mode) throw new Error(previous.mode === "headless" ? "Treeport uses the advanced headless service mode. Run `treeport service disable` with administrator approval. Then run `treeport service enable` to migrate to user/login mode." : "Treeport uses user/login service mode. Run `treeport service disable` first. Then run `treeport service enable --headless` to select advanced headless mode.");
+	if (previous?.manager === "launchd" && path.resolve(previous.definitionPath) !== path.resolve(definitionPath)) throw new Error(`The service record points to an unexpected definition at ${previous.definitionPath}. Refusing to create another definition.`);
+	const base = {
+		schemaVersion: 1,
+		manager,
+		mode,
+		platform: process.platform,
+		uid: user.uid,
+		gid: user.gid,
+		username: user.username,
+		group,
+		home: user.homedir,
+		dataDir: paths.dataDir,
+		runtimeDir: paths.runtimeDir,
+		logPath: paths.logPath,
+		apiUrl,
+		cliEntrypoint,
+		runtimeExecutable: administratorRuntime?.runtimeExecutable ?? null,
+		runtimeEntrypoint: administratorRuntime?.runtimeEntrypoint ?? null,
+		installationMethod: "npm",
+		definitionName,
+		definitionPath,
+		definitionHash: "0".repeat(64),
+		environmentHash: fingerprint(environment),
+		environment,
+		requestedState: "running",
+		pendingAdministratorRequestId: null,
+		createdAt: previous?.createdAt ?? now,
+		updatedAt: now
+	};
+	const definition = definitionForRecord(base);
+	return {
+		record: {
+			...base,
+			definitionHash: fingerprint(definition)
+		},
+		definition
+	};
+}
+async function writeServiceFiles(record, definition) {
+	const locations = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
+	await fs.mkdir(path.dirname(record.logPath), {
+		recursive: true,
+		mode: 448
+	});
+	if (record.mode === "headless") await fs.mkdir(locations.requestsDirectory, {
+		recursive: true,
+		mode: 448
+	});
+	await fs.writeFile(locations.runnerPath, runnerSource(record), { mode: 448 });
+	await fs.chmod(locations.runnerPath, 448);
+	if (record.manager === "launchd" && record.mode === "headless") await fs.writeFile(locations.stagedDefinitionPath, definition, { mode: 384 });
+	else {
+		await fs.mkdir(path.dirname(record.definitionPath), {
+			recursive: true,
+			mode: 448
+		});
+		const temporaryPath = `${record.definitionPath}.${process.pid}.tmp`;
+		await fs.writeFile(temporaryPath, definition, { mode: 384 });
+		await fs.rename(temporaryPath, record.definitionPath);
+	}
+	await saveRecord(record);
+}
+async function prepareAdministratorRequest(record, operation) {
+	if (record.manager !== "launchd" || record.mode !== "headless") throw new Error("Administrator requests are only available for advanced macOS headless service mode.");
+	const runtime = await currentAdministratorRuntime();
+	const requestRecord = {
+		...record,
+		...runtime
+	};
+	const locations = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
+	const id = crypto.randomUUID();
+	const now = /* @__PURE__ */ new Date();
+	const request = {
+		schemaVersion: 1,
+		id,
+		operation,
+		createdAt: now.toISOString(),
+		expiresAt: new Date(now.getTime() + 15 * 6e4).toISOString(),
+		uid: record.uid,
+		gid: record.gid,
+		username: record.username,
+		group: record.group,
+		home: record.home,
+		serviceRecordPath: locations.recordPath,
+		runnerPath: locations.runnerPath,
+		definitionName: record.definitionName,
+		definitionPath: record.definitionPath,
+		stagedDefinitionPath: locations.stagedDefinitionPath,
+		definitionHash: record.definitionHash,
+		apiUrl: record.apiUrl,
+		cliEntrypoint: record.cliEntrypoint,
+		runtimeExecutable: requestRecord.runtimeExecutable,
+		runtimeEntrypoint: requestRecord.runtimeEntrypoint
+	};
+	await writeJson$2(path.join(locations.requestsDirectory, `${id}.json`), request);
+	const next = {
+		...requestRecord,
+		pendingAdministratorRequestId: id,
+		updatedAt: now.toISOString()
+	};
+	await saveRecord(next);
+	return {
+		record: next,
+		command: administratorCommand(next)
+	};
+}
+async function waitForService(record) {
+	const deadline = Date.now() + 15e3;
+	const version = await treeportVersion();
+	while (Date.now() < deadline) {
+		const observed = await daemonHealth(record.apiUrl, 500);
+		if (observed?.daemonLifecycle === "service" && observed.instanceId && observed.version === version) return;
+		await new Promise((resolve) => setTimeout(resolve, 150));
+	}
+	throw new Error(`Treeport service did not become ready at ${record.apiUrl}. See ${record.logPath}.`);
+}
+async function serviceEnable(mode = "user") {
+	const existing = await serviceStatus();
+	if (existing.mode === mode && existing.state === "healthy" && existing.definitionMatches && existing.environmentMatches && existing.entrypointMatches) return {
+		status: existing,
+		changed: false,
+		administratorCommand: null
+	};
+	const { record, definition } = await prepareRecord(mode);
+	const failedChecks = (await runDoctor()).filter((check) => !check.ok);
+	if (failedChecks.length) throw new Error(failedChecks.map((check) => `${check.name}: ${check.detail}`).join("\n"));
+	const systemctl = record.manager === "systemd" ? await executablePath("systemctl") : null;
+	if (systemctl) {
+		const managerAvailable = await runCommand$1(systemctl, ["--user", "show-environment"]);
+		if (managerAvailable.code !== 0) throw commandError("systemctl --user", managerAvailable);
+	}
+	await writeServiceFiles(record, definition);
+	if (record.manager === "launchd") {
+		if (record.mode === "headless") {
+			await daemonDown();
+			const prepared = await prepareAdministratorRequest(record, "enable");
+			return {
+				status: await serviceStatus(),
+				changed: true,
+				administratorCommand: prepared.command
+			};
+		}
+		const launchctl = await executablePath("launchctl");
+		const location = launchdLocation({
+			uid: record.uid,
+			home: record.home,
+			mode: record.mode
+		});
+		const commands = userLaunchdCommands({
+			operation: "enable",
+			location,
+			definitionPath: record.definitionPath
+		});
+		await runCommand$1(launchctl, commands.bootout);
+		await daemonDown();
+		const enabled = await runCommand$1(launchctl, commands.enable);
+		if (enabled.code !== 0) {
+			await Promise.all([fs.rm(record.definitionPath, { force: true }), fs.rm(servicePaths().directory, {
+				recursive: true,
+				force: true
+			})]);
+			await daemonUp({});
+			throw commandError("launchctl enable", enabled);
+		}
+		const bootstrapped = await runCommand$1(launchctl, commands.activate);
+		if (bootstrapped.code !== 0) {
+			await Promise.all([fs.rm(record.definitionPath, { force: true }), fs.rm(servicePaths().directory, {
+				recursive: true,
+				force: true
+			})]);
+			await daemonUp({});
+			throw commandError("launchctl bootstrap", bootstrapped);
+		}
+		const startupError = await waitForService(record).then(() => null, (error) => error);
+		if (startupError) {
+			await runCommand$1(launchctl, ["bootout", location.target]);
+			await Promise.all([fs.rm(record.definitionPath, { force: true }), fs.rm(servicePaths().directory, {
+				recursive: true,
+				force: true
+			})]);
+			await daemonUp({});
+			throw startupError;
+		}
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: null
+		};
+	}
+	if (!systemctl) throw new Error("Treeport could not resolve the systemd command.");
+	await daemonDown();
+	const reload = await runCommand$1(systemctl, ["--user", "daemon-reload"]);
+	if (reload.code !== 0) {
+		await Promise.all([fs.rm(record.definitionPath, { force: true }), fs.rm(servicePaths().directory, {
+			recursive: true,
+			force: true
+		})]);
+		await daemonUp({});
+		throw commandError("systemctl --user daemon-reload", reload);
+	}
+	const enabled = await runCommand$1(systemctl, [
+		"--user",
+		"enable",
+		"--now",
+		record.definitionName
+	]);
+	if (enabled.code !== 0) {
+		await fs.rm(record.definitionPath, { force: true });
+		await runCommand$1(systemctl, ["--user", "daemon-reload"]);
+		await fs.rm(servicePaths().directory, {
+			recursive: true,
+			force: true
+		});
+		await daemonUp({});
+		throw commandError("systemctl --user enable --now", enabled);
+	}
+	const startupError = await waitForService(record).then(() => null, (error) => error);
+	if (startupError) {
+		await runCommand$1(systemctl, [
+			"--user",
+			"disable",
+			"--now",
+			record.definitionName
+		]);
+		await fs.rm(record.definitionPath, { force: true });
+		await runCommand$1(systemctl, ["--user", "daemon-reload"]);
+		await fs.rm(servicePaths().directory, {
+			recursive: true,
+			force: true
+		});
+		await daemonUp({});
+		throw startupError;
+	}
+	const status = await serviceStatus();
+	return {
+		status,
+		changed: true,
+		administratorCommand: status.administratorCommand
+	};
+}
+async function serviceStart() {
+	const record = await currentRecord();
+	if (!record) throw new Error("Treeport service mode is disabled. Run `treeport service enable` first.");
+	const current = await serviceStatus();
+	if (current.state === "healthy") return {
+		status: current,
+		changed: false,
+		administratorCommand: null
+	};
+	if (current.administratorCommand) return {
+		status: current,
+		changed: false,
+		administratorCommand: current.administratorCommand
+	};
+	if (!current.definitionMatches || !current.entrypointMatches) throw new Error(record.manager === "launchd" && record.mode === "headless" ? "The Treeport service definition is stale. Run `treeport service enable --headless` to repair it." : "The Treeport service definition is stale. Run `treeport service enable` to repair it.");
+	const next = {
+		...record,
+		requestedState: "running",
+		pendingAdministratorRequestId: null,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await saveRecord(next);
+	if (record.manager === "launchd") {
+		if (record.mode === "headless") {
+			const prepared = await prepareAdministratorRequest(next, "start");
+			return {
+				status: await serviceStatus(),
+				changed: true,
+				administratorCommand: prepared.command
+			};
+		}
+		const launchctl = await executablePath("launchctl");
+		const location = launchdLocation({
+			uid: record.uid,
+			home: record.home,
+			mode: record.mode
+		});
+		const active = await runCommand$1(launchctl, ["print", location.target]);
+		const commands = userLaunchdCommands({
+			operation: "start",
+			location,
+			definitionPath: record.definitionPath,
+			active: active.code === 0
+		});
+		const enabled = await runCommand$1(launchctl, commands.enable);
+		if (enabled.code !== 0) {
+			await saveRecord(record);
+			throw commandError("launchctl enable", enabled);
+		}
+		const started = await runCommand$1(launchctl, commands.activate);
+		if (started.code !== 0) {
+			await saveRecord(record);
+			throw commandError("launchctl start", started);
+		}
+		await waitForService(next);
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: null
+		};
+	}
+	const result = await runCommand$1(await executablePath("systemctl"), [
+		"--user",
+		"start",
+		record.definitionName
+	]);
+	if (result.code !== 0) throw commandError("systemctl --user start", result);
+	await waitForService(next);
+	return {
+		status: await serviceStatus(),
+		changed: true,
+		administratorCommand: null
+	};
+}
+async function serviceStop() {
+	const record = await currentRecord();
+	if (!record) throw new Error("Treeport service mode is disabled.");
+	const current = await serviceStatus();
+	if (current.state === "stopped") return {
+		status: current,
+		changed: false,
+		administratorCommand: null
+	};
+	const next = {
+		...record,
+		requestedState: "stopped",
+		pendingAdministratorRequestId: null,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	await saveRecord(next);
+	if (record.manager === "launchd") {
+		if (record.mode === "headless") {
+			const prepared = await prepareAdministratorRequest(next, "stop");
+			return {
+				status: await serviceStatus(),
+				changed: true,
+				administratorCommand: prepared.command
+			};
+		}
+		const commands = userLaunchdCommands({
+			operation: "stop",
+			location: launchdLocation({
+				uid: record.uid,
+				home: record.home,
+				mode: record.mode
+			}),
+			definitionPath: record.definitionPath
+		});
+		const result = await runCommand$1(await executablePath("launchctl"), commands.bootout);
+		if (result.code !== 0 && !result.stderr.includes("No such process")) {
+			await saveRecord(record);
+			throw commandError("launchctl bootout", result);
+		}
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: null
+		};
+	}
+	const result = await runCommand$1(await executablePath("systemctl"), [
+		"--user",
+		"stop",
+		record.definitionName
+	]);
+	if (result.code !== 0) {
+		await saveRecord(record);
+		throw commandError("systemctl --user stop", result);
+	}
+	return {
+		status: await serviceStatus(),
+		changed: true,
+		administratorCommand: null
+	};
+}
+async function serviceDisable() {
+	const record = await currentRecord();
+	if (!record) return {
+		status: await serviceStatus(),
+		changed: false,
+		administratorCommand: null
+	};
+	if (record.manager === "launchd") {
+		if (record.mode === "headless") {
+			const prepared = await prepareAdministratorRequest({
+				...record,
+				pendingAdministratorRequestId: null
+			}, "disable");
+			return {
+				status: await serviceStatus(),
+				changed: true,
+				administratorCommand: prepared.command
+			};
+		}
+		const installed = await fs.readFile(record.definitionPath, "utf8").catch((error) => {
+			if (error.code === "ENOENT") return "";
+			throw error;
+		});
+		if (installed && fingerprint(installed) !== record.definitionHash) throw new Error("Refusing to remove a LaunchAgent definition that Treeport did not create.");
+		const commands = userLaunchdCommands({
+			operation: "disable",
+			location: launchdLocation({
+				uid: record.uid,
+				home: record.home,
+				mode: record.mode
+			}),
+			definitionPath: record.definitionPath
+		});
+		const stopped = await runCommand$1(await executablePath("launchctl"), commands.bootout);
+		if (stopped.code !== 0 && !stopped.stderr.includes("No such process")) throw commandError("launchctl bootout", stopped);
+		await fs.rm(record.definitionPath, { force: true });
+		await fs.rm(servicePaths().directory, {
+			recursive: true,
+			force: true
+		});
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: null
+		};
+	}
+	const systemctl = await executablePath("systemctl");
+	const disabled = await runCommand$1(systemctl, [
+		"--user",
+		"disable",
+		"--now",
+		record.definitionName
+	]);
+	if (disabled.code !== 0 && !disabled.stderr.includes("does not exist")) throw commandError("systemctl --user disable --now", disabled);
+	await fs.rm(record.definitionPath, { force: true });
+	await runCommand$1(systemctl, ["--user", "daemon-reload"]);
+	await fs.rm(servicePaths().directory, {
+		recursive: true,
+		force: true
+	});
+	return {
+		status: await serviceStatus(),
+		changed: true,
+		administratorCommand: null
+	};
+}
+async function serviceApply(requestPath) {
+	if (process.platform !== "darwin") throw new Error("Treeport service apply is only available for macOS LaunchDaemons.");
+	if (process.getuid?.() !== 0) throw new Error("Run the printed service apply command with sudo or as root.");
+	if (!path.isAbsolute(requestPath)) throw new Error("The service apply request path must be absolute.");
+	const metadata = await fs.lstat(requestPath);
+	if (!metadata.isFile() || metadata.isSymbolicLink()) throw new Error("The service apply request must be a regular file, not a symlink.");
+	if ((metadata.mode & 63) !== 0) throw new Error("The service apply request must not be readable or writable by other users.");
+	const request = await readJson(requestPath, administratorRequestSchema);
+	if (!request) throw new Error("The service apply request is invalid.");
+	if (metadata.uid !== request.uid) throw new Error("The service apply request owner does not match its target user.");
+	if (Date.parse(request.expiresAt) <= Date.now()) throw new Error("The service apply request expired. Run the original Treeport command again.");
+	const currentRuntime = await currentAdministratorRuntime().catch(() => null);
+	const invokedRuntimeEntrypoint = process.argv[1] ? path.resolve(process.argv[1]) : null;
+	if (!currentRuntime || currentRuntime.runtimeExecutable !== request.runtimeExecutable || currentRuntime.runtimeEntrypoint !== request.runtimeEntrypoint || invokedRuntimeEntrypoint !== request.runtimeEntrypoint) throw new Error("The service apply command did not use the approved Treeport Node runtime and package entrypoint.");
+	const usedPath = `${requestPath}.used`;
+	if (await fs.access(usedPath).then(() => true).catch(() => false)) throw new Error("The service apply request was already used.");
+	const account = os.userInfo({ encoding: "utf8" });
+	const idResult = await runCommand$1(await executablePath("id"), ["-u", request.username]);
+	if (idResult.code !== 0 || Number(idResult.stdout.trim()) !== request.uid) throw new Error("The service apply target user no longer matches the host account.");
+	const record = await readServiceRecord(request.serviceRecordPath);
+	if (!record || record.uid !== request.uid || record.username !== request.username || record.manager !== "launchd" || record.mode !== "headless" || record.definitionName !== request.definitionName || record.definitionPath !== request.definitionPath || record.cliEntrypoint !== request.cliEntrypoint || record.runtimeExecutable !== request.runtimeExecutable || record.runtimeEntrypoint !== request.runtimeEntrypoint || record.definitionHash !== request.definitionHash || record.pendingAdministratorRequestId !== request.id) throw new Error("The service apply request does not match the current Treeport service record.");
+	if (account.uid !== 0) throw new Error("Treeport service apply lost root privileges.");
+	const launchctl = await executablePath("launchctl");
+	const target = `system/${request.definitionName}`;
+	if (request.operation === "enable") {
+		const staged = await fs.readFile(request.stagedDefinitionPath, "utf8");
+		if (fingerprint(staged) !== request.definitionHash || !staged.includes(`<string>${xml(request.username)}</string>`) || !staged.includes(`<string>${xml(request.runnerPath)}</string>`)) throw new Error("The staged LaunchDaemon definition does not match the approved request.");
+		const temporaryPath = `${request.definitionPath}.${process.pid}.tmp`;
+		await fs.copyFile(request.stagedDefinitionPath, temporaryPath);
+		await fs.chown(temporaryPath, 0, 0);
+		await fs.chmod(temporaryPath, 420);
+		await fs.rename(temporaryPath, request.definitionPath);
+		await runCommand$1(launchctl, ["bootout", target]);
+		const enabled = await runCommand$1(launchctl, ["enable", target]);
+		if (enabled.code !== 0) throw commandError("launchctl enable", enabled);
+		const bootstrapped = await runCommand$1(launchctl, [
+			"bootstrap",
+			"system",
+			request.definitionPath
+		]);
+		if (bootstrapped.code !== 0) throw commandError("launchctl bootstrap", bootstrapped);
+	} else if (request.operation === "start") {
+		const enabled = await runCommand$1(launchctl, ["enable", target]);
+		if (enabled.code !== 0) throw commandError("launchctl enable", enabled);
+		const started = (await runCommand$1(launchctl, ["print", target])).code === 0 ? await runCommand$1(launchctl, ["kickstart", target]) : await runCommand$1(launchctl, [
+			"bootstrap",
+			"system",
+			request.definitionPath
+		]);
+		if (started.code !== 0) throw commandError("launchctl start", started);
+	} else if (request.operation === "stop") {
+		const stopped = await runCommand$1(launchctl, ["bootout", target]);
+		if (stopped.code !== 0 && !stopped.stderr.includes("No such process")) throw commandError("launchctl bootout", stopped);
+	} else {
+		const installed = await fs.readFile(request.definitionPath, "utf8").catch(() => "");
+		if (installed && fingerprint(installed) !== request.definitionHash) throw new Error("Refusing to remove a LaunchDaemon definition that Treeport did not create.");
+		await runCommand$1(launchctl, ["bootout", target]);
+		await fs.rm(request.definitionPath, { force: true });
+	}
+	if (request.operation === "enable" || request.operation === "start") await waitForService(record);
+	await fs.rename(requestPath, usedPath);
+	if (request.operation === "disable") await fs.rm(path.dirname(request.serviceRecordPath), {
+		recursive: true,
+		force: true
+	});
+	else {
+		await writeJson$2(request.serviceRecordPath, {
+			...record,
+			requestedState: request.operation === "stop" ? "stopped" : "running",
+			pendingAdministratorRequestId: null,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		await fs.chown(request.serviceRecordPath, request.uid, request.gid);
+	}
+	return {
+		operation: request.operation,
+		applied: true
+	};
+}
+async function serviceRun() {
+	const recordPath = process.env.TREEPORT_SERVICE_RECORD?.trim();
+	if (!recordPath || !path.isAbsolute(recordPath)) throw new Error("Treeport service run requires a valid service record.");
+	const record = await readServiceRecord(recordPath);
+	if (!record) throw new Error(`Treeport service record is invalid: ${recordPath}`);
+	if (process.getuid?.() === 0 || process.getuid?.() !== record.uid) throw new Error(`Treeport service must run as ${record.username} (UID ${record.uid}), never as root.`);
+	await writeJson$2(recordPath, {
+		...record,
+		requestedState: "running",
+		pendingAdministratorRequestId: null,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	const [version, serverEntry, webDist] = await Promise.all([
+		treeportVersion(),
+		resolvePackagePath("dist", "node", "server", "index.js"),
+		resolvePackagePath("dist", "web")
+	]);
+	Object.assign(process.env, record.environment, {
+		TREEPORT_APP_VERSION: version,
+		TREEPORT_INSTANCE_ID: crypto.randomUUID(),
+		TREEPORT_WEB_DIST: webDist,
+		TREEPORT_DAEMON_LIFECYCLE: "service"
+	});
+	await import(pathToFileURL(serverEntry).href);
+}
+async function readServiceLogs(lines) {
+	const record = await currentRecord();
+	if (!record || record.manager === "launchd") return (await fs.readFile(record?.logPath ?? localPaths().logPath, "utf8").catch((error) => {
+		if (error.code === "ENOENT") return "";
+		throw error;
+	})).split("\n").slice(-lines - 1).join("\n");
+	const result = await runCommand$1(await executablePath("journalctl"), [
+		"--user",
+		"--unit",
+		record.definitionName,
+		"--no-pager",
+		"--lines",
+		String(lines)
+	]);
+	if (result.code !== 0) throw commandError("journalctl --user", result);
+	return result.stdout;
+}
+async function serviceDoctorCheck() {
+	const status = await serviceStatus();
+	if (!status.supported) return {
+		name: "Service supervision",
+		ok: false,
+		detail: status.issues.join(" ")
+	};
+	if (status.state === "disabled") return {
+		name: "Service supervision",
+		ok: true,
+		detail: "disabled (opt in with `treeport service enable`)"
+	};
+	if (status.state === "healthy") return {
+		name: "Service supervision",
+		ok: true,
+		detail: status.mode === "headless" ? `${status.manager}; advanced headless mode; healthy` : `${status.manager}; user service mode; healthy`
+	};
+	if (status.state === "stopped") return {
+		name: "Service supervision",
+		ok: true,
+		detail: status.mode === "headless" ? `${status.manager}; advanced headless mode; intentionally stopped` : `${status.manager}; user service mode; intentionally stopped`
+	};
+	return {
+		name: "Service supervision",
+		ok: false,
+		detail: status.issues.join(" ") || `state: ${status.state}`
+	};
+}
+//#endregion
+//#region src/server/update-startup.ts
+const pendingSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	operationId: z.string().uuid(),
+	targetVersion: z.string(),
+	createdAt: z.string()
+});
+function updatePaths(dataDir) {
+	const directory = path.join(dataDir, "updates");
+	return {
+		pending: path.join(directory, "pending-startup.json"),
+		report: path.join(directory, "startup-report.json")
+	};
+}
+async function writeJson$1(filePath, value) {
+	await fs.mkdir(path.dirname(filePath), {
+		recursive: true,
+		mode: 448
+	});
+	const temporaryPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	await fs.writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 384 });
+	await fs.rename(temporaryPath, filePath);
+}
+async function createUpdateStartupReporter(config) {
+	const paths = updatePaths(config.dataDir);
+	const pending = await fs.readFile(paths.pending, "utf8").then((value) => pendingSchema.safeParse(JSON.parse(value))).then((result) => result.success ? result.data : null).catch(() => null);
+	const active = pending && pending.targetVersion === config.appVersion ? pending : null;
+	const report = active ? {
+		schemaVersion: 1,
+		operationId: active.operationId,
+		targetVersion: active.targetVersion,
+		instanceId: config.instanceId ?? null,
+		migrationState: "not_started",
+		ready: false,
+		error: null,
+		logPath: path.join(config.dataDir, "logs", "daemon.log"),
+		snapshotPaths: [],
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	} : null;
+	const save = async () => {
+		if (!report) return;
+		report.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+		await writeJson$1(paths.report, report);
+	};
+	await save();
+	return {
+		async databaseOpening() {
+			if (report) {
+				report.migrationState = "unknown";
+				await save();
+			}
+		},
+		async databaseOpened(input) {
+			if (report) {
+				report.migrationState = input.migrationState;
+				report.snapshotPaths = input.snapshotPaths;
+				await save();
+			}
+		},
+		async ready() {
+			if (report) {
+				report.ready = true;
+				report.error = null;
+				await save();
+				await fs.rm(paths.pending, { force: true });
+			}
+		},
+		async failed(error) {
+			if (report) {
+				report.error = error.message;
+				await save();
+			}
+		}
+	};
+}
+async function readUpdateStartupReport(dataDir) {
+	const schema = z.strictObject({
+		schemaVersion: z.literal(1),
+		operationId: z.string().uuid(),
+		targetVersion: z.string(),
+		instanceId: z.string().nullable(),
+		migrationState: z.enum([
+			"not_started",
+			"unchanged",
+			"advanced",
+			"unknown"
+		]),
+		ready: z.boolean(),
+		error: z.string().nullable(),
+		logPath: z.string(),
+		snapshotPaths: z.array(z.string()),
+		updatedAt: z.string()
+	});
+	return fs.readFile(updatePaths(dataDir).report, "utf8").then((value) => schema.safeParse(JSON.parse(value))).then((result) => result.success ? result.data : null).catch(() => null);
+}
+//#endregion
+//#region src/cli/update.ts
+const PACKAGE_NAME = "@treeport/treeport";
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const DESTRUCTIVE_PHASES = /* @__PURE__ */ new Set([
+	"stop",
+	"activate",
+	"restart",
+	"health_check",
+	"rollback",
+	"recovery_required"
+]);
+const operationSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	operationId: z.string().uuid(),
+	phase: z.enum([
+		"inspect",
+		"resolve",
+		"stage",
+		"verify",
+		"stop",
+		"activate",
+		"restart",
+		"health_check",
+		"rollback",
+		"complete",
+		"recovery_required"
+	]),
+	fromVersion: z.string(),
+	toVersion: z.string().nullable(),
+	npmPrefix: z.string().nullable(),
+	activeTarget: z.string().nullable(),
+	stagedTarget: z.string().nullable(),
+	previousTarget: z.string().nullable(),
+	daemonWasRunning: z.boolean(),
+	daemonLifecycle: z.enum(["treeport", "service"]).nullable(),
+	serviceMode: z.enum(["user", "headless"]).nullable(),
+	terminalIds: z.array(z.string()),
+	activated: z.boolean(),
+	migrationState: z.enum([
+		"not_started",
+		"unchanged",
+		"advanced",
+		"unknown"
+	]),
+	rollbackAttempted: z.boolean(),
+	rollbackSucceeded: z.boolean(),
+	recoveryAction: z.string().nullable(),
+	updatedAt: z.string()
+});
+const lockSchema = z.strictObject({
+	operationId: z.string().uuid(),
+	pid: z.number().int().positive(),
+	fromVersion: z.string(),
+	startedAt: z.string()
+});
+const packageSchema = z.looseObject({
+	name: z.literal(PACKAGE_NAME),
+	version: z.string()
+});
+const releaseSchema = z.looseObject({
+	name: z.literal(PACKAGE_NAME),
+	version: z.string(),
+	dist: z.looseObject({
+		tarball: z.string().url(),
+		integrity: z.string().min(1)
+	})
+});
+const packedReleaseSchema = z.tuple([z.looseObject({
+	filename: z.string().min(1),
+	integrity: z.string().min(1)
+})]);
+var LocalUpdateError = class extends Error {
+	code;
+	details;
+	exitCode;
+	constructor(code, message, details, exitCode) {
+		super(message);
+		this.code = code;
+		this.details = details;
+		this.exitCode = exitCode ?? ([
+			"UPDATE_INSTALLATION_UNSUPPORTED",
+			"UPDATE_INSTALLATION_NOT_WRITABLE",
+			"UPDATE_REMOTE_REFUSED",
+			"UPDATE_EXTERNAL_REFUSED",
+			"UPDATE_IN_PROGRESS",
+			"UPDATE_DOWNGRADE_REFUSED",
+			"UPDATE_DAEMON_OWNERSHIP_FAILED",
+			"UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED"
+		].includes(code) ? 5 : 1);
+	}
+};
+function processExists(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+function shellQuote(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+async function runCommand(executable, args, environment) {
+	return new Promise((resolve) => {
+		const child = spawn(executable, args, {
+			env: environment,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdout.on("data", (value) => {
+			stdout += value;
+		});
+		child.stderr.on("data", (value) => {
+			stderr += value;
+		});
+		child.once("error", (error) => {
+			resolve({
+				code: 127,
+				stdout,
+				stderr: error.message
+			});
+		});
+		child.once("close", (code) => {
+			resolve({
+				code: code ?? 1,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+function commandFailure(command, result) {
+	const detail = [result.stderr.trim(), result.stdout.trim()].filter(Boolean).join("\n");
+	return `${command} failed${detail ? `: ${detail}` : ` with status ${result.code}`}`;
+}
+async function writeJson(filePath, value) {
+	await fs.mkdir(path.dirname(filePath), {
+		recursive: true,
+		mode: 448
+	});
+	const temporaryPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	await fs.writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { mode: 384 });
+	await fs.rename(temporaryPath, filePath);
+}
+async function readOperation(filePath) {
+	return fs.readFile(filePath, "utf8").then((value) => operationSchema.safeParse(JSON.parse(value))).then((result) => result.success ? result.data : null).catch(() => null);
+}
+async function readLocalUpdateProgress(dataDir) {
+	const updateDirectory = path.join(dataDir, "updates");
+	const [operation, lock] = await Promise.all([readOperation(path.join(updateDirectory, "operation.json")), fs.readFile(path.join(updateDirectory, "update.lock"), "utf8").then((value) => lockSchema.safeParse(JSON.parse(value))).then((result) => result.success ? result.data : null).catch(() => null)]);
+	const active = Boolean(lock && processExists(lock.pid));
+	const operationMatchesLock = !lock || operation?.operationId === lock.operationId;
+	return {
+		active,
+		operationId: operationMatchesLock ? operation?.operationId ?? lock?.operationId ?? null : lock?.operationId ?? null,
+		phase: operationMatchesLock ? operation?.phase ?? null : null,
+		fromVersion: operationMatchesLock ? operation?.fromVersion ?? lock?.fromVersion ?? null : lock?.fromVersion ?? null,
+		toVersion: operationMatchesLock ? operation?.toVersion ?? null : null,
+		recoveryAction: operationMatchesLock ? operation?.recoveryAction ?? null : null,
+		migrationState: operationMatchesLock ? operation?.migrationState ?? null : null
+	};
+}
+function isCanonicalTreeportVersion(version) {
+	return VERSION.test(version);
+}
+function compareTreeportVersions(left, right) {
+	const leftMatch = VERSION.exec(left);
+	const rightMatch = VERSION.exec(right);
+	if (!leftMatch || !rightMatch) throw new LocalUpdateError("UPDATE_RELEASE_INVALID", `Treeport update requires canonical stable versions; found ${left} and ${right}.`, {
+		fromVersion: left,
+		toVersion: right
+	});
+	for (let index = 1; index <= 3; index += 1) {
+		const difference = Number(leftMatch[index]) - Number(rightMatch[index]);
+		if (difference !== 0) return difference;
+	}
+	return 0;
+}
+async function replaceSymlink(linkPath, target) {
+	const temporaryPath = `${linkPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	await fs.symlink(target, temporaryPath);
+	await fs.rename(temporaryPath, linkPath);
+}
+async function terminalIds(apiUrl) {
+	const result = await fetch(`${apiUrl}/api/projects`).then(async (response) => response.ok ? response.json() : null).catch(() => null);
+	const parsed = z.looseObject({ projects: z.array(z.looseObject({ worktrees: z.array(z.looseObject({ terminals: z.array(z.looseObject({ id: z.string() })) })) })) }).safeParse(result);
+	if (!parsed.success) throw new Error("Treeport could not read the terminal inventory.");
+	return parsed.data.projects.flatMap((project) => project.worktrees).flatMap((worktree) => worktree.terminals).map((terminal) => terminal.id).sort();
+}
+async function startThroughStableEntrypoint(entrypoint, environment) {
+	const result = await runCommand(entrypoint, ["start", "--json"], environment);
+	if (result.code !== 0) throw new Error(commandFailure("treeport start", result));
+}
+async function inspectLocalUpdateInstallation(environment = process.env) {
+	const entrypointValue = environment.TREEPORT_CLI_ENTRYPOINT?.trim();
+	if (!entrypointValue || !path.isAbsolute(entrypointValue)) throw new LocalUpdateError("UPDATE_INSTALLATION_UNSUPPORTED", "Treeport could not identify a stable npm CLI entrypoint. Reinstall Treeport globally with npm, then retry.", { phase: "inspect" });
+	const npm = await runCommand("npm", ["prefix", "--global"], environment);
+	if (npm.code !== 0 || !npm.stdout.trim()) throw new LocalUpdateError("UPDATE_INSTALLATION_UNSUPPORTED", commandFailure("npm prefix --global", npm), { phase: "inspect" });
+	const prefix = path.resolve(npm.stdout.trim());
+	const entrypoint = path.resolve(entrypointValue);
+	if (entrypoint !== path.join(prefix, "bin", "treeport")) throw new LocalUpdateError("UPDATE_INSTALLATION_UNSUPPORTED", `The active Treeport command is not in the current global npm prefix: ${entrypoint}`, {
+		phase: "inspect",
+		entrypoint,
+		npmPrefix: prefix
+	});
+	const packageDirectory = path.dirname(await resolvePackagePath("package.json"));
+	const directPackage = path.join(prefix, "lib", "node_modules", "@treeport", "treeport");
+	const managedRoot = path.join(prefix, "lib", "treeport");
+	const currentLink = path.join(managedRoot, "current");
+	const managedPackage = path.join(currentLink, "lib", "node_modules", "@treeport", "treeport");
+	const [actualPackage, actualDirect, actualManaged] = await Promise.all([
+		fs.realpath(packageDirectory),
+		fs.realpath(directPackage).catch(() => null),
+		fs.realpath(managedPackage).catch(() => null)
+	]);
+	if (actualPackage !== actualDirect && actualPackage !== actualManaged) throw new LocalUpdateError("UPDATE_INSTALLATION_UNSUPPORTED", "The active Treeport package does not belong to the current global npm prefix. Reinstall Treeport globally with npm, then retry.", {
+		phase: "inspect",
+		npmPrefix: prefix
+	});
+	const manifest = await fs.readFile(path.join(packageDirectory, "package.json"), "utf8").then((value) => packageSchema.safeParse(JSON.parse(value))).catch(() => null);
+	if (!manifest?.success || !VERSION.test(manifest.data.version)) throw new LocalUpdateError("UPDATE_INSTALLATION_UNSUPPORTED", "The active Treeport package manifest is invalid.", { phase: "inspect" });
+	await Promise.all([
+		fs.access(entrypoint, constants.X_OK),
+		fs.access(process.execPath, constants.X_OK),
+		fs.mkdir(managedRoot, {
+			recursive: true,
+			mode: 448
+		}),
+		fs.mkdir(path.join(managedRoot, "versions"), {
+			recursive: true,
+			mode: 448
+		})
+	]).catch((error) => {
+		throw new LocalUpdateError("UPDATE_INSTALLATION_NOT_WRITABLE", "The global npm installation is not writable. Install Node and npm under your user account, reinstall Treeport globally, and retry.", {
+			phase: "inspect",
+			npmPrefix: prefix,
+			cause: error instanceof Error ? error.message : String(error)
+		});
+	});
+	const writeProbe = path.join(path.dirname(entrypoint), `.treeport-update-${process.pid}-${crypto.randomUUID()}`);
+	await fs.writeFile(writeProbe, "", {
+		mode: 384,
+		flag: "wx"
+	}).then(() => fs.rename(writeProbe, `${writeProbe}.renamed`)).then(() => fs.rm(`${writeProbe}.renamed`, { force: true })).catch(async (error) => {
+		await fs.rm(writeProbe, { force: true });
+		await fs.rm(`${writeProbe}.renamed`, { force: true });
+		throw new LocalUpdateError("UPDATE_INSTALLATION_NOT_WRITABLE", "The global npm bin directory is not writable. Install Node and npm under your user account, reinstall Treeport globally, and retry.", {
+			phase: "inspect",
+			npmPrefix: prefix,
+			cause: error instanceof Error ? error.message : String(error)
+		});
+	});
+	return {
+		prefix,
+		packageDirectory,
+		entrypoint,
+		version: manifest.data.version,
+		managedRoot,
+		currentLink,
+		versionsDirectory: path.join(managedRoot, "versions"),
+		managed: actualPackage === actualManaged
+	};
+}
+async function resolveLatestTreeportRelease(environment = process.env, operationId) {
+	const releaseCommand = await runCommand("npm", [
+		"view",
+		`${PACKAGE_NAME}@latest`,
+		"--json"
+	], environment);
+	if (releaseCommand.code !== 0) throw new LocalUpdateError("UPDATE_RELEASE_RESOLUTION_FAILED", commandFailure("npm view", releaseCommand), operationId ? {
+		phase: "resolve",
+		operationId
+	} : { phase: "resolve" });
+	const release = await Promise.resolve(releaseCommand.stdout).then((value) => releaseSchema.safeParse(JSON.parse(value))).catch(() => null);
+	if (!release?.success || !VERSION.test(release.data.version)) throw new LocalUpdateError("UPDATE_RELEASE_INVALID", "npm returned an invalid Treeport stable release.", operationId ? {
+		phase: "resolve",
+		operationId
+	} : { phase: "resolve" });
+	return release.data;
+}
+async function runLocalUpdate(options = {}) {
+	const environment = options.environment ?? process.env;
+	const progress = options.progress ?? (() => void 0);
+	const explicitApiUrl = environment.TREEPORT_API_URL?.trim();
+	if (explicitApiUrl) {
+		const parsed = URL.canParse(explicitApiUrl) ? new URL(explicitApiUrl) : null;
+		if (!parsed || ![
+			"127.0.0.1",
+			"localhost",
+			"::1",
+			"[::1]"
+		].includes(parsed.hostname)) throw new LocalUpdateError("UPDATE_REMOTE_REFUSED", "Run `treeport update` on the computer that owns the selected Treeport daemon.", {
+			phase: "inspect",
+			apiUrl: explicitApiUrl
+		});
+	}
+	if (environment.TREEPORT_DAEMON_LIFECYCLE?.trim() === "external") throw new LocalUpdateError("UPDATE_EXTERNAL_REFUSED", "Cannot update Treeport because this daemon lifecycle is externally managed.", { phase: "inspect" });
+	const paths = localPaths(environment);
+	const updateDirectory = path.join(paths.dataDir, "updates");
+	const lockPath = path.join(updateDirectory, "update.lock");
+	const operationPath = path.join(updateDirectory, "operation.json");
+	await fs.mkdir(updateDirectory, {
+		recursive: true,
+		mode: 448
+	});
+	const operationId = crypto.randomUUID();
+	const staleOperation = await readOperation(operationPath);
+	const provisionalVersion = await fs.readFile(await resolvePackagePath("package.json"), "utf8").then((value) => packageSchema.parse(JSON.parse(value)).version);
+	const lock = {
+		operationId,
+		pid: process.pid,
+		fromVersion: provisionalVersion,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	if (!await fs.open(lockPath, "wx", 384).then(async (file) => {
+		await file.writeFile(`${JSON.stringify(lock)}\n`);
+		await file.close();
+		return true;
+	}).catch(async (error) => {
+		if (error.code !== "EEXIST") throw error;
+		const owner = await fs.readFile(lockPath, "utf8").then((value) => lockSchema.safeParse(JSON.parse(value))).then((result) => result.success ? result.data : null).catch(() => null);
+		if (owner && processExists(owner.pid)) throw new LocalUpdateError("UPDATE_IN_PROGRESS", `Treeport update ${owner.operationId} is already running.`, {
+			phase: "inspect",
+			operationId: owner.operationId
+		});
+		await fs.rm(lockPath, { force: true });
+		const file = await fs.open(lockPath, "wx", 384);
+		await file.writeFile(`${JSON.stringify(lock)}\n`);
+		await file.close();
+		return true;
+	})) throw new LocalUpdateError("UPDATE_IN_PROGRESS", "Another Treeport update is already running.", { phase: "inspect" });
+	let interrupted = false;
+	const interrupt = () => {
+		interrupted = true;
+	};
+	process.on("SIGINT", interrupt);
+	process.on("SIGTERM", interrupt);
+	let operation = {
+		schemaVersion: 1,
+		operationId,
+		phase: "inspect",
+		fromVersion: provisionalVersion,
+		toVersion: null,
+		npmPrefix: null,
+		activeTarget: null,
+		stagedTarget: null,
+		previousTarget: null,
+		daemonWasRunning: false,
+		daemonLifecycle: null,
+		serviceMode: null,
+		terminalIds: [],
+		activated: false,
+		migrationState: "not_started",
+		rollbackAttempted: false,
+		rollbackSucceeded: false,
+		recoveryAction: null,
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	let recoveryOperation = null;
+	const save = async (phase) => {
+		operation = {
+			...operation,
+			phase,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		if (recoveryOperation && !DESTRUCTIVE_PHASES.has(phase)) return;
+		await writeJson(operationPath, operation);
+	};
+	let installation = null;
+	try {
+		installation = await inspectLocalUpdateInstallation(environment);
+		operation = {
+			...operation,
+			fromVersion: installation.version,
+			npmPrefix: installation.prefix,
+			activeTarget: installation.managed ? await fs.realpath(installation.currentLink).catch(() => installation.prefix) : installation.prefix
+		};
+		if (staleOperation && staleOperation.daemonWasRunning && DESTRUCTIVE_PHASES.has(staleOperation.phase) && !(await daemonStatus()).running) {
+			const staleReport = await readUpdateStartupReport(paths.dataDir);
+			if (Boolean(staleReport?.operationId === staleOperation.operationId && ["advanced", "unknown"].includes(staleReport.migrationState))) {
+				if (staleOperation.previousTarget && operation.activeTarget === staleOperation.previousTarget) throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "The older Treeport version is active after a database migration may have started. Treeport will not start it.", {
+					phase: "recovery_required",
+					operationId: staleOperation.operationId,
+					migrationState: staleReport?.migrationState ?? "unknown",
+					recovery: "Install the same or a newer Treeport release and inspect the daemon log."
+				});
+				recoveryOperation = staleOperation;
+			} else {
+				if (staleOperation.previousTarget) await replaceSymlink(installation.currentLink, staleOperation.previousTarget);
+				await fs.rm(path.join(updateDirectory, "pending-startup.json"), { force: true });
+				await fs.rm(path.join(updateDirectory, "startup-report.json"), { force: true });
+				await startThroughStableEntrypoint(installation.entrypoint, environment).catch((error) => {
+					throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport restored the previous version but could not restart its daemon.", {
+						phase: "recovery_required",
+						operationId: staleOperation.operationId,
+						cause: error instanceof Error ? error.message : String(error),
+						recovery: "Inspect the daemon log, then run `treeport start`."
+					});
+				});
+				await writeJson(operationPath, {
+					...staleOperation,
+					phase: "complete",
+					activated: false,
+					rollbackAttempted: true,
+					rollbackSucceeded: true,
+					recoveryAction: "Run `treeport update` again.",
+					updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+				throw new LocalUpdateError("UPDATE_ROLLED_BACK", "Treeport recovered the interrupted update and restored the previous running version. Run `treeport update` again.", {
+					phase: "rollback",
+					operationId: staleOperation.operationId,
+					migrationState: staleReport?.migrationState ?? "not_started",
+					rollback: {
+						attempted: true,
+						safe: true,
+						succeeded: true
+					},
+					recovery: "Run `treeport update` again."
+				});
+			}
+		}
+		await save("inspect");
+		const initialDaemon = await daemonStatus();
+		if (initialDaemon.state && !initialDaemon.verified) throw new LocalUpdateError("UPDATE_DAEMON_OWNERSHIP_FAILED", "Treeport found a daemon whose ownership or health could not be verified.", {
+			phase: "inspect",
+			operationId,
+			pid: initialDaemon.state.pid
+		});
+		if (initialDaemon.health?.daemonLifecycle === "external") throw new LocalUpdateError("UPDATE_EXTERNAL_REFUSED", "Cannot update Treeport because this daemon lifecycle is externally managed.", {
+			phase: "inspect",
+			operationId
+		});
+		if (explicitApiUrl && initialDaemon.state) {
+			const selectedUrl = new URL(explicitApiUrl);
+			const localUrl = new URL(initialDaemon.state.apiUrl);
+			if (selectedUrl.protocol !== localUrl.protocol || (selectedUrl.port || "80") !== (localUrl.port || "80")) throw new LocalUpdateError("UPDATE_REMOTE_REFUSED", "The selected daemon is not the verified local Treeport daemon. Run the update against the local daemon.", {
+				phase: "inspect",
+				operationId,
+				apiUrl: explicitApiUrl
+			});
+		}
+		const installedService = await serviceInstalled();
+		const serviceBefore = installedService ? await serviceStatus() : null;
+		if (serviceBefore?.mode === "headless" && (serviceBefore.active || initialDaemon.running)) throw new LocalUpdateError("UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED", "Stop the advanced headless service with its administrator action, then run `treeport update` again.", {
+			phase: "inspect",
+			operationId,
+			mode: "headless"
+		});
+		if (installedService && initialDaemon.running && initialDaemon.health?.daemonLifecycle !== "service") throw new LocalUpdateError("UPDATE_DAEMON_OWNERSHIP_FAILED", "The running daemon does not belong to the installed Treeport service lifecycle.", {
+			phase: "inspect",
+			operationId
+		});
+		await save("resolve");
+		progress("Resolving the latest Treeport release…");
+		const release = await resolveLatestTreeportRelease(environment, operationId);
+		operation.toVersion = release.version;
+		const comparison = compareTreeportVersions(release.version, installation.version);
+		if (comparison < 0) throw new LocalUpdateError("UPDATE_DOWNGRADE_REFUSED", `Treeport will not downgrade from ${installation.version} to ${release.version}.`, {
+			phase: "resolve",
+			operationId
+		});
+		if (comparison === 0 && recoveryOperation) throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport needs a newer release to recover after the interrupted database migration.", {
+			phase: "recovery_required",
+			operationId: recoveryOperation.operationId,
+			migrationState: recoveryOperation.migrationState,
+			recovery: "Install the next Treeport release when it is available and run `treeport update` again."
+		});
+		if (comparison === 0) {
+			const currentTerminals = initialDaemon.verified ? await terminalIds(initialDaemon.state.apiUrl) : [];
+			const currentLifecycle = initialDaemon.verified ? initialDaemon.health.daemonLifecycle === "service" ? "service" : initialDaemon.health.daemonLifecycle === "treeport" ? "treeport" : null : installedService ? "service" : "treeport";
+			await save("complete");
+			return {
+				schemaVersion: 1,
+				operationId,
+				status: "current",
+				phase: "complete",
+				fromVersion: installation.version,
+				toVersion: release.version,
+				installation: { method: "npm" },
+				daemon: {
+					wasRunning: initialDaemon.verified,
+					lifecycle: currentLifecycle,
+					restarted: false,
+					healthy: initialDaemon.verified,
+					version: initialDaemon.health?.version ?? null
+				},
+				terminals: {
+					before: currentTerminals.length,
+					after: currentTerminals.length,
+					preserved: true
+				},
+				rollback: {
+					attempted: false,
+					safe: true,
+					succeeded: false
+				}
+			};
+		}
+		const stagingPath = path.join(installation.managedRoot, `.staging-${release.version}-${operationId}`);
+		const targetPath = path.join(installation.versionsDirectory, release.version);
+		operation.stagedTarget = stagingPath;
+		await save("stage");
+		progress(`Downloading Treeport ${release.version}…`);
+		await fs.rm(stagingPath, {
+			recursive: true,
+			force: true
+		});
+		const downloadPath = path.join(installation.managedRoot, `.download-${operationId}`);
+		await fs.rm(downloadPath, {
+			recursive: true,
+			force: true
+		});
+		await fs.mkdir(downloadPath, {
+			recursive: true,
+			mode: 448
+		});
+		const packed = await runCommand("npm", [
+			"pack",
+			`${PACKAGE_NAME}@${release.version}`,
+			"--json",
+			"--ignore-scripts",
+			"--pack-destination",
+			downloadPath
+		], environment);
+		const packedRelease = await Promise.resolve(packed.stdout).then((value) => packedReleaseSchema.safeParse(packed.code === 0 ? JSON.parse(value) : null)).catch(() => null);
+		if (!packedRelease?.success || packedRelease.data[0].integrity !== release.dist.integrity || path.basename(packedRelease.data[0].filename) !== packedRelease.data[0].filename) throw new LocalUpdateError("UPDATE_STAGING_FAILED", packed.code === 0 ? "The downloaded Treeport package did not match npm release integrity." : commandFailure("npm pack", packed), {
+			phase: "stage",
+			operationId,
+			toVersion: release.version
+		});
+		const install = await runCommand("npm", [
+			"install",
+			"--global",
+			"--prefix",
+			stagingPath,
+			"--ignore-scripts",
+			"--no-audit",
+			"--no-fund",
+			path.join(downloadPath, packedRelease.data[0].filename)
+		], environment);
+		await fs.rm(downloadPath, {
+			recursive: true,
+			force: true
+		});
+		if (install.code !== 0) throw new LocalUpdateError("UPDATE_STAGING_FAILED", commandFailure("npm install", install), {
+			phase: "stage",
+			operationId,
+			toVersion: release.version
+		});
+		await save("verify");
+		const stagedPackage = path.join(stagingPath, "lib", "node_modules", "@treeport", "treeport");
+		const stagedManifest = await fs.readFile(path.join(stagedPackage, "package.json"), "utf8").then((value) => packageSchema.safeParse(JSON.parse(value))).catch(() => null);
+		if (!stagedManifest?.success || stagedManifest.data.version !== release.version) throw new LocalUpdateError("UPDATE_VERIFICATION_FAILED", "The staged Treeport package does not match the resolved release.", {
+			phase: "verify",
+			operationId,
+			toVersion: release.version
+		});
+		await Promise.all([
+			"bin/treeport.mjs",
+			"dist/node/cli/index.js",
+			"dist/node/server/index.js",
+			"dist/web/index.html",
+			"drizzle/meta/_journal.json",
+			"skills/treeport/SKILL.md"
+		].map((item) => fs.access(path.join(stagedPackage, item), constants.R_OK))).catch((error) => {
+			throw new LocalUpdateError("UPDATE_VERIFICATION_FAILED", `The staged Treeport package is incomplete: ${error instanceof Error ? error.message : String(error)}`, {
+				phase: "verify",
+				operationId,
+				toVersion: release.version
+			});
+		});
+		const verificationData = await fs.mkdtemp(path.join(os.tmpdir(), "treeport-update-verify-"));
+		const stagedVersion = await runCommand(process.execPath, [
+			path.join(stagedPackage, "dist", "node", "cli", "index.js"),
+			"version",
+			"--json"
+		], {
+			...environment,
+			TREEPORT_API_URL: "",
+			TREEPORT_DATA_DIR: path.join(verificationData, "data"),
+			TREEPORT_RUNTIME_DIR: path.join(verificationData, "runtime"),
+			TREEPORT_CLI_ENTRYPOINT: path.join(stagingPath, "bin", "treeport")
+		});
+		await fs.rm(verificationData, {
+			recursive: true,
+			force: true
+		});
+		const verifiedVersion = await Promise.resolve(stagedVersion.stdout).then((value) => z.strictObject({
+			cli: z.string(),
+			daemon: z.string().nullable()
+		}).safeParse(stagedVersion.code === 0 ? JSON.parse(value) : null)).catch(() => null);
+		if (!verifiedVersion?.success || verifiedVersion.data.cli !== release.version) throw new LocalUpdateError("UPDATE_VERIFICATION_FAILED", `The staged Treeport CLI did not report version ${release.version}.`, {
+			phase: "verify",
+			operationId,
+			toVersion: release.version
+		});
+		const daemonBefore = await daemonStatus();
+		if (daemonBefore.state && !daemonBefore.verified) throw new LocalUpdateError("UPDATE_DAEMON_OWNERSHIP_FAILED", "Treeport daemon ownership changed while the update was staged.", {
+			phase: "verify",
+			operationId,
+			pid: daemonBefore.state.pid
+		});
+		if (daemonBefore.running !== initialDaemon.running || daemonBefore.state?.instanceId !== initialDaemon.state?.instanceId) throw new LocalUpdateError("UPDATE_DAEMON_OWNERSHIP_FAILED", "Treeport daemon state changed while the update was staged. Retry the update.", {
+			phase: "verify",
+			operationId
+		});
+		operation.daemonWasRunning = daemonBefore.running && daemonBefore.verified || recoveryOperation !== null;
+		operation.daemonLifecycle = recoveryOperation ? recoveryOperation.daemonLifecycle : operation.daemonWasRunning ? daemonBefore.health?.daemonLifecycle === "service" ? "service" : "treeport" : installedService ? "service" : "treeport";
+		operation.serviceMode = recoveryOperation?.serviceMode ?? serviceBefore?.mode ?? null;
+		operation.terminalIds = recoveryOperation ? recoveryOperation.terminalIds : operation.daemonWasRunning ? await terminalIds(daemonBefore.state.apiUrl) : [];
+		if (interrupted) throw new LocalUpdateError("UPDATE_INTERRUPTED", "Treeport update was interrupted before activation. The installed version and daemon are unchanged.", {
+			phase: "verify",
+			operationId
+		});
+		await save("stop");
+		progress("Stopping the Treeport daemon and preserving terminals…");
+		if (operation.daemonWasRunning) if (operation.daemonLifecycle === "service") {
+			if ((await serviceStop()).administratorCommand) throw new LocalUpdateError("UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED", "The service requires administrator action and was not stopped.", {
+				phase: "stop",
+				operationId
+			});
+		} else await daemonDown();
+		await save("activate");
+		progress(`Activating Treeport ${release.version}…`);
+		await fs.rm(targetPath, {
+			recursive: true,
+			force: true
+		});
+		await fs.rename(stagingPath, targetPath);
+		operation.stagedTarget = targetPath;
+		if (!await fs.lstat(installation.currentLink).then(() => true).catch(() => false)) await fs.symlink(installation.prefix, installation.currentLink);
+		else if (!installation.managed) await replaceSymlink(installation.currentLink, installation.prefix);
+		operation.previousTarget = await fs.realpath(installation.currentLink);
+		await save("activate");
+		const launcher = `#!/bin/sh\nset -eu\n# TREEPORT_MANAGED_LAUNCHER=1\nexport TREEPORT_INSTALLATION_METHOD=npm\nexport TREEPORT_CLI_ENTRYPOINT=${shellQuote(installation.entrypoint)}\nexec ${shellQuote(process.execPath)} ${shellQuote(path.join(installation.currentLink, "lib", "node_modules", "@treeport", "treeport", "bin", "treeport.mjs"))} "$@"\n`;
+		const temporaryLauncher = `${installation.entrypoint}.${process.pid}.${operationId}.tmp`;
+		await fs.writeFile(temporaryLauncher, launcher, { mode: 493 });
+		await fs.chmod(temporaryLauncher, 493);
+		await fs.rename(temporaryLauncher, installation.entrypoint);
+		await replaceSymlink(installation.currentLink, targetPath);
+		operation.activeTarget = targetPath;
+		operation.activated = true;
+		await save("activate");
+		let daemonAfter = null;
+		let terminalsAfter = [];
+		if (operation.daemonWasRunning) {
+			await writeJson(path.join(updateDirectory, "pending-startup.json"), {
+				schemaVersion: 1,
+				operationId,
+				targetVersion: release.version,
+				createdAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			await fs.rm(path.join(updateDirectory, "startup-report.json"), { force: true });
+			await save("restart");
+			progress(`Restarting the ${operation.daemonLifecycle === "service" ? "Treeport service" : "Treeport daemon"}…`);
+			await startThroughStableEntrypoint(installation.entrypoint, environment);
+			await save("health_check");
+			const healthDeadline = Date.now() + 1e4;
+			let report = await readUpdateStartupReport(paths.dataDir);
+			daemonAfter = await daemonStatus();
+			while (Date.now() < healthDeadline && (!daemonAfter.verified || daemonAfter.health?.version !== release.version || report?.operationId !== operationId || !report.ready)) {
+				await new Promise((resolve) => setTimeout(resolve, 100));
+				daemonAfter = await daemonStatus();
+				report = await readUpdateStartupReport(paths.dataDir);
+			}
+			operation.migrationState = report?.operationId === operationId ? report.migrationState : "unknown";
+			if (!daemonAfter.running || !daemonAfter.verified || daemonAfter.health?.version !== release.version || daemonAfter.health.daemonLifecycle !== operation.daemonLifecycle || path.resolve(daemonAfter.state.dataDir) !== paths.dataDir || report?.operationId !== operationId || !report.ready) throw new LocalUpdateError("UPDATE_HEALTH_VERIFICATION_FAILED", `Treeport ${release.version} did not pass startup verification.`, {
+				phase: "health_check",
+				operationId
+			});
+			if (operation.daemonLifecycle === "service") {
+				const serviceAfter = await serviceStatus();
+				if (!serviceAfter.healthy || !serviceAfter.installed || serviceAfter.definitionPath !== serviceBefore?.definitionPath || serviceAfter.mode !== serviceBefore.mode) throw new LocalUpdateError("UPDATE_HEALTH_VERIFICATION_FAILED", "The Treeport service did not preserve its enabled configuration.", {
+					phase: "health_check",
+					operationId
+				});
+			}
+			terminalsAfter = await terminalIds(daemonAfter.state.apiUrl);
+			const missing = operation.terminalIds.filter((terminalId) => !terminalsAfter.includes(terminalId));
+			if (missing.length > 0) throw new LocalUpdateError("UPDATE_TERMINAL_VERIFICATION_FAILED", "Treeport restarted, but one or more terminal sessions were not recovered.", {
+				phase: "health_check",
+				operationId,
+				terminalIds: missing
+			});
+		} else await fs.rm(path.join(updateDirectory, "pending-startup.json"), { force: true });
+		await save("complete");
+		const removable = (await fs.readdir(installation.versionsDirectory, { withFileTypes: true }).then((entries) => entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name)).catch(() => [])).filter((name) => name !== release.version && path.join(installation.versionsDirectory, name) !== operation.previousTarget);
+		await Promise.all(removable.map((name) => fs.rm(path.join(installation.versionsDirectory, name), {
+			recursive: true,
+			force: true
+		}))).catch(() => void 0);
+		return {
+			schemaVersion: 1,
+			operationId,
+			status: "updated",
+			phase: "complete",
+			fromVersion: installation.version,
+			toVersion: release.version,
+			installation: { method: "npm" },
+			daemon: {
+				wasRunning: operation.daemonWasRunning,
+				lifecycle: operation.daemonLifecycle,
+				restarted: operation.daemonWasRunning,
+				healthy: operation.daemonWasRunning ? Boolean(daemonAfter?.verified) : false,
+				version: daemonAfter?.health?.version ?? null
+			},
+			terminals: {
+				before: operation.terminalIds.length,
+				after: terminalsAfter.length,
+				preserved: operation.terminalIds.every((id) => terminalsAfter.includes(id))
+			},
+			rollback: {
+				attempted: false,
+				safe: true,
+				succeeded: false
+			}
+		};
+	} catch (error) {
+		const failedPhase = operation.phase;
+		if (!DESTRUCTIVE_PHASES.has(operation.phase)) {
+			if (error instanceof LocalUpdateError) throw error;
+			throw new LocalUpdateError(operation.phase === "resolve" ? "UPDATE_RELEASE_RESOLUTION_FAILED" : operation.phase === "stage" ? "UPDATE_STAGING_FAILED" : operation.phase === "verify" ? "UPDATE_VERIFICATION_FAILED" : "UPDATE_INSTALLATION_UNSUPPORTED", error instanceof Error ? error.message : String(error), {
+				phase: operation.phase,
+				operationId,
+				fromVersion: operation.fromVersion,
+				toVersion: operation.toVersion
+			});
+		}
+		const startupReport = await readUpdateStartupReport(paths.dataDir);
+		if (startupReport?.operationId === operationId) operation.migrationState = startupReport.migrationState;
+		if (!["not_started", "unchanged"].includes(operation.migrationState)) {
+			const serviceStopError = operation.daemonLifecycle === "service" ? await serviceStop().then(() => null, (cause) => cause instanceof Error ? cause.message : String(cause)) : null;
+			operation.recoveryAction = serviceStopError ? `Keep the new version installed. Stop the service, then inspect the daemon log. Service stop failed: ${serviceStopError}` : "Keep the new version installed. Inspect the daemon log and repair with the same or a newer Treeport release.";
+			await save("recovery_required");
+			throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "The updated daemon did not become healthy after database migration began. Treeport did not start the older daemon.", {
+				operationId,
+				phase: failedPhase,
+				fromVersion: operation.fromVersion,
+				toVersion: operation.toVersion,
+				migrationState: operation.migrationState,
+				rollback: {
+					attempted: false,
+					safe: false,
+					succeeded: false
+				},
+				logPath: startupReport?.logPath ?? paths.logPath,
+				snapshotPaths: startupReport?.snapshotPaths ?? [],
+				recovery: operation.recoveryAction
+			});
+		}
+		operation.rollbackAttempted = true;
+		await save("rollback");
+		if (!installation) throw error;
+		const rollbackError = await (async () => {
+			if (operation.previousTarget) await replaceSymlink(installation.currentLink, operation.previousTarget);
+			await fs.rm(path.join(updateDirectory, "pending-startup.json"), { force: true });
+			if (operation.daemonWasRunning) await startThroughStableEntrypoint(installation.entrypoint, environment);
+		})().then(() => null, (cause) => cause);
+		operation.rollbackSucceeded = rollbackError === null;
+		operation.recoveryAction = rollbackError ? "Inspect the active version and daemon log before starting Treeport." : "The previous Treeport version is active again.";
+		await save(rollbackError ? "recovery_required" : "rollback");
+		throw new LocalUpdateError(rollbackError ? "UPDATE_ROLLBACK_FAILED" : "UPDATE_ROLLED_BACK", rollbackError ? "The update failed and Treeport could not restore the previous running state." : "The update failed. Treeport restored the previous version.", {
+			operationId,
+			phase: failedPhase,
+			fromVersion: operation.fromVersion,
+			toVersion: operation.toVersion,
+			migrationState: operation.migrationState,
+			rollback: {
+				attempted: true,
+				safe: true,
+				succeeded: rollbackError === null
+			},
+			cause: error instanceof Error ? error.message : String(error),
+			recovery: operation.recoveryAction
+		});
+	} finally {
+		process.off("SIGINT", interrupt);
+		process.off("SIGTERM", interrupt);
+		if (installation) await fs.rm(path.join(installation.managedRoot, `.download-${operationId}`), {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		if (!operation.activated && operation.stagedTarget && ["stage", "verify"].includes(operation.phase)) await fs.rm(operation.stagedTarget, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		await fs.rm(lockPath, { force: true }).catch(() => void 0);
+	}
+}
+//#endregion
+export { treeportVersion as A, disableTailscaleRemote as C, resolvePackagePath as D, resolveLocalApiUrl as E, parseDurationMs as M, runDoctor as O, daemonUp as S, readDaemonLogs as T, serviceStatus as _, readLocalUpdateProgress as a, daemonHealth as b, createUpdateStartupReporter as c, serviceDisable as d, serviceDoctorCheck as f, serviceStart as g, serviceRun as h, isCanonicalTreeportVersion as i, assertLoopbackHost as j, tailscaleRemoteStatus as k, readServiceLogs as l, serviceInstalled as m, compareTreeportVersions as n, resolveLatestTreeportRelease as o, serviceEnable as p, inspectLocalUpdateInstallation as r, runLocalUpdate as s, LocalUpdateError as t, serviceApply as u, serviceStop as v, enableTailscaleRemote as w, daemonStatus as x, daemonDown as y };