opentray 0.14.4 → 0.16.0

package/dist/index.mjs

@@ -1,12 +1,126 @@
 import { createRequire } from "node:module";
-import { PROTOCOL_VERSION, PROTOCOL_VERSION as PROTOCOL_VERSION$1, createBrokerEndpointIdentity, createBrokerEndpointIdentity as createBrokerEndpointIdentity$1, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatUnixSocketPath as formatUnixSocketPath$1, formatWindowsPipeName, formatWindowsPipeName as formatWindowsPipeName$1, isSupportedProtocolVersion, parseServerFrame, sanitizeCallerLabel } from "@opentray/spec";
+import { PROTOCOL_VERSION, PROTOCOL_VERSION as PROTOCOL_VERSION$1, brokerArtifactIdentityEquals, createBrokerEndpointIdentity, createBrokerEndpointIdentity as createBrokerEndpointIdentity$1, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatUnixSocketPath as formatUnixSocketPath$1, formatWindowsPipeName, formatWindowsPipeName as formatWindowsPipeName$1, isBrokerArtifactIdentity, isSupportedProtocolVersion, parseServerFrame, sanitizeCallerLabel } from "@opentray/spec";
+import { access, mkdir, open, readFile, realpath, rm, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { basename, dirname, join } from "node:path";
 import { constants } from "node:fs";
-import { access, mkdir, open, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+//#region src/native-extension-artifact.ts
+var NativeExtensionArtifactResolutionError = class extends Error {
+	target;
+	code = "OPENTRAY_NATIVE_EXTENSION_ARTIFACT_RESOLUTION_FAILED";
+	packageName;
+	facadePackageJsonUrl;
+	constructor(message, target, options = {}) {
+		super(message, options);
+		this.target = target;
+		this.name = "NativeExtensionArtifactResolutionError";
+		if (options.packageName !== void 0) this.packageName = options.packageName;
+		if (options.facadePackageJsonUrl !== void 0) this.facadePackageJsonUrl = options.facadePackageJsonUrl;
+	}
+};
+/** Resolve one exact native library from the dependency closure that owns the facade. */
+const resolveNativeExtensionArtifact = async (artifact, platform = process.platform, arch = process.arch) => {
+	const target = nativeExtensionTarget(platform, arch);
+	if (artifact.kind === "file") return {
+		path: await resolveAccessibleLibrary(artifact.path, target),
+		expectedIdentity: artifact.expectedIdentity ?? await resolveExpectedIdentity(artifact.identitySource, target),
+		target
+	};
+	const packageTarget = artifact.targets[target];
+	if (packageTarget === void 0) throw new NativeExtensionArtifactResolutionError(`native extension does not support target ${target}`, target);
+	const expectedIdentity = await resolveExpectedIdentity(artifact, target);
+	const resolveFromFacade = createRequire(artifact.packageJsonUrl);
+	let platformPackageJsonPath;
+	try {
+		platformPackageJsonPath = resolveFromFacade.resolve(`${packageTarget.packageName}/package.json`);
+	} catch (cause) {
+		throw new NativeExtensionArtifactResolutionError(`unable to resolve native extension package "${packageTarget.packageName}" for ${target} from ${artifact.packageJsonUrl}`, target, {
+			cause,
+			packageName: packageTarget.packageName,
+			facadePackageJsonUrl: artifact.packageJsonUrl
+		});
+	}
+	const manifest = await readPlatformPackageManifest(platformPackageJsonPath, target, packageTarget.packageName);
+	return {
+		path: await resolveAccessibleLibrary(join(dirname(platformPackageJsonPath), packageTarget.libraryPath), target, packageTarget.packageName),
+		packageName: packageTarget.packageName,
+		packageVersion: manifest.version,
+		expectedIdentity,
+		target
+	};
+};
+const resolveExpectedIdentity = async (source, target) => {
+	const [facadeManifest, contractManifest] = await Promise.all([readFacadePackageManifest(source.packageJsonUrl, target), readExtensionContractManifest(source.contractManifestUrl, target)]);
+	const [os, arch] = splitTarget(target);
+	return {
+		extensionName: contractManifest.extensionName,
+		artifactSetVersion: facadeManifest.version,
+		contractFingerprint: contractManifest.contractFingerprint,
+		target: {
+			os,
+			arch
+		}
+	};
+};
+const nativeExtensionTarget = (platform, arch) => {
+	if (arch !== "arm64" && arch !== "x64") throw new Error(`unsupported native extension architecture: ${arch}`);
+	return `${platform}-${arch}`;
+};
+const readFacadePackageManifest = async (packageJsonUrl, target) => {
+	const parsed = await readJsonUrl(packageJsonUrl, target, "facade package manifest");
+	if (!isFacadePackageManifest(parsed)) throw new NativeExtensionArtifactResolutionError(`native extension facade manifest is invalid at ${packageJsonUrl}`, target, { facadePackageJsonUrl: packageJsonUrl });
+	return parsed;
+};
+const readExtensionContractManifest = async (contractManifestUrl, target) => {
+	const parsed = await readJsonUrl(contractManifestUrl, target, "extension contract manifest");
+	if (!isExtensionContractManifest(parsed)) throw new NativeExtensionArtifactResolutionError(`native extension contract manifest is invalid at ${contractManifestUrl}`, target);
+	return parsed;
+};
+const readJsonUrl = async (url, target, label) => {
+	try {
+		return JSON.parse(await readFile(new URL(url), "utf8"));
+	} catch (cause) {
+		throw new NativeExtensionArtifactResolutionError(`unable to read ${label} at ${url}`, target, { cause });
+	}
+};
+const readPlatformPackageManifest = async (packageJsonPath, target, packageName) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(packageJsonPath, "utf8"));
+	} catch (cause) {
+		throw new NativeExtensionArtifactResolutionError(`unable to read native extension package manifest at ${packageJsonPath}`, target, {
+			cause,
+			packageName
+		});
+	}
+	if (!isPlatformPackageManifest(parsed) || parsed.name !== packageName) throw new NativeExtensionArtifactResolutionError(`native extension package manifest at ${packageJsonPath} does not identify ${packageName}`, target, { packageName });
+	const [platform, arch] = splitTarget(target);
+	if (parsed.os !== void 0 && !parsed.os.includes(platform)) throw new NativeExtensionArtifactResolutionError(`native extension package ${packageName} does not support os ${platform}`, target, { packageName });
+	if (parsed.cpu !== void 0 && !parsed.cpu.includes(arch)) throw new NativeExtensionArtifactResolutionError(`native extension package ${packageName} does not support cpu ${arch}`, target, { packageName });
+	return parsed;
+};
+const isPlatformPackageManifest = (value) => typeof value === "object" && value !== null && "name" in value && typeof value.name === "string" && "version" in value && typeof value.version === "string" && (!("os" in value) || Array.isArray(value.os) && value.os.every((item) => typeof item === "string")) && (!("cpu" in value) || Array.isArray(value.cpu) && value.cpu.every((item) => typeof item === "string"));
+const isFacadePackageManifest = (value) => typeof value === "object" && value !== null && "name" in value && typeof value.name === "string" && "version" in value && typeof value.version === "string";
+const isExtensionContractManifest = (value) => typeof value === "object" && value !== null && "extensionName" in value && typeof value.extensionName === "string" && "contractFingerprint" in value && typeof value.contractFingerprint === "string";
+const splitTarget = (target) => {
+	const separator = target.lastIndexOf("-");
+	return [target.slice(0, separator), target.slice(separator + 1)];
+};
+const resolveAccessibleLibrary = async (path, target, packageName) => {
+	try {
+		return await realpath(path);
+	} catch (cause) {
+		throw new NativeExtensionArtifactResolutionError(`native extension library is not accessible at ${path}`, target, {
+			cause,
+			...packageName === void 0 ? {} : { packageName }
+		});
+	}
+};
+//#endregion
 //#region src/client.ts
 const createInitFrame = (clientVersion) => ({
 	type: "init",
@@ -15,8 +129,27 @@ const createInitFrame = (clientVersion) => ({
 });
 function createClient(transport, options = {}) {
 	const nextRequestId = createRequestIdFactory(options.requestIdPrefix ?? "opentray");
+	let appPromise;
+	const ensureApp = async (trayOptions) => {
+		appPromise ??= (async () => {
+			const app = await resolveDefaultAppRef(transport, nextRequestId);
+			const handle = createAppHandle(transport, app.appId, nextRequestId);
+			const configured = options.appOptions;
+			if (configured?.name !== void 0) await handle.setName(configured.name);
+			if (configured?.icon !== void 0) await handle.setIcon(configured.icon);
+			else if (trayOptions.icon !== void 0 && await handle.getIcon() === null) await handle.setIcon(trayOptions.icon);
+			return {
+				app,
+				handle
+			};
+		})().catch((error) => {
+			appPromise = void 0;
+			throw error;
+		});
+		return appPromise;
+	};
 	return { async createTray(options) {
-		const app = await resolveDefaultAppRef(transport, nextRequestId);
+		const { app } = await ensureApp(options);
 		const requestId = nextRequestId();
 		const frame = expectResponse(await transport.request({
 			type: "create-tray",
@@ -36,6 +169,7 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 	};
 	const handle = {
 		trayId,
+		app: createAppHandle(transport, appId, nextRequestId),
 		async getBounds() {
 			const requestId = nextRequestId();
 			return expectResponse(await transport.request({
@@ -77,12 +211,14 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 		},
 		async loadExtension(options) {
 			const requestId = nextRequestId();
+			const resolved = await resolveNativeExtensionArtifact(options.artifact);
 			expectResponse(await transport.request({
 				type: "load-ext",
 				requestId,
 				appId,
 				name: options.name,
-				path: options.path,
+				path: resolved.path,
+				expectedIdentity: resolved.expectedIdentity,
 				...options.mountId === void 0 ? {} : { mountId: options.mountId }
 			}), requestId, "ack");
 		},
@@ -172,16 +308,55 @@ const resolveDefaultAppRef = async (transport, nextRequestId) => {
 		requestId
 	}), requestId, "default-app").app;
 };
+const createAppHandle = (transport, appId, nextRequestId) => {
+	const requestIdentity = async () => {
+		const requestId = nextRequestId();
+		return expectResponse(await transport.request({
+			type: "get-app-identity",
+			requestId,
+			appId
+		}), requestId, "app-identity").identity;
+	};
+	return {
+		appId,
+		async getName() {
+			return (await requestIdentity()).appName;
+		},
+		async setName(name) {
+			const requestId = nextRequestId();
+			expectResponse(await transport.request({
+				type: "set-app-name",
+				requestId,
+				appId,
+				name
+			}), requestId, "ack");
+			return (await requestIdentity()).appName;
+		},
+		async getIcon() {
+			return (await requestIdentity()).icon ?? null;
+		},
+		async setIcon(icon) {
+			const requestId = nextRequestId();
+			expectResponse(await transport.request({
+				type: "set-app-icon",
+				requestId,
+				appId,
+				icon
+			}), requestId, "ack");
+			return icon;
+		}
+	};
+};
 const createTrayExtensionContext = (tray, appId, extension, options, nextMountId) => {
 	const mount = extension.resolveMount?.(options) ?? {};
 	const name = mount.name ?? extension.name;
-	const path = mount.path ?? extension.path;
+	const artifact = mount.artifact ?? extension.artifact;
 	const mountId = mount.mountId ?? nextMountId(name);
 	let loadPromise;
 	const ensureLoaded = async () => {
 		if (loadPromise === void 0) loadPromise = tray.loadExtension({
 			name,
-			path,
+			artifact,
 			mountId
 		}).catch((error) => {
 			loadPromise = void 0;
@@ -193,7 +368,7 @@ const createTrayExtensionContext = (tray, appId, extension, options, nextMountId
 		appId,
 		trayId: tray.trayId,
 		name,
-		path,
+		artifact,
 		mountId,
 		ensureLoaded,
 		async command(data) {
@@ -228,6 +403,7 @@ const requestIdOf = (frame) => {
 	switch (frame.type) {
 		case "app-created":
 		case "default-app":
+		case "app-identity":
 		case "tray-created":
 		case "tray-bounds":
 		case "ack":
@@ -271,6 +447,13 @@ const resolveBrokerNativeTarget = (platform = process.platform, arch = process.a
 		binaryRelativePath: `bin/${packageOs === "windows" ? "opentray.exe" : "opentray"}`
 	};
 };
+const resolveBrokerArtifactTarget = (platform = process.platform, arch = process.arch) => {
+	const packageOs = platformToPackageOs(platform);
+	return {
+		os: packageOs === "windows" ? "win32" : packageOs,
+		arch: normalizeArch(arch)
+	};
+};
 const platformToPackageOs = (platform) => {
 	switch (platform) {
 		case "darwin":
@@ -305,6 +488,31 @@ var MissingPlatformBrokerBinaryError = class extends Error {
 //#region src/daemon/broker-command.ts
 const sourceUrl = import.meta.url;
 const requireFromSource = createRequire(sourceUrl);
+const resolveBrokerArtifact = async (paths, options = {}) => {
+	const command = await resolveBrokerCommand(paths, options);
+	const executablePath = await (options.resolveExecutablePath ?? realpath)(command.command);
+	const bytes = await (options.readExecutable ?? readFile)(executablePath);
+	const executableHash = createHash("sha256").update(bytes).digest("hex");
+	const artifactIdentity = {
+		packageVersion: paths.packageVersion,
+		target: resolveBrokerArtifactTarget(options.platform ?? process.platform, options.arch ?? process.arch),
+		executableHash,
+		buildIdentity: `sha256:${executableHash.slice(0, 16)}`
+	};
+	return {
+		...command,
+		command: executablePath,
+		args: [
+			...command.args,
+			"--broker-executable-path",
+			executablePath,
+			"--broker-artifact-identity",
+			JSON.stringify(artifactIdentity)
+		],
+		executablePath,
+		artifactIdentity
+	};
+};
 const resolveBrokerCommand = async (paths, options = {}) => {
 	const explicit = (options.env ?? process.env).OPENTRAY_BROKER_BIN;
 	if (explicit !== void 0 && explicit.length > 0) return commandForBinary(explicit, paths);
@@ -315,7 +523,7 @@ const resolveBrokerCommand = async (paths, options = {}) => {
 	if (installed.binary !== void 0) return commandForBinary(installed.binary, paths);
 	const sourceDir = options.sourceDir ?? dirname(fileURLToPath(sourceUrl));
 	const workspaceRoot = await (options.findWorkspaceRoot ?? findWorkspaceRoot)(sourceDir);
-	if (workspaceRoot !== void 0) return commandForBinary(await (options.ensureDevBrokerBinary ?? ensureDevBrokerBinary)(workspaceRoot), paths);
+	if (workspaceRoot !== void 0) return commandForBinary(await (options.ensureDevBrokerBinary ?? ensureDevBrokerBinary)(workspaceRoot, paths, platform), paths);
 	throw new MissingPlatformBrokerBinaryError(installed.binaryPath === void 0 ? `unable to resolve OpenTray broker binary for ${platform}/${arch}; install "${target.packageName}" for this platform or set OPENTRAY_BROKER_BIN` : `unable to resolve OpenTray broker binary for ${platform}/${arch}; package "${target.packageName}" was found but binary "${installed.binaryPath}" is not accessible; restage the runtime package or set OPENTRAY_BROKER_BIN`, platform, arch, {
 		packageName: target.packageName,
 		...installed.binaryPath === void 0 ? {} : { binaryPath: installed.binaryPath }
@@ -377,22 +585,20 @@ const findWorkspaceRoot = async (start) => {
 		current = parent;
 	}
 };
-const resolveDevBrokerBinaryPath = (workspaceRoot, platform = process.platform) => join(workspaceRoot, "target", "debug", platform === "win32" ? "opentray.exe" : "opentray");
-const terminateWorkspaceDevBrokerProcess = async (workspaceRoot, platform = process.platform) => {
-	if (platform !== "win32") return;
-	await terminateWindowsProcessByExecutable(resolveDevBrokerBinaryPath(workspaceRoot, platform));
-};
-const ensureDevBrokerBinary = async (workspaceRoot) => {
-	const binary = resolveDevBrokerBinaryPath(workspaceRoot);
-	await terminateWorkspaceDevBrokerProcess(workspaceRoot);
-	await runCargoBuild(workspaceRoot);
+const resolveDevBrokerBinaryPath = (workspaceRoot, platform = process.platform, callerLabel = "opentray") => join(resolveDevBrokerTargetDir(workspaceRoot, platform, callerLabel), "debug", platform === "win32" ? "opentray.exe" : "opentray");
+const resolveDevBrokerTargetDir = (workspaceRoot, platform, callerLabel) => platform === "win32" ? join(workspaceRoot, "target", "opentray-source", callerLabel) : join(workspaceRoot, "target");
+const ensureDevBrokerBinary = async (workspaceRoot, paths, platform) => {
+	const targetDir = resolveDevBrokerTargetDir(workspaceRoot, platform, paths.callerLabel);
+	const binary = resolveDevBrokerBinaryPath(workspaceRoot, platform, paths.callerLabel);
+	await runCargoBuild(workspaceRoot, platform === "win32" ? targetDir : void 0);
 	return binary;
 };
-const runCargoBuild = (workspaceRoot) => new Promise((resolve, reject) => {
+const runCargoBuild = (workspaceRoot, targetDir) => new Promise((resolve, reject) => {
 	const child = spawn("cargo", [
 		"build",
 		"-p",
-		"opentray-bin"
+		"opentray-bin",
+		...targetDir === void 0 ? [] : ["--target-dir", targetDir]
 	], {
 		cwd: workspaceRoot,
 		stdio: process.env.OPENTRAY_BROKER_BUILD_LOGS === "1" ? "inherit" : "ignore"
@@ -414,61 +620,25 @@ const exists = async (path) => {
 		return false;
 	}
 };
-const terminateWindowsProcessByExecutable = (binary) => new Promise((resolve, reject) => {
-	const child = spawn("powershell.exe", [
-		"-NoProfile",
-		"-NonInteractive",
-		"-ExecutionPolicy",
-		"Bypass",
-		"-Command",
-		String.raw`
-$ErrorActionPreference = 'Stop'
-$target = [System.IO.Path]::GetFullPath(${powerShellString(binary)})
-$processes = @(Get-CimInstance Win32_Process -Filter "Name = 'opentray.exe'" | Where-Object {
-  $_.ExecutablePath -and ([System.IO.Path]::GetFullPath($_.ExecutablePath) -ieq $target)
-})
-foreach ($process in $processes) {
-  Stop-Process -Id $process.ProcessId -Force -ErrorAction Stop
-}
-foreach ($process in $processes) {
-  Wait-Process -Id $process.ProcessId -Timeout 5 -ErrorAction SilentlyContinue
-}
-`
-	], { stdio: [
-		"ignore",
-		"ignore",
-		"pipe"
-	] });
-	let stderr = "";
-	child.stderr?.on("data", (chunk) => {
-		stderr += String(chunk);
-	});
-	child.once("error", reject);
-	child.once("exit", (code) => {
-		if (code === 0) {
-			resolve();
-			return;
-		}
-		reject(/* @__PURE__ */ new Error(`failed to stop running dev broker before cargo build: ${stderr.trim() || code}`));
-	});
-});
 const binaryAccessMode = (platform) => platform === "win32" ? constants.F_OK : constants.X_OK;
 const assertInstalledBrokerBinaryAccessible = async (binaryPath, platform) => {
 	await access(binaryPath, binaryAccessMode(platform));
 };
-const powerShellString = (value) => `'${value.replace(/'/g, "''")}'`;
 function isNodeError$1(error) {
 	return error instanceof Error && "code" in error;
 }
 //#endregion
 //#region src/daemon/lifecycle.ts
 const DAEMON_STDIO_ENV = "OPENTRAY_DAEMON_STDIO";
+const DEFAULT_DAEMON_LOCK_TIMEOUT_MS = 5e3;
 const createNodeDaemonDriver = (cliEntrypoint) => ({
+	async resolveBroker(paths) {
+		return resolveBrokerArtifact(paths);
+	},
 	async isAlive(pid) {
 		return isProcessAlive(pid);
 	},
-	async spawnBroker(paths) {
-		const broker = await resolveBrokerCommand(paths);
+	async spawnBroker(paths, broker) {
 		const child = spawn(broker.command, broker.args, {
 			cwd: broker.cwd,
 			detached: true,
@@ -493,25 +663,41 @@ const createNodeDaemonDriver = (cliEntrypoint) => ({
 const resolveBrokerStdio = (value) => {
 	return value === "inherit" ? "inherit" : "ignore";
 };
-const startDaemon = async ({ paths, driver, lockTimeoutMs = 1e3 }) => {
+const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_TIMEOUT_MS }) => {
+	const broker = await driver.resolveBroker(paths);
 	await mkdir(paths.runtimeDir, { recursive: true });
 	const lock = await acquireLock(paths.lockFile, lockTimeoutMs);
 	try {
 		const existingPid = await readPid(paths.pidFile);
-		if (existingPid !== void 0 && await driver.isAlive(existingPid)) return {
-			status: "already-running",
-			pid: existingPid,
-			paths
-		};
+		if (existingPid !== void 0 && await driver.isAlive(existingPid)) {
+			if (readyMatchesBroker(await readReadyMetadata(paths.readyFile), paths, existingPid, broker)) return {
+				status: "already-running",
+				pid: existingPid,
+				paths,
+				broker
+			};
+			await driver.stop(existingPid);
+			if (!await waitUntilStopped(driver, existingPid)) throw new Error(`incompatible daemon broker did not stop within the bounded shutdown window: pid=${existingPid}`);
+		}
 		await cleanupRuntimeFiles(paths);
-		const pid = await driver.spawnBroker(paths);
+		const pid = await driver.spawnBroker(paths, broker);
 		if (!Number.isInteger(pid) || pid <= 0) throw new Error("daemon broker process did not expose a valid pid");
 		await writeFile(paths.pidFile, `${pid}\n`, "utf8");
-		await waitForReadyFile(paths.readyFile, driver, pid);
+		try {
+			await waitForReadyFile(paths, driver, pid, broker);
+		} catch (error) {
+			if (await driver.isAlive(pid)) {
+				await driver.stop(pid);
+				await waitUntilStopped(driver, pid);
+			}
+			await cleanupRuntimeFiles(paths);
+			throw error;
+		}
 		return {
 			status: "started",
 			pid,
-			paths
+			paths,
+			broker
 		};
 	} finally {
 		await lock.release();
@@ -532,16 +718,50 @@ const cleanupRuntimeFiles = async (paths) => {
 	await rm(paths.pidFile, { force: true });
 	if (process.platform !== "win32") await rm(paths.endpoint, { force: true });
 };
-const waitForReadyFile = async (readyFile, driver, pid) => {
-	for (let attempt = 0; attempt < 40; attempt += 1) try {
-		await readFile(readyFile, "utf8");
-		return;
-	} catch (error) {
-		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
-		if (!await driver.isAlive(pid)) throw new Error(`daemon broker exited before readiness: pid=${pid}; readyFile=${readyFile}; set ${DAEMON_STDIO_ENV}=inherit to inspect broker stderr`);
+const waitUntilStopped = async (driver, pid) => {
+	for (let attempt = 0; attempt < 20; attempt += 1) {
+		if (!await driver.isAlive(pid)) return true;
+		await sleep(50);
+	}
+	return false;
+};
+const waitForReadyFile = async (paths, driver, pid, broker) => {
+	for (let attempt = 0; attempt < 40; attempt += 1) {
+		const ready = await readReadyMetadata(paths.readyFile);
+		if (readyMatchesBroker(ready, paths, pid, broker)) return;
+		if (ready !== void 0) throw new Error(`daemon readiness artifact identity mismatch: expected=${JSON.stringify(broker.artifactIdentity)} actual=${JSON.stringify(ready.brokerArtifactIdentity)}`);
+		if (!await driver.isAlive(pid)) throw new Error(`daemon broker exited before readiness: pid=${pid}; readyFile=${paths.readyFile}; set ${DAEMON_STDIO_ENV}=inherit to inspect broker stderr`);
 		await sleep(50);
 	}
-	throw new Error(`timed out waiting for daemon readiness: ${readyFile}`);
+	throw new Error(`timed out waiting for daemon readiness: ${paths.readyFile}`);
+};
+const readReadyMetadata = async (readyFile) => {
+	let value;
+	try {
+		value = JSON.parse(await readFile(readyFile, "utf8"));
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return;
+		if (error instanceof SyntaxError) return;
+		throw error;
+	}
+	if (!isRecord(value) || !Number.isInteger(value.pid) || typeof value.pid !== "number" || typeof value.endpoint !== "string" || typeof value.packageVersion !== "string" || typeof value.protocolVersion !== "number" || typeof value.appId !== "string" || typeof value.appName !== "string" || typeof value.callerLabel !== "string" || typeof value.executablePath !== "string" || !isBrokerArtifactIdentity(value.brokerArtifactIdentity)) return;
+	return {
+		pid: value.pid,
+		endpoint: value.endpoint,
+		packageVersion: value.packageVersion,
+		protocolVersion: value.protocolVersion,
+		appId: value.appId,
+		appName: value.appName,
+		callerLabel: value.callerLabel,
+		executablePath: value.executablePath,
+		brokerArtifactIdentity: value.brokerArtifactIdentity
+	};
+};
+const readyMatchesBroker = (ready, paths, pid, broker) => ready !== void 0 && ready.pid === pid && ready.endpoint === paths.endpoint && ready.packageVersion === paths.packageVersion && ready.protocolVersion === paths.protocolVersion && ready.appId === paths.appId && ready.appName === paths.appName && ready.callerLabel === paths.callerLabel && executablePathsEqual(ready.executablePath, broker.executablePath) && brokerArtifactIdentityEquals(ready.brokerArtifactIdentity, broker.artifactIdentity);
+const executablePathsEqual = (left, right, platform = process.platform) => {
+	if (platform !== "win32") return left === right;
+	const normalize = (value) => value.replaceAll("\\", "/").replace(/^\/\/?\?\//u, "").toLowerCase();
+	return normalize(left) === normalize(right);
 };
 const acquireLock = async (lockFile, timeoutMs) => {
 	const deadline = Date.now() + timeoutMs;
@@ -573,6 +793,7 @@ const isProcessAlive = (pid) => {
 };
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const isNodeError = (error) => error instanceof Error && "code" in error;
+const isRecord = (value) => typeof value === "object" && value !== null;
 //#endregion
 //#region src/daemon/package-version.ts
 const readPackageVersion = async (packageJsonUrl) => {
@@ -632,15 +853,19 @@ const connectLocalBroker = async (options = {}) => {
 	const endpoint = options.endpoint ?? paths.endpoint;
 	const autoStart = options.autoStart ?? endpoint === paths.endpoint;
 	if (autoStart && endpoint !== paths.endpoint) throw new Error("local broker autoStart requires the derived same-version endpoint");
-	if (autoStart) {
-		const cliEntrypoint = options.cliEntrypoint ?? resolveCliEntrypoint();
-		await startDaemon({
-			paths,
-			driver: options.daemonDriver ?? createNodeDaemonDriver(cliEntrypoint)
-		});
-	}
+	const cliEntrypoint = options.cliEntrypoint ?? resolveCliEntrypoint();
+	const driver = options.daemonDriver ?? createNodeDaemonDriver(cliEntrypoint);
+	const expectedBrokerArtifactIdentity = autoStart ? (await startDaemon({
+		paths,
+		driver
+	})).broker.artifactIdentity : options.expectedBrokerArtifactIdentity ?? (await driver.resolveBroker(paths)).artifactIdentity;
 	const connection = new LocalBrokerConnection(await connectSocket(endpoint), endpoint, callerLabel);
-	await connection.init(clientVersion, options.protocolVersion ?? PROTOCOL_VERSION$1);
+	try {
+		await connection.init(clientVersion, options.protocolVersion ?? PROTOCOL_VERSION$1, expectedBrokerArtifactIdentity);
+	} catch (error) {
+		await connection.close();
+		throw error;
+	}
 	return connection;
 };
 const normalizeAppIdentityField = (value) => {
@@ -671,7 +896,7 @@ var LocalBrokerConnection = class {
 			this.rejectAll(/* @__PURE__ */ new Error("broker connection closed"));
 		});
 	}
-	async init(clientVersion, protocolVersion) {
+	async init(clientVersion, protocolVersion, expectedBrokerArtifactIdentity) {
 		const ready = new Promise((resolve, reject) => {
 			this.ready = {
 				resolve,
@@ -684,6 +909,7 @@ var LocalBrokerConnection = class {
 			clientVersion
 		});
 		const frame = await ready;
+		if (!brokerArtifactIdentityEquals(frame.brokerArtifactIdentity, expectedBrokerArtifactIdentity)) throw new Error(`broker artifact identity mismatch: expected=${JSON.stringify(expectedBrokerArtifactIdentity)} actual=${JSON.stringify(frame.brokerArtifactIdentity)}`);
 		this.sessionId = frame.sessionId;
 	}
 	async request(frame) {
@@ -778,6 +1004,7 @@ const responseRequestId = (frame) => {
 	switch (frame.type) {
 		case "app-created":
 		case "default-app":
+		case "app-identity":
 		case "tray-created":
 		case "tray-bounds":
 		case "ack":
@@ -914,10 +1141,22 @@ const registerClickId = (state, id) => {
 //#endregion
 //#region src/sdk.ts
 const createTray = async (options, runtimeOptions = {}) => {
-	const connection = await connectLocalBroker(runtimeOptions);
 	const normalized = normalizeCreateTrayOptions(options);
-	const tray = await createClient(connection).createTray(normalized.options);
-	return wrapCreateTrayHandle(tray, { menuUnsubscribe: bindMenuClickHandlers(tray, normalized.menuHandlers) });
+	const connection = await connectLocalBroker(runtimeOptions);
+	try {
+		const tray = await createClient(connection, { appOptions: {
+			...runtimeOptions.appName === void 0 ? {} : { name: runtimeOptions.appName },
+			...runtimeOptions.appIcon === void 0 ? {} : { icon: runtimeOptions.appIcon }
+		} }).createTray(normalized.options);
+		return wrapCreateTrayHandle(tray, {
+			closeConnection: () => connection.close(),
+			destroyPromise: void 0,
+			menuUnsubscribe: bindMenuClickHandlers(tray, normalized.menuHandlers)
+		});
+	} catch (error) {
+		await connection.close().catch(noop);
+		throw error;
+	}
 };
 const normalizeCreateTrayOptions = (options) => {
 	const protocolOptions = {
@@ -951,9 +1190,16 @@ const wrapCreateTrayHandle = (tray, state) => {
 			return wrapCreateTrayHandle(tray.extend(extension, options), state);
 		},
 		async destroy() {
-			state.menuUnsubscribe();
-			state.menuUnsubscribe = noop;
-			await tray.destroy();
+			state.destroyPromise ??= (async () => {
+				state.menuUnsubscribe();
+				state.menuUnsubscribe = noop;
+				try {
+					await tray.destroy();
+				} finally {
+					await state.closeConnection();
+				}
+			})();
+			await state.destroyPromise;
 		}
 	};
 };
@@ -965,6 +1211,6 @@ const bindMenuClickHandlers = (tray, handlers) => {
 };
 const noop = () => {};
 //#endregion
-export { PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion };
+export { NativeExtensionArtifactResolutionError, PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveNativeExtensionArtifact };
 
 //# sourceMappingURL=index.mjs.map