@treeport/treeport 0.1.0 → 0.2.2

package/dist/node/cli/index.js

@@ -1,11 +1,12 @@
 #!/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-4XVZbAD1.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 crypto from "node:crypto";
 import fsSync from "node:fs";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
@@ -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,62 @@ 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(filePath, schema) {
+	return fs.readFile(filePath, "utf8").then((value) => schema.parse(JSON.parse(value))).catch(() => null);
+}
+const preferencesSchema = z.looseObject({
+	host: z.string().optional(),
+	port: z.number().optional(),
+	remote: z.strictObject({
+		port: z.number(),
+		target: z.string()
+	}).optional()
+});
+const daemonRecordSchema = z.strictObject({
+	pid: z.number(),
+	instanceId: z.string(),
+	version: z.string(),
+	apiUrl: z.string(),
+	dataDir: z.string(),
+	startedAt: z.string(),
+	installationMethod: z.string()
+});
+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", "external"]),
+	url: z.string()
+});
+async function preferences(env = process.env) {
+	return await readJson(localPaths(env).preferencesPath, preferencesSchema) ?? {};
 }
-async function preferences() {
-	return await readJson(localPaths().preferencesPath) ?? {};
+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() {
-	const explicit = process.env.TREEPORT_API_URL?.trim();
+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(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 +167,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(await resolvePackagePath("package.json"), z.looseObject({ version: z.string().optional() })))?.version ?? "development";
 }
 function processExists(pid) {
 	try {
@@ -68,31 +177,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(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(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 +239,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 up --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((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 +461,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 +474,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();
@@ -287,7 +551,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 +576,23 @@ 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/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 +604,11 @@ var CliError = class extends Error {
 		this.details = details;
 	}
 };
+async function resolveDaemonLifecycle() {
+	if (configuredDaemonLifecycle === "external") return "external";
+	if (configuredApiUrl) return (await daemonHealth(apiUrl))?.daemonLifecycle ?? "treeport";
+	return "treeport";
+}
 async function request(pathname, options = {}) {
 	const controller = new AbortController();
 	const externalSignal = options.signal;
@@ -363,6 +640,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 +672,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 +695,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 +716,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 +769,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 +864,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 +900,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,14 +908,59 @@ 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 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 });
+		});
+		if (await resolveDaemonLifecycle() === "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({});
+		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 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");
+	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 port = options.port === void 0 ? void 0 : Number(options.port);
 		const result = await daemonUp({
@@ -585,22 +970,43 @@ async function main(args) {
 		});
 		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 () => {
+		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();
 		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" });
 		const result = await daemonDown();
 		print(result, () => result.wasRunning ? "Treeport is down" : "Treeport is already down");
 	});
+	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 () => {
+		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 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 });
+		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 projectList = status.verified ? await projects() : [];
@@ -620,12 +1026,12 @@ async function main(args) {
 	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 readDaemonLogs(lines));
 	});
 	program.command("doctor").description("Diagnose local requirements and paths").option("--json", "emit machine-readable JSON").action(async () => {
 		const checks = await runDoctor();
 		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 +1042,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 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);
 	});
 	program.command("context").description("Show the current Treeport-managed terminal context").option("--json", "emit machine-readable JSON").action(async () => {
 		const projectId = contextProjectId;
@@ -674,6 +1081,7 @@ async function main(args) {
 		const context = {
 			managed: true,
 			apiUrl,
+			daemonLifecycle: await resolveDaemonLifecycle(),
 			project: {
 				id: project.id,
 				name: project.name,
@@ -690,8 +1098,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 +1108,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" : "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 +1188,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 +1209,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}` : ""}`;
+		});
+	});
+	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
+			})
 		});
-		print(result.operation, () => `Remove accepted: ${result.operation.id}`);
+		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 +1291,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 +1319,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 +1340,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 {};