@treeport/treeport 0.1.0 → 0.3.0

package/dist/node/cli/index.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { E as parseTerminalRuntimeMetadata, _ as SOCKET_IO_PATH, g as parseProductEvent, h as parseEventsSnapshot, t as TERMINAL_CAPTURE_MAX_LINES } from "../../dist-CUkImh2W.js";
+import { A as parseProductEvent, j as SOCKET_IO_PATH, k as parseEventsSnapshot, n as parseDurationMs, r as TERMINAL_CAPTURE_MAX_LINES, t as assertLoopbackHost } from "../../loopback-Dyv_owrb.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Command, CommanderError } from "commander";
 import { io } from "socket.io-client";
-import crypto from "node:crypto";
+import { z } from "zod";
 import { spawn } from "node:child_process";
-import fsSync from "node:fs";
+import crypto from "node:crypto";
+import fsSync, { constants } from "node:fs";
 import os from "node:os";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 //#region src/cli/args.ts
 function extractJsonOutput(args) {
 	const separator = args.indexOf("--");
@@ -18,6 +19,69 @@ function extractJsonOutput(args) {
 	return true;
 }
 //#endregion
+//#region src/cli/open.ts
+const DESKTOP_BUNDLE_ID = "tech.noice.treeport";
+const LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set([
+	"127.0.0.1",
+	"localhost",
+	"[::1]"
+]);
+var OpenWorkspaceError = class extends Error {};
+function defaultLaunch(executable, args) {
+	return new Promise((resolve) => {
+		const child = spawn(executable, args, { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		let settled = false;
+		let stderr = "";
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk) => {
+			stderr = `${stderr}${chunk}`.slice(-4096);
+		});
+		child.once("error", (error) => {
+			if (!settled) {
+				settled = true;
+				resolve({
+					code: null,
+					stderr: error.message
+				});
+			}
+		});
+		child.once("close", (code) => {
+			if (!settled) {
+				settled = true;
+				resolve({
+					code,
+					stderr: stderr.trim()
+				});
+			}
+		});
+	});
+}
+function desktopCanOpen(workspaceUrl) {
+	if (!URL.canParse(workspaceUrl)) return false;
+	const url = new URL(workspaceUrl);
+	return !url.username && !url.password && (url.protocol === "https:" || url.protocol === "http:" && LOOPBACK_HOSTNAMES.has(url.hostname.toLowerCase()));
+}
+async function openWorkspace(workspaceUrl, options = {}) {
+	const platform = options.platform ?? process.platform;
+	const launch = options.launch ?? defaultLaunch;
+	if (platform === "darwin" && desktopCanOpen(workspaceUrl)) {
+		const deepLink = new URL("treeport://open");
+		deepLink.searchParams.set("url", workspaceUrl);
+		if ((await launch("open", [
+			"-b",
+			DESKTOP_BUNDLE_ID,
+			deepLink.href
+		])).code === 0) return { client: "desktop" };
+	}
+	const browser = await launch(platform === "darwin" ? "open" : "xdg-open", [workspaceUrl]);
+	if (browser.code === 0) return { client: "browser" };
+	throw new OpenWorkspaceError(`Treeport registered the folder, but could not open it automatically.${browser.stderr ? ` ${browser.stderr}` : ""}\nOpen this URL manually: ${workspaceUrl}`);
+}
+//#endregion
 //#region src/cli/lifecycle.ts
 const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_PORT = 8733;
@@ -40,17 +104,71 @@ function localPaths(env = process.env) {
 		logPath: path.join(dataDir, "logs", "daemon.log")
 	};
 }
-async function readJson(filePath) {
-	return fs.readFile(filePath, "utf8").then((value) => JSON.parse(value)).catch(() => null);
+async function readJson$1(filePath, schema) {
+	return fs.readFile(filePath, "utf8").then((value) => schema.parse(JSON.parse(value))).catch(() => null);
 }
-async function preferences() {
-	return await readJson(localPaths().preferencesPath) ?? {};
+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 resolveLocalApiUrl() {
-	const explicit = process.env.TREEPORT_API_URL?.trim();
+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();
-	return listenerUrl(process.env.TREEPORT_HOST?.trim() || process.env.HOST?.trim() || saved.host || DEFAULT_HOST, Number.parseInt(process.env.TREEPORT_PORT?.trim() || process.env.PORT?.trim() || String(saved.port ?? DEFAULT_PORT), 10));
+	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))];
@@ -58,7 +176,7 @@ async function resolvePackagePath(...segments) {
 	throw new Error("Could not locate the Treeport package directory");
 }
 async function treeportVersion() {
-	return (await readJson(await resolvePackagePath("package.json")))?.version ?? "development";
+	return (await readJson$1(await resolvePackagePath("package.json"), z.looseObject({ version: z.string().optional() })))?.version ?? "development";
 }
 function processExists(pid) {
 	try {
@@ -68,31 +186,30 @@ function processExists(pid) {
 		return error.code === "EPERM";
 	}
 }
-async function health(apiUrl, timeoutMs = 1500) {
+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 value = await response.json();
-		return value.ok && typeof value.pid === "number" ? value : 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() {
-	const value = await readJson(localPaths().statePath);
-	return value && typeof value.pid === "number" && typeof value.instanceId === "string" && typeof value.apiUrl === "string" && typeof value.dataDir === "string" ? value : null;
+	return readJson$1(localPaths().statePath, daemonRecordSchema);
 }
 async function removeStaleState(state) {
 	const paths = localPaths();
-	for (const filePath of [paths.statePath, paths.lockPath]) if ((await readJson(filePath))?.instanceId === state.instanceId) await fs.rm(filePath, { force: true });
+	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(state.pid)) {
 		await removeStaleState(state);
 		return;
 	}
-	const observed = await health(state.apiUrl);
+	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;
@@ -131,6 +248,168 @@ async function executableCheck(executable, args) {
 		}));
 	});
 }
+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";
@@ -191,7 +470,7 @@ async function daemonStatus() {
 			verified: false
 		};
 	}
-	const observed = await health(state.apiUrl);
+	const observed = await daemonHealth(state.apiUrl);
 	return {
 		running: Boolean(observed),
 		state,
@@ -204,20 +483,14 @@ async function daemonUp(options) {
 	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
 	};
-	if (options.host !== void 0 || options.port !== void 0) {
-		await fs.mkdir(paths.dataDir, {
-			recursive: true,
-			mode: 448
-		});
-		const temporaryPath = `${paths.preferencesPath}.${process.pid}.tmp`;
-		await fs.writeFile(temporaryPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 384 });
-		await fs.rename(temporaryPath, paths.preferencesPath);
-	}
-	const host = options.host?.trim() || process.env.TREEPORT_HOST?.trim() || next.host;
-	const port = Number.parseInt(options.port === void 0 ? process.env.TREEPORT_PORT?.trim() || String(next.port) : String(options.port), 10);
+	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();
@@ -254,6 +527,7 @@ async function daemonUp(options) {
 		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) {
@@ -287,7 +561,7 @@ async function daemonUp(options) {
 	fsSync.closeSync(log);
 	const deadline = Date.now() + 15e3;
 	while (Date.now() < deadline) {
-		const observed = await health(apiUrl, 500);
+		const observed = await daemonHealth(apiUrl, 500);
 		if (observed && observed.pid === child.pid && observed.instanceId === instanceId && observed.version === currentVersion) return {
 			alreadyRunning: false,
 			apiUrl,
@@ -312,15 +586,1032 @@ async function readDaemonLogs(lines = 100) {
 	})).split("\n").slice(-lines - 1).join("\n");
 }
 //#endregion
-//#region src/cli/index.ts
-const configuredApiUrl = process.env.TREEPORT_API_URL?.trim();
-const apiUrl = (await resolveLocalApiUrl()).replace(/\/$/, "");
+//#region src/cli/service.ts
+const serviceRecordSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	manager: z.enum(["launchd", "systemd"]),
+	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),
+	installationMethod: z.enum(["curl", "npm"]),
+	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)
+});
+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")
+	};
+}
+async function readJson(filePath, schema) {
+	return fs.readFile(filePath, "utf8").then((value) => schema.parse(JSON.parse(value))).catch(() => null);
+}
+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);
+}
+function fingerprint(value) {
+	const source = typeof value === "string" ? value : 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(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+function systemdValue(value) {
+	return value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("%", "%%").replaceAll("\n", "\\n");
+}
+function createLaunchdDefinition(input) {
+	return {
+		label: input.label,
+		programArguments: [input.runnerPath],
+		username: input.username,
+		group: input.group,
+		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");
+	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>
+    <key>UserName</key>
+    <string>${xml(definition.username)}</string>
+    <key>GroupName</key>
+    <string>${xml(definition.group)}</string>
+    <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(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(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(installationMethod) {
+	const entrypoint = currentEntrypoint();
+	if (!entrypoint) throw new Error("Treeport could not identify a stable CLI entrypoint. Install Treeport with npm or the curl installer, 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.`);
+	});
+	if (installationMethod === "npm") {
+		const [actual, expected] = await Promise.all([fs.realpath(entrypoint), fs.realpath(await resolvePackagePath("bin", "treeport.mjs"))]);
+		if (actual !== expected) throw new Error(`The current CLI entrypoint is not the installed Treeport npm bin: ${entrypoint}`);
+	}
+	return entrypoint;
+}
+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,
+		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(record.cliEntrypoint)}
+record=${shellQuote(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).recordPath)}
+log=${shellQuote(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
+`;
+}
+async function currentRecord() {
+	return readJson(servicePaths().recordPath, serviceRecordSchema);
+}
+async function saveRecord(record) {
+	await writeJson(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).recordPath, record);
+}
+async function managerState(record) {
+	if (record.manager === "launchd") {
+		const launchctl = await executablePath("launchctl");
+		const [active, disabled, definitionExists] = await Promise.all([
+			runCommand(launchctl, ["print", `system/${record.definitionName}`]),
+			runCommand(launchctl, ["print-disabled", "system"]),
+			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(systemctl, [
+			"--user",
+			"is-active",
+			record.definitionName
+		]),
+		runCommand(systemctl, [
+			"--user",
+			"is-enabled",
+			record.definitionName
+		]),
+		runCommand(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) return null;
+	const requestPath = path.join(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).requestsDirectory, `${requestId}.json`);
+	return `sudo ${shellQuote(record.cliEntrypoint)} service apply --request ${shellQuote(requestPath)}`;
+}
+async function untrackedDefinition() {
+	const manager = managerForPlatform();
+	if (!manager) return null;
+	const user = os.userInfo();
+	const name = manager === "launchd" ? `app.treeport.daemon.${user.uid}` : "treeport.service";
+	const definitionPath = manager === "launchd" ? `/Library/LaunchDaemons/${name}.plist` : 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,
+		name,
+		path: definitionPath
+	} : 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,
+		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,
+			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
+		};
+		return {
+			supported: true,
+			manager,
+			state: "stale",
+			installed: true,
+			enabledAtBoot: true,
+			active: (untracked.manager === "launchd" ? await runCommand(await executablePath("launchctl"), ["print", `system/${untracked.name}`]) : await runCommand(await executablePath("systemctl"), [
+				"--user",
+				"is-active",
+				untracked.name
+			])).code === 0,
+			healthy: false,
+			rebootReady: false,
+			definitionMatches: false,
+			environmentMatches: false,
+			entrypointMatches: false,
+			requestedState: null,
+			definitionPath: untracked.path,
+			entrypoint: null,
+			daemon: null,
+			issues: [`A Treeport service definition exists at ${untracked.path}, but its service record is missing. Restore the original Treeport data directory or ask an administrator to inspect and remove the 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 = 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 rebootReady = installed && (record.manager === "launchd" || managerStatus.lingering);
+	const pendingCommand = administratorCommand(record) ?? (record.manager === "systemd" && managerStatus.enabled && !managerStatus.lingering ? `sudo loginctl enable-linger ${record.username}` : null);
+	const issues = [];
+	const recoveryCommands = [];
+	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("treeport service enable");
+	}
+	if (definitionMatches && !installed && !record.pendingAdministratorRequestId) {
+		issues.push("The service definition is not enabled for startup after reboot.");
+		recoveryCommands.push("treeport service enable");
+	}
+	if (!entrypointMatches) {
+		issues.push(`The service CLI entrypoint is unavailable or moved: ${record.cliEntrypoint}`);
+		recoveryCommands.push("treeport service enable");
+	}
+	if (!environmentMatches) {
+		issues.push("The service environment differs from the current Treeport environment.");
+		recoveryCommands.push("treeport service enable");
+	}
+	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;
+	return {
+		supported: true,
+		manager,
+		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",
+		installed,
+		enabledAtBoot: installed,
+		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() {
+	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);
+	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 installationMethod = process.env.TREEPORT_INSTALLATION_METHOD?.trim() === "curl" ? "curl" : "npm";
+	const cliEntrypoint = await ensureEntrypoint(installationMethod);
+	const group = await primaryGroup(user.username);
+	const definitionName = manager === "launchd" ? `app.treeport.daemon.${user.uid}` : "treeport.service";
+	const definitionPath = manager === "launchd" ? `/Library/LaunchDaemons/${definitionName}.plist` : 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
+	});
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const previous = await currentRecord();
+	if (await fs.access(definitionPath).then(() => true).catch(() => false) && !previous) throw new Error(`A Treeport service definition already exists at ${definitionPath}. Disable it from its original data directory before enabling another service.`);
+	if (previous && path.resolve(previous.dataDir) !== paths.dataDir) throw new Error(`Treeport service mode already uses ${previous.dataDir}. Disable it before enabling ${paths.dataDir}.`);
+	const base = {
+		schemaVersion: 1,
+		manager,
+		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,
+		installationMethod,
+		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 Promise.all([fs.mkdir(path.dirname(record.logPath), {
+		recursive: true,
+		mode: 448
+	}), 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") 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) {
+	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
+	};
+	await writeJson(path.join(locations.requestsDirectory, `${id}.json`), request);
+	const next = {
+		...record,
+		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() {
+	const existing = await serviceStatus();
+	if (existing.state === "healthy" && existing.definitionMatches && existing.environmentMatches && existing.entrypointMatches) return {
+		status: existing,
+		changed: false,
+		administratorCommand: null
+	};
+	const { record, definition } = await prepareRecord();
+	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(systemctl, ["--user", "show-environment"]);
+		if (managerAvailable.code !== 0) throw commandError("systemctl --user", managerAvailable);
+	}
+	await writeServiceFiles(record, definition);
+	if (record.manager === "launchd") {
+		await daemonDown();
+		const prepared = await prepareAdministratorRequest(record, "enable");
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: prepared.command
+		};
+	}
+	if (!systemctl) throw new Error("Treeport could not resolve the systemd command.");
+	await daemonDown();
+	const reload = await runCommand(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(systemctl, [
+		"--user",
+		"enable",
+		"--now",
+		record.definitionName
+	]);
+	if (enabled.code !== 0) {
+		await fs.rm(record.definitionPath, { force: true });
+		await runCommand(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(systemctl, [
+			"--user",
+			"disable",
+			"--now",
+			record.definitionName
+		]);
+		await fs.rm(record.definitionPath, { force: true });
+		await runCommand(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("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") {
+		const prepared = await prepareAdministratorRequest(next, "start");
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: prepared.command
+		};
+	}
+	const result = await runCommand(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") {
+		const prepared = await prepareAdministratorRequest(next, "stop");
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: prepared.command
+		};
+	}
+	const result = await runCommand(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") {
+		const prepared = await prepareAdministratorRequest({
+			...record,
+			pendingAdministratorRequestId: null
+		}, "disable");
+		return {
+			status: await serviceStatus(),
+			changed: true,
+			administratorCommand: prepared.command
+		};
+	}
+	const systemctl = await executablePath("systemctl");
+	const disabled = await runCommand(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(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 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(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 readJson(request.serviceRecordPath, serviceRecordSchema);
+	if (!record || record.uid !== request.uid || record.username !== request.username || record.manager !== "launchd" || record.definitionName !== request.definitionName || record.definitionPath !== request.definitionPath || record.cliEntrypoint !== request.cliEntrypoint || 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(launchctl, ["bootout", target]);
+		const enabled = await runCommand(launchctl, ["enable", target]);
+		if (enabled.code !== 0) throw commandError("launchctl enable", enabled);
+		const bootstrapped = await runCommand(launchctl, [
+			"bootstrap",
+			"system",
+			request.definitionPath
+		]);
+		if (bootstrapped.code !== 0) throw commandError("launchctl bootstrap", bootstrapped);
+	} else if (request.operation === "start") {
+		const enabled = await runCommand(launchctl, ["enable", target]);
+		if (enabled.code !== 0) throw commandError("launchctl enable", enabled);
+		const started = (await runCommand(launchctl, ["print", target])).code === 0 ? await runCommand(launchctl, ["kickstart", target]) : await runCommand(launchctl, [
+			"bootstrap",
+			"system",
+			request.definitionPath
+		]);
+		if (started.code !== 0) throw commandError("launchctl start", started);
+	} else if (request.operation === "stop") {
+		const stopped = await runCommand(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(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(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 readJson(recordPath, serviceRecordSchema);
+	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(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(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.manager}; enabled at boot and healthy`
+	};
+	if (status.state === "stopped") return {
+		name: "Service supervision",
+		ok: true,
+		detail: `${status.manager}; intentionally stopped and enabled for next boot`
+	};
+	return {
+		name: "Service supervision",
+		ok: false,
+		detail: status.issues.join(" ") || `state: ${status.state}`
+	};
+}
+//#endregion
+//#region src/cli/application.ts
 const contextPrefix = "TREEPORT";
-const contextProjectId = process.env.TREEPORT_PROJECT_ID?.trim();
-const contextWorktreeId = process.env.TREEPORT_WORKTREE_ID?.trim();
-const contextTerminalId = process.env.TREEPORT_TERMINAL_ID?.trim();
-const rawArgs = process.argv.slice(2);
-const jsonOutput = extractJsonOutput(rawArgs);
+let configuredApiUrl;
+let apiUrl = "";
+let contextProjectId;
+let contextWorktreeId;
+let contextTerminalId;
+let configuredDaemonLifecycle;
+let jsonOutput = false;
+let workingDirectory = process.cwd();
+let writeStdout = (value) => {
+	process.stdout.write(value);
+};
+let writeStderr = (value) => {
+	process.stderr.write(value);
+};
+let requestedExitCode = 0;
 var CliError = class extends Error {
 	exitCode;
 	code;
@@ -332,6 +1623,43 @@ var CliError = class extends Error {
 		this.details = details;
 	}
 };
+async function resolveDaemonLifecycle() {
+	if (configuredDaemonLifecycle === "external") return "external";
+	if (configuredDaemonLifecycle === "service") return "service";
+	if (configuredApiUrl) {
+		const observed = await daemonHealth(apiUrl);
+		if (observed) return observed.daemonLifecycle;
+	}
+	return await serviceInstalled() ? "service" : "treeport";
+}
+function formatServiceStatus(status) {
+	const lines = [
+		`Treeport service: ${status.state}`,
+		`Manager: ${status.manager ?? "unsupported"}`,
+		`Starts at boot: ${status.enabledAtBoot ? "yes" : "no"}`,
+		`Active: ${status.active ? "yes" : "no"}`,
+		`Definition: ${status.definitionPath ?? "not installed"}`
+	];
+	if (status.daemon?.state) lines.push(`PID: ${status.daemon.state.pid}`);
+	if (status.issues.length) lines.push(...status.issues.map((issue) => `Issue: ${issue}`));
+	if (status.administratorCommand) lines.push("Administrator action required:", status.administratorCommand, "Then run: treeport service status");
+	else if (status.recoveryCommands.length) lines.push(`Next: ${status.recoveryCommands[0]}`);
+	return lines.join("\n");
+}
+async function ensureServiceDaemon() {
+	const result = await serviceStart();
+	const state = result.status.daemon?.state;
+	if (state && result.status.healthy) return {
+		apiUrl: state.apiUrl,
+		pid: state.pid
+	};
+	if (result.administratorCommand) throw new CliError(`An administrator must start the Treeport service:\n${result.administratorCommand}`, 5, "SERVICE_ADMINISTRATOR_ACTION_REQUIRED", result);
+	if (!state || !result.status.healthy) throw new CliError("The Treeport service did not become healthy. Run `treeport service status`.", 3, "DAEMON_UNREACHABLE", result.status);
+	return {
+		apiUrl: state.apiUrl,
+		pid: state.pid
+	};
+}
 async function request(pathname, options = {}) {
 	const controller = new AbortController();
 	const externalSignal = options.signal;
@@ -363,6 +1691,29 @@ async function request(pathname, options = {}) {
 		externalSignal?.removeEventListener("abort", abort);
 	}
 }
+async function createWorktree(projectId, input) {
+	let operation = (await request(`/api/projects/${encodeURIComponent(projectId)}/worktree-operations`, {
+		method: "POST",
+		body: JSON.stringify(input)
+	})).operation;
+	while (operation.status === "pending" || operation.status === "running") {
+		await new Promise((resolve) => setTimeout(resolve, 100));
+		operation = (await request(`/api/operations/${encodeURIComponent(operation.id)}`)).operation;
+	}
+	if (operation.status === "failed") throw new CliError(operation.error ?? "Worktree creation failed", 5, "WORKTREE_CREATION_FAILED");
+	if (operation.kind !== "create") throw new CliError("Worktree creation returned an unexpected operation kind", 5, "INVALID_OPERATION_RESULT");
+	const worktreeId = typeof operation.result?.worktreeId === "string" ? operation.result.worktreeId : operation.worktreeId;
+	if (!worktreeId) throw new CliError("Completed worktree creation did not identify its worktree", 5, "INVALID_OPERATION_RESULT");
+	const worktree = (await request(`/api/projects/${encodeURIComponent(projectId)}`)).project.worktrees.find((item) => item.id === worktreeId);
+	if (!worktree) throw new CliError(`Created worktree ${worktreeId} was not found`, 5, "INVALID_OPERATION_RESULT");
+	const terminalId = typeof operation.result?.terminalId === "string" ? operation.result.terminalId : null;
+	return {
+		worktree,
+		terminal: worktree.terminals.find((item) => item.id === terminalId) ?? null,
+		terminalError: typeof operation.result?.terminalError === "string" ? operation.result.terminalError : null,
+		setupError: typeof operation.result?.setupError === "string" ? operation.result.setupError : null
+	};
+}
 function commandArgv(args) {
 	const separator = args.indexOf("--");
 	if (separator === -1) return;
@@ -372,7 +1723,8 @@ function commandArgv(args) {
 	return argv;
 }
 async function canonical(value) {
-	return fs.realpath(path.resolve(value)).catch(() => path.resolve(value));
+	const resolved = path.resolve(workingDirectory, value);
+	return fs.realpath(resolved).catch(() => resolved);
 }
 async function projects() {
 	return (await request("/api/projects")).projects;
@@ -394,6 +1746,14 @@ async function resolveProject(identifier) {
 	if (!match) throw new CliError(`No registered project matches ${identifier}`, 5);
 	return match;
 }
+async function packageSource(value) {
+	if (value.startsWith("npm:")) return value;
+	if (path.isAbsolute(value) || value === "." || value === ".." || value.startsWith("./") || value.startsWith("../") || value === "~" || value.startsWith("~/")) return canonical(value);
+	return value;
+}
+async function localPackageProjectId() {
+	return (await request(`/api/packages/project?${new URLSearchParams({ path: await canonical(workingDirectory) }).toString()}`)).project.id;
+}
 async function resolveWorktree(identifier) {
 	const all = (await projects()).flatMap((project) => project.worktrees);
 	const direct = all.find((worktree) => worktree.id === identifier);
@@ -407,6 +1767,43 @@ async function resolveWorktree(identifier) {
 	if (!match) throw new CliError(`No registered worktree matches ${identifier}`, 5);
 	return match;
 }
+function parseWebPanelInput(value) {
+	if (value === void 0) return null;
+	if (Buffer.byteLength(value) > 65536) throw new CliError("Web panel input is limited to 64 KiB", 2);
+	let parsed;
+	try {
+		parsed = JSON.parse(value);
+	} catch (error) {
+		throw new CliError(`--input must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`, 2);
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new CliError("--input must contain a JSON object", 2);
+	return parsed;
+}
+async function webPanelDefinition(worktreeId, identifier) {
+	const definitions = (await request(`/api/worktrees/${encodeURIComponent(worktreeId)}/web-panel-definitions`)).definitions;
+	const exact = definitions.find((definition) => definition.id === identifier);
+	if (exact) return exact;
+	const matches = definitions.filter((definition) => decodeURIComponent(definition.id.split(":").at(-1) ?? "") === identifier);
+	if (matches.length === 1) return matches[0];
+	if (matches.length > 1) throw new CliError(`Web panel name ${identifier} is ambiguous: ${matches.map((match) => match.id).join(", ")}`, 5, "WEB_PANEL_DEFINITION_AMBIGUOUS", { definitionIds: matches.map((match) => match.id) });
+	throw new CliError(`Web panel ${identifier} is not available in this worktree`, 5, "WEB_PANEL_DEFINITION_NOT_FOUND");
+}
+async function webPanelLaunchCwd(worktree) {
+	const [cwd, worktreeRoot] = await Promise.all([canonical(workingDirectory), canonical(worktree.path)]);
+	if (!pathContains(cwd, worktreeRoot)) throw new CliError(`The current directory is outside worktree ${worktree.name}`, 5, "INVALID_WEB_PANEL_LAUNCH_CWD", {
+		cwd,
+		worktreeId: worktree.id,
+		worktreePath: worktree.path
+	});
+	return path.relative(worktreeRoot, cwd) || ".";
+}
+function webPanelUrl(worktree, panelId) {
+	const target = new URL(apiUrl);
+	target.pathname = `/projects/${encodeURIComponent(worktree.projectId)}/worktrees/${encodeURIComponent(worktree.id)}/panels/${encodeURIComponent(panelId)}`;
+	target.search = "";
+	target.hash = "";
+	return target.href;
+}
 function resolveTerminalId(identifier) {
 	if (identifier !== ".") return identifier;
 	const terminalId = contextTerminalId;
@@ -423,16 +1820,11 @@ function parseCaptureLines(value) {
 	return lines;
 }
 function parseDuration(value) {
-	const match = /^(\d+)(ms|s|m|h)$/.exec(value);
-	if (!match) throw new CliError("Timeout must be a positive duration such as 500ms, 30s, 5m, or 1h", 2);
-	const timeoutMs = Number(match[1]) * {
-		ms: 1,
-		s: 1e3,
-		m: 6e4,
-		h: 36e5
-	}[match[2]];
-	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) throw new CliError("Timeout must be between 1ms and 2147483647ms", 2);
-	return timeoutMs;
+	try {
+		return parseDurationMs(value);
+	} catch (error) {
+		throw new CliError(error instanceof Error ? error.message : String(error), 2);
+	}
 }
 async function inspectTerminal(terminalId, signal) {
 	return request(`/api/terminals/${encodeURIComponent(terminalId)}`, signal ? { signal } : {});
@@ -523,8 +1915,8 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 					condition
 				});
 				if (event.type === "terminal.metadata") {
-					const metadata = parseTerminalRuntimeMetadata(event.data);
-					if (!metadata || !observation) throw new CliError("Treeport daemon sent invalid terminal metadata", 3, "DAEMON_PROTOCOL_ERROR");
+					const { worktreeId: _worktreeId, ...metadata } = event.data;
+					if (!observation) throw new CliError("Treeport daemon sent invalid terminal metadata", 3, "DAEMON_PROTOCOL_ERROR");
 					observation = {
 						...observation,
 						metadata
@@ -559,8 +1951,7 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 	}
 }
 function print(value, human) {
-	if (jsonOutput) console.log(JSON.stringify(value));
-	else console.log(human ? human() : JSON.stringify(value, null, 2));
+	writeStdout(`${jsonOutput ? JSON.stringify(value) : human ? human() : JSON.stringify(value, null, 2)}\n`);
 }
 const agentGuidance = `AI agents:
   If you're an AI agent, use \`treeport skills\` to see the usage guide.
@@ -568,15 +1959,70 @@ const agentGuidance = `AI agents:
 async function main(args) {
 	const argv = args[0] === "spawn" || args[0] === "terminal" && args[1] === "create" ? commandArgv(args) : void 0;
 	let parserError = "";
-	const program = new Command().name("treeport").description("Manage Treeport projects, worktrees, and terminals.").option("--json", "emit machine-readable JSON").addHelpText("beforeAll", agentGuidance).configureOutput({ writeErr: (value) => {
-		parserError += value;
-	} }).showHelpAfterError().exitOverride();
-	program.action(() => {
-		process.stdout.write(program.helpInformation());
-	});
-	const upCommand = program.command("up").description("Ensure the local Treeport daemon is running").option("--host <address>", "listener address").option("--port <port>", "listener port").option("--foreground", "run in the foreground").option("--json", "emit machine-readable JSON");
-	upCommand.action(async () => {
-		const options = upCommand.opts();
+	const program = new Command().name("treeport").usage("[options] [folder] [command]").description("Manage Treeport projects, worktrees, and terminals.").argument("[folder]", "folder inside a Git repository to open").option("--json", "emit machine-readable JSON").addHelpText("beforeAll", agentGuidance).configureOutput({
+		writeOut: writeStdout,
+		writeErr: (value) => {
+			parserError += value;
+		}
+	}).showHelpAfterError().exitOverride();
+	program.action(async (folder) => {
+		if (folder === void 0) {
+			writeStdout(program.helpInformation());
+			return;
+		}
+		const absoluteFolder = path.resolve(workingDirectory, folder);
+		if (!(await fs.stat(absoluteFolder).catch((error) => {
+			if ((typeof error === "object" && error !== null && "code" in error ? error.code : void 0) === "ENOENT") throw new CliError(`Folder does not exist: ${absoluteFolder}`, 5, "FOLDER_NOT_FOUND", { path: absoluteFolder });
+			throw new CliError(`Cannot access folder ${absoluteFolder}: ${error instanceof Error ? error.message : String(error)}`, 5, "FOLDER_UNREADABLE", { path: absoluteFolder });
+		})).isDirectory()) throw new CliError(`Path is not a folder: ${absoluteFolder}`, 5, "FOLDER_NOT_DIRECTORY", { path: absoluteFolder });
+		const canonicalFolder = await fs.realpath(absoluteFolder).catch((error) => {
+			throw new CliError(`Cannot access folder ${absoluteFolder}: ${error instanceof Error ? error.message : String(error)}`, 5, "FOLDER_UNREADABLE", { path: absoluteFolder });
+		});
+		const lifecycle = await resolveDaemonLifecycle();
+		if (lifecycle === "external") {
+			if (!await daemonHealth(apiUrl)) throw new CliError(`Cannot reach the externally managed Treeport daemon at ${apiUrl}. Start it through the process that owns its lifecycle and retry.`, 3, "DAEMON_UNREACHABLE");
+		} else if (lifecycle === "service") await ensureServiceDaemon();
+		else await daemonUp({});
+		const registered = await request("/api/projects", {
+			method: "POST",
+			body: JSON.stringify({ path: canonicalFolder })
+		}).catch((error) => {
+			if (error instanceof CliError && error.code === "NOT_A_GIT_REPOSITORY") throw new CliError(`No Git repository contains ${canonicalFolder}.`, error.exitCode, error.code, error.details);
+			throw error;
+		});
+		const targetWorktree = registered.project.worktrees.filter((worktree) => !worktree.prunable && pathContains(canonicalFolder, worktree.path)).sort((left, right) => right.path.length - left.path.length)[0];
+		if (!targetWorktree) throw new CliError(`Git did not report an active worktree containing ${canonicalFolder}.`, 5, "WORKTREE_NOT_FOUND", {
+			path: canonicalFolder,
+			projectId: registered.project.id
+		});
+		const target = new URL(apiUrl);
+		target.pathname = `/projects/${encodeURIComponent(registered.project.id)}/worktrees/${encodeURIComponent(targetWorktree.id)}`;
+		target.search = "";
+		target.hash = "";
+		const opened = await openWorkspace(target.href).catch((error) => {
+			if (error instanceof OpenWorkspaceError) throw new CliError(error.message, 1, "OPEN_FAILED", { url: target.href });
+			throw error;
+		});
+		print({
+			projectId: registered.project.id,
+			worktreeId: targetWorktree.id,
+			path: canonicalFolder,
+			url: target.href,
+			client: opened.client
+		}, () => `Opened ${registered.project.name} / ${targetWorktree.name} in the ${opened.client === "desktop" ? "Treeport desktop app" : "browser"}\n${target.href}`);
+	});
+	const startCommand = program.command("start").description("Ensure the local Treeport daemon is running").option("--host <address>", "loopback listener address").option("--port <port>", "listener port").option("--foreground", "run in the foreground").option("--json", "emit machine-readable JSON");
+	startCommand.action(async () => {
+		const lifecycle = await resolveDaemonLifecycle();
+		if (lifecycle === "external") throw new CliError("Cannot run `treeport start` because the daemon lifecycle is externally managed. Control the process that started Treeport instead.", 5, "DAEMON_LIFECYCLE_EXTERNAL");
+		const options = startCommand.opts();
+		if (lifecycle === "service") {
+			if (options.foreground || options.host || options.port) throw new CliError("An installed service owns the listener and process mode. Run `treeport service enable` to refresh its configuration, or `treeport service disable` to return to local background mode.", 5, "DAEMON_LIFECYCLE_SERVICE");
+			const result = await serviceStart();
+			print(result, () => formatServiceStatus(result.status));
+			if (result.administratorCommand || !result.status.healthy) requestedExitCode = 1;
+			return;
+		}
 		const port = options.port === void 0 ? void 0 : Number(options.port);
 		const result = await daemonUp({
 			...options.host === void 0 ? {} : { host: options.host },
@@ -584,48 +2030,113 @@ async function main(args) {
 			...options.foreground === void 0 ? {} : { foreground: options.foreground }
 		});
 		if (options.foreground) return;
-		print(result, () => `Treeport is up\n${result.apiUrl}`);
-		const listenerHost = new URL(result.apiUrl).hostname;
-		if (![
-			"127.0.0.1",
-			"::1",
-			"[::1]",
-			"localhost"
-		].includes(listenerHost)) process.stderr.write("Warning: Treeport has no authentication. Use only a trusted private network.\n");
-	});
-	const downCommand = program.command("down").description("Stop the local daemon and preserve terminal sessions").option("--terminate-terminals", "terminate every Treeport-owned tmux server").option("--force", "confirm termination of all terminals").option("--json", "emit machine-readable JSON");
-	downCommand.action(async () => {
-		const options = downCommand.opts();
+		print(result, () => `Treeport is running\n${result.apiUrl}`);
+	});
+	const stopCommand = program.command("stop").description("Stop the local daemon and preserve terminal sessions").option("--terminate-terminals", "terminate every Treeport-owned tmux server").option("--force", "confirm termination of all terminals").option("--json", "emit machine-readable JSON");
+	stopCommand.action(async () => {
+		const lifecycle = await resolveDaemonLifecycle();
+		if (lifecycle === "external") throw new CliError("Cannot run `treeport stop` because the daemon lifecycle is externally managed. Control the process that started Treeport instead.", 5, "DAEMON_LIFECYCLE_EXTERNAL");
+		const options = stopCommand.opts();
 		if (options.terminateTerminals && !options.force) throw new CliError("Re-run with --terminate-terminals --force to confirm termination of every terminal.", 2);
 		if (options.terminateTerminals) await request("/api/admin/terminate-terminals", { method: "POST" });
+		if (lifecycle === "service") {
+			const result = await serviceStop();
+			print(result, () => formatServiceStatus(result.status));
+			if (result.administratorCommand) requestedExitCode = 1;
+			return;
+		}
 		const result = await daemonDown();
-		print(result, () => result.wasRunning ? "Treeport is down" : "Treeport is already down");
+		print(result, () => result.wasRunning ? "Treeport is stopped" : "Treeport is already stopped");
+	});
+	const serviceCommand = program.command("service").description("Manage opt-in OS service supervision");
+	serviceCommand.action(() => {
+		writeStdout(serviceCommand.helpInformation());
+	});
+	serviceCommand.command("enable").description("Enable startup after reboot and unexpected-exit restarts").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await serviceEnable();
+		print(result, () => formatServiceStatus(result.status));
+		if (result.status.state === "action_required") requestedExitCode = 1;
+	});
+	serviceCommand.command("status").description("Show OS service supervision status").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await serviceStatus();
+		print(result, () => formatServiceStatus(result));
+		if (![
+			"disabled",
+			"healthy",
+			"stopped"
+		].includes(result.state) || !result.supported) requestedExitCode = 1;
+	});
+	serviceCommand.command("disable").description("Stop and unregister OS service supervision").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await serviceDisable();
+		print(result, () => formatServiceStatus(result.status));
+		if (result.administratorCommand || result.status.state !== "disabled") requestedExitCode = 1;
+	});
+	serviceCommand.command("run", { hidden: true }).action(async () => serviceRun());
+	const serviceApplyCommand = serviceCommand.command("apply", { hidden: true }).requiredOption("--request <absolute-path>", "prepared request");
+	serviceApplyCommand.action(async () => {
+		const { request: requestPath } = serviceApplyCommand.opts();
+		const result = await serviceApply(requestPath);
+		print(result, () => `Applied Treeport service ${result.operation} request.`);
+	});
+	const remoteCommand = program.command("remote").description("Expose Treeport privately through Tailscale Serve");
+	remoteCommand.action(() => {
+		writeStdout(remoteCommand.helpInformation());
+	});
+	const remoteEnableCommand = remoteCommand.command("enable").description("Enable private HTTPS access through Tailscale").option("--port <port>", "Tailscale HTTPS port (default: 8733)").option("--json", "emit machine-readable JSON");
+	remoteEnableCommand.action(async () => {
+		const lifecycle = await resolveDaemonLifecycle();
+		if (lifecycle === "external") throw new CliError("Cannot run `treeport remote enable` because the daemon lifecycle is externally managed. Configure remote access through the process that started Treeport instead.", 5, "DAEMON_LIFECYCLE_EXTERNAL");
+		const options = remoteEnableCommand.opts();
+		const port = options.port === void 0 ? void 0 : Number(options.port);
+		if (port !== void 0 && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new CliError("--port must be an integer between 1 and 65535", 2);
+		const serviceDaemon = lifecycle === "service" ? await ensureServiceDaemon() : void 0;
+		const result = await enableTailscaleRemote({
+			...port === void 0 ? {} : { port },
+			...serviceDaemon === void 0 ? {} : { daemon: serviceDaemon }
+		});
+		print(result, () => `Treeport remote access is ${result.alreadyEnabled ? "already enabled" : "enabled"}\n${result.url}\nTailscale authenticates each remote user. Access is limited by your Tailscale policy.`);
+	});
+	remoteCommand.command("status").description("Show Tailscale remote access status").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await tailscaleRemoteStatus();
+		print(result, () => {
+			if (!result.configured) return "Treeport remote access is disabled";
+			return result.active ? `Treeport remote access is enabled\n${result.url}` : `Treeport remote access is unavailable\nExpected: ${result.url}\nThe Tailscale Serve route no longer points to Treeport.`;
+		});
+	});
+	remoteCommand.command("disable").description("Disable Treeport Tailscale remote access").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await disableTailscaleRemote();
+		print(result, () => {
+			if (result.changedTailscale) return "Treeport remote access is disabled";
+			return result.wasEnabled ? "Treeport remote access is disabled" : "Treeport remote access was already disabled; the current Tailscale route was left unchanged.";
+		});
 	});
 	program.command("status").description("Show local daemon status").option("--json", "emit machine-readable JSON").action(async () => {
 		const status = await daemonStatus();
+		const supervision = await serviceInstalled() ? await serviceStatus() : null;
 		const projectList = status.verified ? await projects() : [];
 		const result = {
 			...status,
+			service: supervision,
 			projects: projectList.length,
 			worktrees: projectList.reduce((count, project) => count + project.worktrees.length, 0),
 			terminals: projectList.reduce((count, project) => count + project.worktrees.reduce((worktreeCount, worktree) => worktreeCount + worktree.terminals.length, 0), 0)
 		};
 		print(result, () => {
-			if (!status.state) return "Treeport is down";
+			if (!status.state) return supervision ? formatServiceStatus(supervision) : "Treeport is stopped";
 			if (!status.running || !status.verified) return `Treeport is unhealthy (PID ${status.state.pid})\nLogs: ${path.join(status.state.dataDir, "logs", "daemon.log")}`;
-			return `Treeport is up\n${status.state.apiUrl}\nVersion: ${status.health?.version}\nPID: ${status.state.pid}\nProjects: ${result.projects}\nWorktrees: ${result.worktrees}\nTerminals: ${result.terminals}`;
+			return `Treeport is running\n${status.state.apiUrl}\nLifecycle: ${status.health?.daemonLifecycle}\nVersion: ${status.health?.version}\nPID: ${status.state.pid}\nProjects: ${result.projects}\nWorktrees: ${result.worktrees}\nTerminals: ${result.terminals}`;
 		});
 	});
 	const logsCommand = program.command("logs").description("Show recent daemon logs").option("--lines <count>", "number of lines", "100");
 	logsCommand.action(async () => {
 		const lines = Number(logsCommand.opts().lines);
 		if (!Number.isInteger(lines) || lines < 1 || lines > 1e4) throw new CliError("--lines must be an integer between 1 and 10000", 2);
-		process.stdout.write(await readDaemonLogs(lines));
+		writeStdout(await serviceInstalled() ? await readServiceLogs(lines) : await readDaemonLogs(lines));
 	});
 	program.command("doctor").description("Diagnose local requirements and paths").option("--json", "emit machine-readable JSON").action(async () => {
-		const checks = await runDoctor();
+		const checks = [...await runDoctor(), await serviceDoctorCheck()];
 		print(checks, () => checks.map((check) => `${check.ok ? "ok" : "error"}\t${check.name}\t${check.detail}`).join("\n"));
-		if (checks.some((check) => !check.ok)) process.exitCode = 1;
+		if (checks.some((check) => !check.ok)) requestedExitCode = 1;
 	});
 	program.command("version").description("Show CLI and daemon versions").option("--json", "emit machine-readable JSON").action(async () => {
 		const [cli, status] = await Promise.all([treeportVersion(), daemonStatus()]);
@@ -636,7 +2147,8 @@ async function main(args) {
 		print(result, () => `CLI: ${result.cli}\nDaemon: ${result.daemon ?? "not running"}`);
 	});
 	program.command("skills").description("Print the Treeport usage guide for AI agents").action(async () => {
-		process.stdout.write(await fs.readFile(await resolvePackagePath("skills", "treeport", "SKILL.md"), "utf8"));
+		const skill = await fs.readFile(await resolvePackagePath("skills", "treeport", "SKILL.md"), "utf8");
+		writeStdout(await resolveDaemonLifecycle() === "external" ? skill.replace("\n# Treeport\n", "\n# Treeport\n\n> **Externally managed daemon lifecycle:** Do not run `treeport start`, `treeport stop`, or `treeport remote enable`. The process that started Treeport owns startup, shutdown, remote exposure, and logs. Other Treeport commands continue to use the configured daemon normally.\n") : skill);
 	});
 	program.command("context").description("Show the current Treeport-managed terminal context").option("--json", "emit machine-readable JSON").action(async () => {
 		const projectId = contextProjectId;
@@ -674,6 +2186,7 @@ async function main(args) {
 		const context = {
 			managed: true,
 			apiUrl,
+			daemonLifecycle: await resolveDaemonLifecycle(),
 			project: {
 				id: project.id,
 				name: project.name,
@@ -690,8 +2203,7 @@ async function main(args) {
 				head: worktree.head,
 				branch: worktree.branch,
 				detached: worktree.detached,
-				kind: worktree.kind,
-				status: worktree.status
+				kind: worktree.kind
 			},
 			terminal: {
 				id: terminal.id,
@@ -701,7 +2213,62 @@ async function main(args) {
 				exitCode: terminal.exitCode
 			}
 		};
-		print(context, () => `Treeport context\n\nProject:  ${context.project.name} (${context.project.id})\nWorktree: ${context.worktree.name} (${context.worktree.id})\nPath:     ${context.worktree.path}\nTerminal: ${context.terminal.name} (${context.terminal.id}) — ${context.terminal.status}\nAPI:      ${context.apiUrl}`);
+		print(context, () => `Treeport context\n\nProject:  ${context.project.name} (${context.project.id})\nWorktree: ${context.worktree.name} (${context.worktree.id})\nPath:     ${context.worktree.path}\nTerminal: ${context.terminal.name} (${context.terminal.id}) — ${context.terminal.status}\nAPI:      ${context.apiUrl}\nLifecycle: ${context.daemonLifecycle === "external" ? "externally managed" : context.daemonLifecycle === "service" ? "managed by the OS service" : "managed by Treeport"}`);
+	});
+	const installCommand = program.command("install").description("Install and configure a Treeport package").argument("<source>", "npm: source or local directory").option("-l, --local", "configure the registered project containing the current directory").option("--json", "emit machine-readable JSON");
+	installCommand.action(async (source) => {
+		const options = installCommand.opts();
+		const result = (await request("/api/packages/install", {
+			method: "POST",
+			body: JSON.stringify({
+				source: await packageSource(source),
+				...options.local ? { projectId: await localPackageProjectId() } : {}
+			})
+		})).result;
+		print(result, () => `Installed ${result.source}${result.scope === "project" ? ` for project ${result.projectId}` : " globally"}`);
+	});
+	const removePackageCommand = program.command("remove").alias("uninstall").description("Remove a configured Treeport package").argument("<source>", "npm: source or local directory").option("-l, --local", "remove from the registered project containing the current directory").option("--json", "emit machine-readable JSON");
+	removePackageCommand.action(async (source) => {
+		const options = removePackageCommand.opts();
+		const result = (await request("/api/packages/remove", {
+			method: "POST",
+			body: JSON.stringify({
+				source: await packageSource(source),
+				...options.local ? { projectId: await localPackageProjectId() } : {}
+			})
+		})).result;
+		print(result, () => `Removed ${result.source}`);
+	});
+	program.command("list").description("List configured Treeport packages").option("--json", "emit machine-readable JSON").action(async () => {
+		const result = await request("/api/packages");
+		print(result, () => {
+			const lines = result.packages.map((pkg) => {
+				return `${pkg.scope === "global" ? "global" : `project:${pkg.projectName ?? pkg.projectId}`}\t${pkg.source}\t${pkg.resources.webPanels} web panels, ${pkg.resources.terminalPresets} terminal presets`;
+			});
+			lines.push(...result.diagnostics.map((item) => `error\t${item.scope}\t${item.source ?? item.path ?? "settings"}\t${item.message}`));
+			return lines.join("\n");
+		});
+	});
+	const updatePackagesCommand = program.command("update").description("Explicitly update configured Treeport packages").argument("[source]", "one configured npm: source").option("--packages", "update every eligible configured package").option("--json", "emit machine-readable JSON");
+	updatePackagesCommand.action(async (source) => {
+		const options = updatePackagesCommand.opts();
+		if (!source && !options.packages || source && options.packages) throw new CliError("Specify a package source or --packages. Bare `treeport update` is reserved for a future Treeport self-update.", 2);
+		const results = (await request("/api/packages/update", {
+			method: "POST",
+			body: JSON.stringify(source ? { source: await packageSource(source) } : {})
+		})).results;
+		print(results, () => results.map((result) => `${result.status}\t${result.scope}\t${result.source ?? "packages"}${result.reason ? `\t${result.reason}` : ""}`).join("\n"));
+	});
+	const reloadCommand = program.command("reload").description("Reload package settings and resources without restarting").option("-l, --local", "reload only the registered project containing the current directory").option("--json", "emit machine-readable JSON");
+	reloadCommand.action(async () => {
+		const options = reloadCommand.opts();
+		const result = await request("/api/packages/reload", {
+			method: "POST",
+			body: JSON.stringify(options.local ? { projectId: await localPackageProjectId() } : {})
+		});
+		print(result, () => {
+			return [...result.results.map((item) => `Reloaded ${item.scope === "global" ? "global packages" : `project ${item.projectId}`}`), ...result.diagnostics.map((item) => `Error: ${item.source ?? item.path ?? item.scope}: ${item.message}`)].join("\n");
+		});
 	});
 	const projectCommand = program.command("project").description("Register and list projects");
 	projectCommand.action(() => {
@@ -726,20 +2293,17 @@ async function main(args) {
 	worktreeListCommand.action(async () => {
 		const { project: projectIdentifier } = worktreeListCommand.opts();
 		const list = projectIdentifier ? (await resolveProject(projectIdentifier)).worktrees : (await projects()).flatMap((project) => project.worktrees);
-		print(list, () => list.map((worktree) => `${worktree.id}\t${worktree.name}\t${worktree.branch ?? `detached@${worktree.head.slice(0, 8)}`}\t${worktree.status}\t${worktree.path}`).join("\n"));
+		print(list, () => list.map((worktree) => `${worktree.id}\t${worktree.name}\t${worktree.branch ?? `detached@${worktree.head.slice(0, 8)}`}\t${worktree.path}`).join("\n"));
 	});
 	const worktreeCreateCommand = worktreeCommand.command("create").description("Create a linked worktree").requiredOption("--project <id-or-path>", "project to create from").requiredOption("--name <name>", "worktree name").option("--from-current", "base the worktree on the current worktree").option("--json", "emit machine-readable JSON");
 	worktreeCreateCommand.action(async () => {
 		const options = worktreeCreateCommand.opts();
 		const project = await resolveProject(options.project);
 		const sourceWorktreeId = options.fromCurrent ? (await resolveWorktree(".")).id : void 0;
-		const result = await request(`/api/projects/${project.id}/worktrees`, {
-			method: "POST",
-			body: JSON.stringify({
-				name: options.name,
-				base: options.fromCurrent ? "current" : "default",
-				...sourceWorktreeId ? { sourceWorktreeId } : {}
-			})
+		const result = await createWorktree(project.id, {
+			name: options.name,
+			base: options.fromCurrent ? "current" : "default",
+			...sourceWorktreeId ? { sourceWorktreeId } : {}
 		});
 		print(result, () => `Created ${result.worktree.name} (${result.worktree.id})\n${result.worktree.path}${result.setupError ? `\nSetup error: ${result.setupError}` : ""}`);
 	});
@@ -750,14 +2314,48 @@ async function main(args) {
 		const preview = (await request(`/api/worktrees/${worktree.id}/remove-preview`)).preview;
 		if (!preview.eligible) throw new CliError(preview.reasons.join("\n"), 5);
 		if (preview.warnings.length && !confirmed) throw new CliError(`${preview.warnings.join("\n")}\nRe-run with --force to confirm removal.`, 5);
-		const result = await request(`/api/worktrees/${worktree.id}/remove`, {
+		let operation = (await request(`/api/worktrees/${worktree.id}/remove`, {
 			method: "POST",
 			body: JSON.stringify({
 				confirmationToken: preview.confirmationToken,
 				confirmDestructive: preview.warnings.length > 0
 			})
+		})).operation;
+		while (operation.status === "pending" || operation.status === "running") {
+			await new Promise((resolve) => setTimeout(resolve, 100));
+			operation = (await request(`/api/operations/${encodeURIComponent(operation.id)}`)).operation;
+		}
+		if (operation.status === "failed") throw new CliError(operation.error ?? "Worktree removal failed", 5, "WORKTREE_REMOVAL_FAILED");
+		if (operation.kind !== "remove" || !operation.result) throw new CliError("Worktree removal returned an unexpected operation result", 5, "INVALID_OPERATION_RESULT");
+		print(operation.result, () => {
+			const warning = operation.result?.cleanup.warning;
+			return `Removed ${worktree.name} (${worktree.id})${warning ? `\nWarning: ${warning}` : ""}`;
 		});
-		print(result.operation, () => `Remove accepted: ${result.operation.id}`);
+	});
+	const webPanelCommand = program.command("web-panel").description("Open persistent web panels");
+	webPanelCommand.action(() => {
+		throw new CliError(webPanelCommand.helpInformation(), 2);
+	});
+	const webPanelOpenCommand = webPanelCommand.command("open").description("Create or reuse a web panel and request client navigation").argument("<definition>", "definition ID or unique short name").requiredOption("--worktree <id-or-path-or-dot>", "owning worktree").option("--input <json>", "structured panel input as a JSON object").option("--new", "create a separate panel instance").option("--json", "emit machine-readable JSON");
+	webPanelOpenCommand.action(async (identifier) => {
+		const options = webPanelOpenCommand.opts();
+		const worktree = await resolveWorktree(options.worktree);
+		const definition = await webPanelDefinition(worktree.id, identifier);
+		const result = await request(`/api/worktrees/${encodeURIComponent(worktree.id)}/panels/open`, {
+			method: "POST",
+			body: JSON.stringify({
+				definitionId: definition.id,
+				input: parseWebPanelInput(options.input),
+				launchCwd: await webPanelLaunchCwd(worktree),
+				newInstance: options.new ?? false,
+				sourceTerminalId: contextTerminalId ?? null
+			})
+		});
+		const output = {
+			...result,
+			url: webPanelUrl(worktree, result.panel.id)
+		};
+		print(output, () => `${result.reused ? "Reused" : "Opened"} ${result.panel.title} (${result.panel.id})\n${output.url}`);
 	});
 	const terminalCommand = program.command("terminal").description("Manage persistent worktree terminals");
 	terminalCommand.action(() => {
@@ -798,8 +2396,8 @@ async function main(args) {
 		const capture = await request(`/api/terminals/${encodeURIComponent(terminalId)}/capture?lines=${lines}`);
 		if (jsonOutput) print(capture);
 		else {
-			process.stdout.write(capture.content);
-			if (capture.content && !capture.content.endsWith("\n")) process.stdout.write("\n");
+			writeStdout(capture.content);
+			if (capture.content && !capture.content.endsWith("\n")) writeStdout("\n");
 		}
 	});
 	const terminalWaitCommand = terminalCommand.command("wait").description("Wait for a terminal runtime condition").argument("<terminal-id-or-dot>", "terminal to observe").requiredOption("--until <idle|working|bell|exit>", "condition to wait for").option("--timeout <duration>", "maximum wait, such as 30s or 5m").option("--json", "emit machine-readable JSON");
@@ -826,16 +2424,14 @@ async function main(args) {
 		const options = spawnCommand.opts();
 		const project = await resolveProject(options.project);
 		const sourceWorktreeId = options.fromCurrent ? (await resolveWorktree(".")).id : void 0;
-		const result = await request("/api/spawn", {
-			method: "POST",
-			body: JSON.stringify({
-				project: project.id,
-				worktreeName: options.worktreeName,
+		const result = await createWorktree(project.id, {
+			name: options.worktreeName,
+			base: options.fromCurrent ? "current" : "default",
+			initialTerminal: {
 				name: options.name,
-				base: options.fromCurrent ? "current" : "default",
-				...sourceWorktreeId ? { sourceWorktreeId } : {},
 				...argv ? { argv } : {}
-			})
+			},
+			...sourceWorktreeId ? { sourceWorktreeId } : {}
 		});
 		print(result, () => `Created worktree ${result.worktree.name} (${result.worktree.id})\nPath: ${result.worktree.path}\n${result.terminal ? `Terminal: ${result.terminal.name} (${result.terminal.id}) — ${result.terminal.status}` : "Terminal: not created"}${result.setupError ? `\nSetup error: ${result.setupError}` : ""}${result.terminalError ? `\nTerminal error: ${result.terminalError}` : ""}`);
 	});
@@ -849,17 +2445,37 @@ async function main(args) {
 		throw error;
 	}
 }
-main(rawArgs).catch((error) => {
-	const cliError = error instanceof CliError ? error : new CliError(error instanceof Error ? error.message : String(error), 1);
-	if (jsonOutput) {
-		const body = { error: {
-			code: cliError.code,
-			message: cliError.message,
-			...cliError.details === void 0 ? {} : { details: cliError.details }
-		} };
-		process.stderr.write(`${JSON.stringify(body)}\n`);
-	} else process.stderr.write(`${cliError.message}\n`);
-	process.exitCode = cliError.exitCode;
-});
+async function runCliApplication(options) {
+	const environment = options.environment ?? process.env;
+	configuredApiUrl = environment.TREEPORT_API_URL?.trim();
+	apiUrl = (await resolveLocalApiUrl(environment)).replace(/\/$/, "");
+	contextProjectId = environment.TREEPORT_PROJECT_ID?.trim() || void 0;
+	contextWorktreeId = environment.TREEPORT_WORKTREE_ID?.trim() || void 0;
+	contextTerminalId = environment.TREEPORT_TERMINAL_ID?.trim() || void 0;
+	configuredDaemonLifecycle = environment.TREEPORT_DAEMON_LIFECYCLE?.trim();
+	jsonOutput = extractJsonOutput(options.args);
+	workingDirectory = options.cwd ?? process.cwd();
+	writeStdout = options.stdout ?? ((value) => process.stdout.write(value));
+	writeStderr = options.stderr ?? ((value) => process.stderr.write(value));
+	requestedExitCode = 0;
+	try {
+		await main([...options.args]);
+	} catch (error) {
+		const cliError = error instanceof CliError ? error : new CliError(error instanceof Error ? error.message : String(error), 1);
+		if (jsonOutput) {
+			const body = { error: {
+				code: cliError.code,
+				message: cliError.message,
+				...cliError.details === void 0 ? {} : { details: cliError.details }
+			} };
+			writeStderr(`${JSON.stringify(body)}\n`);
+		} else writeStderr(`${cliError.message}\n`);
+		requestedExitCode = cliError.exitCode;
+	}
+	return requestedExitCode;
+}
+//#endregion
+//#region src/cli/index.ts
+process.exitCode = await runCliApplication({ args: process.argv.slice(2) });
 //#endregion
 export {};