@treeport/treeport 0.6.1 → 0.8.3

package/dist/{update-qVp7yL5D.js → update-BYHlwpAq.js}

@@ -1,11 +1,14 @@
+import { Ct as projectsResponseSchema, U as decodeUnknownOrNull, ct as healthResponseSchema } from "./dist-BsLn2Gbc.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { z } from "zod";
 import { spawn } from "node:child_process";
 import crypto from "node:crypto";
 import fsSync, { constants } from "node:fs";
 import os from "node:os";
+import { createInterface } from "node:readline";
+import { z } from "zod";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import kleur from "kleur";
 //#region src/duration.ts
 const DURATION_UNITS = /* @__PURE__ */ new Map([
 	["ms", 1],
@@ -39,6 +42,90 @@ 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
+//#region src/cli/output.ts
+/** Human output only. JSON and raw streams must bypass this formatter. */
+function humanOutput(environment = process.env, isTTY = false, json = false) {
+	const force = environment.FORCE_COLOR;
+	const enabled = !json && environment.NO_COLOR === void 0 && !environment.NODE_DISABLE_COLORS && (force !== void 0 ? force !== "0" && force !== "false" : isTTY && environment.TERM !== "dumb");
+	const style = (format) => (text) => {
+		if (!enabled || !text) return text;
+		const previous = kleur.enabled;
+		kleur.enabled = true;
+		try {
+			return format(text);
+		} finally {
+			kleur.enabled = previous;
+		}
+	};
+	const heading = style(kleur.bold);
+	const detail = style(kleur.dim);
+	const action = style(kleur.cyan);
+	const tones = {
+		success: style(kleur.green),
+		warning: style(kleur.yellow),
+		failure: style(kleur.red),
+		neutral: (text) => text
+	};
+	const indent = (text) => text ? text.split("\n").map((line) => `  ${line}`).join("\n") : "";
+	const summary = (text, tone = "neutral") => tones[tone](`${{
+		success: "✓ ",
+		warning: "! ",
+		failure: "✖ ",
+		neutral: ""
+	}[tone]}${text}`);
+	const section = (title, text) => `${heading(title)}\n${indent(text)}`;
+	const rows = (values) => {
+		const entries = values.filter((entry) => entry !== null);
+		const width = Math.max(0, ...entries.map(([label]) => label.length));
+		return entries.map(([label, value]) => `  ${label.padEnd(width)}  ${String(value).replaceAll("\n", "\n" + " ".repeat(width + 4))}`).join("\n");
+	};
+	const next = (commands) => commands.length ? section("Next", commands.map((command, index) => index === 0 ? action(command) : command).join("\n")) : "";
+	const blocks = (...parts) => parts.filter(Boolean).join("\n\n");
+	return {
+		enabled,
+		heading,
+		detail,
+		action,
+		summary,
+		section,
+		rows,
+		next,
+		blocks,
+		indent
+	};
+}
+function stateName(state) {
+	const words = state.replaceAll("_", " ");
+	return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function formatServiceStatus(status, output) {
+	const tone = !status.supported || status.state === "unhealthy" ? "failure" : status.state === "healthy" || status.state === "stopped" || status.state === "disabled" ? "success" : "warning";
+	return output.blocks(output.heading("Treeport service"), output.summary(status.administratorCommand ? "Administrator action required" : status.state === "stale" ? "Needs repair" : status.state === "disabled" ? "Not installed" : stateName(status.state), tone), output.rows([["Mode", status.mode === "headless" ? "Headless service" : status.mode === "user" ? "User service" : "Not installed"], ["Startup", !status.installed ? "Not enabled" : status.enabledAtBoot ? "Before login" : status.mode === "headless" ? "Not enabled before login" : "After login"]]), output.detail(output.rows([
+		["Manager", status.manager ?? "Unsupported"],
+		status.definitionPath && status.issues.length ? ["Definition", status.definitionPath] : null,
+		status.daemon?.state ? ["PID", status.daemon.state.pid] : null
+	])), status.issues.length > 0 && output.section("Attention", [...new Set(status.issues)].map((issue) => issue.replace("Run `treeport service enable --headless`; routine start and stop then need no administrator.", "After migration, routine start and stop need no administrator.")).join("\n")), status.administratorCommand ? output.next([status.administratorCommand, "Then run: treeport service status"]) : output.next([...new Set(status.recoveryCommands)]));
+}
+function formatLocalUpdateError$1(message, details, output, cancelled = false) {
+	const reason = details.rollback?.succeeded && message === "The update failed. Treeport restored the previous version." ? details.cause ?? "The update could not be completed." : details.recovery && message.endsWith(details.recovery) ? message.slice(0, -details.recovery.length).trim() : message;
+	const reasons = [...new Set([details.recovery === "Re-run `treeport update --yes` to approve the update." ? reason.replace(/ Re-run with --yes\.$/, "") : cancelled ? reason.replace(/^Treeport update cancelled\. /, "") : reason, details.cause].filter((value) => Boolean(value)))];
+	const recovery = [...new Set([
+		details.rollback?.succeeded || details.recovery === "The previous Treeport version is active again." ? "Treeport restored the previous version." : null,
+		details.recovery === "The previous Treeport version is active again." ? null : details.recovery,
+		details.administratorCommand
+	].filter((value) => Boolean(value)))];
+	return output.blocks(output.summary(cancelled ? "Update cancelled" : "Update failed", cancelled ? "warning" : "failure"), output.indent(reasons.join("\n")), details.rollback?.attempted && !details.rollback.succeeded && output.summary("Rollback did not succeed", "failure"), output.next(recovery), output.detail(output.rows([
+		details.phase ? ["Phase", stateName(details.phase)] : null,
+		details.migrationState ? ["Migration", stateName(details.migrationState)] : null,
+		details.logPath ? ["Daemon log", details.logPath] : null,
+		...(details.snapshotPaths ?? []).map((snapshot) => ["Pre-migration snapshot", snapshot])
+	])));
+}
+function formatLocalUpdateResult(result, output) {
+	if (result.status === "current") return output.summary(`Treeport ${result.toVersion} is current`, "success");
+	return output.blocks(output.summary(`Updated Treeport ${result.fromVersion} → ${result.toVersion}`, "success"), result.daemon.restarted ? output.summary(`Treeport ${result.daemon.wasRunning ? "restarted" : "started"} — ${result.daemon.healthy ? "Healthy" : "Health not verified"}`, result.daemon.healthy ? "success" : "warning") : "Treeport remains stopped", result.daemon.restarted && output.rows([["Daemon version", result.daemon.version ?? "Unavailable"], ["Terminals", result.terminals.preserved ? `${result.terminals.before} preserved · ${result.terminals.after} available` : `${result.terminals.after} of ${result.terminals.before} found`]]), !result.daemon.restarted && output.next(["treeport start"]));
+}
+//#endregion
 //#region src/cli/lifecycle.ts
 const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_PORT = 8733;
@@ -86,21 +173,6 @@ const daemonRecordSchema = z.strictObject({
 		"external"
 	])
 });
-const healthRecordSchema = z.strictObject({
-	ok: z.literal(true),
-	version: z.string(),
-	protocolVersion: z.number(),
-	hostname: z.string().optional(),
-	pid: z.number(),
-	instanceId: z.string().nullable(),
-	installationMethod: z.string(),
-	daemonLifecycle: z.enum([
-		"treeport",
-		"service",
-		"external"
-	]),
-	url: z.string()
-});
 async function preferences(env = process.env) {
 	return await readJson$1(localPaths(env).preferencesPath, preferencesSchema) ?? {};
 }
@@ -151,15 +223,18 @@ async function daemonHealth(apiUrl, timeoutMs = 1500) {
 	const signal = AbortSignal.timeout(timeoutMs);
 	return fetch(`${apiUrl}/api/health`, { signal }).then(async (response) => {
 		if (!response.ok) return null;
-		const result = healthRecordSchema.safeParse(await response.json());
-		return result.success ? result.data : null;
+		return decodeUnknownOrNull(healthResponseSchema, await response.json());
 	}).catch(() => null);
 }
 function matchesOwnership(state, observed) {
 	return observed.pid === state.pid && observed.instanceId === state.instanceId && path.resolve(state.dataDir) === localPaths().dataDir;
 }
 async function readState() {
-	return readJson$1(localPaths().statePath, daemonRecordSchema);
+	const paths = localPaths();
+	return await fs.readFile(paths.lockPath, "utf8").then((value) => daemonRecordSchema.parse(JSON.parse(value))).catch((error) => {
+		if (error.code === "ENOENT") return null;
+		throw new Error(`Cannot verify daemon ownership at ${paths.lockPath}. Inspect the daemon log before starting or stopping Treeport.`, { cause: error });
+	}) ?? readJson$1(paths.statePath, daemonRecordSchema);
 }
 async function removeStaleState(state) {
 	const paths = localPaths();
@@ -373,11 +448,7 @@ async function disableTailscaleRemote() {
 }
 async function runDoctor() {
 	const paths = localPaths();
-	const gitPath = process.env.TREEPORT_GIT_PATH?.trim() || "git";
-	const tmuxPath = process.env.TREEPORT_TMUX_PATH?.trim() || "tmux";
-	const [git, tmux] = await Promise.all([executableCheck(gitPath, ["--version"]), executableCheck(tmuxPath, ["-V"])]);
-	const tmuxMatch = /tmux\s+(\d+)\.(\d+)/i.exec(tmux.detail);
-	const tmuxSupported = Boolean(tmux.ok && tmuxMatch && (Number(tmuxMatch[1]) > 3 || Number(tmuxMatch[1]) === 3 && Number(tmuxMatch[2]) >= 2));
+	const git = await executableCheck(process.env.TREEPORT_GIT_PATH?.trim() || "git", ["--version"]);
 	const checkDirectory = (directoryPath) => fs.mkdir(directoryPath, {
 		recursive: true,
 		mode: 448
@@ -399,11 +470,6 @@ async function runDoctor() {
 			name: "Git",
 			...git
 		},
-		{
-			name: "tmux",
-			ok: tmuxSupported,
-			detail: tmuxSupported ? tmux.detail : `${tmux.detail}. Treeport requires tmux 3.2 or newer.`
-		},
 		{
 			name: "Data directory",
 			...dataDirectory
@@ -492,7 +558,8 @@ async function daemonUp(options) {
 		TREEPORT_WEB_DIST: webDist
 	};
 	if (options.foreground) {
-		console.log(`Treeport will listen on ${apiUrl}`);
+		const output = options.output ?? humanOutput(process.env, Boolean(process.stdout.isTTY));
+		console.log(output.blocks(output.summary("Treeport is starting", "warning"), output.rows([["URL", apiUrl]])));
 		const child = spawn(process.execPath, [serverEntry], {
 			env: childEnvironment,
 			stdio: "inherit"
@@ -547,9 +614,109 @@ async function readDaemonLogs(lines = 100) {
 	})).split("\n").slice(-lines - 1).join("\n");
 }
 //#endregion
+//#region src/cli/service-supervisor.ts
+function serviceSupervisorSource() {
+	return `import fs from 'node:fs/promises'
+import { constants } from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+
+const [recordPath, owner] = process.argv.slice(2)
+const uid = Number(owner)
+if (!Number.isInteger(uid) || uid <= 0 || process.getuid?.() !== uid || !path.isAbsolute(recordPath)) {
+  throw new Error('Treeport supervisor must run as its non-root owner')
+}
+const directory = path.dirname(recordPath)
+const statePath = path.join(directory, 'supervisor.json')
+let child = null
+let stopping = null
+let lastState = ''
+let exiting = false
+let retryAt = 0
+let reported = ''
+process.on('SIGTERM', () => { exiting = true })
+process.on('SIGINT', () => { exiting = true })
+
+async function readRecord() {
+  // Reject symlinks and paths writable by another account, including ancestors.
+  for (let current = directory; ; current = path.dirname(current)) {
+    const stat = await fs.lstat(current)
+    if (!stat.isDirectory() || (stat.uid !== uid && stat.uid !== 0) ||
+        ((stat.mode & 0o022) !== 0 && !(stat.uid === 0 && (stat.mode & 0o1000)))) {
+      throw new Error('Unsafe Treeport service directory: ' + current)
+    }
+    if (current === path.dirname(current)) break
+  }
+  const handle = await fs.open(recordPath, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const stat = await handle.stat()
+    if (!stat.isFile() || stat.uid !== uid || (stat.mode & 0o077) !== 0) {
+      throw new Error('Unsafe Treeport service record')
+    }
+    const record = JSON.parse(await handle.readFile('utf8'))
+    if (record.uid !== uid || record.supervisorVersion !== 1 ||
+        !['running', 'stopped'].includes(record.requestedState) ||
+        typeof record.updatedAt !== 'string' || !path.isAbsolute(record.cliEntrypoint) ||
+        record.environment?.TREEPORT_SERVICE_RECORD !== recordPath) {
+      throw new Error('Invalid Treeport supervisor record')
+    }
+    return record
+  } finally {
+    await handle.close()
+  }
+}
+
+while (true) {
+  const record = await readRecord().catch(error => {
+    if (reported !== error.message) console.error(error.message)
+    reported = error.message
+    return null
+  })
+  if (exiting || !record || record.requestedState === 'stopped') {
+    if (child && stopping !== child) {
+      stopping = child
+      child.kill('SIGTERM')
+    }
+  } else if (!child && Date.now() >= retryAt) {
+    // Resolve the stable CLI path on every spawn, after the updater's atomic switch.
+    const log = await fs.open(record.logPath, 'a', 0o600)
+    const launched = spawn(record.cliEntrypoint, ['service', 'run'], {
+      env: { ...record.environment, PATH: path.dirname(process.execPath) + ':' + record.environment.PATH },
+      stdio: ['ignore', log.fd, log.fd]
+    })
+    child = launched
+    const finished = () => {
+      if (child === launched) child = null
+      retryAt = Date.now() + 1000
+    }
+    launched.once('error', error => { console.error(error.message); finished() })
+    launched.once('exit', finished)
+    await log.close()
+  }
+  if (record) {
+    const state = JSON.stringify({
+      pid: process.pid, childPid: child?.pid ?? null,
+      requestedState: record.requestedState, updatedAt: record.updatedAt,
+      requestId: record.supervisorRequestId ?? null
+    })
+    if (state !== lastState) {
+      const temporary = statePath + '.' + process.pid + '.' + Date.now() + '.tmp'
+      await fs.writeFile(temporary, state, { mode: 0o600, flag: 'wx' })
+      await fs.rename(temporary, statePath)
+      lastState = state
+    }
+  }
+  if (exiting && !child) break
+  await new Promise(resolve => setTimeout(resolve, 100))
+}
+`;
+}
+//#endregion
 //#region src/cli/service.ts
 const serviceRecordSchema = z.strictObject({
 	schemaVersion: z.literal(1),
+	supervisorVersion: z.literal(1).nullable().default(null),
+	supervisorRequestId: z.string().uuid().nullable().default(null),
 	manager: z.enum(["launchd", "systemd"]),
 	mode: z.enum(["user", "headless"]).optional(),
 	platform: z.string(),
@@ -883,7 +1050,6 @@ function createServiceEnvironment(input) {
 		TREEPORT_CACHE_DIR: cacheDirectory(input.user.homedir, env),
 		TREEPORT_DATABASE_PATH: env.TREEPORT_DATABASE_PATH?.trim() || path.join(input.paths.dataDir, "treeport.db"),
 		TREEPORT_SHELL: env.TREEPORT_SHELL?.trim() || env.SHELL?.trim() || "/bin/sh",
-		TREEPORT_TMUX_PATH: env.TREEPORT_TMUX_PATH?.trim() || "tmux",
 		TREEPORT_GIT_PATH: env.TREEPORT_GIT_PATH?.trim() || "git",
 		TREEPORT_GH_PATH: env.TREEPORT_GH_PATH?.trim() || "gh",
 		TREEPORT_DAEMON_LIFECYCLE: "service",
@@ -897,12 +1063,12 @@ function definitionForRecord(record) {
 	if (record.manager === "launchd") return serializeLaunchdDefinition(createLaunchdDefinition({
 		label: record.definitionName,
 		mode: record.mode,
-		runnerPath: servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).runnerPath,
+		runnerPath: servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).runnerPath + (record.supervisorVersion ? "-supervised" : ""),
 		username: record.username,
 		group: record.group,
-		environment: record.environment,
+		environment: record.supervisorVersion ? { HOME: record.home } : record.environment,
 		home: record.home,
-		logPath: record.logPath
+		logPath: record.supervisorVersion ? "/dev/null" : record.logPath
 	}));
 	return serializeSystemdDefinition(createSystemdDefinition({
 		runnerPath: servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).runnerPath,
@@ -910,6 +1076,10 @@ function definitionForRecord(record) {
 	}));
 }
 function runnerSource(record) {
+	if (record.supervisorVersion) {
+		const locations = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
+		return `#!/bin/sh\nexec ${shellQuote$1(record.runtimeExecutable)} ${shellQuote$1(path.join(locations.directory, "supervisor.mjs"))} ${shellQuote$1(locations.recordPath)} ${record.uid} >> ${shellQuote$1(record.logPath)} 2>&1\n`;
+	}
 	return `#!/bin/sh
 set -u
 entrypoint=${shellQuote$1(record.cliEntrypoint)}
@@ -931,8 +1101,23 @@ exec "$entrypoint" service run
 function storedServiceMode(input) {
 	return input.mode ?? (input.manager === "launchd" ? "headless" : "user");
 }
+async function assertServiceDirectory(directory, uid) {
+	for (let current = directory;; current = path.dirname(current)) {
+		const metadata = await fs.lstat(current);
+		if (!metadata.isDirectory() || metadata.uid !== uid && metadata.uid !== 0 || (metadata.mode & 18) !== 0 && !(metadata.uid === 0 && metadata.mode & 512)) throw new Error(`Unsafe Treeport service directory: ${current}`);
+		if (current === path.dirname(current)) break;
+	}
+}
 async function readServiceRecord(recordPath) {
+	const metadata = await fs.lstat(recordPath).catch((error) => {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	});
+	if (!metadata) return null;
+	if (!metadata.isFile() || metadata.isSymbolicLink() || (metadata.mode & 63) !== 0) throw new Error("Refusing an unsafe Treeport service record.");
+	await assertServiceDirectory(path.dirname(recordPath), metadata.uid);
 	const record = await readJson(recordPath, serviceRecordSchema);
+	if (record && (!metadata.isFile() || metadata.isSymbolicLink() || metadata.uid !== record.uid || (metadata.mode & 63) !== 0 || process.getuid?.() !== 0 && process.getuid?.() !== record.uid)) throw new Error("Refusing an unsafe or foreign-owned Treeport service record.");
 	if (!record) return null;
 	return {
 		...record,
@@ -943,7 +1128,14 @@ async function currentRecord() {
 	return readServiceRecord(servicePaths().recordPath);
 }
 async function saveRecord(record) {
-	await writeJson$2(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).recordPath, record);
+	if (process.getuid?.() !== record.uid || record.uid === 0) throw new Error("Run service lifecycle commands as the non-root Treeport data owner.");
+	const locations = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
+	await assertServiceDirectory(locations.directory, record.uid);
+	await writeJson$2(locations.recordPath, {
+		...record,
+		supervisorVersion: record.supervisorVersion ?? void 0,
+		supervisorRequestId: record.supervisorRequestId ?? void 0
+	});
 }
 async function managerState(record) {
 	if (record.manager === "launchd") {
@@ -1034,6 +1226,14 @@ async function untrackedDefinition() {
 async function serviceInstalled() {
 	return await currentRecord() !== null || await untrackedDefinition() !== null;
 }
+function serviceHealthState(input) {
+	if (input.actionRequired) return "action_required";
+	if (input.stale) return "stale";
+	if (input.installed && input.requestedState === "stopped") return input.daemonRunning ? "unhealthy" : "stopped";
+	if (input.healthy) return "healthy";
+	if (input.installed && input.managerActive && !input.supervised) return "starting";
+	return input.installed ? "unhealthy" : "disabled";
+}
 async function serviceStatus() {
 	const manager = managerForPlatform();
 	const record = await currentRecord();
@@ -1118,8 +1318,8 @@ async function serviceStatus() {
 	const definitionPresent = definitionContent !== "";
 	const definitionMatches = definitionPresent && fingerprint(definitionContent) === record.definitionHash;
 	const invokedEntrypoint = currentEntrypoint();
-	const entrypointMatches = Boolean(entrypointExists && (invokedEntrypoint === null || path.resolve(invokedEntrypoint) === path.resolve(record.cliEntrypoint)));
-	const environmentMatches = fingerprint(createServiceEnvironment({
+	const entrypointMatches = Boolean(entrypointExists && (record.supervisorVersion !== null || invokedEntrypoint === null || path.resolve(invokedEntrypoint) === path.resolve(record.cliEntrypoint)));
+	const currentEnvironment = createServiceEnvironment({
 		user: {
 			uid: record.uid,
 			gid: record.gid,
@@ -1134,7 +1334,8 @@ async function serviceStatus() {
 		apiUrl: record.apiUrl,
 		recordPath: paths.recordPath,
 		installationMethod: record.installationMethod
-	})) === record.environmentHash;
+	});
+	const environmentMatches = fingerprint(record.supervisorVersion ? record.environment : currentEnvironment) === record.environmentHash;
 	const healthy = Boolean(daemon.verified && daemon.health?.daemonLifecycle === "service" && daemon.state?.daemonLifecycle === "service" && path.resolve(daemon.state.dataDir) === path.resolve(record.dataDir));
 	const installed = managerStatus.enabled;
 	const enabledAtBoot = installed && (record.manager === "launchd" ? record.mode === "headless" : managerStatus.lingering);
@@ -1143,6 +1344,11 @@ async function serviceStatus() {
 	const issues = [];
 	const recoveryCommands = [];
 	const repairCommand = record.manager === "launchd" && record.mode === "headless" ? "treeport service enable --headless" : "treeport service enable";
+	const needsMigration = record.manager === "launchd" && record.mode === "headless" && !record.supervisorVersion;
+	if (needsMigration) {
+		issues.push("This headless installation needs a one-time administrator migration. Run `treeport service enable --headless`; routine start and stop then need no administrator.");
+		recoveryCommands.push(repairCommand);
+	}
 	if (record.manager !== manager) issues.push(`The service record uses ${record.manager}, but this host requires ${manager}.`);
 	if (!definitionMatches && !record.pendingAdministratorRequestId) {
 		issues.push(definitionPresent ? `The service definition at ${record.definitionPath} was changed.` : `The service definition is missing at ${record.definitionPath}.`);
@@ -1169,8 +1375,17 @@ async function serviceStatus() {
 		issues.push("The supervised Treeport daemon is not healthy.");
 		recoveryCommands.push("treeport start");
 	}
-	const stale = record.manager !== manager || !definitionMatches || !environmentMatches || !entrypointMatches || definitionPresent && !installed || managerStatus.managerIssue !== null;
-	const state = record.pendingAdministratorRequestId || record.manager === "systemd" && installed && !managerStatus.lingering ? "action_required" : stale ? "stale" : healthy ? "healthy" : installed && record.requestedState === "stopped" ? "stopped" : installed && managerStatus.active ? "starting" : installed ? "unhealthy" : "disabled";
+	const stale = needsMigration || record.manager !== manager || !definitionMatches || !environmentMatches || !entrypointMatches || definitionPresent && !installed || managerStatus.managerIssue !== null;
+	const state = serviceHealthState({
+		actionRequired: Boolean(record.pendingAdministratorRequestId) || record.manager === "systemd" && installed && !managerStatus.lingering,
+		stale,
+		healthy,
+		installed,
+		requestedState: record.requestedState,
+		daemonRunning: daemon.running,
+		managerActive: managerStatus.active,
+		supervised: record.supervisorVersion !== null
+	});
 	return {
 		supported: true,
 		manager,
@@ -1233,6 +1448,8 @@ async function prepareRecord(requestedMode) {
 	if (previous?.manager === "launchd" && path.resolve(previous.definitionPath) !== path.resolve(definitionPath)) throw new Error(`The service record points to an unexpected definition at ${previous.definitionPath}. Refusing to create another definition.`);
 	const base = {
 		schemaVersion: 1,
+		supervisorVersion: manager === "launchd" && mode === "headless" ? 1 : null,
+		supervisorRequestId: null,
 		manager,
 		mode,
 		platform: process.platform,
@@ -1270,6 +1487,11 @@ async function prepareRecord(requestedMode) {
 }
 async function writeServiceFiles(record, definition) {
 	const locations = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
+	await fs.mkdir(locations.directory, {
+		recursive: true,
+		mode: 448
+	});
+	await assertServiceDirectory(locations.directory, record.uid);
 	await fs.mkdir(path.dirname(record.logPath), {
 		recursive: true,
 		mode: 448
@@ -1278,8 +1500,10 @@ async function writeServiceFiles(record, definition) {
 		recursive: true,
 		mode: 448
 	});
-	await fs.writeFile(locations.runnerPath, runnerSource(record), { mode: 448 });
-	await fs.chmod(locations.runnerPath, 448);
+	if (record.supervisorVersion) await fs.writeFile(path.join(locations.directory, "supervisor.mjs"), serviceSupervisorSource(), { mode: 384 });
+	const runnerPath = locations.runnerPath + (record.supervisorVersion ? "-supervised" : "");
+	await fs.writeFile(runnerPath, runnerSource(record), { mode: 448 });
+	await fs.chmod(runnerPath, 448);
 	if (record.manager === "launchd" && record.mode === "headless") await fs.writeFile(locations.stagedDefinitionPath, definition, { mode: 384 });
 	else {
 		await fs.mkdir(path.dirname(record.definitionPath), {
@@ -1314,7 +1538,7 @@ async function prepareAdministratorRequest(record, operation) {
 		group: record.group,
 		home: record.home,
 		serviceRecordPath: locations.recordPath,
-		runnerPath: locations.runnerPath,
+		runnerPath: locations.runnerPath + (record.supervisorVersion ? "-supervised" : ""),
 		definitionName: record.definitionName,
 		definitionPath: record.definitionPath,
 		stagedDefinitionPath: locations.stagedDefinitionPath,
@@ -1474,11 +1698,13 @@ async function serviceStart() {
 	const record = await currentRecord();
 	if (!record) throw new Error("Treeport service mode is disabled. Run `treeport service enable` first.");
 	const current = await serviceStatus();
-	if (current.state === "healthy") return {
+	if (current.state === "healthy" && record.requestedState === "running") return {
 		status: current,
 		changed: false,
 		administratorCommand: null
 	};
+	if (record.manager === "launchd" && record.mode === "headless" && !record.supervisorVersion) throw new Error("This headless service needs a one-time administrator migration. Run `treeport service enable --headless` first.");
+	if (record.supervisorVersion && !current.active) throw new Error("The headless supervisor is not loaded. Run `treeport service enable --headless` to repair the startup integration with administrator approval.");
 	if (current.administratorCommand) return {
 		status: current,
 		changed: false,
@@ -1488,17 +1714,18 @@ async function serviceStart() {
 	const next = {
 		...record,
 		requestedState: "running",
+		supervisorRequestId: record.supervisorVersion ? crypto.randomUUID() : null,
 		pendingAdministratorRequestId: null,
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
 	await saveRecord(next);
 	if (record.manager === "launchd") {
 		if (record.mode === "headless") {
-			const prepared = await prepareAdministratorRequest(next, "start");
+			await waitForService(next);
 			return {
 				status: await serviceStatus(),
 				changed: true,
-				administratorCommand: prepared.command
+				administratorCommand: null
 			};
 		}
 		const launchctl = await executablePath("launchctl");
@@ -1548,7 +1775,8 @@ async function serviceStop() {
 	const record = await currentRecord();
 	if (!record) throw new Error("Treeport service mode is disabled.");
 	const current = await serviceStatus();
-	if (current.state === "stopped") return {
+	if (record.manager === "launchd" && record.mode === "headless" && !record.supervisorVersion) throw new Error("This headless service needs a one-time administrator migration. Run `treeport service enable --headless` first, or `treeport service disable` for administrator-approved removal.");
+	if (current.state === "stopped" && !record.supervisorVersion) return {
 		status: current,
 		changed: false,
 		administratorCommand: null
@@ -1556,17 +1784,36 @@ async function serviceStop() {
 	const next = {
 		...record,
 		requestedState: "stopped",
+		supervisorRequestId: record.supervisorVersion ? crypto.randomUUID() : null,
 		pendingAdministratorRequestId: null,
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
 	await saveRecord(next);
 	if (record.manager === "launchd") {
 		if (record.mode === "headless") {
-			const prepared = await prepareAdministratorRequest(next, "stop");
+			if (current.active) {
+				const statePath = path.join(servicePaths({ TREEPORT_DATA_DIR: record.dataDir }).directory, "supervisor.json");
+				const deadline = Date.now() + 15e3;
+				let stopped = false;
+				while (Date.now() < deadline) {
+					const acknowledgement = await readJson(statePath, z.object({
+						requestedState: z.enum(["running", "stopped"]),
+						requestId: z.string().nullable(),
+						childPid: z.number().nullable()
+					}));
+					if (acknowledgement?.requestedState === "stopped" && acknowledgement.requestId === next.supervisorRequestId && acknowledgement.childPid === null) {
+						stopped = true;
+						break;
+					}
+					await new Promise((resolve) => setTimeout(resolve, 100));
+				}
+				if (!stopped) throw new Error(`Treeport supervisor did not confirm shutdown. Stopped intent is preserved; inspect ${record.logPath} before updating.`);
+			}
+			await daemonDown();
 			return {
 				status: await serviceStatus(),
 				changed: true,
-				administratorCommand: prepared.command
+				administratorCommand: null
 			};
 		}
 		const commands = userLaunchdCommands({
@@ -1679,7 +1926,7 @@ async function serviceApply(requestPath) {
 	if ((metadata.mode & 63) !== 0) throw new Error("The service apply request must not be readable or writable by other users.");
 	const request = await readJson(requestPath, administratorRequestSchema);
 	if (!request) throw new Error("The service apply request is invalid.");
-	if (metadata.uid !== request.uid) throw new Error("The service apply request owner does not match its target user.");
+	if (request.uid <= 0 || 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;
@@ -1692,13 +1939,27 @@ async function serviceApply(requestPath) {
 	const record = await readServiceRecord(request.serviceRecordPath);
 	if (!record || record.uid !== request.uid || record.username !== request.username || record.manager !== "launchd" || record.mode !== "headless" || record.definitionName !== request.definitionName || record.definitionPath !== request.definitionPath || record.cliEntrypoint !== request.cliEntrypoint || record.runtimeExecutable !== request.runtimeExecutable || record.runtimeEntrypoint !== request.runtimeEntrypoint || record.definitionHash !== request.definitionHash || record.pendingAdministratorRequestId !== request.id) throw new Error("The service apply request does not match the current Treeport service record.");
 	if (account.uid !== 0) throw new Error("Treeport service apply lost root privileges.");
+	const locations = servicePaths({ TREEPORT_DATA_DIR: record.dataDir });
+	const location = launchdLocation({
+		uid: record.uid,
+		home: record.home,
+		mode: "headless"
+	});
+	const groupId = await runCommand$1(await executablePath("id"), ["-g", record.username]);
+	const groupName = await primaryGroup(record.username);
+	if (groupId.code !== 0 || Number(groupId.stdout.trim()) !== record.gid || record.gid !== request.gid || groupName !== record.group || record.group !== request.group || request.definitionName !== location.name || request.definitionPath !== location.path || request.serviceRecordPath !== locations.recordPath || request.runnerPath !== locations.runnerPath + (record.supervisorVersion ? "-supervised" : "") || request.stagedDefinitionPath !== locations.stagedDefinitionPath || requestPath !== path.join(locations.requestsDirectory, `${request.id}.json`)) throw new Error("The administrator request has an unsafe account or installation path.");
+	await assertServiceDirectory(locations.requestsDirectory, record.uid);
+	if (request.operation === "start" || request.operation === "stop") throw new Error("Legacy administrator start/stop requests are no longer supported. Run `treeport service enable --headless` for the one-time startup integration migration.");
 	const launchctl = await executablePath("launchctl");
 	const target = `system/${request.definitionName}`;
 	if (request.operation === "enable") {
-		const staged = await fs.readFile(request.stagedDefinitionPath, "utf8");
-		if (fingerprint(staged) !== request.definitionHash || !staged.includes(`<string>${xml(request.username)}</string>`) || !staged.includes(`<string>${xml(request.runnerPath)}</string>`)) throw new Error("The staged LaunchDaemon definition does not match the approved request.");
+		const definition = definitionForRecord(record);
+		if (!record.supervisorVersion || fingerprint(definition) !== request.definitionHash) throw new Error("The staged LaunchDaemon definition does not match the approved request.");
 		const temporaryPath = `${request.definitionPath}.${process.pid}.tmp`;
-		await fs.copyFile(request.stagedDefinitionPath, temporaryPath);
+		await fs.writeFile(temporaryPath, definition, {
+			mode: 420,
+			flag: "wx"
+		});
 		await fs.chown(temporaryPath, 0, 0);
 		await fs.chmod(temporaryPath, 420);
 		await fs.rename(temporaryPath, request.definitionPath);
@@ -1711,38 +1972,28 @@ async function serviceApply(requestPath) {
 			request.definitionPath
 		]);
 		if (bootstrapped.code !== 0) throw commandError("launchctl bootstrap", bootstrapped);
-	} else if (request.operation === "start") {
-		const enabled = await runCommand$1(launchctl, ["enable", target]);
-		if (enabled.code !== 0) throw commandError("launchctl enable", enabled);
-		const started = (await runCommand$1(launchctl, ["print", target])).code === 0 ? await runCommand$1(launchctl, ["kickstart", target]) : await runCommand$1(launchctl, [
-			"bootstrap",
-			"system",
-			request.definitionPath
-		]);
-		if (started.code !== 0) throw commandError("launchctl start", started);
-	} else if (request.operation === "stop") {
-		const stopped = await runCommand$1(launchctl, ["bootout", target]);
-		if (stopped.code !== 0 && !stopped.stderr.includes("No such process")) throw commandError("launchctl bootout", stopped);
 	} else {
 		const installed = await fs.readFile(request.definitionPath, "utf8").catch(() => "");
 		if (installed && fingerprint(installed) !== request.definitionHash) throw new Error("Refusing to remove a LaunchDaemon definition that Treeport did not create.");
 		await runCommand$1(launchctl, ["bootout", target]);
 		await fs.rm(request.definitionPath, { force: true });
 	}
-	if (request.operation === "enable" || request.operation === "start") await waitForService(record);
+	process.setgroups([]);
+	process.setgid(request.gid);
+	process.setuid(request.uid);
+	if (request.operation === "enable") await waitForService(record);
 	await fs.rename(requestPath, usedPath);
 	if (request.operation === "disable") await fs.rm(path.dirname(request.serviceRecordPath), {
 		recursive: true,
 		force: true
 	});
 	else {
-		await writeJson$2(request.serviceRecordPath, {
-			...record,
-			requestedState: request.operation === "stop" ? "stopped" : "running",
+		const latest = await readServiceRecord(request.serviceRecordPath);
+		if (latest?.pendingAdministratorRequestId === request.id) await writeJson$2(request.serviceRecordPath, {
+			...latest,
 			pendingAdministratorRequestId: null,
 			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		await fs.chown(request.serviceRecordPath, request.uid, request.gid);
 	}
 	return {
 		operation: request.operation,
@@ -1755,8 +2006,12 @@ async function serviceRun() {
 	const record = await readServiceRecord(recordPath);
 	if (!record) throw new Error(`Treeport service record is invalid: ${recordPath}`);
 	if (process.getuid?.() === 0 || process.getuid?.() !== record.uid) throw new Error(`Treeport service must run as ${record.username} (UID ${record.uid}), never as root.`);
-	await writeJson$2(recordPath, {
+	if (record.supervisorVersion) {
+		if (record.requestedState === "stopped") return;
+	} else await writeJson$2(recordPath, {
 		...record,
+		supervisorVersion: void 0,
+		supervisorRequestId: void 0,
 		requestedState: "running",
 		pendingAdministratorRequestId: null,
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -1847,16 +2102,18 @@ async function createUpdateStartupReporter(config) {
 	const paths = updatePaths(config.dataDir);
 	const pending = await fs.readFile(paths.pending, "utf8").then((value) => pendingSchema.safeParse(JSON.parse(value))).then((result) => result.success ? result.data : null).catch(() => null);
 	const active = pending && pending.targetVersion === config.appVersion ? pending : null;
+	const previous = await readUpdateStartupReport(config.dataDir);
+	const previousState = active && previous?.operationId === active.operationId && previous.targetVersion === active.targetVersion ? previous.migrationState : "unknown";
 	const report = active ? {
 		schemaVersion: 1,
 		operationId: active.operationId,
 		targetVersion: active.targetVersion,
 		instanceId: config.instanceId ?? null,
-		migrationState: "not_started",
+		migrationState: previousState,
 		ready: false,
 		error: null,
 		logPath: path.join(config.dataDir, "logs", "daemon.log"),
-		snapshotPaths: [],
+		snapshotPaths: previous?.operationId === active.operationId && previous.targetVersion === active.targetVersion ? previous.snapshotPaths : [],
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 	} : null;
 	const save = async () => {
@@ -1868,14 +2125,20 @@ async function createUpdateStartupReporter(config) {
 	return {
 		async databaseOpening() {
 			if (report) {
-				report.migrationState = "unknown";
+				report.migrationState = previousState === "advanced" ? "advanced" : "unknown";
+				await save();
+			}
+		},
+		async snapshotCreated(snapshotPath) {
+			if (report) {
+				report.snapshotPaths = [.../* @__PURE__ */ new Set([...report.snapshotPaths, snapshotPath])];
 				await save();
 			}
 		},
 		async databaseOpened(input) {
 			if (report) {
-				report.migrationState = input.migrationState;
-				report.snapshotPaths = input.snapshotPaths;
+				report.migrationState = previousState === "advanced" || input.migrationState === "advanced" ? "advanced" : previousState === "unknown" ? "unknown" : "unchanged";
+				report.snapshotPaths = [.../* @__PURE__ */ new Set([...report.snapshotPaths, ...input.snapshotPaths])];
 				await save();
 			}
 		},
@@ -1950,6 +2213,7 @@ const operationSchema = z.strictObject({
 	stagedTarget: z.string().nullable(),
 	previousTarget: z.string().nullable(),
 	daemonWasRunning: z.boolean(),
+	startRequested: z.boolean().default(false),
 	daemonLifecycle: z.enum(["treeport", "service"]).nullable(),
 	serviceMode: z.enum(["user", "headless"]).nullable(),
 	terminalIds: z.array(z.string()),
@@ -1987,6 +2251,35 @@ const packedReleaseSchema = z.tuple([z.looseObject({
 	filename: z.string().min(1),
 	integrity: z.string().min(1)
 })]);
+function formatLocalUpdateError(message, details = {}) {
+	return [...new Set([
+		message,
+		details.cause,
+		details.recovery,
+		details.logPath ? `Daemon log: ${details.logPath}` : null,
+		...(details.snapshotPaths ?? []).map((snapshot) => `Pre-migration snapshot: ${snapshot}`)
+	].filter(Boolean))].join("\n");
+}
+async function confirmLocalUpdate(preview, signal, input = process.stdin, output = process.stderr, style = humanOutput(process.env, output === process.stderr && Boolean(process.stderr.isTTY))) {
+	if (signal.aborted) return false;
+	return new Promise((resolve) => {
+		const prompt = createInterface({
+			input,
+			output
+		});
+		const cancel = () => prompt.close();
+		signal.addEventListener("abort", cancel, { once: true });
+		prompt.once("SIGINT", cancel);
+		prompt.once("close", () => {
+			signal.removeEventListener("abort", cancel);
+			resolve(false);
+		});
+		prompt.question(style.blocks(style.heading(`Update Treeport ${preview.fromVersion} -> ${preview.toVersion}?`), style.indent(["Clients can briefly disconnect. Terminal sessions are preserved.", preview.recovery ? "This also repairs an interrupted update." : preview.daemonWasRunning ? "Treeport will stop, update, and restart." : preview.startRequested ? "Treeport will start after the update." : "Treeport will remain stopped."].join("\n")), style.action("Continue? [y/N] ")), (answer) => {
+			resolve(/^(y|yes)$/i.test(answer.trim()) && !signal.aborted);
+			prompt.close();
+		});
+	});
+}
 var LocalUpdateError = class extends Error {
 	code;
 	details;
@@ -2003,7 +2296,9 @@ var LocalUpdateError = class extends Error {
 			"UPDATE_IN_PROGRESS",
 			"UPDATE_DOWNGRADE_REFUSED",
 			"UPDATE_DAEMON_OWNERSHIP_FAILED",
-			"UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED"
+			"UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED",
+			"UPDATE_CONFIRMATION_REQUIRED",
+			"UPDATE_SERVICE_NOT_READY"
 		].includes(code) ? 5 : 1);
 	}
 };
@@ -2107,15 +2402,45 @@ async function replaceSymlink(linkPath, target) {
 	await fs.rename(temporaryPath, linkPath);
 }
 async function terminalIds(apiUrl) {
-	const result = await fetch(`${apiUrl}/api/projects`).then(async (response) => response.ok ? response.json() : null).catch(() => null);
-	const parsed = z.looseObject({ projects: z.array(z.looseObject({ worktrees: z.array(z.looseObject({ terminals: z.array(z.looseObject({ id: z.string() })) })) })) }).safeParse(result);
-	if (!parsed.success) throw new Error("Treeport could not read the terminal inventory.");
-	return parsed.data.projects.flatMap((project) => project.worktrees).flatMap((worktree) => worktree.terminals).map((terminal) => terminal.id).sort();
+	const parsed = decodeUnknownOrNull(projectsResponseSchema, await fetch(`${apiUrl}/api/projects`).then(async (response) => response.ok ? response.json() : null).catch(() => null));
+	if (!parsed) throw new Error("Treeport could not read the terminal inventory.");
+	return parsed.projects.flatMap((project) => project.worktrees).flatMap((worktree) => worktree.terminals).map((terminal) => terminal.id).sort();
+}
+function updateMigrationState(operation, report) {
+	if (operation.migrationState === "advanced") return "advanced";
+	if (report?.operationId === operation.operationId && report.targetVersion === operation.toVersion) return report.migrationState;
+	return ["stop", "activate"].includes(operation.phase) && operation.migrationState === "not_started" ? "not_started" : "unknown";
+}
+async function stopUpdateDaemon(lifecycle) {
+	if (lifecycle === "service") {
+		const stopped = await serviceStop();
+		if (stopped.administratorCommand) throw new LocalUpdateError("UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED", "The service requires administrator action and was not stopped.", {
+			phase: "stop",
+			administratorCommand: stopped.administratorCommand,
+			recovery: stopped.administratorCommand
+		});
+		const deadline = Date.now() + 7e3;
+		while ((await daemonStatus()).state) {
+			if (Date.now() >= deadline) throw new Error("Treeport could not verify that the service daemon stopped. Inspect the daemon log before changing the installed version.");
+			await new Promise((resolve) => setTimeout(resolve, 100));
+		}
+	} else await daemonDown();
 }
 async function startThroughStableEntrypoint(entrypoint, environment) {
 	const result = await runCommand(entrypoint, ["start", "--json"], environment);
 	if (result.code !== 0) throw new Error(commandFailure("treeport start", result));
 }
+async function verifyRestoredDaemon(operation, dataDir) {
+	const deadline = Date.now() + 1e4;
+	let daemon = await daemonStatus();
+	while (Date.now() < deadline && !daemon.verified) {
+		await new Promise((resolve) => setTimeout(resolve, 100));
+		daemon = await daemonStatus();
+	}
+	if (!daemon.verified || daemon.health?.version !== operation.fromVersion || daemon.health?.daemonLifecycle !== operation.daemonLifecycle || path.resolve(daemon.state.dataDir) !== dataDir) throw new Error("The previous Treeport daemon did not pass recovery verification.");
+	const recovered = await terminalIds(daemon.state.apiUrl);
+	if (operation.terminalIds.some((id) => !recovered.includes(id))) throw new Error("The previous Treeport daemon did not recover every terminal.");
+}
 async function inspectLocalUpdateInstallation(environment = process.env) {
 	const entrypointValue = environment.TREEPORT_CLI_ENTRYPOINT?.trim();
 	if (!entrypointValue || !path.isAbsolute(entrypointValue)) throw new LocalUpdateError("UPDATE_INSTALLATION_UNSUPPORTED", "Treeport could not identify a stable npm CLI entrypoint. Reinstall Treeport globally with npm, then retry.", { phase: "inspect" });
@@ -2255,8 +2580,10 @@ async function runLocalUpdate(options = {}) {
 		return true;
 	})) throw new LocalUpdateError("UPDATE_IN_PROGRESS", "Another Treeport update is already running.", { phase: "inspect" });
 	let interrupted = false;
+	const cancellation = new AbortController();
 	const interrupt = () => {
 		interrupted = true;
+		cancellation.abort();
 	};
 	process.on("SIGINT", interrupt);
 	process.on("SIGTERM", interrupt);
@@ -2271,6 +2598,7 @@ async function runLocalUpdate(options = {}) {
 		stagedTarget: null,
 		previousTarget: null,
 		daemonWasRunning: false,
+		startRequested: options.start ?? false,
 		daemonLifecycle: null,
 		serviceMode: null,
 		terminalIds: [],
@@ -2282,6 +2610,8 @@ async function runLocalUpdate(options = {}) {
 		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 	};
 	let recoveryOperation = null;
+	let recoveryReport = null;
+	let recoveringPrevious = false;
 	const save = async (phase) => {
 		operation = {
 			...operation,
@@ -2300,49 +2630,21 @@ async function runLocalUpdate(options = {}) {
 			npmPrefix: installation.prefix,
 			activeTarget: installation.managed ? await fs.realpath(installation.currentLink).catch(() => installation.prefix) : installation.prefix
 		};
-		if (staleOperation && staleOperation.daemonWasRunning && DESTRUCTIVE_PHASES.has(staleOperation.phase) && !(await daemonStatus()).running) {
+		if (staleOperation && (staleOperation.daemonWasRunning || staleOperation.startRequested || staleOperation.activated) && DESTRUCTIVE_PHASES.has(staleOperation.phase) && !staleOperation.rollbackSucceeded && !(await daemonStatus()).running) {
 			const staleReport = await readUpdateStartupReport(paths.dataDir);
-			if (Boolean(staleReport?.operationId === staleOperation.operationId && ["advanced", "unknown"].includes(staleReport.migrationState))) {
+			staleOperation.migrationState = updateMigrationState(staleOperation, staleReport);
+			if (["advanced", "unknown"].includes(staleOperation.migrationState)) {
+				recoveryReport = staleReport?.operationId === staleOperation.operationId && staleReport.targetVersion === staleOperation.toVersion ? staleReport : null;
 				if (staleOperation.previousTarget && operation.activeTarget === staleOperation.previousTarget) throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "The older Treeport version is active after a database migration may have started. Treeport will not start it.", {
 					phase: "recovery_required",
 					operationId: staleOperation.operationId,
-					migrationState: staleReport?.migrationState ?? "unknown",
+					migrationState: staleOperation.migrationState,
+					logPath: recoveryReport?.logPath ?? paths.logPath,
+					snapshotPaths: recoveryReport?.snapshotPaths ?? [],
 					recovery: "Install the same or a newer Treeport release and inspect the daemon log."
 				});
-				recoveryOperation = staleOperation;
-			} else {
-				if (staleOperation.previousTarget) await replaceSymlink(installation.currentLink, staleOperation.previousTarget);
-				await fs.rm(path.join(updateDirectory, "pending-startup.json"), { force: true });
-				await fs.rm(path.join(updateDirectory, "startup-report.json"), { force: true });
-				await startThroughStableEntrypoint(installation.entrypoint, environment).catch((error) => {
-					throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport restored the previous version but could not restart its daemon.", {
-						phase: "recovery_required",
-						operationId: staleOperation.operationId,
-						cause: error instanceof Error ? error.message : String(error),
-						recovery: "Inspect the daemon log, then run `treeport start`."
-					});
-				});
-				await writeJson(operationPath, {
-					...staleOperation,
-					phase: "complete",
-					activated: false,
-					rollbackAttempted: true,
-					rollbackSucceeded: true,
-					recoveryAction: "Run `treeport update` again.",
-					updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-				});
-				throw new LocalUpdateError("UPDATE_ROLLED_BACK", "Treeport recovered the interrupted update and restored the previous running version. Run `treeport update` again.", {
-					phase: "rollback",
-					operationId: staleOperation.operationId,
-					migrationState: staleReport?.migrationState ?? "not_started",
-					rollback: {
-						attempted: true,
-						safe: true,
-						succeeded: true
-					},
-					recovery: "Run `treeport update` again."
-				});
 			}
+			recoveryOperation = staleOperation;
 		}
 		await save("inspect");
 		const initialDaemon = await daemonStatus();
@@ -2366,11 +2668,6 @@ async function runLocalUpdate(options = {}) {
 		}
 		const installedService = await serviceInstalled();
 		const serviceBefore = installedService ? await serviceStatus() : null;
-		if (serviceBefore?.mode === "headless" && (serviceBefore.active || initialDaemon.running)) throw new LocalUpdateError("UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED", "Stop the advanced headless service with its administrator action, then run `treeport update` again.", {
-			phase: "inspect",
-			operationId,
-			mode: "headless"
-		});
 		if (installedService && initialDaemon.running && initialDaemon.health?.daemonLifecycle !== "service") throw new LocalUpdateError("UPDATE_DAEMON_OWNERSHIP_FAILED", "The running daemon does not belong to the installed Treeport service lifecycle.", {
 			phase: "inspect",
 			operationId
@@ -2384,13 +2681,15 @@ async function runLocalUpdate(options = {}) {
 			phase: "resolve",
 			operationId
 		});
-		if (comparison === 0 && recoveryOperation) throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport needs a newer release to recover after the interrupted database migration.", {
+		if (comparison === 0 && recoveryOperation && ["advanced", "unknown"].includes(recoveryOperation.migrationState)) throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport needs a newer release to recover after the interrupted database migration.", {
 			phase: "recovery_required",
 			operationId: recoveryOperation.operationId,
 			migrationState: recoveryOperation.migrationState,
+			logPath: recoveryReport?.logPath ?? paths.logPath,
+			snapshotPaths: recoveryReport?.snapshotPaths ?? [],
 			recovery: "Install the next Treeport release when it is available and run `treeport update` again."
 		});
-		if (comparison === 0) {
+		if (comparison === 0 && !recoveryOperation) {
 			const currentTerminals = initialDaemon.verified ? await terminalIds(initialDaemon.state.apiUrl) : [];
 			const currentLifecycle = initialDaemon.verified ? initialDaemon.health.daemonLifecycle === "service" ? "service" : initialDaemon.health.daemonLifecycle === "treeport" ? "treeport" : null : installedService ? "service" : "treeport";
 			await save("complete");
@@ -2421,6 +2720,99 @@ async function runLocalUpdate(options = {}) {
 				}
 			};
 		}
+		const intendedRunning = initialDaemon.verified || serviceBefore?.requestedState === "running";
+		const shouldRun = intendedRunning || Boolean(options.start) || Boolean(recoveryOperation?.daemonWasRunning) || Boolean(recoveryOperation?.startRequested);
+		if (serviceBefore) {
+			if (serviceBefore.administratorCommand) throw new LocalUpdateError("UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED", "Complete the service action before updating Treeport.", {
+				phase: "inspect",
+				operationId,
+				administratorCommand: serviceBefore.administratorCommand,
+				recovery: serviceBefore.administratorCommand
+			});
+			if (!serviceBefore.installed || !serviceBefore.definitionMatches || !serviceBefore.entrypointMatches || !serviceBefore.environmentMatches || serviceBefore.state === "stale" || serviceBefore.state === "action_required") throw new LocalUpdateError("UPDATE_SERVICE_NOT_READY", "Repair the Treeport service before updating.", {
+				phase: "inspect",
+				operationId,
+				cause: serviceBefore.issues.join("\n"),
+				recovery: serviceBefore.recoveryCommands.join("\n")
+			});
+		}
+		const preview = {
+			fromVersion: installation.version,
+			toVersion: release.version,
+			daemonWasRunning: intendedRunning,
+			startRequested: Boolean(options.start),
+			recovery: recoveryOperation !== null
+		};
+		if (!options.yes && !interrupted) {
+			if (options.confirm) {
+				if (!await options.confirm(preview, cancellation.signal)) throw new LocalUpdateError("UPDATE_CANCELLED", "Treeport update cancelled. The installed version and daemon are unchanged.", {
+					phase: "resolve",
+					operationId,
+					fromVersion: preview.fromVersion,
+					toVersion: preview.toVersion
+				}, 130);
+			} else if (shouldRun || recoveryOperation) throw new LocalUpdateError("UPDATE_CONFIRMATION_REQUIRED", `Updating Treeport ${installation.version} -> ${release.version} requires consent. Clients can briefly disconnect; terminals are preserved. Re-run with --yes.`, {
+				phase: "resolve",
+				operationId,
+				fromVersion: preview.fromVersion,
+				toVersion: preview.toVersion,
+				recovery: "Re-run `treeport update --yes` to approve the update."
+			});
+		}
+		if (interrupted) throw new LocalUpdateError("UPDATE_CANCELLED", "Treeport update cancelled. The installed version and daemon are unchanged.", {
+			phase: "resolve",
+			operationId
+		}, 130);
+		if (recoveryOperation && ["not_started", "unchanged"].includes(recoveryOperation.migrationState)) {
+			recoveringPrevious = true;
+			if (recoveryOperation.daemonLifecycle === "service" || recoveryOperation.daemonWasRunning || recoveryOperation.startRequested) await stopUpdateDaemon(recoveryOperation.daemonLifecycle);
+			recoveryOperation.migrationState = updateMigrationState(recoveryOperation, await readUpdateStartupReport(paths.dataDir));
+			if (["advanced", "unknown"].includes(recoveryOperation.migrationState)) {
+				recoveryOperation.recoveryAction = "Keep the installed version. Inspect the daemon log and retry with the same or a newer release.";
+				await writeJson(operationPath, {
+					...recoveryOperation,
+					phase: "recovery_required",
+					updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+				throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Startup evidence changed during recovery. Treeport will not start the older version.", {
+					phase: "recovery_required",
+					operationId: recoveryOperation.operationId,
+					migrationState: recoveryOperation.migrationState,
+					recovery: recoveryOperation.recoveryAction
+				});
+			}
+			if (recoveryOperation.previousTarget) await replaceSymlink(installation.currentLink, recoveryOperation.previousTarget);
+			await fs.rm(path.join(updateDirectory, "pending-startup.json"), { force: true });
+			await fs.rm(path.join(updateDirectory, "startup-report.json"), { force: true });
+			if (recoveryOperation.daemonWasRunning) await startThroughStableEntrypoint(installation.entrypoint, environment).then(() => verifyRestoredDaemon(recoveryOperation, paths.dataDir)).catch((error) => {
+				throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport restored the previous version but could not verify daemon and terminal recovery.", {
+					phase: "recovery_required",
+					operationId: recoveryOperation.operationId,
+					cause: error instanceof Error ? error.message : String(error),
+					recovery: "Inspect the daemon log, then run `treeport start`."
+				});
+			});
+			await writeJson(operationPath, {
+				...recoveryOperation,
+				phase: "complete",
+				activated: false,
+				rollbackAttempted: true,
+				rollbackSucceeded: true,
+				recoveryAction: "Run `treeport update` again.",
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			throw new LocalUpdateError("UPDATE_ROLLED_BACK", "Treeport recovered the interrupted update and restored the previous state. Run `treeport update` again.", {
+				phase: "rollback",
+				operationId: recoveryOperation.operationId,
+				migrationState: recoveryOperation.migrationState,
+				rollback: {
+					attempted: true,
+					safe: true,
+					succeeded: true
+				},
+				recovery: "Run `treeport update` again."
+			});
+		}
 		const stagingPath = path.join(installation.managedRoot, `.staging-${release.version}-${operationId}`);
 		const targetPath = path.join(installation.versionsDirectory, release.version);
 		operation.stagedTarget = stagingPath;
@@ -2529,22 +2921,26 @@ async function runLocalUpdate(options = {}) {
 			phase: "verify",
 			operationId
 		});
-		operation.daemonWasRunning = daemonBefore.running && daemonBefore.verified || recoveryOperation !== null;
-		operation.daemonLifecycle = recoveryOperation ? recoveryOperation.daemonLifecycle : operation.daemonWasRunning ? daemonBefore.health?.daemonLifecycle === "service" ? "service" : "treeport" : installedService ? "service" : "treeport";
+		operation.migrationState = recoveryOperation?.migrationState ?? "not_started";
+		const serviceReady = installedService ? await serviceStatus() : null;
+		if (serviceReady?.installed !== serviceBefore?.installed || serviceReady?.requestedState !== serviceBefore?.requestedState || serviceReady?.definitionPath !== serviceBefore?.definitionPath || serviceReady?.mode !== serviceBefore?.mode || serviceReady && (serviceReady.state === "stale" || serviceReady.state === "action_required" || !serviceReady.definitionMatches || !serviceReady.environmentMatches || !serviceReady.entrypointMatches || serviceReady.administratorCommand)) throw new LocalUpdateError("UPDATE_SERVICE_NOT_READY", "Treeport service state changed while the update was staged. Retry the update.", {
+			phase: "verify",
+			operationId
+		});
+		operation.daemonWasRunning = intendedRunning || Boolean(recoveryOperation?.daemonWasRunning);
+		operation.startRequested = Boolean(options.start) || Boolean(recoveryOperation?.startRequested);
+		operation.daemonLifecycle = recoveryOperation ? recoveryOperation.daemonLifecycle : daemonBefore.verified ? daemonBefore.health?.daemonLifecycle === "service" ? "service" : "treeport" : installedService ? "service" : "treeport";
 		operation.serviceMode = recoveryOperation?.serviceMode ?? serviceBefore?.mode ?? null;
-		operation.terminalIds = recoveryOperation ? recoveryOperation.terminalIds : operation.daemonWasRunning ? await terminalIds(daemonBefore.state.apiUrl) : [];
+		operation.terminalIds = recoveryOperation ? recoveryOperation.terminalIds : daemonBefore.verified ? await terminalIds(daemonBefore.state.apiUrl) : [];
 		if (interrupted) throw new LocalUpdateError("UPDATE_INTERRUPTED", "Treeport update was interrupted before activation. The installed version and daemon are unchanged.", {
 			phase: "verify",
 			operationId
 		});
 		await save("stop");
-		progress("Stopping the Treeport daemon and preserving terminals…");
-		if (operation.daemonWasRunning) if (operation.daemonLifecycle === "service") {
-			if ((await serviceStop()).administratorCommand) throw new LocalUpdateError("UPDATE_SERVICE_ADMINISTRATOR_ACTION_REQUIRED", "The service requires administrator action and was not stopped.", {
-				phase: "stop",
-				operationId
-			});
-		} else await daemonDown();
+		if (operation.daemonLifecycle === "service" || operation.daemonWasRunning || recoveryOperation) {
+			progress("Stopping the Treeport daemon and preserving terminals…");
+			await stopUpdateDaemon(operation.daemonLifecycle);
+		}
 		await save("activate");
 		progress(`Activating Treeport ${release.version}…`);
 		await fs.rm(targetPath, {
@@ -2568,14 +2964,26 @@ async function runLocalUpdate(options = {}) {
 		await save("activate");
 		let daemonAfter = null;
 		let terminalsAfter = [];
-		if (operation.daemonWasRunning) {
+		if (shouldRun) {
 			await writeJson(path.join(updateDirectory, "pending-startup.json"), {
 				schemaVersion: 1,
 				operationId,
 				targetVersion: release.version,
 				createdAt: (/* @__PURE__ */ new Date()).toISOString()
 			});
-			await fs.rm(path.join(updateDirectory, "startup-report.json"), { force: true });
+			await writeJson(path.join(updateDirectory, "startup-report.json"), {
+				schemaVersion: 1,
+				operationId,
+				targetVersion: release.version,
+				instanceId: null,
+				migrationState: operation.migrationState,
+				ready: false,
+				error: null,
+				logPath: paths.logPath,
+				snapshotPaths: recoveryReport?.snapshotPaths ?? [],
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			operation.migrationState = operation.migrationState === "advanced" ? "advanced" : "unknown";
 			await save("restart");
 			progress(`Restarting the ${operation.daemonLifecycle === "service" ? "Treeport service" : "Treeport daemon"}…`);
 			await startThroughStableEntrypoint(installation.entrypoint, environment);
@@ -2588,7 +2996,7 @@ async function runLocalUpdate(options = {}) {
 				daemonAfter = await daemonStatus();
 				report = await readUpdateStartupReport(paths.dataDir);
 			}
-			operation.migrationState = report?.operationId === operationId ? report.migrationState : "unknown";
+			operation.migrationState = updateMigrationState(operation, report);
 			if (!daemonAfter.running || !daemonAfter.verified || daemonAfter.health?.version !== release.version || daemonAfter.health.daemonLifecycle !== operation.daemonLifecycle || path.resolve(daemonAfter.state.dataDir) !== paths.dataDir || report?.operationId !== operationId || !report.ready) throw new LocalUpdateError("UPDATE_HEALTH_VERIFICATION_FAILED", `Treeport ${release.version} did not pass startup verification.`, {
 				phase: "health_check",
 				operationId
@@ -2625,8 +3033,8 @@ async function runLocalUpdate(options = {}) {
 			daemon: {
 				wasRunning: operation.daemonWasRunning,
 				lifecycle: operation.daemonLifecycle,
-				restarted: operation.daemonWasRunning,
-				healthy: operation.daemonWasRunning ? Boolean(daemonAfter?.verified) : false,
+				restarted: shouldRun,
+				healthy: Boolean(daemonAfter?.verified),
 				version: daemonAfter?.health?.version ?? null
 			},
 			terminals: {
@@ -2644,6 +3052,12 @@ async function runLocalUpdate(options = {}) {
 		const failedPhase = operation.phase;
 		if (!DESTRUCTIVE_PHASES.has(operation.phase)) {
 			if (error instanceof LocalUpdateError) throw error;
+			if (recoveringPrevious && recoveryOperation) throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport could not restore the interrupted update. Recovery is still required.", {
+				phase: "recovery_required",
+				operationId: recoveryOperation.operationId,
+				cause: error instanceof Error ? error.message : String(error),
+				recovery: "Inspect the active version and daemon log before retrying."
+			});
 			throw new LocalUpdateError(operation.phase === "resolve" ? "UPDATE_RELEASE_RESOLUTION_FAILED" : operation.phase === "stage" ? "UPDATE_STAGING_FAILED" : operation.phase === "verify" ? "UPDATE_VERIFICATION_FAILED" : "UPDATE_INSTALLATION_UNSUPPORTED", error instanceof Error ? error.message : String(error), {
 				phase: operation.phase,
 				operationId,
@@ -2651,13 +3065,14 @@ async function runLocalUpdate(options = {}) {
 				toVersion: operation.toVersion
 			});
 		}
-		const startupReport = await readUpdateStartupReport(paths.dataDir);
-		if (startupReport?.operationId === operationId) operation.migrationState = startupReport.migrationState;
-		if (!["not_started", "unchanged"].includes(operation.migrationState)) {
-			const serviceStopError = operation.daemonLifecycle === "service" ? await serviceStop().then(() => null, (cause) => cause instanceof Error ? cause.message : String(cause)) : null;
-			operation.recoveryAction = serviceStopError ? `Keep the new version installed. Stop the service, then inspect the daemon log. Service stop failed: ${serviceStopError}` : "Keep the new version installed. Inspect the daemon log and repair with the same or a newer Treeport release.";
+		const stopError = operation.daemonLifecycle === "service" || operation.daemonWasRunning || operation.startRequested ? await stopUpdateDaemon(operation.daemonLifecycle).then(() => null, (cause) => cause instanceof Error ? cause.message : String(cause)) : null;
+		const observedReport = await readUpdateStartupReport(paths.dataDir);
+		const startupReport = observedReport?.operationId === operationId && observedReport.targetVersion === operation.toVersion ? observedReport : null;
+		operation.migrationState = updateMigrationState(operation, startupReport);
+		if (!(!stopError && ["not_started", "unchanged"].includes(operation.migrationState))) {
+			operation.recoveryAction = stopError ? `Keep the active version installed. Stop the daemon, then inspect the daemon log. Stop failed: ${stopError}` : "Keep the new version installed. Inspect the daemon log and repair with the same or a newer Treeport release.";
 			await save("recovery_required");
-			throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "The updated daemon did not become healthy after database migration began. Treeport did not start the older daemon.", {
+			throw new LocalUpdateError("UPDATE_RECOVERY_REQUIRED", "Treeport could not prove that rollback is safe. Treeport did not start the older daemon.", {
 				operationId,
 				phase: failedPhase,
 				fromVersion: operation.fromVersion,
@@ -2668,6 +3083,7 @@ async function runLocalUpdate(options = {}) {
 					safe: false,
 					succeeded: false
 				},
+				cause: startupReport?.error ?? (error instanceof Error ? error.message : String(error)),
 				logPath: startupReport?.logPath ?? paths.logPath,
 				snapshotPaths: startupReport?.snapshotPaths ?? [],
 				recovery: operation.recoveryAction
@@ -2679,7 +3095,10 @@ async function runLocalUpdate(options = {}) {
 		const rollbackError = await (async () => {
 			if (operation.previousTarget) await replaceSymlink(installation.currentLink, operation.previousTarget);
 			await fs.rm(path.join(updateDirectory, "pending-startup.json"), { force: true });
-			if (operation.daemonWasRunning) await startThroughStableEntrypoint(installation.entrypoint, environment);
+			if (operation.daemonWasRunning) {
+				await startThroughStableEntrypoint(installation.entrypoint, environment);
+				await verifyRestoredDaemon(operation, paths.dataDir);
+			}
 		})().then(() => null, (cause) => cause);
 		operation.rollbackSucceeded = rollbackError === null;
 		operation.recoveryAction = rollbackError ? "Inspect the active version and daemon log before starting Treeport." : "The previous Treeport version is active again.";
@@ -2696,6 +3115,8 @@ async function runLocalUpdate(options = {}) {
 				succeeded: rollbackError === null
 			},
 			cause: error instanceof Error ? error.message : String(error),
+			logPath: startupReport?.logPath ?? paths.logPath,
+			snapshotPaths: startupReport?.snapshotPaths ?? [],
 			recovery: operation.recoveryAction
 		});
 	} finally {
@@ -2713,4 +3134,4 @@ async function runLocalUpdate(options = {}) {
 	}
 }
 //#endregion
-export { treeportVersion as A, disableTailscaleRemote as C, resolvePackagePath as D, resolveLocalApiUrl as E, parseDurationMs as M, runDoctor as O, daemonUp as S, readDaemonLogs as T, serviceStatus as _, readLocalUpdateProgress as a, daemonHealth as b, createUpdateStartupReporter as c, serviceDisable as d, serviceDoctorCheck as f, serviceStart as g, serviceRun as h, isCanonicalTreeportVersion as i, assertLoopbackHost as j, tailscaleRemoteStatus as k, readServiceLogs as l, serviceInstalled as m, compareTreeportVersions as n, resolveLatestTreeportRelease as o, serviceEnable as p, inspectLocalUpdateInstallation as r, runLocalUpdate as s, LocalUpdateError as t, serviceApply as u, serviceStop as v, enableTailscaleRemote as w, daemonStatus as x, daemonDown as y };
+export { runDoctor as A, daemonStatus as C, readDaemonLogs as D, enableTailscaleRemote as E, formatServiceStatus as F, humanOutput as I, stateName as L, treeportVersion as M, formatLocalUpdateError$1 as N, resolveLocalApiUrl as O, formatLocalUpdateResult as P, assertLoopbackHost as R, daemonHealth as S, disableTailscaleRemote as T, serviceRun as _, inspectLocalUpdateInstallation as a, serviceStop as b, resolveLatestTreeportRelease as c, readServiceLogs as d, serviceApply as f, serviceInstalled as g, serviceEnable as h, formatLocalUpdateError as i, tailscaleRemoteStatus as j, resolvePackagePath as k, runLocalUpdate as l, serviceDoctorCheck as m, compareTreeportVersions as n, isCanonicalTreeportVersion as o, serviceDisable as p, confirmLocalUpdate as r, readLocalUpdateProgress as s, LocalUpdateError as t, createUpdateStartupReporter as u, serviceStart as v, daemonUp as w, daemonDown as x, serviceStatus as y, parseDurationMs as z };