@opentig/cli 0.2.3 → 0.2.4

package/dist/chunks/{cli-L6lvCZdX.mjs → cli-gyjD1t0O.mjs}

@@ -1,13 +1,16 @@
-import { c as redactSensitiveText, i as applicationName, n as runOpenTigServer, o as normalizeRuntimePlatform, s as writeFileAtomically } from "./server-Cz0gvydn.mjs";
-import { a as newerVersion, c as saveInstallation, i as execute, l as stableVersion, n as createServiceManager, o as packageDirectory, r as atomicWrite, s as readInstallation, t as assertManager } from "./service-manager-Jyx-MWo-.mjs";
+import { i as applicationName, n as runOpenTigServer, o as normalizeRuntimePlatform } from "./server-DMk8-Xxt.mjs";
+import { c as redactSensitiveText, i as loadStartupNetwork, s as writeFileAtomically } from "./network-settings-CdFeKFRB.mjs";
+import { a as newerVersion, c as saveInstallation, d as cliCommand, f as diagnostic, h as serviceError, i as execute, l as stableVersion, m as operationError, n as createServiceManager, o as packageDirectory, p as errorCode, r as atomicWrite, s as readInstallation, t as assertManager, u as CliError } from "./service-manager-BxSmV_8Z.mjs";
 import process$1 from "node:process";
-import { execFile, spawn } from "node:child_process";
-import { createHash, randomBytes } from "node:crypto";
 import { access, appendFile, chmod, cp, mkdir, mkdtemp, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
+import { execFile, spawn } from "node:child_process";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
+import { createServer } from "node:net";
+import { lookup } from "node:dns/promises";
 //#region ../../src/shared/date-format.ts
 var pad = (value, width = 2) => String(value).padStart(width, "0");
 function localDate(value) {
@@ -908,6 +911,354 @@ function renderUnicodeCompact(data, options = {}) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/cli-network.ts
+async function cliNetwork(config) {
+	try {
+		const { network, savedListener } = await loadStartupNetwork({
+			settingsPath: path.join(config.home, "settings.json"),
+			serverDataPath: path.join(config.home, "server"),
+			mode: "web-access",
+			host: config.host,
+			port: config.port
+		});
+		return {
+			...network,
+			savedListener
+		};
+	} catch (cause) {
+		throw new CliError("ACCESS_SETTINGS_INVALID", "Could not load the saved web access settings.", [
+			`Check ${path.join(config.home, "server/web-access.json")} and its permissions.`,
+			`To restore startup address and browser access, run ${cliCommand(config.home, "reset-access")} and restart this instance.`,
+			"Resetting access preserves paired browsers but removes the saved listener and access switches."
+		], { cause });
+	}
+}
+function listenerError(error, config, network, command) {
+	const code = errorCode(error);
+	const address = `${network.listenerHost.includes(":") ? `[${network.listenerHost}]` : network.listenerHost}:${network.listenerPort}`;
+	const context = network.savedListener || network.listenerHost !== config.host || network.listenerPort !== config.port ? [
+		"This address is affected by saved Settings → Web access. Saved listener fields override the corresponding startup options.",
+		"Change the saved listener in that instance before retrying. If access recovery is needed:",
+		`${cliCommand(config.home, "reset-access")} removes saved access switches and listener; restart with the desired options.`
+	] : [
+		"Listener selected by startup options, OPENTIG_HOST/OPENTIG_PORT, or defaults.",
+		`Choose another port, for example: ${cliCommand(config.home, ...command.split(" "), "--host", config.host, "--port", String(network.listenerPort === 65535 ? 6767 : network.listenerPort + 1))}`,
+		"The example port has not been checked for availability."
+	];
+	if (code === "EADDRINUSE") return new CliError("PORT_IN_USE", `Port ${network.listenerPort} is already in use (${address}); cannot run ${command}.`, [
+		"OpenTig Desktop or another process may be using this address. Close it and retry, or use a different port.",
+		...context,
+		"No other application was stopped."
+	], { cause: error });
+	if (code === "EADDRNOTAVAIL" || code === "ENOTFOUND" || code === "EAI_AGAIN") return new CliError("HOST_UNAVAILABLE", `Cannot listen on ${address}: this host is not available on this machine.`, ["Use a local listening address, such as 127.0.0.1 for access from this computer.", ...context], { cause: error });
+	if (code === "EACCES" || code === "EPERM") return new CliError("LISTENER_PERMISSION_DENIED", `Permission denied when listening on ${address}.`, ["Check OS port restrictions and choose an allowed port. Do not run the server as administrator.", ...context], { cause: error });
+	return error;
+}
+/** Same bind semantics as OpenTigServer; advisory only, the real bind still handles races. */
+async function assertListenerAvailable(config, network, command) {
+	const socket = createServer();
+	try {
+		await new Promise((resolve, reject) => {
+			socket.once("error", reject);
+			socket.listen(network.listenerPort, network.listenerHost, resolve);
+		});
+	} catch (error) {
+		throw listenerError(error, config, network, command);
+	} finally {
+		if (socket.listening) await new Promise((resolve, reject) => socket.close((error) => error ? reject(error) : resolve()));
+	}
+}
+async function sameListener(network, runtime) {
+	if (network.listenerPort !== runtime.port) return false;
+	if (network.listenerHost === runtime.host) return true;
+	try {
+		return (await lookup(network.listenerHost)).address === runtime.host;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/cli-home.ts
+var RUNTIME_STATE_VERSION = 1;
+function resolveCliPaths(home) {
+	const resolved = path.resolve(home);
+	const serverData = path.join(resolved, "server");
+	const logs = path.join(resolved, "logs");
+	return {
+		home: resolved,
+		settings: path.join(resolved, "settings.json"),
+		aiLog: path.join(resolved, "ai-log.jsonl"),
+		problems: path.join(resolved, "problems.jsonl"),
+		serverData,
+		logs,
+		serverLog: path.join(logs, "server.log"),
+		runtimeState: path.join(resolved, "runtime.json"),
+		adminToken: path.join(serverData, "admin-token")
+	};
+}
+async function prepareCliHome(paths) {
+	await mkdir(paths.home, {
+		recursive: true,
+		mode: 448
+	});
+	await chmod(paths.home, 448);
+	await Promise.all([mkdir(paths.serverData, {
+		recursive: true,
+		mode: 448
+	}), mkdir(paths.logs, {
+		recursive: true,
+		mode: 448
+	})]);
+	await Promise.all([chmod(paths.serverData, 448), chmod(paths.logs, 448)]);
+}
+async function loadOrCreateAdminToken(filePath) {
+	try {
+		return await readAdminToken(filePath);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	const token = randomBytes(32).toString("base64url");
+	await writeFileAtomically(filePath, `${token}\n`, { directoryMode: 448 });
+	return token;
+}
+async function readAdminToken(filePath) {
+	const token = (await readFile(filePath, "utf8")).trim();
+	if (!isToken(token)) throw new CliError("ADMIN_CREDENTIAL_INVALID", "OpenTig local admin credential is corrupt.", ["Check the private home permissions and restore this credential from a trusted backup; do not delete the home or copy a credential from another instance."]);
+	await chmod(filePath, 384);
+	return token;
+}
+async function writeRuntimeState(filePath, state) {
+	await writeFileAtomically(filePath, `${JSON.stringify({
+		version: RUNTIME_STATE_VERSION,
+		...state
+	}, null, 2)}\n`, {
+		parseJson: true,
+		directoryMode: 448
+	});
+}
+async function readRuntimeState(filePath) {
+	let value;
+	try {
+		value = JSON.parse(await readFile(filePath, "utf8"));
+	} catch (error) {
+		if (error.code === "ENOENT") throw new CliError("RUNTIME_MISSING", "No running OpenTig server was found for this home.", [`Start it with ${cliCommand(path.dirname(filePath), "serve")}`, `Or check ${cliCommand(path.dirname(filePath), "service", "status")}`], { cause: error });
+		throw new CliError("RUNTIME_INVALID", "OpenTig runtime state is unreadable.", [`Check permissions and server logs in ${path.dirname(filePath)}. Do not delete settings or credentials.`], { cause: error });
+	}
+	if (!isRuntimeState(value)) throw new CliError("RUNTIME_INVALID", "OpenTig runtime state is invalid.", [`Inspect ${filePath} and the service status before restarting; do not delete the home.`]);
+	await chmod(filePath, 384);
+	return value;
+}
+async function clearRuntimeState(filePath, instanceId) {
+	try {
+		if ((await readRuntimeState(filePath)).instanceId === instanceId) await rm(filePath, { force: true });
+	} catch (error) {
+		if (!(error instanceof CliError && error.code === "RUNTIME_MISSING")) throw error;
+	}
+}
+function newInstanceId() {
+	return randomBytes(24).toString("base64url");
+}
+function isToken(value) {
+	return /^[A-Za-z0-9_-]{43}$/.test(value);
+}
+function isRuntimeState(value) {
+	const state = value;
+	return Boolean(state && state.version === RUNTIME_STATE_VERSION && Number.isSafeInteger(state.pid) && Number(state.pid) > 0 && typeof state.host === "string" && state.host.length > 0 && state.host.length <= 255 && Number.isSafeInteger(state.port) && Number(state.port) > 0 && Number(state.port) <= 65535 && Number.isSafeInteger(state.protocolVersion) && Number(state.protocolVersion) > 0 && typeof state.appVersion === "string" && state.appVersion.length > 0 && state.appVersion.length <= 128 && typeof state.instanceId === "string" && /^[A-Za-z0-9_-]{32}$/.test(state.instanceId) && typeof state.startedAt === "string" && !Number.isNaN(Date.parse(state.startedAt)));
+}
+//#endregion
+//#region src/cli-runtime.ts
+function publicOrigin(host, port) {
+	const displayHost = host === "0.0.0.0" ? "127.0.0.1" : host === "::" ? "::1" : host;
+	return `http://${displayHost.includes(":") ? `[${displayHost}]` : displayHost}:${port}`;
+}
+function isProcessRunning(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+}
+/** The admin endpoint proves the listener owns both this home's token and instance ID. */
+async function probeRuntime(home, runtime, allowLegacy = false) {
+	const paths = resolveCliPaths(home);
+	const state = runtime ?? await readRuntimeState(paths.runtimeState);
+	if (!isProcessRunning(state.pid)) throw new CliError("RUNTIME_STALE", "OpenTig runtime state is stale; its process is not running.", [`Start this instance: ${cliCommand(home, "serve")}`, `Or restart its service: ${cliCommand(home, "service", "restart")}`]);
+	const token = await readAdminToken(paths.adminToken).catch((cause) => {
+		throw new CliError("ADMIN_CREDENTIAL_INVALID", "OpenTig local admin credential is missing or unreadable.", [`Check the private credential and permissions in ${paths.serverData}; do not delete the home or copy another instance's credential.`], { cause });
+	});
+	const response = await fetch(`${publicOrigin(state.host, state.port)}/api/admin/status`, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"X-OpenTig-Admin": token
+		},
+		body: JSON.stringify({ instanceId: state.instanceId }),
+		signal: AbortSignal.timeout(1e3)
+	});
+	if (response.status === 404 && allowLegacy) {
+		const check = await fetch(`${publicOrigin(state.host, state.port)}/api/admin/pair`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"X-OpenTig-Admin": token
+			},
+			body: JSON.stringify({
+				instanceId: state.instanceId,
+				publicOrigin: "invalid-origin"
+			}),
+			signal: AbortSignal.timeout(1e3)
+		});
+		if (check.status === 400 && (await check.json()).error === "Invalid public origin.") {
+			const ready = await fetch(`${publicOrigin(state.host, state.port)}/readyz`, { signal: AbortSignal.timeout(1e3) });
+			const identity = await ready.json();
+			if (ready.ok && identity.status === "ready" && identity.appVersion === state.appVersion && identity.protocolVersion === state.protocolVersion) return {
+				...state,
+				legacy: true
+			};
+		}
+	}
+	if (!response.ok) throw new CliError("RUNTIME_MISMATCH", "OpenTig runtime state does not match the running server.", [`Inspect this instance: ${cliCommand(home, "service", "status")}`, "Do not stop an unknown process or remove credentials to work around an identity mismatch."]);
+	const identity = await response.json();
+	if (identity.instanceId !== state.instanceId || identity.pid !== state.pid || identity.appVersion !== state.appVersion || identity.protocolVersion !== state.protocolVersion || identity.status !== "ready") throw new CliError("RUNTIME_MISMATCH", "The running server identity or readiness does not match this home.", [`Check ${path.join(home, "logs/server.log")} before restarting this instance.`]);
+	return state;
+}
+function assertGitAvailable() {
+	return new Promise((resolve, reject) => {
+		execFile("git", ["--version"], {
+			timeout: 1e4,
+			windowsHide: true
+		}, (error, stdout) => {
+			if (error || !stdout.trim().startsWith("git version ")) reject(new CliError("GIT_UNAVAILABLE", "Git is required and could not be executed from PATH.", ["Install Git or correct PATH in this terminal, then retry.", "If tool locations changed, reinstall the service from this terminal to capture the updated PATH."], { cause: error }));
+			else resolve();
+		});
+	});
+}
+//#endregion
+//#region src/cli-log.ts
+var MAX_BYTES = 1048576;
+var BACKUPS = 3;
+var CliServerLog = class {
+	filePath;
+	queue = Promise.resolve();
+	constructor(filePath) {
+		this.filePath = filePath;
+	}
+	logger = (level, message) => {
+		const line = `${(/* @__PURE__ */ new Date()).toISOString()} [${level}] ${redactSensitiveText(message)}\n`;
+		this.queue = this.queue.then(async () => {
+			await mkdir(path.dirname(this.filePath), {
+				recursive: true,
+				mode: 448
+			});
+			if (await wouldExceed(this.filePath, Buffer.byteLength(line))) await this.rotate();
+			await appendFile(this.filePath, line, {
+				encoding: "utf8",
+				mode: 384
+			});
+		}).catch(() => void 0);
+	};
+	close() {
+		return this.queue;
+	}
+	async rotate() {
+		await rm(`${this.filePath}.${BACKUPS}`, { force: true });
+		for (let index = 2; index >= 1; index -= 1) await moveIfPresent(`${this.filePath}.${index}`, `${this.filePath}.${index + 1}`);
+		await moveIfPresent(this.filePath, `${this.filePath}.1`);
+	}
+};
+async function wouldExceed(filePath, incomingBytes) {
+	try {
+		return (await stat(filePath)).size + incomingBytes > MAX_BYTES;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+async function moveIfPresent(source, target) {
+	try {
+		await rename(source, target);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+}
+//#endregion
+//#region src/cli-startup.ts
+var file = (home) => path.join(home, "service/startup.json");
+async function readStartup(home) {
+	try {
+		const value = JSON.parse(await readFile(file(home), "utf8"));
+		return value && typeof value.attempt === "string" && typeof value.requestedAt === "string" && [
+			"pending",
+			"starting",
+			"ready",
+			"failed"
+		].includes(value.phase) ? value : null;
+	} catch (error) {
+		if (errorCode(error) === "ENOENT" || error instanceof SyntaxError) return null;
+		throw error;
+	}
+}
+/** One private bounded record, replaced for each installation/restart attempt. */
+async function requestStartup(home) {
+	const attempt = randomUUID();
+	await atomicWrite(file(home), JSON.stringify({
+		attempt,
+		requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		phase: "pending"
+	}));
+	return attempt;
+}
+async function startupReporter(home) {
+	if (!process.env.OPENTIG_SERVICE_HOME || path.resolve(process.env.OPENTIG_SERVICE_HOME) !== path.resolve(home)) return null;
+	const previous = await readStartup(home);
+	const result = previous?.phase === "pending" ? previous : {
+		attempt: randomUUID(),
+		requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		phase: "pending"
+	};
+	const save = async (patch, initial = false) => {
+		const current = await readStartup(home);
+		if (current && current.attempt !== result.attempt && (!initial || current.attempt !== previous?.attempt)) return;
+		await atomicWrite(file(home), JSON.stringify({
+			...result,
+			...patch,
+			pid: process.pid
+		}));
+	};
+	await save({ phase: "starting" }, true);
+	return {
+		ready: (instanceId) => save({
+			phase: "ready",
+			instanceId
+		}),
+		failed: (error) => save({
+			phase: "failed",
+			code: error instanceof CliError ? error.code : "STARTUP_FAILED",
+			message: diagnostic(error)
+		})
+	};
+}
+async function recordCliFailure(home, error) {
+	const log = new CliServerLog(path.join(home, "logs/server.log"));
+	log.logger("error", diagnostic(error));
+	let cause = error instanceof Error ? error.cause : void 0;
+	for (let depth = 0; cause && depth < 4; depth++) {
+		log.logger("error", `Cause: ${cause instanceof Error ? cause.message : "Unknown failure"}`);
+		if (cause instanceof AggregateError) for (const item of cause.errors) log.logger("error", `Recovery detail: ${diagnostic(item)}`);
+		cause = cause instanceof Error ? cause.cause : void 0;
+	}
+	await log.close();
+}
+function startupTimeout(home) {
+	return new CliError("STARTUP_TIMEOUT", "The managed service did not become ready before the startup timeout.", [
+		"The cause could not be determined automatically.",
+		`Check: ${cliCommand(home, "service", "status")}`,
+		`Server log: ${path.join(home, "logs/server.log")}`,
+		`Windows startup output: ${path.join(home, "logs/service-stderr.log")}; on Linux/macOS inspect the user supervisor's logs.`
+	]);
+}
+//#endregion
 //#region src/browser.ts
 function browserCommand(url, platform = process.platform) {
 	if (platform === "win32") return {
@@ -981,8 +1332,13 @@ function parseCliArguments(args, environment = process.env, currentDirectory = p
 		}
 		if (!optionsEnded && argument.startsWith("--")) {
 			const [name, inline] = splitOption(argument);
+			if (![
+				"--host",
+				"--port",
+				"--home"
+			].includes(name)) throw new CliUsageError(`Unknown option: ${name}. Use --host, --port, or --home.`);
 			const value = inline ?? args[++index];
-			if (value === void 0 || value.startsWith("--")) throw new CliUsageError(`Missing value for ${name}.`);
+			if (value === void 0 || value === "" || value.startsWith("-")) throw new CliUsageError(`Missing value for ${name}.`);
 			if (name === "--host") hostValue = value;
 			else if (name === "--port") portValue = value;
 			else if (name === "--home") homeValue = value;
@@ -999,14 +1355,16 @@ function parseCliArguments(args, environment = process.env, currentDirectory = p
 			serviceAction = argument;
 			continue;
 		}
-		throw new CliUsageError(`Unexpected argument: ${argument}. Add and select repositories from the OpenTig web UI.`);
+		if (command === "service" && serviceAction === null) throw new CliUsageError(`Unknown service action: ${argument}. Use install, status, restart, or uninstall.`);
+		throw new CliUsageError(`Unexpected argument: ${argument}. Check the command spelling with opentig --help. Add and select repositories from the OpenTig web UI.`);
 	}
-	if (command === "pair" && (hostValue !== void 0 || portValue !== void 0 || noBrowser)) throw new CliUsageError("The pair command only accepts --home.");
+	if (noBrowser && command !== "start") throw new CliUsageError("--no-browser is only supported by start; serve and services already run without opening a browser.");
+	if ((command === "pair" || command === "reset-access") && (hostValue !== void 0 || portValue !== void 0 || noBrowser)) throw new CliUsageError(`The ${command} command only accepts --home.`);
 	if (command === "service" && serviceAction === null) throw new CliUsageError("The service command requires install, status, restart, or uninstall.");
 	if (command === "service" && serviceAction !== "install" && (hostValue !== void 0 || portValue !== void 0 || noBrowser)) throw new CliUsageError(`The service ${serviceAction} command only accepts --home.`);
-	if (command === "pair") return {
+	if (command === "pair" || command === "reset-access" || command === "service" && serviceAction !== "install") return {
 		command,
-		serviceAction: null,
+		serviceAction,
 		host: DEFAULT_SERVER_HOST,
 		port: DEFAULT_SERVER_PORT,
 		home: resolvePath(homeValue ?? environment.OPENTIG_HOME ?? path.join(homeDirectory, ".opentig"), currentDirectory, "home"),
@@ -1033,6 +1391,7 @@ Usage:
   opentig start [options]
   opentig serve [options]
   opentig pair [--home <path>]
+  opentig reset-access [--home <path>]
   opentig service <install|status|restart|uninstall> [options]
   opentig help
   opentig version
@@ -1041,6 +1400,7 @@ Commands:
   start       Start OpenTig and open the one-use pairing link (default)
   serve       Start OpenTig without opening a browser; ideal for servers
   pair        Print a fresh five-minute code/link for a running server
+  reset-access Restore browser access and startup listener settings on next restart
   service     Manage a background server (Linux, macOS, Windows)
   help        Show this help
   version     Show the OpenTig version
@@ -1073,8 +1433,13 @@ Pairing and remote access:
   a trusted LAN/VPN; pairing is still required.
 
 Runtime behavior:
+  serve runs in this terminal and stops when it closes. service install starts
+  a background server and installs startup persistence; do not run both for
+  the same home. Desktop runs its own server and needs a different port.
   The configured port is never changed silently. If it is occupied, OpenTig
-  exits and asks you to stop that process or choose another --port. SIGINT and
+  exits and asks you to stop that process or choose another --port. Saved
+  Settings → Web access take precedence over startup host/port options.
+  Service installation checks the effective address before registering a service. SIGINT and
   SIGTERM shut the server down cleanly. npx and bunx never install a service;
   service installation is explicit. Linux uses systemd with lingering; macOS
   and Windows start at login and stop at logout.
@@ -1097,7 +1462,7 @@ function splitOption(argument) {
 	return separator < 0 ? [argument, void 0] : [argument.slice(0, separator), argument.slice(separator + 1)];
 }
 function isCommand(value) {
-	return value === "start" || value === "serve" || value === "pair" || value === "service" || value === "help" || value === "version";
+	return value === "start" || value === "serve" || value === "pair" || value === "reset-access" || value === "service" || value === "help" || value === "version";
 }
 function isServiceAction(value) {
 	return value === "install" || value === "status" || value === "restart" || value === "uninstall";
@@ -1114,15 +1479,15 @@ function validatePort(value) {
 	return port;
 }
 function resolvePath(value, currentDirectory, label) {
-	if (!value || value.includes("\0")) throw new CliUsageError(`Invalid ${label}.`);
+	if (!value || /[\0\r\n]/.test(value)) throw new CliUsageError(`Invalid ${label}.`);
 	return path.resolve(currentDirectory, value);
 }
 //#endregion
 //#region src/version.ts
 var OPEN_TIG_APP_VERSION = {
 	name: "@opentig/cli",
-	version: "0.2.3",
-	description: "Run the OpenTig local-first Git client in a browser from any Git worktree.",
+	version: "0.2.4",
+	description: "Run OpenTig, a free, open-source Git client, on your repository host and access it through a paired browser.",
 	type: "module",
 	main: "dist/server.mjs",
 	bin: { "opentig": "dist/bin.mjs" },
@@ -1154,7 +1519,7 @@ var OPEN_TIG_APP_VERSION = {
 		"cli",
 		"headless"
 	],
-	author: "OpenTig contributors",
+	author: "OpenTig",
 	license: "MIT",
 	repository: {
 		"type": "git",
@@ -1162,7 +1527,7 @@ var OPEN_TIG_APP_VERSION = {
 		"directory": "packages/server"
 	},
 	bugs: { "url": "https://github.com/jorgefl8/opentig/issues" },
-	homepage: "https://github.com/jorgefl8/opentig#readme",
+	homepage: "https://opentig.com/",
 	publishConfig: {
 		"access": "public",
 		"provenance": true
@@ -1176,6 +1541,31 @@ var OPEN_TIG_APP_VERSION = {
 //#region src/service-npm.ts
 /** Run npm's JS entry with Node, never a .cmd file or interpolated shell command. */
 async function runServiceNpm(args, cwd) {
+	const entry = await resolveServiceNpm();
+	try {
+		await execute(process.execPath, [entry, ...args], {
+			cwd,
+			timeout: 18e4,
+			maxBuffer: 2e6,
+			windowsHide: true
+		});
+	} catch (cause) {
+		const code = (cause && typeof cause === "object" && "stderr" in cause && typeof cause.stderr === "string" ? cause.stderr : "").match(/npm (?:error|ERR!) code (E[A-Z0-9]+)/)?.[1];
+		const action = code && [
+			"ENOTFOUND",
+			"EAI_AGAIN",
+			"ETIMEDOUT",
+			"ECONNREFUSED",
+			"ECONNRESET"
+		].includes(code) ? "npm could not reach the package registry. Check the network and npm proxy/registry configuration." : code === "E401" || code === "E403" ? "npm registry access was denied. Check npm authentication and registry policies." : code === "ENOSPC" ? "npm ran out of disk space. Free space on the service volume and npm cache volume." : code === "EACCES" || code === "EPERM" ? "npm could not write the dependencies. Check permissions for this user and the npm cache." : "Check npm registry connectivity, proxy configuration, available disk space, and permissions.";
+		throw new CliError("DEPENDENCIES_FAILED", `Could not prepare the managed service dependencies with npm${code ? ` (${code})` : ""}.`, [
+			action,
+			"The existing service has not been replaced.",
+			"Correct the npm error recorded in the server log, then retry the installation."
+		], { cause });
+	}
+}
+async function resolveServiceNpm() {
 	const candidates = [
 		process.env.npm_execpath,
 		path.join(path.dirname(process.execPath), "node_modules/npm/bin/npm-cli.js"),
@@ -1195,37 +1585,47 @@ async function runServiceNpm(args, cwd) {
 		} catch {
 			continue;
 		}
-		await execute(process.execPath, [candidate, ...args], {
-			cwd,
-			timeout: 18e4,
-			maxBuffer: 2e6,
-			windowsHide: true
-		});
-		return;
+		return candidate;
 	}
-	throw new Error("npm could not be located. Install Node.js with npm and run service install from that terminal.");
+	throw new CliError("NPM_UNAVAILABLE", "npm could not be located.", ["Install Node.js with npm and run service install from that terminal."]);
 }
 //#endregion
 //#region src/cli-service.ts
 async function manageCliService(config, io, managerOverride) {
-	const manager = managerOverride ?? await createServiceManager(config.home);
+	try {
+		return await manage(config, io, managerOverride ?? await createServiceManager(config.home));
+	} catch (error) {
+		throw serviceError(error, config.home, config.serviceAction ?? "manage");
+	}
+}
+async function manage(config, io, manager) {
 	const action = config.serviceAction;
-	if (!action) throw new Error("A service action is required.");
+	if (!action) throw new CliError("SERVICE_ACTION_REQUIRED", "A service action is required.", ["Use install, status, restart, or uninstall."]);
 	const installed = await readInstallation(config.home);
-	if (action !== "status" && installed && newerVersion(installed.version, OPEN_TIG_APP_VERSION)) throw new Error("A newer managed service is installed. Use its CLI to administer it; downgrades are not automatic.");
+	if (action !== "status" && installed && newerVersion(installed.version, OPEN_TIG_APP_VERSION)) throw new CliError("SERVICE_VERSION_NEWER", "A newer managed service is installed; downgrades are not automatic.", ["Update the global CLI to that version or later before administering this service.", `Check versions: ${cliCommand(config.home, "--version")}`]);
 	const definition = await manager.read();
-	if (definition && !manager.owns(definition)) throw new Error("Another OpenTig home owns this service. Use its --home before changing or removing it.");
+	if (definition && !manager.owns(definition)) throw new CliError("SERVICE_HOME_MISMATCH", "Another OpenTig home owns this service.", ["Use the original installation's --home for status, restart, or uninstall. No service was changed.", `Service definition: ${manager.location}`]);
 	if (installed) assertManager(installed, manager.kind);
 	if (action === "status") {
 		if (!definition) {
 			io.out("OpenTig service is not installed.");
+			io.out(`Install: ${cliCommand(config.home, "service", "install")}`);
 			return 1;
 		}
 		const state = await manager.status();
-		io.out(`OpenTig service: ${state.running ? "running" : "stopped"} (${state.enabled ? "enabled" : "disabled"}).`);
+		let status = state.starting ? "starting" : state.running ? "running" : "stopped";
+		let ready = false;
+		if (state.running) try {
+			await verifiedServiceRuntime(config.home, manager);
+			ready = true;
+		} catch {
+			status = "running, backend not ready or identity not verified";
+		}
+		io.out(`OpenTig service: ${status} (${state.enabled ? "enabled" : "disabled"}).`);
 		io.out(manager.location);
 		io.out(manager.startup);
-		return state.running && state.enabled ? 0 : 1;
+		if (!ready) io.out(`Inspect ${path.join(config.home, "logs/server.log")}; restart with ${cliCommand(config.home, "service", "restart")}`);
+		return ready && state.enabled ? 0 : 1;
 	}
 	if (action === "uninstall" && !definition && !installed) {
 		io.out("OpenTig service is not installed.");
@@ -1238,16 +1638,18 @@ async function manageCliService(config, io, managerOverride) {
 	const lock = path.join(config.home, "service/update-lock");
 	try {
 		await mkdir(lock, { mode: 448 });
-	} catch (error) {
-		if (error.code === "EEXIST") throw new Error("A service installation or update is already in progress.", { cause: error });
-		throw error;
+	} catch (cause) {
+		if (errorCode(cause) === "EEXIST") throw new CliError("SERVICE_BUSY", "A service installation or update is already in progress.", [`Check ${cliCommand(config.home, "service", "status")} and wait for the operation to finish.`, "Do not delete its lock until you have verified that no installation or update is active."], { cause });
+		throw cause;
 	}
-	try {
+	return withServiceLock(config.home, lock, async () => {
 		if (action === "restart") {
-			if (!definition || !installed) throw new Error("OpenTig service is not installed.");
+			if (!definition || !installed) throw new CliError("SERVICE_MISSING", "OpenTig service is not installed.", [`Install: ${cliCommand(config.home, "service", "install")}`]);
+			const attempt = await requestStartup(config.home);
+			io.out("Restarting the OpenTig service...");
 			await manager.restart();
-			await waitServiceReady(config.home, installed, manager);
-			io.out("OpenTig service restarted.");
+			const runtime = await waitServiceReady(config.home, installed, manager, attempt);
+			io.out(`OpenTig service restarted. Connection URL: ${publicOrigin(runtime.host, runtime.port)}`);
 			return 0;
 		}
 		if (action === "uninstall") {
@@ -1262,14 +1664,53 @@ async function manageCliService(config, io, managerOverride) {
 			io.out("OpenTig service removed. Repository settings and paired sessions were kept.");
 			return 0;
 		}
+		io.out("Checking service configuration and listening address...");
+		const network = await cliNetwork(config);
+		let ownRuntime = null;
+		try {
+			if (isProcessRunning((await readRuntimeState(resolveCliPaths(config.home).runtimeState)).pid)) {
+				if (definition && installed) ownRuntime = await verifiedServiceRuntime(config.home, manager);
+				else throw new CliError("HOME_ACTIVE", "OpenTig is already running for this home.", [
+					`Pair a browser: ${cliCommand(config.home, "pair")}`,
+					"To install a service for this home, stop the foreground instance in its terminal and retry.",
+					"No service was installed and the existing process was left running."
+				]);
+			}
+		} catch (error) {
+			if (!(error instanceof CliError && error.code === "RUNTIME_MISSING")) throw error;
+		}
+		if (!ownRuntime || !await sameListener(network, ownRuntime)) try {
+			await assertListenerAvailable(config, network, "service install");
+		} catch (error) {
+			if (error instanceof CliError) throw new CliError(error.code, error.message, [...error.actions, "No service was installed or replaced."], { cause: error });
+			throw error;
+		}
+		await assertGitAvailable();
+		await resolveServiceNpm();
 		await manager.preflight();
 		return await installService(config, manager, installed, definition, io);
-	} finally {
+	});
+}
+async function withServiceLock(home, lock, run) {
+	let result = 1;
+	let failed = false;
+	let failure;
+	try {
+		result = await run();
+	} catch (error) {
+		failed = true;
+		failure = error;
+	}
+	try {
 		await rm(lock, {
 			recursive: true,
 			force: true
 		});
+	} catch (cleanup) {
+		throw new CliError("SERVICE_LOCK_CLEANUP_FAILED", failed ? diagnostic(serviceError(failure, home, "complete the operation")) : "The service operation completed, but its lock could not be removed.", [`Lock cleanup also failed: check permissions on ${lock}.`, `Inspect ${cliCommand(home, "service", "status")} and verify no operation is active before repairing the lock.`], { cause: failed ? new AggregateError([failure, cleanup], "Service operation and lock cleanup failed.") : cleanup });
 	}
+	if (failed) throw failure;
+	return result;
 }
 async function installService(config, manager, installed, previousDefinition, io) {
 	const packageRoot = await findPackageRoot(fileURLToPath(import.meta.url));
@@ -1278,6 +1719,7 @@ async function installService(config, manager, installed, previousDefinition, io
 	const reuse = installed?.version === OPEN_TIG_APP_VERSION;
 	const target = reuse ? packageDirectory(config.home, installed) : path.join(serviceRoot, `app-${OPEN_TIG_APP_VERSION}`);
 	const temporary = path.join(serviceRoot, `.install-${process.pid}-${Date.now()}`);
+	io.out("Preparing the managed CLI and dependencies...");
 	try {
 		if (!reuse) {
 			await mkdir(temporary, {
@@ -1329,65 +1771,83 @@ async function installService(config, manager, installed, previousDefinition, io
 		port: next.port,
 		environmentPath: next.environmentPath
 	});
+	let runtime;
 	try {
+		io.out("Registering the OpenTig user service...");
 		await manager.write(definition);
 		await saveInstallation(config.home, next);
+		const attempt = await requestStartup(config.home);
+		io.out("Starting the service and verifying its identity...");
 		await manager.restart();
-		await waitServiceReady(config.home, next, manager);
+		runtime = await waitServiceReady(config.home, next, manager, attempt);
 	} catch (error) {
-		if (previousDefinition) {
-			await manager.write(previousDefinition);
-			if (installed) await saveInstallation(config.home, installed);
-			else await rm(path.join(serviceRoot, "installation.json"), { force: true });
-			await manager.restart();
-		} else {
-			await manager.stop();
-			await manager.remove();
-			await rm(path.join(serviceRoot, "installation.json"), { force: true });
+		const original = serviceError(error, config.home, "install");
+		try {
+			if (previousDefinition) {
+				await manager.write(previousDefinition);
+				if (installed) await saveInstallation(config.home, installed);
+				else await rm(path.join(serviceRoot, "installation.json"), { force: true });
+				const attempt = await requestStartup(config.home);
+				await manager.restart();
+				if (!installed) throw new CliError("RECOVERY_UNVERIFIED", "The previous service definition has no installation metadata.");
+				await waitServiceReady(config.home, installed, manager, attempt);
+			} else {
+				await manager.stop();
+				await manager.remove();
+				await rm(path.join(serviceRoot, "installation.json"), { force: true });
+			}
+		} catch (recovery) {
+			throw new CliError("SERVICE_RECOVERY_FAILED", diagnostic(original), [`Recovery also failed: ${diagnostic(serviceError(recovery, config.home, "restore or remove"))}`, `The final service state is not verified. Inspect ${cliCommand(config.home, "service", "status")} before retrying.`], { cause: new AggregateError([original, recovery], "Installation and recovery both failed.") });
 		}
-		throw error;
+		throw new CliError(original.code, diagnostic(original), [previousDefinition ? "The previous service was restored and verified." : "The newly registered service was removed. Existing applications were left running."], { cause: original });
 	}
-	io.out(`OpenTig service installed and started on ${config.host}:${config.port}.`);
+	io.out(`OpenTig service installed and started on ${runtime.host}:${runtime.port}.`);
+	io.out(`Connection URL: ${publicOrigin(runtime.host, runtime.port)}`);
 	io.out(manager.location);
 	io.out(manager.startup);
-	io.out(`Pair another browser with: opentig pair --home ${JSON.stringify(config.home)}`);
+	io.out(`Pair another browser with: ${cliCommand(config.home, "pair")}`);
 	return 0;
 }
-async function waitServiceReady(home, installation, manager) {
-	const host = ["0.0.0.0", "::"].includes(installation.host) ? installation.host === "::" ? "[::1]" : "127.0.0.1" : installation.host.includes(":") ? `[${installation.host}]` : installation.host;
+async function verifiedServiceRuntime(home, manager) {
+	const runtime = await readRuntimeState(resolveCliPaths(home).runtimeState);
+	const state = await manager.status();
+	const owned = state.pid ? state.pid === runtime.pid : await manager.ownsRuntime?.(runtime.pid);
+	if (!state.running || !owned) throw new CliError("SERVICE_PROCESS_MISMATCH", "The running OpenTig instance is not verified as this managed service.", [`Check ${cliCommand(home, "service", "status")}. If a foreground instance uses this home, stop it in its terminal before installing the service.`, "No unknown process was stopped."]);
+	return probeRuntime(home, runtime, true);
+}
+async function waitServiceReady(home, installation, manager, attempt) {
 	for (let i = 0; i < 30; i++) {
+		const startup = await readStartup(home);
+		if (attempt && startup?.attempt === attempt && startup.phase === "failed") throw new CliError(startup.code ?? "STARTUP_FAILED", startup.message ?? "The service failed during startup.");
 		try {
-			const state = await manager.status();
-			const runtime = JSON.parse(await readFile(path.join(home, "runtime.json"), "utf8"));
-			const response = await fetch(`http://${host}:${installation.port}/readyz`, { signal: AbortSignal.timeout(1e3) });
-			const value = await response.json();
-			if (state.running && (!state.pid || state.pid === runtime.pid) && runtime.appVersion === installation.version && response.ok && value.status === "ready" && value.appVersion === installation.version) return;
+			const runtime = await verifiedServiceRuntime(home, manager);
+			if (runtime.appVersion === installation.version && (!attempt || startup?.attempt === attempt && startup.phase === "ready" && startup.pid === runtime.pid && startup.instanceId === runtime.instanceId || runtime.legacy && startup?.attempt === attempt && startup.phase === "pending" && Date.parse(runtime.startedAt) >= Date.parse(startup.requestedAt))) return runtime;
 		} catch {}
 		await setTimeout$1(1e3);
 	}
-	throw new Error("The managed service did not become ready. Inspect service status and logs; check Git, Node.js, and the configured port.");
+	throw startupTimeout(home);
 }
 async function assertPackageBuild(packageRoot) {
 	await Promise.all([
-		access(path.join(packageRoot, "dist", "bin.mjs")),
-		access(path.join(packageRoot, "dist", "client", "index.html")),
+		access(path.join(packageRoot, "dist/bin.mjs")),
+		access(path.join(packageRoot, "dist/client/index.html")),
 		readFile(path.join(packageRoot, "package.json"), "utf8")
-	]).catch(() => {
-		throw new Error("The OpenTig package is incomplete and cannot be installed as a service.");
+	]).catch((cause) => {
+		throw new CliError("PACKAGE_INCOMPLETE", "The OpenTig package is incomplete and cannot be installed as a service.", ["Reinstall the same CLI version from npm, then retry."], { cause });
 	});
 }
-async function findPackageRoot(modulePath) {
-	let directory = path.dirname(modulePath);
-	for (let depth = 0; depth < 4; depth += 1) {
+async function findPackageRoot(moduleUrl) {
+	let directory = path.dirname(moduleUrl);
+	for (let depth = 0; depth < 4; depth++) {
 		try {
-			await Promise.all([access(path.join(directory, "package.json")), access(path.join(directory, "dist", "bin.mjs"))]);
+			await Promise.all([access(path.join(directory, "package.json")), access(path.join(directory, "dist/bin.mjs"))]);
 			return directory;
 		} catch {}
 		const parent = path.dirname(directory);
 		if (parent === directory) break;
 		directory = parent;
 	}
-	throw new Error("Could not locate the installed OpenTig package.");
+	throw new CliError("PACKAGE_INCOMPLETE", "Could not locate the installed OpenTig package.", ["Reinstall the CLI from npm, then retry."]);
 }
 //#endregion
 //#region ../../src/shared/desktop-updates.ts
@@ -1673,142 +2133,6 @@ async function createServiceUpdater(home, version, profile, address) {
 	}, failedUpdate);
 }
 //#endregion
-//#region src/cli-home.ts
-var RUNTIME_STATE_VERSION = 1;
-function resolveCliPaths(home) {
-	const resolved = path.resolve(home);
-	const serverData = path.join(resolved, "server");
-	const logs = path.join(resolved, "logs");
-	return {
-		home: resolved,
-		settings: path.join(resolved, "settings.json"),
-		aiLog: path.join(resolved, "ai-log.jsonl"),
-		problems: path.join(resolved, "problems.jsonl"),
-		serverData,
-		logs,
-		serverLog: path.join(logs, "server.log"),
-		runtimeState: path.join(resolved, "runtime.json"),
-		adminToken: path.join(serverData, "admin-token")
-	};
-}
-async function prepareCliHome(paths) {
-	await mkdir(paths.home, {
-		recursive: true,
-		mode: 448
-	});
-	await chmod(paths.home, 448);
-	await Promise.all([mkdir(paths.serverData, {
-		recursive: true,
-		mode: 448
-	}), mkdir(paths.logs, {
-		recursive: true,
-		mode: 448
-	})]);
-	await Promise.all([chmod(paths.serverData, 448), chmod(paths.logs, 448)]);
-}
-async function loadOrCreateAdminToken(filePath) {
-	try {
-		return await readAdminToken(filePath);
-	} catch (error) {
-		if (error.code !== "ENOENT") throw error;
-	}
-	const token = randomBytes(32).toString("base64url");
-	await writeFileAtomically(filePath, `${token}\n`, { directoryMode: 448 });
-	return token;
-}
-async function readAdminToken(filePath) {
-	const token = (await readFile(filePath, "utf8")).trim();
-	if (!isToken(token)) throw new Error("OpenTig local admin credential is corrupt.");
-	await chmod(filePath, 384);
-	return token;
-}
-async function writeRuntimeState(filePath, state) {
-	await writeFileAtomically(filePath, `${JSON.stringify({
-		version: RUNTIME_STATE_VERSION,
-		...state
-	}, null, 2)}\n`, {
-		parseJson: true,
-		directoryMode: 448
-	});
-}
-async function readRuntimeState(filePath) {
-	let value;
-	try {
-		value = JSON.parse(await readFile(filePath, "utf8"));
-	} catch (error) {
-		if (error.code === "ENOENT") throw new Error("No running OpenTig server was found for this home.", { cause: error });
-		throw new Error("OpenTig runtime state is unreadable.", { cause: error });
-	}
-	if (!isRuntimeState(value)) throw new Error("OpenTig runtime state is invalid.");
-	await chmod(filePath, 384);
-	return value;
-}
-async function clearRuntimeState(filePath, instanceId) {
-	try {
-		if ((await readRuntimeState(filePath)).instanceId === instanceId) await rm(filePath, { force: true });
-	} catch (error) {
-		if (!(error instanceof Error && error.message === "No running OpenTig server was found for this home.")) throw error;
-	}
-}
-function newInstanceId() {
-	return randomBytes(24).toString("base64url");
-}
-function isToken(value) {
-	return /^[A-Za-z0-9_-]{43}$/.test(value);
-}
-function isRuntimeState(value) {
-	const state = value;
-	return Boolean(state && state.version === RUNTIME_STATE_VERSION && Number.isSafeInteger(state.pid) && Number(state.pid) > 0 && typeof state.host === "string" && state.host.length > 0 && state.host.length <= 255 && Number.isSafeInteger(state.port) && Number(state.port) > 0 && Number(state.port) <= 65535 && Number.isSafeInteger(state.protocolVersion) && Number(state.protocolVersion) > 0 && typeof state.appVersion === "string" && state.appVersion.length > 0 && state.appVersion.length <= 128 && typeof state.instanceId === "string" && /^[A-Za-z0-9_-]{32}$/.test(state.instanceId) && typeof state.startedAt === "string" && !Number.isNaN(Date.parse(state.startedAt)));
-}
-//#endregion
-//#region src/cli-log.ts
-var MAX_BYTES = 1048576;
-var BACKUPS = 3;
-var CliServerLog = class {
-	filePath;
-	queue = Promise.resolve();
-	constructor(filePath) {
-		this.filePath = filePath;
-	}
-	logger = (level, message) => {
-		const line = `${(/* @__PURE__ */ new Date()).toISOString()} [${level}] ${redactSensitiveText(message)}\n`;
-		this.queue = this.queue.then(async () => {
-			await mkdir(path.dirname(this.filePath), {
-				recursive: true,
-				mode: 448
-			});
-			if (await wouldExceed(this.filePath, Buffer.byteLength(line))) await this.rotate();
-			await appendFile(this.filePath, line, {
-				encoding: "utf8",
-				mode: 384
-			});
-		}).catch(() => void 0);
-	};
-	close() {
-		return this.queue;
-	}
-	async rotate() {
-		await rm(`${this.filePath}.${BACKUPS}`, { force: true });
-		for (let index = 2; index >= 1; index -= 1) await moveIfPresent(`${this.filePath}.${index}`, `${this.filePath}.${index + 1}`);
-		await moveIfPresent(this.filePath, `${this.filePath}.1`);
-	}
-};
-async function wouldExceed(filePath, incomingBytes) {
-	try {
-		return (await stat(filePath)).size + incomingBytes > MAX_BYTES;
-	} catch (error) {
-		if (error.code === "ENOENT") return false;
-		throw error;
-	}
-}
-async function moveIfPresent(source, target) {
-	try {
-		await rename(source, target);
-	} catch (error) {
-		if (error.code !== "ENOENT") throw error;
-	}
-}
-//#endregion
 //#region src/cli.ts
 var SHUTDOWN_TIMEOUT_MS = 8e3;
 var consoleIo = {
@@ -1816,9 +2140,10 @@ var consoleIo = {
 	error: (value) => process$1.stderr.write(`${value}\n`)
 };
 async function runCli(args, environment = process$1.env, io = consoleIo, profile = "production") {
+	let config;
+	let reporter = null;
 	try {
-		assertNodeVersion();
-		const config = parseCliArguments(args, environment);
+		config = parseCliArguments(args, environment);
 		if (config.command === "help") {
 			io.out(cliHelp(OPEN_TIG_APP_VERSION));
 			return 0;
@@ -1827,21 +2152,35 @@ async function runCli(args, environment = process$1.env, io = consoleIo, profile
 			io.out(OPEN_TIG_APP_VERSION);
 			return 0;
 		}
+		if (config.command === "serve" || config.command === "start") reporter = await startupReporter(config.home);
+		assertNodeVersion();
 		if (config.command === "service") return await manageCliService(config, io);
+		if (config.command === "reset-access") {
+			await rm(path.join(resolveCliPaths(config.home).serverData, "web-access.json"), { force: true });
+			io.out("Web access settings reset. Restart this OpenTig instance to enable browser access on its startup address and port. Paired devices are preserved.");
+			io.out(`Managed service: ${cliCommand(config.home, "service", "restart")}`);
+			io.out(`Foreground server: stop it in its terminal, then run ${cliCommand(config.home, "serve")}`);
+			return 0;
+		}
 		if (config.command === "pair") return await pairRunningServer(config, io, profile);
-		return await startCliServer(config, io, profile);
+		return await startCliServer(config, io, profile, reporter);
 	} catch (error) {
-		const message = redactSensitiveText(error instanceof Error ? error.message : String(error));
-		io.error(`OpenTig: ${message}`);
+		const failure = error instanceof CliUsageError || !config ? error : operationError(error, config.home, config.command === "service" ? `run service ${config.serviceAction}` : `run ${config.command}`);
+		if (config && !(error instanceof CliUsageError)) {
+			await reporter?.failed(failure).catch(() => void 0);
+			await recordCliFailure(config.home, failure).catch(() => void 0);
+		}
+		io.error(`OpenTig: ${diagnostic(failure)}`);
 		if (error instanceof CliUsageError) io.error("Run \"opentig --help\" for usage.");
 		return error instanceof CliUsageError ? error.exitCode : 1;
 	}
 }
-async function startCliServer(config, io, profile) {
+async function startCliServer(config, io, profile, reporter) {
 	await assertGitAvailable();
 	const paths = resolveCliPaths(config.home);
 	await prepareCliHome(paths);
-	await refuseActiveRuntime(paths.runtimeState, profile);
+	await refuseActiveRuntime(config, profile);
+	await assertListenerAvailable(config, await cliNetwork(config), config.command);
 	const adminToken = await loadOrCreateAdminToken(paths.adminToken);
 	const instanceId = newInstanceId();
 	const log = new CliServerLog(paths.serverLog);
@@ -1863,29 +2202,40 @@ async function startCliServer(config, io, profile) {
 			admin: {
 				token: adminToken,
 				instanceId
+			},
+			recoveryCommand: profile === "dev" ? "node packages/server/dist/dev.mjs reset-access" : "opentig reset-access",
+			onNetworkChanged: async (network) => {
+				const state = await readRuntimeState(paths.runtimeState);
+				await writeRuntimeState(paths.runtimeState, {
+					...state,
+					host: network.listenerHost,
+					port: network.listenerPort
+				});
 			}
-		}, config.port);
+		}, config.port, config);
 		await writeRuntimeState(paths.runtimeState, {
 			pid: process$1.pid,
-			host: config.host,
+			host: server.host,
 			port: server.port,
 			protocolVersion: server.protocolVersion,
 			appVersion: server.appVersion,
 			instanceId,
 			startedAt: (/* @__PURE__ */ new Date()).toISOString()
 		});
-		log.logger("info", `OpenTig CLI ready on ${publicOrigin(config.host, server.port)}.`);
-		const origin = publicOrigin(config.host, server.port);
-		const pairing = rewritePairingOrigin(server.createPairingLink(), origin);
+		await reporter?.ready(instanceId);
+		log.logger("info", `OpenTig CLI ready on ${publicOrigin(server.host, server.port)}.`);
+		const origin = publicOrigin(server.host, server.port);
+		const pairing = server.getStatus().browserAccessEnabled ? rewritePairingOrigin(server.createPairingLink(), origin) : null;
 		io.out(`${applicationName(profile)} ${server.appVersion} is ready.`);
 		if (profile === "dev") io.out(`Dev data directory: ${paths.home}`);
 		io.out(`Connection URL: ${origin}`);
-		printPairing(pairing, io, config.command === "serve");
-		if (!isLoopbackHost(config.host)) {
+		if (pairing) printPairing(pairing, io, config.command === "serve");
+		else io.out("Web access is paused. Use reset-access locally and restart to restore it.");
+		if (!isLoopbackHost(server.host)) {
 			io.error("WARNING: This listener grants owner-level access as your OS user. Use only a trusted LAN/VPN or an HTTPS/SSH tunnel; never expose it directly to the public Internet.");
-			if (config.host === "0.0.0.0" || config.host === "::") io.error("Replace the loopback host in the printed link with a trusted address of this machine for another device.");
+			if (server.host === "0.0.0.0" || server.host === "::") io.error("Replace the loopback host in the printed link with a trusted address of this machine for another device.");
 		}
-		if (config.openBrowser) await openSystemBrowser(pairing.url).catch(() => {
+		if (config.openBrowser && pairing) await openSystemBrowser(pairing.url).catch(() => {
 			io.error("Could not open the system browser. Open the one-time pairing link shown above manually.");
 		});
 		updates.start();
@@ -1895,7 +2245,7 @@ async function startCliServer(config, io, profile) {
 			await log.close();
 		}, io);
 	} catch (error) {
-		await updates.stop();
+		await updates.stop().catch(() => void 0);
 		if (server) await server.close().catch(() => void 0);
 		await clearRuntimeState(paths.runtimeState, instanceId).catch(() => void 0);
 		await log.close();
@@ -1905,15 +2255,15 @@ async function startCliServer(config, io, profile) {
 async function pairRunningServer(config, io, profile) {
 	const paths = resolveCliPaths(config.home);
 	const state = await readRuntimeState(paths.runtimeState);
-	if (!isProcessRunning(state.pid)) throw new Error("OpenTig runtime state is stale; its process is not running.");
+	if (!isProcessRunning(state.pid)) throw new CliError("RUNTIME_STALE", "OpenTig runtime state is stale; its process is not running.", [`Start ${cliCommand(config.home, "serve")} or restart its managed service.`]);
 	const origin = publicOrigin(state.host, state.port);
-	const adminOrigin = localAdminOrigin(state);
+	const adminOrigin = publicOrigin(state.host, state.port);
 	const ready = await fetch(`${adminOrigin}/readyz`, { signal: AbortSignal.timeout(3e3) });
-	if (!ready.ok) throw new Error("The running OpenTig server is not ready.");
+	if (!ready.ok) throw new CliError("SERVER_NOT_READY", "The running OpenTig server is not ready.", [`Check ${cliCommand(config.home, "service", "status")} and retry when startup completes.`]);
 	const identity = await ready.json();
-	if (identity.status !== "ready" || identity.protocolVersion !== state.protocolVersion || identity.appVersion !== state.appVersion || profile === "dev" && identity.profile !== "dev") throw new Error("OpenTig runtime state does not match the running server.");
+	if (identity.status !== "ready" || identity.protocolVersion !== state.protocolVersion || identity.appVersion !== state.appVersion || profile === "dev" && identity.profile !== "dev") throw new CliError("RUNTIME_MISMATCH", "OpenTig runtime state does not match the running server.", [`Inspect ${cliCommand(config.home, "service", "status")} before restarting this instance.`]);
 	const adminToken = await readAdminToken(paths.adminToken).catch(() => {
-		throw new Error("OpenTig local admin credential is missing or unreadable.");
+		throw new CliError("ADMIN_CREDENTIAL_INVALID", "OpenTig local admin credential is missing or unreadable.", [`Check the private credential and permissions in ${paths.serverData}. Do not copy credentials from another instance.`]);
 	});
 	const response = await fetch(`${adminOrigin}/api/admin/pair`, {
 		method: "POST",
@@ -1927,32 +2277,50 @@ async function pairRunningServer(config, io, profile) {
 		}),
 		signal: AbortSignal.timeout(3e3)
 	});
-	if (!response.ok) throw new Error("The running server refused the local pairing request.");
-	printPairing(validatePairing(await response.json(), origin), io, true);
+	if (response.status === 403) throw new CliError("WEB_ACCESS_DISABLED", "Web access is paused; no pairing link was created.", [`Enable browser access in Settings → Web access, or run ${cliCommand(config.home, "reset-access")} and restart this instance.`, "Resetting access restores startup listener settings and preserves paired browsers."]);
+	if (!response.ok) throw new CliError("PAIRING_REFUSED", "The running server refused the local pairing request.", [`Check ${cliCommand(config.home, "service", "status")} and the selected home before retrying.`]);
+	let pairing;
+	try {
+		pairing = validatePairing(await response.json(), origin);
+	} catch (cause) {
+		throw new CliError("PAIRING_INVALID", "The server returned an invalid pairing link.", [`No link was printed. Inspect ${cliCommand(config.home, "service", "status")} and the server log before retrying.`], { cause });
+	}
+	printPairing(pairing, io, true);
 	return 0;
 }
-async function startOnConfiguredPort(baseConfig, port) {
+async function startOnConfiguredPort(baseConfig, port, cliConfig) {
 	try {
 		return await runOpenTigServer({
 			...baseConfig,
 			port
 		});
 	} catch (error) {
-		if (isAddressInUse(error)) throw new Error(`Port ${port} is already in use. Stop that process or select another port with --port.`, { cause: error });
-		throw error;
+		const config = cliConfig ?? {
+			home: path.dirname(baseConfig.settingsPath),
+			host: baseConfig.host ?? "127.0.0.1",
+			port
+		};
+		const { network, savedListener } = await loadStartupNetwork({
+			...baseConfig,
+			port
+		});
+		throw listenerError(error, config, {
+			...network,
+			savedListener
+		}, cliConfig?.command ?? "serve");
 	}
 }
-function publicOrigin(host, port) {
-	const displayHost = host === "0.0.0.0" ? "127.0.0.1" : host === "::" ? "::1" : host;
-	return `http://${displayHost.includes(":") ? `[${displayHost}]` : displayHost}:${port}`;
-}
-async function refuseActiveRuntime(runtimeStatePath, profile) {
+async function refuseActiveRuntime(config, profile) {
+	const paths = resolveCliPaths(config.home);
 	try {
-		const state = await readRuntimeState(runtimeStatePath);
-		if (isProcessRunning(state.pid)) throw new Error(`OpenTig is already running for this home (PID ${state.pid}). Use "${profile === "dev" ? "npm run pair:web:dev" : "opentig pair"}" to add a device.`);
-		await clearRuntimeState(runtimeStatePath, state.instanceId);
+		const state = await readRuntimeState(paths.runtimeState);
+		if (isProcessRunning(state.pid)) {
+			await probeRuntime(config.home, state);
+			throw new CliError("HOME_ACTIVE", "OpenTig is already running for this home.", [`Pair a browser with ${profile === "dev" ? "npm run pair:web:dev" : cliCommand(config.home, "pair")}`, "To switch a foreground instance to a service, stop it in its terminal first."]);
+		}
+		await clearRuntimeState(paths.runtimeState, state.instanceId);
 	} catch (error) {
-		if (error instanceof Error && error.message === "No running OpenTig server was found for this home.") return;
+		if (error instanceof CliError && error.code === "RUNTIME_MISSING") return;
 		throw error;
 	}
 }
@@ -2002,47 +2370,22 @@ function rewritePairingOrigin(pairing, origin) {
 }
 function validatePairing(value, origin) {
 	const pairing = value;
-	if (!pairing || typeof pairing.url !== "string" || typeof pairing.expiresAt !== "string") throw new Error("The server returned an invalid pairing link.");
+	if (!pairing || typeof pairing.url !== "string" || typeof pairing.expiresAt !== "string") throw new CliError("PAIRING_INVALID", "The server returned an invalid pairing link.", ["No link was printed. Check the selected instance and server logs before retrying."]);
 	const url = new URL(pairing.url);
 	const token = new URLSearchParams(url.hash.slice(1)).get("token");
 	const expiresAt = Date.parse(pairing.expiresAt);
-	if (url.origin !== origin || url.pathname !== "/pair" || url.search || !token || !/^[A-Za-z0-9_-]{43}$/.test(token) || expiresAt <= Date.now() || expiresAt > Date.now() + 9e5) throw new Error("The server returned an invalid pairing link.");
+	if (url.origin !== origin || url.username || url.password || url.pathname !== "/pair" || url.search || !token || !/^[A-Za-z0-9_-]{43}$/.test(token) || !Number.isFinite(expiresAt) || expiresAt <= Date.now() || expiresAt > Date.now() + 9e5) throw new CliError("PAIRING_INVALID", "The server returned an invalid pairing link.", ["No link was printed. Check the selected instance and server logs before retrying."]);
 	return {
 		url: url.href,
 		expiresAt: pairing.expiresAt
 	};
 }
-function localAdminOrigin(state) {
-	return publicOrigin(state.host, state.port);
-}
 function isLoopbackHost(host) {
 	return host === "127.0.0.1" || host === "::1" || host.toLowerCase() === "localhost";
 }
-function isAddressInUse(error) {
-	return error instanceof Error && "code" in error && error.code === "EADDRINUSE";
-}
-function isProcessRunning(pid) {
-	try {
-		process$1.kill(pid, 0);
-		return true;
-	} catch (error) {
-		return error.code === "EPERM";
-	}
-}
 function assertNodeVersion() {
 	const major = Number(process$1.versions.node.split(".", 1)[0]);
-	if (!Number.isSafeInteger(major) || major < 24) throw new Error("Node.js 24 or later is required.");
-}
-function assertGitAvailable() {
-	return new Promise((resolve, reject) => {
-		execFile("git", ["--version"], {
-			timeout: 1e4,
-			windowsHide: true
-		}, (error, stdout) => {
-			if (error || !stdout.trim().startsWith("git version ")) reject(/* @__PURE__ */ new Error("Git is required and was not found on PATH."));
-			else resolve();
-		});
-	});
+	if (!Number.isSafeInteger(major) || major < 24) throw new CliError("NODE_UNSUPPORTED", "Node.js 24 or later is required.", ["Install a supported Node.js version, then retry from that terminal."]);
 }
 //#endregion
 export { parseCliArguments as i, OPEN_TIG_APP_VERSION as n, CliUsageError as r, runCli as t };