opentray 0.17.0 → 0.18.0

package/README.md

@@ -123,6 +123,11 @@ const tray = await createTray(options, {
   appId: "com.example.first-app",
   appName: "First App",
   appIcon,
+  appLaunch: {
+    command: process.execPath,
+    args: ["./dist/main.mjs", "--desktop"],
+    cwd: process.cwd(),
+  },
   appBundle: {
     // Relative paths resolve from the caller package root.
     path: "dist/First App.app",
@@ -132,9 +137,47 @@ const tray = await createTray(options, {
 });
 ```
 
+`appLaunch` is optional. When omitted or `null`, OpenTray snapshots
+`process.execPath`, `process.argv.slice(1)`, and `process.cwd()` after the local
+runtime handshake succeeds. Opening the stable macOS bundle later launches that
+latest vector directly, without a shell. Explicit commands may name an
+executable or script launcher and may provide `args`/`cwd`; OpenTray never stores
+the full process environment in the bundle.
+
 `appBundle.reinitialize` defaults to `true`. A prebuilt bundle must contain the
 matching broker, `Info.plist`, target, icon, and OpenTray manifest; incompatible
-bundles fail with a typed error instead of being silently rebuilt.
+bundles fail with a typed error instead of being silently rebuilt. In prebuilt
+mode those assets remain read-only, while the runtime-owned
+`Contents/Resources/opentray-launch.json` descriptor is still atomically updated
+after a successful handshake.
+
+Cold launch is currently a Darwin carrier capability. A live retained session
+does not execute this descriptor: the broker emits an app-scoped
+`reopenRequested` event instead. `@opentray/ext-webview` consumes that intent by
+revealing and focusing the most recently active retained `appMode` window.
+Ordinary Windows/Linux taskbar entries are not claimed as persistent post-exit
+launchers.
+
+Development callers must describe the command that owns the complete process
+tree. For a pnpm/Vite app, persist `process.execPath` with the absolute
+`npm_execpath` and directly address the Vite-owning workspace, for example
+`[npm_execpath, "--dir", absoluteWebuiDir, "dev"]`, plus the repository-root
+`cwd`. Every transitive command must resolve from the package graph or be
+absolute. Persisting only a daemon child, a shell string, or a script that later
+invokes bare `pnpm` cannot reliably restore Vite, its proxy, and the final
+WebView URL from Finder's minimal environment.
+
+### Runtime diagnostics
+
+Detached brokers append stdout and stderr to the caller-scoped
+`<home>/.opentray/<package-version>/<caller-label>/runtime/broker.log` by default.
+Set `OPENTRAY_DAEMON_STDIO=inherit` for an interactive terminal or
+`OPENTRAY_DAEMON_STDIO=ignore` when silence is deliberate. Broker readiness uses
+a bounded native cold-start budget while continuing to validate process liveness
+and exact artifact identity; early-exit and timeout errors include the broker log
+path. When a Darwin app carrier is opened without the private `broker` arguments, its
+`Contents/Resources/opentray-launch.log` records descriptor parsing, spawn PID or
+error, and the relaunched consumer's stdout/stderr.
 
 ## Runtime Ownership
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AppIcon, AppIcon as AppIcon$1, AppIconAsset, AppIconSource, AppIconVariant, AppIconVariantOf, AppId, AppIdentity, AppOptions, AppRef, BrokerEndpointIdentity, BrokerEndpointIdentityOptions, ClientFrame, ClientFrame as ClientFrame$1, ClientRequestFrame, ClientRequestFrame as ClientRequestFrame$1, DarwinIcon, DarwinIconText, ExpectedExtensionIdentity, ExtensionEnvelope, ExtensionEnvelope as ExtensionEnvelope$1, Icon, Icon as Icon$1, Icon as TrayIcon, IconCandidates, IconImage, IconText, LinuxIcon, Menu, Menu as Menu$1, MenuItem, MenuItemId, MenuItemId as MenuItemId$1, MouseButton, PROTOCOL_VERSION, Rect, RequestId, ServerFrame, ServerFrame as ServerFrame$1, SimpleIcon, Tooltip, Tooltip as Tooltip$1, Tooltip as TrayTooltip, TrayBoundsKind, TrayBoundsResult, TrayBoundsResult as TrayBoundsResult$1, TrayEvent, TrayEvent as TrayEvent$1, TrayId, TrayId as TrayId$1, TrayOptions, TrayOptions as TrayOptions$1, Win32Icon, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion } from "@opentray/spec";
-import { OpenTrayAppBundleOptions, OpenTrayAppBundleOptions as OpenTrayAppBundleOptions$1 } from "@opentray/packaging";
+import { AppEvent, AppEvent as AppEvent$1, AppIcon, AppIcon as AppIcon$1, AppIconAsset, AppIconSource, AppIconVariant, AppIconVariantOf, AppId, AppIdentity, AppOptions, AppRef, BrokerEndpointIdentity, BrokerEndpointIdentityOptions, ClientFrame, ClientFrame as ClientFrame$1, ClientRequestFrame, ClientRequestFrame as ClientRequestFrame$1, DarwinIcon, DarwinIconText, ExpectedExtensionIdentity, ExtensionEnvelope, ExtensionEnvelope as ExtensionEnvelope$1, Icon, Icon as Icon$1, Icon as TrayIcon, IconCandidates, IconImage, IconText, LinuxIcon, Menu, Menu as Menu$1, MenuItem, MenuItemId, MenuItemId as MenuItemId$1, MouseButton, PROTOCOL_VERSION, Rect, RequestId, ServerFrame, ServerFrame as ServerFrame$1, SimpleIcon, Tooltip, Tooltip as Tooltip$1, Tooltip as TrayTooltip, TrayBoundsKind, TrayBoundsResult, TrayBoundsResult as TrayBoundsResult$1, TrayEvent, TrayEvent as TrayEvent$1, TrayId, TrayId as TrayId$1, TrayOptions, TrayOptions as TrayOptions$1, Win32Icon, createBrokerEndpointIdentity, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion } from "@opentray/spec";
+import { OpenTrayAppBundleOptions, OpenTrayAppBundleOptions as OpenTrayAppBundleOptions$1, OpenTrayAppLaunchOptions, OpenTrayAppLaunchOptions as OpenTrayAppLaunchOptions$1 } from "@opentray/packaging";
 
 //#region src/native-extension-artifact.d.ts
 type NativeExtensionArch = "arm64" | "x64";
@@ -54,7 +54,7 @@ interface OpenTrayTransport {
   request(frame: ClientRequestFrame$1): Promise<ServerFrame$1>;
 }
 type OpenTrayEventFrame = Extract<ServerFrame$1, {
-  type: "event" | "ext-event";
+  type: "event" | "app-event" | "ext-event";
 }>;
 interface OpenTrayEventSource {
   onEvent(listener: (frame: OpenTrayEventFrame) => void): () => void;
@@ -101,6 +101,9 @@ interface EventfulTrayHandle extends TrayHandle {
   onMenuClick(handler: (event: TrayEventByType<"menuClick">) => void): () => void;
   onTrayClick(handler: (event: TrayEventByType<"trayClick">) => void): () => void;
   onTrayDoubleClick(handler: (event: TrayEventByType<"trayDoubleClick">) => void): () => void;
+  onAppReopenRequested(handler: (event: Extract<AppEvent$1, {
+    type: "reopenRequested";
+  }>) => void): () => void;
 }
 interface ExtensionLoadOptions {
   name: string;
@@ -196,6 +199,8 @@ interface OpenTrayRuntimeOptions {
   appName?: string;
   appIcon?: AppIcon$1;
   appBundle?: OpenTrayAppBundleOptions$1;
+  /** Stable app-entry launch vector. Omitted/null snapshots the current invocation. */
+  appLaunch?: OpenTrayAppLaunchOptions$1 | null;
   autoStart?: boolean;
 }
 /** App-facing tray options accepted by top-level createTray. */
@@ -228,5 +233,5 @@ declare class AppIconVariantNotFoundError extends Error {
 /** Validate an explicit AppIcon, including native file signatures, before broker startup. */
 declare const validateAppIcon: (icon: unknown, platform?: NodeJS.Platform) => Promise<void>;
 //#endregion
-export { type AppHandle, type AppIcon, type AppIconAsset, type AppIconSource, type AppIconVariant, AppIconVariantNotFoundError, type AppIconVariantOf, type AppId, type AppIdentity, type AppOptions, type AppRef, type BrokerEndpointIdentity, type BrokerEndpointIdentityOptions, type ClientFrame, type ClientRequestFrame, type CreateClientOptions, type CreateTrayCheckItem, type CreateTrayHandle, type CreateTrayItem, type CreateTrayMenu, type CreateTrayMenu as TrayMenu, type CreateTrayMenuClickHandler, type CreateTrayMenuItem, type CreateTrayOptions, type CreateTrayRadioItem, type CreateTraySeparatorItem, type CreateTraySubmenuItem, DEFAULT_APP_ICON_VARIANT, type DarwinIcon, type DarwinIconText, type EventfulTrayHandle, type ExtensionEnvelope, type ExtensionLoadOptions, type Icon, type IconCandidates, type IconImage, type IconText, InvalidAppIconError, type LinuxIcon, type Menu, type MenuItem, type MenuItemId, type MouseButton, type NativeExtensionArch, type NativeExtensionArtifact, NativeExtensionArtifactResolutionError, type NativeExtensionExpectedIdentity, type NativeExtensionFileArtifact, type NativeExtensionIdentitySource, type NativeExtensionPackageArtifact, type NativeExtensionPackageTarget, type NativeExtensionTarget, type OpenTrayAppBundleOptions, type OpenTrayClient, type OpenTrayConnection, type OpenTrayEventFrame, type OpenTrayEventSource, type OpenTrayRuntimeOptions, type OpenTrayTransport, PROTOCOL_VERSION, type Rect, type ResolvedNativeExtensionArtifact, type ServerFrame, type SimpleIcon, type Tooltip, type TrayBoundsKind, type TrayBoundsResult, type TrayEvent, type TrayEventByType, type TrayEventType, type TrayExtension, type TrayExtensionContext, type TrayExtensionMountSpec, type TrayHandle, type TrayIcon, type TrayId, type TrayOptions, type TrayTooltip, type Win32Icon, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveNativeExtensionArtifact, validateAppIcon };
+export { type AppEvent, type AppHandle, type AppIcon, type AppIconAsset, type AppIconSource, type AppIconVariant, AppIconVariantNotFoundError, type AppIconVariantOf, type AppId, type AppIdentity, type AppOptions, type AppRef, type BrokerEndpointIdentity, type BrokerEndpointIdentityOptions, type ClientFrame, type ClientRequestFrame, type CreateClientOptions, type CreateTrayCheckItem, type CreateTrayHandle, type CreateTrayItem, type CreateTrayMenu, type CreateTrayMenu as TrayMenu, type CreateTrayMenuClickHandler, type CreateTrayMenuItem, type CreateTrayOptions, type CreateTrayRadioItem, type CreateTraySeparatorItem, type CreateTraySubmenuItem, DEFAULT_APP_ICON_VARIANT, type DarwinIcon, type DarwinIconText, type EventfulTrayHandle, type ExtensionEnvelope, type ExtensionLoadOptions, type Icon, type IconCandidates, type IconImage, type IconText, InvalidAppIconError, type LinuxIcon, type Menu, type MenuItem, type MenuItemId, type MouseButton, type NativeExtensionArch, type NativeExtensionArtifact, NativeExtensionArtifactResolutionError, type NativeExtensionExpectedIdentity, type NativeExtensionFileArtifact, type NativeExtensionIdentitySource, type NativeExtensionPackageArtifact, type NativeExtensionPackageTarget, type NativeExtensionTarget, type OpenTrayAppBundleOptions, type OpenTrayAppLaunchOptions, type OpenTrayClient, type OpenTrayConnection, type OpenTrayEventFrame, type OpenTrayEventSource, type OpenTrayRuntimeOptions, type OpenTrayTransport, PROTOCOL_VERSION, type Rect, type ResolvedNativeExtensionArtifact, type ServerFrame, type SimpleIcon, type Tooltip, type TrayBoundsKind, type TrayBoundsResult, type TrayEvent, type TrayEventByType, type TrayEventType, type TrayExtension, type TrayExtensionContext, type TrayExtensionMountSpec, type TrayHandle, type TrayIcon, type TrayId, type TrayOptions, type TrayTooltip, type Win32Icon, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveNativeExtensionArtifact, validateAppIcon };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/native-extension-artifact.ts","../src/client.ts","../src/menu-input.ts","../src/sdk.ts","../src/app-icon.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/native-extension-artifact.ts","../src/client.ts","../src/menu-input.ts","../src/sdk.ts","../src/app-icon.ts"],"mappings":"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"}

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}$/;
@@ -517,6 +517,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);
@@ -655,6 +660,7 @@ const requestIdOf = (frame) => {
 		case "error": return frame.requestId;
 		case "ready":
 		case "event":
+		case "app-event":
 		case "ext-event": return;
 	}
 };
@@ -928,7 +934,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 +950,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 +1027,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);
@@ -1000,7 +1063,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 +1100,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 +1146,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 +1172,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 +1276,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 +1321,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 +1478,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 +1510,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 +1638,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: {