@treeport/treeport 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # Treeport
 
-Treeport is a worktree-first terminal driver for persistent development workspaces.
+Treeport is a tree-first terminal driver for persistent development workspaces.
 
 ```sh
 npm install --global @treeport/treeport
@@ -8,7 +8,7 @@ cd /path/to/repository
 treeport .
 ```
 
-Treeport starts its backend if needed, registers the repository and its worktrees, and opens the current worktree in the desktop app or browser. Run `treeport start` to start only the backend. Use `treeport service enable` when a host must start Treeport after reboot.
+Treeport starts its backend if needed, registers the repository and its trees, and opens the current tree in the desktop app or browser. Run `treeport start` to start only the backend. Use `treeport service enable` when a host must start Treeport after reboot.
 
 Treeport supports macOS and Linux and requires Node.js 24 or newer, Git, and tmux 3.2 or newer.
 

package/dist/{loopback-Dyv_owrb.js → loopback-D7k_J_Wl.js}

@@ -12,6 +12,7 @@ const TERMINAL_SELECTION_START_SEQUENCE = "\x1B[9001~";
 const TERMINAL_SELECTION_STOP_SEQUENCE = "\x1B[9002~";
 const TERMINAL_SELECTION_CLEAR_SEQUENCE = "\x1B[9003~";
 const TERMINAL_SELECTION_RESTORE_SEQUENCE = "\x1B[9004~";
+z.unknown();
 const terminalId = z.string().min(1).max(128);
 const clientId = z.string().min(1).max(128);
 const streamId = z.string().min(1).max(128);
@@ -238,6 +239,7 @@ const eventsSnapshotSchema = z.strictObject({
 	terminalMetadata: z.array(terminalRuntimeMetadataSchema),
 	webPanels: z.array(webPanelSnapshotSchema)
 });
+z.unknown();
 function parseEventsSnapshot(value) {
 	const parsed = eventsSnapshotSchema.safeParse(value);
 	return parsed.success ? parsed.data : null;
@@ -304,7 +306,7 @@ const createWorktreeSchema = z.object({
 	if (value.base === "current" && !value.sourceWorktreeId) context.addIssue({
 		code: "custom",
 		path: ["sourceWorktreeId"],
-		message: "A source worktree is required when starting from current"
+		message: "A source tree is required when starting from current"
 	});
 });
 const terminalCwdSchema = z.string().min(1).max(4096).refine((value) => value.trim().length > 0 && !value.includes("\0"), { message: "Working directory cannot be blank or contain NUL" });
@@ -370,22 +372,25 @@ z.object({
 	if (value.base === "current" && !value.sourceWorktreeId) context.addIssue({
 		code: "custom",
 		path: ["sourceWorktreeId"],
-		message: "A source worktree is required when starting from current"
+		message: "A source tree is required when starting from current"
 	});
 });
 //#endregion
 //#region src/duration.ts
-const DURATION_UNITS = {
-	ms: 1,
-	s: 1e3,
-	m: 6e4,
-	h: 36e5
-};
+const DURATION_UNITS = /* @__PURE__ */ new Map([
+	["ms", 1],
+	["s", 1e3],
+	["m", 6e4],
+	["h", 36e5]
+]);
 const MAX_DURATION_MS = 2147483647;
 function parseDurationMs(value) {
 	const match = /^(\d+)(ms|s|m|h)$/.exec(value);
 	if (!match) throw new Error("Timeout must be a positive duration such as 500ms, 30s, 5m, or 1h");
-	const timeoutMs = Number(match[1]) * DURATION_UNITS[match[2]];
+	const amount = Number(match[1]);
+	const multiplier = DURATION_UNITS.get(match[2] ?? "");
+	if (multiplier === void 0) throw new Error("Timeout has an unsupported duration unit");
+	const timeoutMs = amount * multiplier;
 	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_DURATION_MS) throw new Error("Timeout must be between 1ms and 2147483647ms");
 	return timeoutMs;
 }
@@ -404,4 +409,4 @@ function assertLoopbackHost(host) {
 	throw new Error("Treeport supports only loopback listeners. Run `treeport start --host 127.0.0.1`, then use `treeport remote enable` for private remote access.");
 }
 //#endregion
-export { parseProductEvent as A, TERMINAL_SELECTION_RESTORE_SEQUENCE as B, repositoryTerminalPresetsFileSchema as C, updateTerminalPresetSchema as D, updateProjectSchema as E, TERMINAL_OUTPUT_HIGH_WATERMARK as F, terminalBellAcknowledgementSchema as G, TERMINAL_SELECTION_STOP_SEQUENCE as H, TERMINAL_OUTPUT_LOW_WATERMARK as I, terminalLegacyTakeControlSchema as J, terminalBinarySchema as K, TERMINAL_OUTPUT_STALL_TIMEOUT_MS as L, TERMINAL_CONTROLLER_GRACE_MS as M, TERMINAL_MAX_CLIENT_MESSAGE_BYTES as N, updateTerminalSchema as O, TERMINAL_MAX_INPUT_BYTES as P, terminalTakeControlSchema as Q, TERMINAL_SCROLL_EXIT_SEQUENCE as R, repositoryTerminalPresetSchema as S, terminalCaptureQuerySchema as T, parseTerminalAuth as U, TERMINAL_SELECTION_START_SEQUENCE as V, parseTerminalProgress as W, terminalResizeSchema as X, terminalOutputAckSchema as Y, terminalSizeSchema as Z, packageReloadSchema as _, WEB_PANEL_INPUT_MAX_BYTES as a, registerProjectSchema as b, createTerminalSchema as c, deleteTerminalPresetSchema as d, deleteWebPanelStorageSchema as f, packageProjectQuerySchema as g, packageInstallSchema as h, TERMINAL_MAX_UPLOAD_BYTES as i, SOCKET_IO_PATH as j, parseEventsSnapshot as k, createWebPanelSchema as l, openWebPanelSchema as m, parseDurationMs as n, browseDirectoryQuerySchema as o, getWebPanelStorageSchema as p, terminalInputSchema as q, TERMINAL_CAPTURE_MAX_LINES as r, createTerminalPresetSchema as s, assertLoopbackHost as t, createWorktreeSchema as u, packageRemoveSchema as v, setWebPanelStorageSchema as w, removeWorktreeSchema as x, packageUpdateSchema as y, TERMINAL_SELECTION_CLEAR_SEQUENCE as z };
+export { terminalTakeControlSchema as $, parseEventsSnapshot as A, TERMINAL_SELECTION_CLEAR_SEQUENCE as B, repositoryTerminalPresetsFileSchema as C, updateTerminalPresetSchema as D, updateProjectSchema as E, TERMINAL_MAX_INPUT_BYTES as F, parseTerminalProgress as G, TERMINAL_SELECTION_START_SEQUENCE as H, TERMINAL_OUTPUT_HIGH_WATERMARK as I, terminalInputSchema as J, terminalBellAcknowledgementSchema as K, TERMINAL_OUTPUT_LOW_WATERMARK as L, SOCKET_IO_PATH as M, TERMINAL_CONTROLLER_GRACE_MS as N, updateTerminalSchema as O, TERMINAL_MAX_CLIENT_MESSAGE_BYTES as P, terminalSizeSchema as Q, TERMINAL_OUTPUT_STALL_TIMEOUT_MS as R, repositoryTerminalPresetSchema as S, terminalCaptureQuerySchema as T, TERMINAL_SELECTION_STOP_SEQUENCE as U, TERMINAL_SELECTION_RESTORE_SEQUENCE as V, parseTerminalAuth as W, terminalOutputAckSchema as X, terminalLegacyTakeControlSchema as Y, terminalResizeSchema as Z, packageReloadSchema as _, WEB_PANEL_INPUT_MAX_BYTES as a, registerProjectSchema as b, createTerminalSchema as c, deleteTerminalPresetSchema as d, deleteWebPanelStorageSchema as f, packageProjectQuerySchema as g, packageInstallSchema as h, TERMINAL_MAX_UPLOAD_BYTES as i, parseProductEvent as j, webPanelInputSchema as k, createWebPanelSchema as l, openWebPanelSchema as m, parseDurationMs as n, browseDirectoryQuerySchema as o, getWebPanelStorageSchema as p, terminalBinarySchema as q, TERMINAL_CAPTURE_MAX_LINES as r, createTerminalPresetSchema as s, assertLoopbackHost as t, createWorktreeSchema as u, packageRemoveSchema as v, setWebPanelStorageSchema as w, removeWorktreeSchema as x, packageUpdateSchema as y, TERMINAL_SCROLL_EXIT_SEQUENCE as z };

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-Dyv_owrb.js";
+import { A as parseEventsSnapshot, M as SOCKET_IO_PATH, j as parseProductEvent, k as webPanelInputSchema, n as parseDurationMs, r as TERMINAL_CAPTURE_MAX_LINES, t as assertLoopbackHost } from "../../loopback-D7k_J_Wl.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { Command, CommanderError } from "commander";
@@ -601,6 +601,8 @@ const serviceRecordSchema = z.strictObject({
 	logPath: z.string().min(1),
 	apiUrl: z.string().min(1),
 	cliEntrypoint: z.string().min(1),
+	runtimeExecutable: z.string().min(1).nullable().default(null),
+	runtimeEntrypoint: z.string().min(1).nullable().default(null),
 	installationMethod: z.enum(["curl", "npm"]),
 	definitionName: z.string().min(1),
 	definitionPath: z.string().min(1),
@@ -635,7 +637,9 @@ const administratorRequestSchema = z.strictObject({
 	stagedDefinitionPath: z.string().min(1),
 	definitionHash: z.string().length(64),
 	apiUrl: z.string().min(1),
-	cliEntrypoint: z.string().min(1)
+	cliEntrypoint: z.string().min(1),
+	runtimeExecutable: z.string().min(1),
+	runtimeEntrypoint: z.string().min(1)
 });
 function managerForPlatform(platform = process.platform) {
 	return platform === "darwin" ? "launchd" : platform === "linux" ? "systemd" : null;
@@ -664,7 +668,8 @@ async function writeJson(filePath, value) {
 	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))));
+	const parsed = z.string().safeParse(value);
+	const source = parsed.success ? parsed.data : JSON.stringify(Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right))));
 	return crypto.createHash("sha256").update(source).digest("hex");
 }
 function xml(value) {
@@ -673,6 +678,9 @@ function xml(value) {
 function shellQuote(value) {
 	return `'${value.replaceAll("'", `'\\''`)}'`;
 }
+function createAdministratorCommand(input) {
+	return `sudo ${input.installationMethod === "curl" ? shellQuote(input.cliEntrypoint) : `${shellQuote(input.runtimeExecutable)} ${shellQuote(input.runtimeEntrypoint)}`} service apply --request ${shellQuote(input.requestPath)}`;
+}
 function systemdValue(value) {
 	return value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("%", "%%").replaceAll("\n", "\\n");
 }
@@ -833,6 +841,23 @@ async function ensureEntrypoint(installationMethod) {
 	}
 	return entrypoint;
 }
+async function currentAdministratorRuntime() {
+	const invokedEntrypoint = process.argv[1]?.trim();
+	if (!invokedEntrypoint) throw new Error("Treeport could not identify its Node entrypoint.");
+	const runtimeEntrypoint = path.resolve(invokedEntrypoint);
+	const [runtimeExecutable, actualEntrypoint, packageBinEntrypoint, packageCliEntrypoint] = await Promise.all([
+		fs.realpath(process.execPath),
+		fs.realpath(runtimeEntrypoint),
+		fs.realpath(await resolvePackagePath("bin", "treeport.mjs")),
+		fs.realpath(await resolvePackagePath("dist", "node", "cli", "index.js"))
+	]);
+	if (actualEntrypoint !== packageBinEntrypoint && actualEntrypoint !== packageCliEntrypoint) throw new Error(`Treeport cannot use an unrecognized package entrypoint for administrator commands: ${runtimeEntrypoint}`);
+	await Promise.all([fs.access(runtimeExecutable, constants.X_OK), fs.access(runtimeEntrypoint, constants.R_OK)]);
+	return {
+		runtimeExecutable,
+		runtimeEntrypoint
+	};
+}
 function cacheDirectory(home, env) {
 	const configured = env.TREEPORT_CACHE_DIR?.trim();
 	if (configured) return path.resolve(configured.replace(/^~(?=\/|$)/, home));
@@ -950,9 +975,15 @@ async function managerState(record) {
 }
 function administratorCommand(record) {
 	const requestId = record.pendingAdministratorRequestId;
-	if (!requestId) return null;
+	if (!requestId || !record.runtimeExecutable || !record.runtimeEntrypoint) 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)}`;
+	return createAdministratorCommand({
+		installationMethod: record.installationMethod,
+		cliEntrypoint: record.cliEntrypoint,
+		runtimeExecutable: record.runtimeExecutable,
+		runtimeEntrypoint: record.runtimeEntrypoint,
+		requestPath
+	});
 }
 async function untrackedDefinition() {
 	const manager = managerForPlatform();
@@ -1040,16 +1071,19 @@ async function serviceStatus() {
 		};
 	}
 	const paths = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
-	const [managerStatus, definitionContent, entrypointExists, daemon] = await Promise.all([
+	const [managerStatus, definitionContent, entrypointExists, runtimeExecutableExists, runtimeEntrypointExists, currentRuntime, daemon] = await Promise.all([
 		managerState(record),
 		fs.readFile(record.definitionPath, "utf8").catch(() => ""),
 		fs.access(record.cliEntrypoint, constants.X_OK).then(() => true).catch(() => false),
+		record.runtimeExecutable ? fs.access(record.runtimeExecutable, constants.X_OK).then(() => true).catch(() => false) : Promise.resolve(false),
+		record.runtimeEntrypoint ? fs.access(record.runtimeEntrypoint, constants.R_OK).then(() => true).catch(() => false) : Promise.resolve(false),
+		currentAdministratorRuntime().catch(() => null),
 		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 entrypointMatches = Boolean(entrypointExists && runtimeExecutableExists && runtimeEntrypointExists && currentRuntime && record.runtimeExecutable === currentRuntime.runtimeExecutable && record.runtimeEntrypoint === currentRuntime.runtimeEntrypoint && (invokedEntrypoint === null || path.resolve(invokedEntrypoint) === path.resolve(record.cliEntrypoint)));
 	const environmentMatches = fingerprint(createServiceEnvironment({
 		user: {
 			uid: record.uid,
@@ -1082,7 +1116,7 @@ async function serviceStatus() {
 		recoveryCommands.push("treeport service enable");
 	}
 	if (!entrypointMatches) {
-		issues.push(`The service CLI entrypoint is unavailable or moved: ${record.cliEntrypoint}`);
+		issues.push(`The service CLI entrypoint or Node runtime is unavailable or moved: ${record.cliEntrypoint}`);
 		recoveryCommands.push("treeport service enable");
 	}
 	if (!environmentMatches) {
@@ -1134,7 +1168,7 @@ async function prepareRecord() {
 	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 [cliEntrypoint, administratorRuntime] = await Promise.all([ensureEntrypoint(installationMethod), currentAdministratorRuntime()]);
 	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);
@@ -1163,6 +1197,8 @@ async function prepareRecord() {
 		logPath: paths.logPath,
 		apiUrl,
 		cliEntrypoint,
+		runtimeExecutable: administratorRuntime.runtimeExecutable,
+		runtimeEntrypoint: administratorRuntime.runtimeEntrypoint,
 		installationMethod,
 		definitionName,
 		definitionPath,
@@ -1207,6 +1243,14 @@ async function writeServiceFiles(record, definition) {
 	await saveRecord(record);
 }
 async function prepareAdministratorRequest(record, operation) {
+	const runtime = record.runtimeExecutable && record.runtimeEntrypoint ? {
+		runtimeExecutable: record.runtimeExecutable,
+		runtimeEntrypoint: record.runtimeEntrypoint
+	} : await currentAdministratorRuntime();
+	const requestRecord = {
+		...record,
+		...runtime
+	};
 	const locations = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
 	const id = crypto.randomUUID();
 	const now = /* @__PURE__ */ new Date();
@@ -1228,11 +1272,13 @@ async function prepareAdministratorRequest(record, operation) {
 		stagedDefinitionPath: locations.stagedDefinitionPath,
 		definitionHash: record.definitionHash,
 		apiUrl: record.apiUrl,
-		cliEntrypoint: record.cliEntrypoint
+		cliEntrypoint: record.cliEntrypoint,
+		runtimeExecutable: requestRecord.runtimeExecutable,
+		runtimeEntrypoint: requestRecord.runtimeEntrypoint
 	};
 	await writeJson(path.join(locations.requestsDirectory, `${id}.json`), request);
 	const next = {
-		...record,
+		...requestRecord,
 		pendingAdministratorRequestId: id,
 		updatedAt: now.toISOString()
 	};
@@ -1459,13 +1505,16 @@ async function serviceApply(requestPath) {
 	if (!request) throw new Error("The service apply request is invalid.");
 	if (metadata.uid !== request.uid) throw new Error("The service apply request owner does not match its target user.");
 	if (Date.parse(request.expiresAt) <= Date.now()) throw new Error("The service apply request expired. Run the original Treeport command again.");
+	const currentRuntime = await currentAdministratorRuntime().catch(() => null);
+	const invokedRuntimeEntrypoint = process.argv[1] ? path.resolve(process.argv[1]) : null;
+	if (!currentRuntime || currentRuntime.runtimeExecutable !== request.runtimeExecutable || currentRuntime.runtimeEntrypoint !== request.runtimeEntrypoint || invokedRuntimeEntrypoint !== request.runtimeEntrypoint) throw new Error("The service apply command did not use the approved Treeport Node runtime and package entrypoint.");
 	const usedPath = `${requestPath}.used`;
 	if (await fs.access(usedPath).then(() => true).catch(() => false)) throw new Error("The service apply request was already used.");
 	const account = os.userInfo({ encoding: "utf8" });
 	const idResult = await runCommand(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 (!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.runtimeExecutable !== request.runtimeExecutable || record.runtimeEntrypoint !== request.runtimeEntrypoint || record.definitionHash !== request.definitionHash || record.pendingAdministratorRequestId !== request.id) throw new Error("The service apply request does not match the current Treeport service record.");
 	if (account.uid !== 0) throw new Error("Treeport service apply lost root privileges.");
 	const launchctl = await executablePath("launchctl");
 	const target = `system/${request.definitionName}`;
@@ -1668,14 +1717,13 @@ async function request(pathname, options = {}) {
 	else externalSignal?.addEventListener("abort", abort, { once: true });
 	const timeout = setTimeout(abort, 9e4);
 	try {
+		const headers = new Headers({ accept: "application/json" });
+		if (options.body) headers.set("content-type", "application/json");
+		new Headers(options.headers).forEach((value, key) => headers.set(key, value));
 		const response = await fetch(`${apiUrl}${pathname}`, {
 			...options,
 			signal: controller.signal,
-			headers: {
-				accept: "application/json",
-				...options.body ? { "content-type": "application/json" } : {},
-				...options.headers
-			}
+			headers
 		});
 		const body = await response.json().catch(() => ({}));
 		if (!response.ok) {
@@ -1700,18 +1748,18 @@ async function createWorktree(projectId, input) {
 		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");
+	if (operation.status === "failed") throw new CliError(operation.error ?? "Tree creation failed", 5, "WORKTREE_CREATION_FAILED");
+	if (operation.kind !== "create") throw new CliError("Tree creation returned an unexpected operation kind", 5, "INVALID_OPERATION_RESULT");
+	const worktreeId = operation.result?.worktreeId ?? operation.worktreeId;
+	if (!worktreeId) throw new CliError("Completed tree creation did not identify its tree", 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;
+	if (!worktree) throw new CliError(`Created tree ${worktreeId} was not found`, 5, "INVALID_OPERATION_RESULT");
+	const terminalId = 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
+		terminalError: operation.result?.terminalError ?? null,
+		setupError: operation.result?.setupError ?? null
 	};
 }
 function commandArgv(args) {
@@ -1764,7 +1812,7 @@ async function resolveWorktree(identifier) {
 	}
 	const candidate = await canonical(identifier);
 	const match = all.filter((worktree) => pathContains(candidate, worktree.path)).sort((a, b) => b.path.length - a.path.length)[0];
-	if (!match) throw new CliError(`No registered worktree matches ${identifier}`, 5);
+	if (!match) throw new CliError(`No registered tree matches ${identifier}`, 5);
 	return match;
 }
 function parseWebPanelInput(value) {
@@ -1776,8 +1824,9 @@ function parseWebPanelInput(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;
+	const validated = webPanelInputSchema.safeParse(parsed);
+	if (!validated.success) throw new CliError("--input must contain a JSON object", 2);
+	return validated.data;
 }
 async function webPanelDefinition(worktreeId, identifier) {
 	const definitions = (await request(`/api/worktrees/${encodeURIComponent(worktreeId)}/web-panel-definitions`)).definitions;
@@ -1786,11 +1835,11 @@ async function webPanelDefinition(worktreeId, identifier) {
 	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");
+	throw new CliError(`Web panel ${identifier} is not available in this tree`, 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", {
+	if (!pathContains(cwd, worktreeRoot)) throw new CliError(`The current directory is outside tree ${worktree.name}`, 5, "INVALID_WEB_PANEL_LAUNCH_CWD", {
 		cwd,
 		worktreeId: worktree.id,
 		worktreePath: worktree.path
@@ -1876,10 +1925,10 @@ async function waitForTerminal(terminalId, condition, timeoutMs) {
 					resolve(result);
 				}
 			};
-			const fail = (error) => {
+			const fail = (cause) => {
 				if (!settled) {
 					settled = true;
-					reject(error);
+					reject(cause);
 				}
 			};
 			const enqueue = (task) => {
@@ -1959,7 +2008,7 @@ 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").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({
+	const program = new Command().name("treeport").usage("[options] [folder] [command]").description("Manage Treeport projects, trees, 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;
@@ -1972,7 +2021,7 @@ async function main(args) {
 		}
 		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 });
+			if (error instanceof Error && "code" in error && error.code === "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) => {
@@ -2024,11 +2073,11 @@ async function main(args) {
 			return;
 		}
 		const port = options.port === void 0 ? void 0 : Number(options.port);
-		const result = await daemonUp({
-			...options.host === void 0 ? {} : { host: options.host },
-			...port === void 0 ? {} : { port },
-			...options.foreground === void 0 ? {} : { foreground: options.foreground }
-		});
+		const daemonOptions = {};
+		if (options.host !== void 0) daemonOptions.host = options.host;
+		if (port !== void 0) daemonOptions.port = port;
+		if (options.foreground !== void 0) daemonOptions.foreground = options.foreground;
+		const result = await daemonUp(daemonOptions);
 		if (options.foreground) return;
 		print(result, () => `Treeport is running\n${result.apiUrl}`);
 	});
@@ -2090,10 +2139,10 @@ async function main(args) {
 		const port = options.port === void 0 ? void 0 : Number(options.port);
 		if (port !== void 0 && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new CliError("--port must be an integer between 1 and 65535", 2);
 		const serviceDaemon = lifecycle === "service" ? await ensureServiceDaemon() : void 0;
-		const result = await enableTailscaleRemote({
-			...port === void 0 ? {} : { port },
-			...serviceDaemon === void 0 ? {} : { daemon: serviceDaemon }
-		});
+		const remoteOptions = {};
+		if (port !== void 0) remoteOptions.port = port;
+		if (serviceDaemon !== void 0) remoteOptions.daemon = serviceDaemon;
+		const result = await enableTailscaleRemote(remoteOptions);
 		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 () => {
@@ -2124,7 +2173,7 @@ async function main(args) {
 		print(result, () => {
 			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 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}`;
+			return `Treeport is running\n${status.state.apiUrl}\nLifecycle: ${status.health?.daemonLifecycle}\nVersion: ${status.health?.version}\nPID: ${status.state.pid}\nProjects: ${result.projects}\nTrees: ${result.worktrees}\nTerminals: ${result.terminals}`;
 		});
 	});
 	const logsCommand = program.command("logs").description("Show recent daemon logs").option("--lines <count>", "number of lines", "100");
@@ -2174,12 +2223,12 @@ async function main(args) {
 		if (missing.length) throw new CliError(`Incomplete Treeport context; missing ${missing.join(", ")}`, 5, "TREEPORT_CONTEXT_INCOMPLETE", { missing });
 		const project = (await request(`/api/projects/${encodeURIComponent(projectId)}`)).project;
 		const worktree = project.worktrees.find((candidate) => candidate.id === worktreeId);
-		if (!worktree) throw new CliError("Treeport context worktree does not belong to the current project", 5, "TREEPORT_CONTEXT_INVALID", {
+		if (!worktree) throw new CliError("Treeport context tree does not belong to the current project", 5, "TREEPORT_CONTEXT_INVALID", {
 			projectId,
 			worktreeId
 		});
 		const terminal = worktree.terminals.find((candidate) => candidate.id === terminalId);
-		if (!terminal) throw new CliError("Treeport context terminal does not belong to the current worktree", 5, "TREEPORT_CONTEXT_INVALID", {
+		if (!terminal) throw new CliError("Treeport context terminal does not belong to the current tree", 5, "TREEPORT_CONTEXT_INVALID", {
 			worktreeId,
 			terminalId
 		});
@@ -2213,29 +2262,27 @@ 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" : context.daemonLifecycle === "service" ? "managed by the OS service" : "managed by Treeport"}`);
+		print(context, () => `Treeport context\n\nProject:  ${context.project.name} (${context.project.id})\nTree:     ${context.worktree.name} (${context.worktree.id})\nPath:     ${context.worktree.path}\nTerminal: ${context.terminal.name} (${context.terminal.id}) — ${context.terminal.status}\nAPI:      ${context.apiUrl}\nLifecycle: ${context.daemonLifecycle === "external" ? "externally managed" : context.daemonLifecycle === "service" ? "managed by the OS service" : "managed by Treeport"}`);
 	});
 	const installCommand = program.command("install").description("Install and configure a Treeport package").argument("<source>", "npm: source or local directory").option("-l, --local", "configure the registered project containing the current directory").option("--json", "emit machine-readable JSON");
 	installCommand.action(async (source) => {
 		const options = installCommand.opts();
+		const body = { source: await packageSource(source) };
+		if (options.local) body.projectId = await localPackageProjectId();
 		const result = (await request("/api/packages/install", {
 			method: "POST",
-			body: JSON.stringify({
-				source: await packageSource(source),
-				...options.local ? { projectId: await localPackageProjectId() } : {}
-			})
+			body: JSON.stringify(body)
 		})).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 body = { source: await packageSource(source) };
+		if (options.local) body.projectId = await localPackageProjectId();
 		const result = (await request("/api/packages/remove", {
 			method: "POST",
-			body: JSON.stringify({
-				source: await packageSource(source),
-				...options.local ? { projectId: await localPackageProjectId() } : {}
-			})
+			body: JSON.stringify(body)
 		})).result;
 		print(result, () => `Removed ${result.source}`);
 	});
@@ -2285,29 +2332,30 @@ async function main(args) {
 		const list = await projects();
 		print(list, () => list.map((project) => `${project.id}\t${project.name}\t${project.repositoryPath}`).join("\n"));
 	});
-	const worktreeCommand = program.command("worktree").description("List, create, and remove worktrees");
+	const worktreeCommand = program.command("worktree").description("List, create, and remove trees");
 	worktreeCommand.action(() => {
 		throw new CliError(worktreeCommand.helpInformation(), 2);
 	});
-	const worktreeListCommand = worktreeCommand.command("list").description("List discovered worktrees").option("--project <id-or-path>", "limit results to a project").option("--json", "emit machine-readable JSON");
+	const worktreeListCommand = worktreeCommand.command("list").description("List discovered trees").option("--project <id-or-path>", "limit results to a project").option("--json", "emit machine-readable JSON");
 	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.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");
+	const worktreeCreateCommand = worktreeCommand.command("create").description("Create a linked tree").requiredOption("--project <id-or-path>", "project to create from").requiredOption("--name <name>", "Tree name").option("--from-current", "base the tree on the current tree").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 createWorktree(project.id, {
+		const request = {
 			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}` : ""}`);
+			base: options.fromCurrent ? "current" : "default"
+		};
+		if (sourceWorktreeId) request.sourceWorktreeId = sourceWorktreeId;
+		const result = await createWorktree(project.id, request);
+		print(result, () => `Created tree ${result.worktree.name} (${result.worktree.id})\n${result.worktree.path}${result.setupError ? `\nSetup error: ${result.setupError}` : ""}`);
 	});
-	const worktreeRemoveCommand = worktreeCommand.command("remove").description("Remove a linked worktree").argument("<id-or-path-or-dot>", "worktree to remove").option("--force", "confirm destructive removal warnings").option("--json", "emit machine-readable JSON");
+	const worktreeRemoveCommand = worktreeCommand.command("remove").description("Remove a linked tree").argument("<id-or-path-or-dot>", "Tree to remove").option("--force", "confirm destructive removal warnings").option("--json", "emit machine-readable JSON");
 	worktreeRemoveCommand.action(async (identifier) => {
 		const { force: confirmed } = worktreeRemoveCommand.opts();
 		const worktree = await resolveWorktree(identifier);
@@ -2325,18 +2373,18 @@ async function main(args) {
 			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");
+		if (operation.status === "failed") throw new CliError(operation.error ?? "Tree removal failed", 5, "WORKTREE_REMOVAL_FAILED");
+		if (operation.kind !== "remove" || !operation.result) throw new CliError("Tree 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}` : ""}`;
+			return `Removed tree ${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");
+	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 tree").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);
@@ -2357,25 +2405,25 @@ async function main(args) {
 		};
 		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");
+	const terminalCommand = program.command("terminal").description("Manage persistent tree terminals");
 	terminalCommand.action(() => {
 		throw new CliError(terminalCommand.helpInformation(), 2);
 	});
-	const terminalListCommand = terminalCommand.command("list").description("List terminals").option("--worktree <id-or-path>", "limit results to a worktree").option("--json", "emit machine-readable JSON");
+	const terminalListCommand = terminalCommand.command("list").description("List terminals").option("--worktree <id-or-path>", "limit results to a tree").option("--json", "emit machine-readable JSON");
 	terminalListCommand.action(async () => {
 		const { worktree: identifier } = terminalListCommand.opts();
 		const list = identifier ? (await resolveWorktree(identifier)).terminals : (await projects()).flatMap((project) => project.worktrees.flatMap((worktree) => worktree.terminals));
 		print(list, () => list.map((terminal) => `${terminal.id}\t${terminal.name}\t${terminal.status}\t${JSON.stringify(terminal.argv)}`).join("\n"));
 	});
-	const terminalCreateCommand = terminalCommand.command("create").description("Create a persistent terminal").usage("[options] [-- <command> args...]").requiredOption("--worktree <id-or-path-or-dot>", "owning worktree").requiredOption("--name <name>", "terminal name").option("--json", "emit machine-readable JSON").addHelpText("after", "\nCommand arguments may be passed after --.\n");
+	const terminalCreateCommand = terminalCommand.command("create").description("Create a persistent terminal").usage("[options] [-- <command> args...]").requiredOption("--worktree <id-or-path-or-dot>", "owning tree").requiredOption("--name <name>", "terminal name").option("--json", "emit machine-readable JSON").addHelpText("after", "\nCommand arguments may be passed after --.\n");
 	terminalCreateCommand.action(async () => {
 		const options = terminalCreateCommand.opts();
-		const result = await request(`/api/worktrees/${(await resolveWorktree(options.worktree)).id}/terminals`, {
+		const worktree = await resolveWorktree(options.worktree);
+		const body = { name: options.name };
+		if (argv) body.argv = argv;
+		const result = await request(`/api/worktrees/${worktree.id}/terminals`, {
 			method: "POST",
-			body: JSON.stringify({
-				name: options.name,
-				...argv ? { argv } : {}
-			})
+			body: JSON.stringify(body)
 		});
 		print(result.terminal, () => `Created ${result.terminal.name} (${result.terminal.id})`);
 	});
@@ -2419,21 +2467,21 @@ async function main(args) {
 			terminalId
 		}, () => `Deleted ${terminalId}`);
 	});
-	const spawnCommand = program.command("spawn").description("Create a worktree and its first terminal").usage("[options] [-- <command> args...]").requiredOption("--project <id-or-path-or-dot>", "project to create from").requiredOption("--worktree-name <name>", "worktree name").requiredOption("--name <terminal-name>", "terminal name").option("--from-current", "base the worktree on the current worktree").option("--json", "emit machine-readable JSON").addHelpText("after", "\nCommand arguments may be passed after --.\n");
+	const spawnCommand = program.command("spawn").description("Create a tree and its first terminal").usage("[options] [-- <command> args...]").requiredOption("--project <id-or-path-or-dot>", "project to create from").requiredOption("--worktree-name <name>", "Tree name").requiredOption("--name <terminal-name>", "terminal name").option("--from-current", "base the tree on the current tree").option("--json", "emit machine-readable JSON").addHelpText("after", "\nCommand arguments may be passed after --.\n");
 	spawnCommand.action(async () => {
 		const options = spawnCommand.opts();
 		const project = await resolveProject(options.project);
 		const sourceWorktreeId = options.fromCurrent ? (await resolveWorktree(".")).id : void 0;
-		const result = await createWorktree(project.id, {
+		const initialTerminal = { name: options.name };
+		if (argv) initialTerminal.argv = argv;
+		const request = {
 			name: options.worktreeName,
 			base: options.fromCurrent ? "current" : "default",
-			initialTerminal: {
-				name: options.name,
-				...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}` : ""}`);
+			initialTerminal
+		};
+		if (sourceWorktreeId) request.sourceWorktreeId = sourceWorktreeId;
+		const result = await createWorktree(project.id, request);
+		print(result, () => `Created tree ${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}` : ""}`);
 	});
 	try {
 		await program.parseAsync(args, { from: "user" });
@@ -2465,9 +2513,9 @@ async function runCliApplication(options) {
 		if (jsonOutput) {
 			const body = { error: {
 				code: cliError.code,
-				message: cliError.message,
-				...cliError.details === void 0 ? {} : { details: cliError.details }
+				message: cliError.message
 			} };
+			if (cliError.details !== void 0) body.error.details = cliError.details;
 			writeStderr(`${JSON.stringify(body)}\n`);
 		} else writeStderr(`${cliError.message}\n`);
 		requestedExitCode = cliError.exitCode;