opentray 0.17.0 → 0.19.0

package/dist/index.mjs

@@ -1,14 +1,14 @@
 import { createRequire } from "node:module";
 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 { access, appendFile, link, mkdir, open, readFile, realpath, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { clearDarwinAppBundleOwner, ensureDarwinAppBundle, resolveDefaultDarwinAppBundlePath, resolveOpenTrayPackageIdentity, writeDarwinAppBundleOwner } from "@opentray/packaging";
+import { clearDarwinAppBundleOwner, convergeDarwinAppBundleIdentity, ensureDarwinAppBundle, resolveDefaultDarwinAppBundlePath, resolveOpenTrayPackageIdentity, updateDarwinAppLaunchDescriptor, writeDarwinAppBundleOwner } from "@opentray/packaging";
+import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
 //#region src/app-icon.ts
 const DEFAULT_APP_ICON_VARIANT = "default";
 const APP_ICON_VARIANT_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
@@ -221,7 +221,7 @@ const matchesFormat = (bytes, format) => {
 const hasPrefix = (bytes, prefix) => bytes.length >= prefix.length && prefix.every((byte, index) => bytes[index] === byte);
 const assertExactKeys = (record, expected, platform, optional = []) => {
 	const actual = Object.keys(record);
-	const allowed = new Set([...expected, ...optional]);
+	const allowed = /* @__PURE__ */ new Set([...expected, ...optional]);
 	const unexpected = actual.find((key) => !allowed.has(key));
 	if (unexpected !== void 0) throw new InvalidAppIconError(`unexpected asset field ${unexpected}`, platform);
 	const missing = expected.find((key) => !(key in record));
@@ -272,8 +272,9 @@ const resolveNativeExtensionArtifact = async (artifact, platform = process.platf
 		});
 	}
 	const manifest = await readPlatformPackageManifest(platformPackageJsonPath, target, packageTarget.packageName);
+	const libraryPath = join(dirname(platformPackageJsonPath), packageTarget.libraryPath);
 	return {
-		path: await resolveAccessibleLibrary(join(dirname(platformPackageJsonPath), packageTarget.libraryPath), target, packageTarget.packageName),
+		path: await resolveAccessibleLibrary(libraryPath, target, packageTarget.packageName),
 		packageName: packageTarget.packageName,
 		packageVersion: manifest.version,
 		expectedIdentity,
@@ -377,12 +378,13 @@ function createClient(transport, options = {}) {
 	return { async createTray(options) {
 		const { app } = await ensureApp(options);
 		const requestId = nextRequestId();
-		const frame = expectResponse(await transport.request({
+		const response = await transport.request({
 			type: "create-tray",
 			requestId,
 			app,
 			tray: options
-		}), requestId, "tray-created");
+		});
+		const frame = expectResponse(response, requestId, "tray-created");
 		return createTrayHandle(transport, app.appId, frame.trayId ?? options.id, nextRequestId);
 	} };
 }
@@ -398,47 +400,51 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 		app: createAppHandle(transport, appId, nextRequestId),
 		async getBounds() {
 			const requestId = nextRequestId();
-			return expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "get-tray-bounds",
 				requestId,
 				appId,
 				trayId
-			}), requestId, "tray-bounds").bounds;
+			});
+			return expectResponse(response, requestId, "tray-bounds").bounds;
 		},
 		async setMenu(menu) {
 			const requestId = nextRequestId();
-			expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "set-tray-menu",
 				requestId,
 				appId,
 				trayId,
 				menu
-			}), requestId, "ack");
+			});
+			expectResponse(response, requestId, "ack");
 		},
 		async setTooltip(tooltip) {
 			const requestId = nextRequestId();
-			expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "set-tray-tooltip",
 				requestId,
 				appId,
 				trayId,
 				tooltip
-			}), requestId, "ack");
+			});
+			expectResponse(response, requestId, "ack");
 		},
 		async setIcon(icon) {
 			const requestId = nextRequestId();
-			expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "set-tray-icon",
 				requestId,
 				appId,
 				trayId,
 				icon
-			}), requestId, "ack");
+			});
+			expectResponse(response, requestId, "ack");
 		},
 		async loadExtension(options) {
 			const requestId = nextRequestId();
 			const resolved = await resolveNativeExtensionArtifact(options.artifact);
-			expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "load-ext",
 				requestId,
 				appId,
@@ -446,7 +452,8 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 				path: resolved.path,
 				expectedIdentity: resolved.expectedIdentity,
 				...options.mountId === void 0 ? {} : { mountId: options.mountId }
-			}), requestId, "ack");
+			});
+			expectResponse(response, requestId, "ack");
 		},
 		async commandExtension(ext, data) {
 			await this.requestExtension(ext, data);
@@ -474,12 +481,13 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 		},
 		async destroy() {
 			const requestId = nextRequestId();
-			expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "destroy-tray",
 				requestId,
 				appId,
 				trayId
-			}), requestId, "ack");
+			});
+			expectResponse(response, requestId, "ack");
 		}
 	};
 	if (!isOpenTrayEventSource(transport)) return handle;
@@ -517,6 +525,11 @@ const attachEventfulTrayHandle = (handle, source, appId, nextMountId) => {
 		onTrayDoubleClick(handler) {
 			return listen("trayDoubleClick", handler);
 		},
+		onAppReopenRequested(handler) {
+			return source.onEvent((frame) => {
+				if (frame.type === "app-event" && frame.event.type === "reopenRequested" && frame.event.appId === appId) handler(frame.event);
+			});
+		},
 		extend(extension, options) {
 			const context = createTrayExtensionContext(eventful, appId, extension, options, nextMountId);
 			const capability = extension.extend(eventful, context, options);
@@ -529,19 +542,21 @@ const isOwnedTrayEvent = (event, appId, trayId) => event.type !== "ready" && eve
 const isOpenTrayEventSource = (transport) => "onEvent" in transport && typeof transport.onEvent === "function";
 const resolveDefaultAppRef = async (transport, nextRequestId) => {
 	const requestId = nextRequestId();
-	return expectResponse(await transport.request({
+	const response = await transport.request({
 		type: "resolve-default-app",
 		requestId
-	}), requestId, "default-app").app;
+	});
+	return expectResponse(response, requestId, "default-app").app;
 };
 const createAppHandle = (transport, appId, nextRequestId) => {
 	const requestIdentity = async () => {
 		const requestId = nextRequestId();
-		return expectResponse(await transport.request({
+		const response = await transport.request({
 			type: "get-app-identity",
 			requestId,
 			appId
-		}), requestId, "app-identity").identity;
+		});
+		return expectResponse(response, requestId, "app-identity").identity;
 	};
 	return {
 		appId,
@@ -550,12 +565,13 @@ const createAppHandle = (transport, appId, nextRequestId) => {
 		},
 		async setName(name) {
 			const requestId = nextRequestId();
-			expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "set-app-name",
 				requestId,
 				appId,
 				name
-			}), requestId, "ack");
+			});
+			expectResponse(response, requestId, "ack");
 			return (await requestIdentity()).appName;
 		},
 		async getAppIcon() {
@@ -570,23 +586,25 @@ const createAppHandle = (transport, appId, nextRequestId) => {
 				if (identity.appIcon === void 0) selectAppIconVariant([], iconOrVariant);
 				else selectAppIconVariant(identity.appIcon, iconOrVariant);
 				const requestId = nextRequestId();
-				expectResponse(await transport.request({
+				const response = await transport.request({
 					type: "set-app-icon-variant",
 					requestId,
 					appId,
 					variant: iconOrVariant
-				}), requestId, "ack");
+				});
+				expectResponse(response, requestId, "ack");
 				return;
 			}
 			if (iconOrVariant !== null) await validateAppIcon(iconOrVariant);
 			const appIcon = iconOrVariant === null ? null : normalizeAppIcon(iconOrVariant);
 			const requestId = nextRequestId();
-			expectResponse(await transport.request({
+			const response = await transport.request({
 				type: "set-app-icon",
 				requestId,
 				appId,
 				appIcon
-			}), requestId, "ack");
+			});
+			expectResponse(response, requestId, "ack");
 		}
 	};
 };
@@ -655,6 +673,7 @@ const requestIdOf = (frame) => {
 		case "error": return frame.requestId;
 		case "ready":
 		case "event":
+		case "app-event":
 		case "ext-event": return;
 	}
 };
@@ -768,14 +787,16 @@ const resolveBrokerCommand = async (paths, options = {}) => {
 		if (platform !== "darwin") return commandForBinary(installed.binary, paths);
 		if (options.appBundle === void 0) return commandForBinary(installed.binary, paths);
 		if (installed.carrierTemplate === void 0) throw missingDarwinCarrierError(target, installed, arch);
-		return commandForBinary(await ensureDarwinBundle(options, paths, installed.binary, installed.carrierTemplate), paths);
+		const binary = await ensureDarwinBundle(options, paths, installed.binary, installed.carrierTemplate);
+		return commandForBinary(binary, paths);
 	}
 	const sourceDir = options.sourceDir ?? dirname(fileURLToPath(sourceUrl));
 	const workspaceRoot = await (options.findWorkspaceRoot ?? findWorkspaceRoot)(sourceDir);
 	if (workspaceRoot !== void 0) {
 		const binary = await (options.ensureDevBrokerBinary ?? ensureDevBrokerBinary)(workspaceRoot, paths, platform);
 		if (platform !== "darwin") return commandForBinary(binary, paths);
-		return commandForBinary(options.appBundle === void 0 ? binary : await ensureDarwinBundle(options, paths, binary, await (options.ensureDevDarwinCarrierTemplate ?? ensureDevDarwinCarrierTemplate)(workspaceRoot, paths)), paths);
+		const carrierBinary = options.appBundle === void 0 ? binary : await ensureDarwinBundle(options, paths, binary, await (options.ensureDevDarwinCarrierTemplate ?? ensureDevDarwinCarrierTemplate)(workspaceRoot, paths));
+		return commandForBinary(carrierBinary, 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,
@@ -928,7 +949,10 @@ function isNodeError$1(error) {
 //#endregion
 //#region src/daemon/lifecycle.ts
 const DAEMON_STDIO_ENV = "OPENTRAY_DAEMON_STDIO";
-const DEFAULT_DAEMON_LOCK_TIMEOUT_MS = 5e3;
+const DAEMON_POLL_INTERVAL_MS = 50;
+const DEFAULT_DAEMON_READY_TIMEOUT_MS = 1e4;
+const DEFAULT_DAEMON_LOCK_TIMEOUT_MS = 15e3;
+const ABANDONED_RECLAIM_CLAIM_MS = 1e3;
 const createNodeDaemonDriver = (cliEntrypoint, options = {}) => ({
 	async resolveBroker(paths) {
 		return resolveBrokerArtifact(paths, {
@@ -941,19 +965,71 @@ const createNodeDaemonDriver = (cliEntrypoint, options = {}) => ({
 		return isProcessAlive(pid);
 	},
 	async spawnBroker(paths, broker) {
-		const child = spawn(broker.command, broker.args, {
-			cwd: broker.cwd,
-			detached: true,
-			env: {
-				...process.env,
-				OPENTRAY_DAEMON_HOME: paths.homeDir,
-				OPENTRAY_DAEMON_PACKAGE_VERSION: paths.packageVersion,
-				OPENTRAY_DAEMON_CLI_ENTRYPOINT: cliEntrypoint,
-				OPENTRAY_DAEMON_APP_ID: paths.appId,
-				OPENTRAY_DAEMON_APP_NAME: paths.appName,
-				OPENTRAY_DAEMON_CALLER_LABEL: paths.callerLabel
-			},
-			stdio: resolveBrokerStdio(process.env[DAEMON_STDIO_ENV])
+		const env = options.env ?? process.env;
+		const stdio = resolveBrokerStdio(env[DAEMON_STDIO_ENV]);
+		if (stdio === "log") await mkdir(paths.runtimeDir, { recursive: true });
+		const logHandle = stdio === "log" ? await open(paths.brokerLog, "a") : void 0;
+		if (logHandle !== void 0) await logHandle.appendFile(`${JSON.stringify({
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			event: "broker-spawn",
+			command: broker.command,
+			cwd: broker.cwd ?? process.cwd(),
+			appId: paths.appId,
+			appName: paths.appName
+		})}\n`, "utf8");
+		if (isAbsolute(broker.command)) try {
+			await access(broker.command, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+		} catch (error) {
+			if (stdio === "log") await appendFile(paths.brokerLog, `${JSON.stringify({
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				event: "broker-spawn-error",
+				command: broker.command,
+				error: error instanceof Error ? error.message : String(error)
+			})}\n`, "utf8").catch(() => void 0);
+			await logHandle?.close();
+			return 0;
+		}
+		let child;
+		try {
+			child = spawn(broker.command, broker.args, {
+				cwd: broker.cwd,
+				detached: true,
+				env: {
+					...env,
+					OPENTRAY_DAEMON_HOME: paths.homeDir,
+					OPENTRAY_DAEMON_PACKAGE_VERSION: paths.packageVersion,
+					OPENTRAY_DAEMON_CLI_ENTRYPOINT: cliEntrypoint,
+					OPENTRAY_DAEMON_APP_ID: paths.appId,
+					OPENTRAY_DAEMON_APP_NAME: paths.appName,
+					OPENTRAY_DAEMON_CALLER_LABEL: paths.callerLabel
+				},
+				stdio: logHandle === void 0 ? stdio === "log" ? "ignore" : stdio : [
+					"ignore",
+					logHandle.fd,
+					logHandle.fd
+				]
+			});
+		} finally {
+			await logHandle?.close();
+		}
+		child.on("error", (error) => {
+			if (stdio !== "log") return;
+			appendFile(paths.brokerLog, `${JSON.stringify({
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				event: "broker-spawn-error",
+				command: broker.command,
+				error: error.message
+			})}\n`, "utf8").catch(() => void 0);
+		});
+		child.once("exit", (code, signal) => {
+			if (stdio !== "log") return;
+			appendFile(paths.brokerLog, `${JSON.stringify({
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				event: "broker-exit",
+				command: broker.command,
+				code,
+				signal
+			})}\n`, "utf8").catch(() => void 0);
 		});
 		child.unref();
 		const pid = child.pid ?? 0;
@@ -966,11 +1042,13 @@ const createNodeDaemonDriver = (cliEntrypoint, options = {}) => ({
 	}
 });
 const resolveBrokerStdio = (value) => {
-	return value === "inherit" ? "inherit" : "ignore";
+	if (value === "inherit") return "inherit";
+	if (value === "ignore") return "ignore";
+	return "log";
 };
-const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_TIMEOUT_MS }) => {
+const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_TIMEOUT_MS, readinessTimeoutMs = DEFAULT_DAEMON_READY_TIMEOUT_MS }) => {
 	await mkdir(paths.runtimeDir, { recursive: true });
-	const lock = await acquireLock(paths.lockFile, lockTimeoutMs);
+	const lock = await acquireDaemonLock(paths.lockFile, lockTimeoutMs);
 	try {
 		const existingPid = await readPid(paths.pidFile);
 		let existingAlive = existingPid !== void 0 && await driver.isAlive(existingPid);
@@ -986,7 +1064,8 @@ const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_
 			} else throw error;
 		}
 		if (existingPid !== void 0 && existingAlive) {
-			if (readyMatchesBroker(await readReadyMetadata(paths.readyFile), paths, existingPid, broker)) return {
+			const ready = await readReadyMetadata(paths.readyFile);
+			if (readyMatchesBroker(ready, paths, existingPid, broker)) return {
 				status: "already-running",
 				pid: existingPid,
 				paths,
@@ -1000,7 +1079,7 @@ const startDaemon = async ({ paths, driver, lockTimeoutMs = DEFAULT_DAEMON_LOCK_
 		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");
 		try {
-			await waitForReadyFile(paths, driver, pid, broker);
+			await waitForReadyFile(paths, driver, pid, broker, readinessTimeoutMs);
 		} catch (error) {
 			if (await driver.isAlive(pid)) {
 				await driver.stop(pid);
@@ -1037,19 +1116,22 @@ const cleanupRuntimeFiles = async (paths) => {
 const waitUntilStopped = async (driver, pid) => {
 	for (let attempt = 0; attempt < 20; attempt += 1) {
 		if (!await driver.isAlive(pid)) return true;
-		await sleep(50);
+		await sleep(DAEMON_POLL_INTERVAL_MS);
 	}
 	return false;
 };
-const waitForReadyFile = async (paths, driver, pid, broker) => {
-	for (let attempt = 0; attempt < 40; attempt += 1) {
+const waitForReadyFile = async (paths, driver, pid, broker, timeoutMs) => {
+	const deadline = Date.now() + timeoutMs;
+	while (true) {
 		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);
+		if (!await driver.isAlive(pid)) throw new Error(`daemon broker exited before readiness: pid=${pid}; readyFile=${paths.readyFile}; brokerLog=${paths.brokerLog}; set ${DAEMON_STDIO_ENV}=inherit to mirror broker stderr`);
+		const remainingMs = deadline - Date.now();
+		if (remainingMs <= 0) break;
+		await sleep(Math.min(DAEMON_POLL_INTERVAL_MS, remainingMs));
 	}
-	throw new Error(`timed out waiting for daemon readiness: ${paths.readyFile}`);
+	throw new Error(`timed out waiting for daemon readiness after ${timeoutMs}ms: pid=${pid}; readyFile=${paths.readyFile}; brokerLog=${paths.brokerLog}; set ${DAEMON_STDIO_ENV}=inherit to mirror broker stderr`);
 };
 const readReadyMetadata = async (readyFile) => {
 	let value;
@@ -1080,19 +1162,25 @@ const executablePathsEqual = (left, right, platform = process.platform) => {
 	const normalize = (value) => value.replaceAll("\\", "/").replace(/^\/\/?\?\//u, "").toLowerCase();
 	return normalize(left) === normalize(right);
 };
-const acquireLock = async (lockFile, timeoutMs) => {
+const acquireDaemonLock = async (lockFile, timeoutMs) => {
 	const deadline = Date.now() + timeoutMs;
+	const owner = `${JSON.stringify({
+		pid: process.pid,
+		token: randomUUID()
+	})}\n`;
 	while (Date.now() <= deadline) try {
 		const handle = await open(lockFile, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
-		await handle.writeFile(`${process.pid}\n`, "utf8");
+		await handle.writeFile(owner, "utf8");
 		return { async release() {
 			await handle.close();
+			if (await readLockSource(lockFile) !== owner) return;
 			await unlink(lockFile).catch((error) => {
 				if (!isNodeError(error) || error.code !== "ENOENT") throw error;
 			});
 		} };
 	} catch (error) {
 		if (isNodeError(error) && error.code === "EEXIST") {
+			if (await reclaimDeadLockOwner(lockFile)) continue;
 			await sleep(25);
 			continue;
 		}
@@ -1100,12 +1188,72 @@ const acquireLock = async (lockFile, timeoutMs) => {
 	}
 	throw new Error(`timed out acquiring daemon lock: ${lockFile}`);
 };
+const reclaimDeadLockOwner = async (lockFile) => {
+	const observed = await readLockSource(lockFile);
+	if (observed === void 0) return true;
+	const owner = parseLockOwner(observed);
+	if (owner === void 0 || isProcessAlive(owner.pid)) return false;
+	const claimFile = `${lockFile}.reclaim-${createHash("sha256").update(observed).digest("hex").slice(0, 16)}`;
+	try {
+		await link(lockFile, claimFile);
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return true;
+		if (isNodeError(error) && error.code === "EEXIST") {
+			await clearAbandonedReclaimClaim(claimFile);
+			return false;
+		}
+		throw error;
+	}
+	try {
+		if (await readLockSource(lockFile) !== observed || isProcessAlive(owner.pid)) return false;
+		try {
+			await unlink(lockFile);
+			return true;
+		} catch (error) {
+			if (isNodeError(error) && error.code === "ENOENT") return true;
+			throw error;
+		}
+	} finally {
+		await unlink(claimFile).catch((error) => {
+			if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+		});
+	}
+};
+const clearAbandonedReclaimClaim = async (claimFile) => {
+	try {
+		const claim = await stat(claimFile);
+		if (Date.now() - claim.ctimeMs < ABANDONED_RECLAIM_CLAIM_MS) return;
+		await unlink(claimFile);
+	} catch (error) {
+		if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+	}
+};
+const readLockSource = async (lockFile) => {
+	try {
+		return await readFile(lockFile, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return void 0;
+		throw error;
+	}
+};
+const parseLockOwner = (source) => {
+	const legacyPid = Number(source.trim());
+	if (Number.isInteger(legacyPid) && legacyPid > 0) return { pid: legacyPid };
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		return;
+	}
+	if (!isRecord(value) || typeof value.pid !== "number" || !Number.isInteger(value.pid) || value.pid <= 0 || typeof value.token !== "string" || value.token.length === 0) return;
+	return { pid: value.pid };
+};
 const isProcessAlive = (pid) => {
 	try {
 		process.kill(pid, 0);
 		return true;
-	} catch {
-		return false;
+	} catch (error) {
+		return !(isNodeError(error) && error.code === "ESRCH");
 	}
 };
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -1144,7 +1292,8 @@ const resolveDaemonPaths = ({ homeDir, packageVersion, callerLabel, appId, appNa
 		endpoint,
 		pidFile: `${runtimeDir}/broker.pid`,
 		lockFile: `${runtimeDir}/broker.lock`,
-		readyFile: `${runtimeDir}/ready.json`
+		readyFile: `${runtimeDir}/ready.json`,
+		brokerLog: `${runtimeDir}/broker.log`
 	};
 };
 const normalizeAppIdentityField$1 = (value, fallback) => {
@@ -1188,12 +1337,37 @@ const connectLocalBroker = async (options = {}) => {
 	const connection = new LocalBrokerConnection(await connectSocket(endpoint), endpoint, callerLabel);
 	try {
 		await connection.init(clientVersion, options.protocolVersion ?? PROTOCOL_VERSION$1, expectedBrokerArtifactIdentity);
+		if (appBundle !== void 0 && options.appLaunch !== void 0) {
+			await updateDarwinAppLaunchDescriptor(appBundle.path, options.appLaunch);
+			const convergence = await convergeDarwinAppBundleIdentity({
+				currentBundlePath: appBundle.path,
+				appId: paths.appId,
+				managedAppsRoot: resolve(paths.homeDir, ".opentray/apps"),
+				legacyRuntimeRoot: resolve(paths.homeDir, ".opentray"),
+				legacyBundlePaths: [resolve(paths.runtimeDir, "darwin-carrier/OpenTray.app")]
+			});
+			await appendBrokerDiagnostic(paths.brokerLog, {
+				event: "bundle-identity-convergence",
+				removed: convergence.removed,
+				skippedLiveOwner: convergence.skippedLiveOwner,
+				failedUnregister: convergence.failedUnregister
+			});
+		}
 	} catch (error) {
 		await connection.close();
 		throw error;
 	}
 	return connection;
 };
+const appendBrokerDiagnostic = async (path, value) => {
+	try {
+		await mkdir(dirname(path), { recursive: true });
+		await appendFile(path, `${JSON.stringify({
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			...value
+		})}\n`, "utf8");
+	} catch {}
+};
 const resolveDarwinAppBundleOptions = (configured, paths, packageIdentity) => {
 	if (packageIdentity === void 0) throw new Error("Darwin app bundle resolution requires the caller package identity");
 	const configuredPath = configured?.path;
@@ -1320,7 +1494,7 @@ var LocalBrokerConnection = class {
 			this.pending.delete(requestId);
 			return;
 		}
-		if (frame.type === "event" || frame.type === "ext-event") for (const listener of this.listeners) listener(frame);
+		if (frame.type === "event" || frame.type === "app-event" || frame.type === "ext-event") for (const listener of this.listeners) listener(frame);
 	}
 	write(frame) {
 		this.socket.write(`${JSON.stringify(frame)}\n`);
@@ -1352,6 +1526,7 @@ const responseRequestId = (frame) => {
 		case "runtime-host-health": return frame.requestId;
 		case "ready":
 		case "event":
+		case "app-event":
 		case "ext-event":
 		case "error": return;
 	}
@@ -1479,14 +1654,48 @@ const registerClickId = (state, id) => {
 	state.seenClickIds = seen;
 };
 //#endregion
+//#region src/app-launch.ts
+const normalizeAppLaunch = (configured, context = {}) => {
+	const currentCwd = context.cwd ?? process.cwd();
+	if (configured === void 0 || configured === null) return {
+		schemaVersion: 1,
+		command: validateRequiredText(context.execPath ?? process.execPath, "process.execPath"),
+		args: [...(context.argv ?? process.argv).slice(1)].map((arg, index) => validateArg(arg, `process.argv[${index + 1}]`)),
+		cwd: validateRequiredText(currentCwd, "process.cwd()")
+	};
+	const command = validateRequiredText(configured.command, "appLaunch.command");
+	const cwd = resolve(currentCwd, configured.cwd === void 0 ? currentCwd : validateRequiredText(configured.cwd, "appLaunch.cwd"));
+	const args = [...configured.args ?? []].map((arg, index) => validateArg(arg, `appLaunch.args[${index}]`));
+	return {
+		schemaVersion: 1,
+		command: resolvePathLikeCommand(command, currentCwd),
+		args,
+		cwd
+	};
+};
+const resolvePathLikeCommand = (command, cwd) => {
+	if (isAbsolute(command) || command.includes("/") || command.includes("\\")) return resolve(cwd, command);
+	return command;
+};
+const validateRequiredText = (value, field) => {
+	if (value.trim().length === 0 || value.includes("\0")) throw new Error(`${field} must be a non-empty string without NUL`);
+	return value;
+};
+const validateArg = (value, field) => {
+	if (value.includes("\0")) throw new Error(`${field} must be a string without NUL`);
+	return value;
+};
+//#endregion
 //#region src/sdk.ts
 const createTray = async (options, runtimeOptions = {}) => {
 	if (runtimeOptions.appIcon !== void 0) await validateAppIcon(runtimeOptions.appIcon);
 	const appIcon = runtimeOptions.appIcon === void 0 ? void 0 : normalizeAppIcon(runtimeOptions.appIcon);
 	const normalized = normalizeCreateTrayOptions(options);
+	const appLaunch = normalizeAppLaunch(runtimeOptions.appLaunch);
 	const connection = await connectLocalBroker({
 		...runtimeOptions,
-		...appIcon === void 0 ? {} : { appIcon }
+		...appIcon === void 0 ? {} : { appIcon },
+		appLaunch
 	});
 	try {
 		const tray = await createClient(connection, { appOptions: {
@@ -1532,7 +1741,8 @@ const wrapCreateTrayHandle = (tray, state) => {
 			state.menuUnsubscribe = bindMenuClickHandlers(tray, normalized.handlers);
 		},
 		extend(extension, options) {
-			return wrapCreateTrayHandle(tray.extend(extension, options), state);
+			const extended = tray.extend(extension, options);
+			return wrapCreateTrayHandle(extended, state);
 		},
 		async destroy() {
 			state.destroyPromise ??= (async () => {