@treeport/treeport 0.2.2 → 0.3.0

package/dist/node/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-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-4XVZbAD1.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";
@@ -7,9 +7,9 @@ import { io } from "socket.io-client";
 import { z } from "zod";
 import { spawn } from "node:child_process";
 import crypto from "node:crypto";
-import fsSync from "node:fs";
+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("--");
@@ -104,7 +104,7 @@ function localPaths(env = process.env) {
 		logPath: path.join(dataDir, "logs", "daemon.log")
 	};
 }
-async function readJson(filePath, schema) {
+async function readJson$1(filePath, schema) {
 	return fs.readFile(filePath, "utf8").then((value) => schema.parse(JSON.parse(value))).catch(() => null);
 }
 const preferencesSchema = z.looseObject({
@@ -122,7 +122,12 @@ const daemonRecordSchema = z.strictObject({
 	apiUrl: z.string(),
 	dataDir: z.string(),
 	startedAt: z.string(),
-	installationMethod: z.string()
+	installationMethod: z.string(),
+	daemonLifecycle: z.enum([
+		"treeport",
+		"service",
+		"external"
+	])
 });
 const healthRecordSchema = z.strictObject({
 	ok: z.literal(true),
@@ -132,11 +137,15 @@ const healthRecordSchema = z.strictObject({
 	pid: z.number(),
 	instanceId: z.string().nullable(),
 	installationMethod: z.string(),
-	daemonLifecycle: z.enum(["treeport", "external"]),
+	daemonLifecycle: z.enum([
+		"treeport",
+		"service",
+		"external"
+	]),
 	url: z.string()
 });
 async function preferences(env = process.env) {
-	return await readJson(localPaths(env).preferencesPath, preferencesSchema) ?? {};
+	return await readJson$1(localPaths(env).preferencesPath, preferencesSchema) ?? {};
 }
 async function savePreferences(value) {
 	const paths = localPaths();
@@ -154,7 +163,7 @@ async function resolveLocalApiUrl(env = process.env) {
 	const daemonRecordPath = env.TREEPORT_DAEMON_RECORD?.trim();
 	if (explicit && explicit !== managedApiUrl) return explicit.replace(/\/$/, "");
 	if (managedApiUrl && daemonRecordPath) {
-		const record = await readJson(path.resolve(expandHome(daemonRecordPath)), daemonRecordSchema);
+		const record = await readJson$1(path.resolve(expandHome(daemonRecordPath)), daemonRecordSchema);
 		if (record) return record.apiUrl.replace(/\/$/, "");
 	}
 	if (explicit) return explicit.replace(/\/$/, "");
@@ -167,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"), z.looseObject({ version: z.string().optional() })))?.version ?? "development";
+	return (await readJson$1(await resolvePackagePath("package.json"), z.looseObject({ version: z.string().optional() })))?.version ?? "development";
 }
 function processExists(pid) {
 	try {
@@ -189,11 +198,11 @@ function matchesOwnership(state, observed) {
 	return observed.pid === state.pid && observed.instanceId === state.instanceId && path.resolve(state.dataDir) === localPaths().dataDir;
 }
 async function readState() {
-	return readJson(localPaths().statePath, daemonRecordSchema);
+	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, z.looseObject({ instanceId: z.string() })))?.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)) {
@@ -294,7 +303,7 @@ function localProxyTarget(apiUrl) {
 		"localhost",
 		"::1",
 		"[::1]"
-	].includes(url.hostname)) throw new Error("Treeport remote access requires a loopback daemon. Run `treeport up --host 127.0.0.1`, then try again.");
+	].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) {
@@ -337,7 +346,7 @@ async function enableTailscaleRemote(options) {
 	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((await daemonUp({})).apiUrl);
+	const target = localProxyTarget((options.daemon ?? await daemonUp({})).apiUrl);
 	const alreadyEnabled = proxyMatches(existingTarget, target);
 	if (!alreadyEnabled) await tailscale([
 		"serve",
@@ -518,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) {
@@ -576,6 +586,1015 @@ async function readDaemonLogs(lines = 100) {
 	})).split("\n").slice(-lines - 1).join("\n");
 }
 //#endregion
+//#region src/cli/service.ts
+const serviceRecordSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	manager: z.enum(["launchd", "systemd"]),
+	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";
 let configuredApiUrl;
@@ -606,8 +1625,40 @@ var CliError = class extends Error {
 };
 async function resolveDaemonLifecycle() {
 	if (configuredDaemonLifecycle === "external") return "external";
-	if (configuredApiUrl) return (await daemonHealth(apiUrl))?.daemonLifecycle ?? "treeport";
-	return "treeport";
+	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();
@@ -927,9 +1978,11 @@ async function main(args) {
 		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 });
 		});
-		if (await resolveDaemonLifecycle() === "external") {
+		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 await daemonUp({});
+		} else if (lifecycle === "service") await ensureServiceDaemon();
+		else await daemonUp({});
 		const registered = await request("/api/projects", {
 			method: "POST",
 			body: JSON.stringify({ path: canonicalFolder })
@@ -958,10 +2011,18 @@ async function main(args) {
 			client: opened.client
 		}, () => `Opened ${registered.project.name} / ${targetWorktree.name} in the ${opened.client === "desktop" ? "Treeport desktop app" : "browser"}\n${target.href}`);
 	});
-	const upCommand = program.command("up").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");
-	upCommand.action(async () => {
-		if (await resolveDaemonLifecycle() === "external") throw new CliError("Cannot run `treeport up` because the daemon lifecycle is externally managed. Control the process that started Treeport instead.", 5, "DAEMON_LIFECYCLE_EXTERNAL");
-		const options = upCommand.opts();
+	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 },
@@ -969,16 +2030,53 @@ async function main(args) {
 			...options.foreground === void 0 ? {} : { foreground: options.foreground }
 		});
 		if (options.foreground) return;
-		print(result, () => `Treeport is up\n${result.apiUrl}`);
+		print(result, () => `Treeport is running\n${result.apiUrl}`);
 	});
-	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 () => {
-		if (await resolveDaemonLifecycle() === "external") throw new CliError("Cannot run `treeport down` because the daemon lifecycle is externally managed. Control the process that started Treeport instead.", 5, "DAEMON_LIFECYCLE_EXTERNAL");
-		const options = downCommand.opts();
+	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(() => {
@@ -986,11 +2084,16 @@ async function main(args) {
 	});
 	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 () => {
-		if (await resolveDaemonLifecycle() === "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 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 result = await enableTailscaleRemote(port === void 0 ? {} : { port });
+		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 () => {
@@ -1009,27 +2112,29 @@ async function main(args) {
 	});
 	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);
-		writeStdout(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)) requestedExitCode = 1;
 	});
@@ -1043,7 +2148,7 @@ async function main(args) {
 	});
 	program.command("skills").description("Print the Treeport usage guide for AI agents").action(async () => {
 		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 up`, `treeport down`, 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);
+		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;
@@ -1108,7 +2213,7 @@ 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}\nLifecycle: ${context.daemonLifecycle === "external" ? "externally managed" : "managed by Treeport"}`);
+		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) => {