opentray 0.32.0 → 0.33.1

package/dist/index.mjs

@@ -484,6 +484,37 @@ const resolveAccessibleLibrary = async (path, target, packageName) => {
 //#endregion
 //#region src/client.ts
 /**
+* Default per-call deadline classes (W1, harden-transport-robustness;
+* field-validated against the pnpm-pub silent-wedge incident): interactive
+* calls settle or reject within 5 s, teardown-class frames within 2 s, and
+* bootstrap-class round-trips (connection init and first bring-up) within
+* 10 s. They live beside `OpenTrayTransport` because they are part of the
+* generic transport call contract, not of one broker implementation.
+*/
+const INTERACTIVE_CALL_DEADLINE_MS = 5e3;
+const TEARDOWN_CALL_DEADLINE_MS = 2e3;
+const BOOTSTRAP_CALL_DEADLINE_MS = 1e4;
+/**
+* Typed per-call deadline rejection: the transport's budget for one
+* round-trip expired without a correlated reply. This is the third
+* rejection class, distinct from transport-lost (the plain
+* `BROKER_CONNECTION_CLOSED_MESSAGE` sentinel family, or the typed
+* `extension_transport_closed` for accepted deferred operations) and from
+* broker-rejected (`BrokerServerError` / `ExtensionOperationError`). An
+* expiry settles exactly one call; it never declares the transport dead —
+* death stays a socket-close/error (and, later, heartbeat) verdict.
+*/
+var TransportTimeoutError = class extends Error {
+	requestId;
+	deadlineMs;
+	constructor(requestId, deadlineMs) {
+		super(`transport call deadline expired after ${deadlineMs}ms: ${requestId}`);
+		this.name = "TransportTimeoutError";
+		this.requestId = requestId;
+		this.deadlineMs = deadlineMs;
+	}
+};
+/**
 * Typed rejection for synchronous broker error frames: carries the wire
 * `code`, the structured `details` payload when the error family freezes one,
 * and the transport cause when relevant. Consumers match on `code`; the human
@@ -606,10 +637,10 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 			});
 			expectResponse(response, requestId, "ack");
 		},
-		async commandExtension(ext, data) {
-			await this.requestExtension(ext, data);
+		async commandExtension(ext, data, callOptions) {
+			await this.requestExtension(ext, data, callOptions);
 		},
-		async requestExtension(ext, data) {
+		async requestExtension(ext, data, callOptions) {
 			const requestId = nextRequestId();
 			const response = await transport.request({
 				type: "ext-command",
@@ -618,7 +649,7 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 				trayId,
 				ext,
 				data
-			});
+			}, callOptions);
 			if (response.type === "ack") {
 				expectResponse(response, requestId, "ack");
 				return {
@@ -652,7 +683,7 @@ function createTrayHandle(transport, appId, trayId, nextRequestId = createReques
 				requestId,
 				appId,
 				trayId
-			});
+			}, { deadlineMs: TEARDOWN_CALL_DEADLINE_MS });
 			expectResponse(response, requestId, "ack");
 		}
 	};
@@ -665,10 +696,15 @@ const attachEventfulTrayHandle = (handle, source, appId, nextMountId, sessionId)
 		if (!isOwnedTrayEvent(frame.event, appId, handle.trayId)) return;
 		handler(frame.event);
 	});
-	const onConnectionDead = isConnectionDeadSource(source) ? (handler) => source.onConnectionDead(handler) : void 0;
+	const onConnectionDead = isConnectionDeadSource$1(source) ? (handler) => source.onConnectionDead(handler) : void 0;
+	const transportSupervision = isTransportSupervisionSource(source) ? {
+		onTransportStateChange: (handler) => source.onTransportStateChange(handler),
+		registerTransportRebuild: (rebuild) => source.registerTransportRebuild(rebuild)
+	} : void 0;
 	const eventful = {
 		...handle,
 		...onConnectionDead === void 0 ? {} : { onConnectionDead },
+		...transportSupervision === void 0 ? {} : transportSupervision,
 		listenExtension(ext, handler) {
 			return source.onEvent((frame) => {
 				if (frame.type !== "ext-event" || frame.ext !== ext) return;
@@ -708,7 +744,8 @@ const attachEventfulTrayHandle = (handle, source, appId, nextMountId, sessionId)
 };
 const isOwnedTrayEvent = (event, appId, trayId) => event.type !== "ready" && event.appId === appId && event.trayId === trayId;
 const isOpenTrayEventSource = (transport) => "onEvent" in transport && typeof transport.onEvent === "function";
-const isConnectionDeadSource = (transport) => "onConnectionDead" in transport && typeof transport.onConnectionDead === "function";
+const isConnectionDeadSource$1 = (transport) => "onConnectionDead" in transport && typeof transport.onConnectionDead === "function";
+const isTransportSupervisionSource = (transport) => "onTransportStateChange" in transport && typeof transport.onTransportStateChange === "function" && "registerTransportRebuild" in transport && typeof transport.registerTransportRebuild === "function";
 const resolveDefaultAppRef = async (transport, nextRequestId) => {
 	const requestId = nextRequestId();
 	const response = await transport.request({
@@ -802,13 +839,13 @@ const createTrayExtensionContext = (tray, appId, extension, options, nextMountId
 		artifact,
 		mountId,
 		ensureLoaded,
-		async command(data) {
+		async command(data, callOptions) {
 			await ensureLoaded();
-			await tray.commandExtension(mountId, data);
+			await tray.commandExtension(mountId, data, callOptions);
 		},
-		async request(data) {
+		async request(data, callOptions) {
 			await ensureLoaded();
-			return tray.requestExtension(mountId, data);
+			return tray.requestExtension(mountId, data, callOptions);
 		}
 	};
 };
@@ -1559,6 +1596,12 @@ var ExtensionOperationError = class extends Error {
 };
 const extensionTransportClosedError = (cause) => new ExtensionOperationError(EXTENSION_TRANSPORT_CLOSED_CODE, "the broker transport closed while a deferred extension operation was pending", { cause });
 /**
+* Correlation label the bootstrap deadline reports under: the init frame
+* carries no requestId on the wire, so the typed timeout names the call class
+* itself.
+*/
+const INIT_REQUEST_ID = "init";
+/**
 * Typed handshake rejection for a Ready frame whose protocol version does not
 * equal the version this client sent in its Init frame: a structurally valid
 * Ready frame alone must never accept the session (add-ext-dialog batch A
@@ -1669,6 +1712,7 @@ var LocalBrokerConnection = class {
 	/** operationId -> requestId of accepted-but-unsettled deferred operations. */
 	deferredOperations = /* @__PURE__ */ new Map();
 	deadListeners = /* @__PURE__ */ new Set();
+	deadlineExpiryListeners = /* @__PURE__ */ new Set();
 	deadError;
 	ready;
 	constructor(socket, endpoint, callerLabel) {
@@ -1695,6 +1739,12 @@ var LocalBrokerConnection = class {
 			this.deadListeners.delete(listener);
 		};
 	}
+	onDeadlineExpiry(listener) {
+		this.deadlineExpiryListeners.add(listener);
+		return () => {
+			this.deadlineExpiryListeners.delete(listener);
+		};
+	}
 	async init(clientVersion, protocolVersion, expectedBrokerArtifactIdentity) {
 		const ready = new Promise((resolve, reject) => {
 			this.ready = {
@@ -1707,18 +1757,24 @@ var LocalBrokerConnection = class {
 			protocolVersion,
 			clientVersion
 		});
-		const frame = await ready;
+		const frame = await this.raceBootstrapDeadline(ready);
 		if (frame.protocolVersion !== protocolVersion) throw new BrokerProtocolVersionError(protocolVersion, frame.protocolVersion);
 		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) {
+	async request(frame, options = {}) {
 		if (this.pending.has(frame.requestId)) throw new Error(`duplicate requestId: ${frame.requestId}`);
 		if (this.deadError !== void 0) throw new Error(this.deadError.message);
+		const deadlineMs = options.deadlineMs ?? 5e3;
 		const response = new Promise((resolve, reject) => {
+			const deadlineTimer = setTimeout(() => {
+				this.expireRequest(frame.requestId, deadlineMs);
+			}, deadlineMs);
+			deadlineTimer.unref();
 			this.pending.set(frame.requestId, {
 				resolve,
-				reject
+				reject,
+				deadlineTimer
 			});
 		});
 		this.write(frame);
@@ -1734,7 +1790,15 @@ var LocalBrokerConnection = class {
 		if (this.deadError !== void 0) return;
 		this.write({ type: "exit" });
 		await new Promise((resolve) => {
-			this.socket.end(resolve);
+			const degrade = setTimeout(() => {
+				this.socket.destroy();
+				resolve();
+			}, TEARDOWN_CALL_DEADLINE_MS);
+			degrade.unref();
+			this.socket.end(() => {
+				clearTimeout(degrade);
+				resolve();
+			});
 		});
 	}
 	consume(chunk) {
@@ -1764,8 +1828,7 @@ var LocalBrokerConnection = class {
 		if (frame.type === "error") {
 			const error = new BrokerServerError(frame.code, frame.message, { details: frame.details });
 			if (frame.requestId !== void 0) {
-				this.pending.get(frame.requestId)?.reject(error);
-				this.pending.delete(frame.requestId);
+				this.takePending(frame.requestId)?.reject(error);
 				return;
 			}
 			if (this.ready) {
@@ -1786,8 +1849,7 @@ var LocalBrokerConnection = class {
 		}
 		const requestId = responseRequestId(frame);
 		if (requestId !== void 0) {
-			this.pending.get(requestId)?.resolve(frame);
-			this.pending.delete(requestId);
+			this.takePending(requestId)?.resolve(frame);
 			return;
 		}
 		if (frame.type === "event" || frame.type === "app-event" || frame.type === "ext-event") for (const listener of this.listeners) listener(frame);
@@ -1800,7 +1862,10 @@ var LocalBrokerConnection = class {
 	* settles the request. The broker's owner loop guarantees exactly one
 	* terminal per operation; a second acceptance for the same request or an
 	* already-bound operationId is defensively ignored, never a second
-	* registration.
+	* registration. Acceptance also stops the call's deadline: dispatch was the
+	* bounded transport phase the client owns, and the accepted operation now
+	* awaits a native terminal that can be legitimately user-paced (a held modal
+	* dialog), bounded only by transport liveness.
 	*/
 	acceptDeferredOperation(requestId, operationId) {
 		const entry = this.pending.get(requestId);
@@ -1808,6 +1873,7 @@ var LocalBrokerConnection = class {
 		if (this.deferredOperations.has(operationId)) return;
 		entry.deferredOperation = operationId;
 		this.deferredOperations.set(operationId, requestId);
+		this.clearDeadline(entry);
 	}
 	/**
 	* The single terminal settlement: resolves the still-pending request with
@@ -1815,15 +1881,17 @@ var LocalBrokerConnection = class {
 	* typed wire error (`"error"`). Terminals for unknown or already-settled
 	* operationIds are silently dropped - the broker side already settles
 	* through a one-shot CAS; the client mirrors that stateless drop instead of
-	* guessing an owner.
+	* guessing an owner. A terminal arriving after the call's deadline expired
+	* is the same stateless drop (W1).
 	*/
 	settleDeferredOperation(operationId, payload) {
 		const requestId = this.deferredOperations.get(operationId);
 		if (requestId === void 0) return;
-		const entry = this.pending.get(requestId);
-		this.deferredOperations.delete(operationId);
-		this.pending.delete(requestId);
-		if (entry === void 0) return;
+		const entry = this.takePending(requestId);
+		if (entry === void 0) {
+			this.deferredOperations.delete(operationId);
+			return;
+		}
 		if (payload.kind === "result") {
 			const terminal = {
 				type: "ext-operation-terminal",
@@ -1836,10 +1904,83 @@ var LocalBrokerConnection = class {
 		const wireError = payload.error;
 		entry.reject(new ExtensionOperationError(wireError.code, wireError.message, { details: wireError.details }));
 	}
+	/**
+	* Removes and fully cleans one pending entry: clears its deadline timer and
+	* the deferred-operation reverse mapping, so every settle path (response,
+	* correlated error, deferred terminal, expiry) leaves no timer or mapping
+	* behind.
+	*/
+	takePending(requestId) {
+		const entry = this.pending.get(requestId);
+		if (entry === void 0) return;
+		this.pending.delete(requestId);
+		this.clearDeadline(entry);
+		if (entry.deferredOperation !== void 0) this.deferredOperations.delete(entry.deferredOperation);
+		return entry;
+	}
+	clearDeadline(entry) {
+		if (entry.deadlineTimer !== void 0) {
+			clearTimeout(entry.deadlineTimer);
+			entry.deadlineTimer = void 0;
+		}
+	}
+	/**
+	* Deadline expiry (W1): settles exactly this call with the typed timeout
+	* rejection and removes its entries, so a late reply or terminal finds no
+	* owner. Deliberately NOT `markDead` — an unanswered call is one liveness
+	* signal, not a death verdict; the connection stays usable and the death
+	* listeners stay silent. The expiry is reported through the internal seam
+	* for the Phase C heartbeat's failure classification.
+	*/
+	expireRequest(requestId, deadlineMs) {
+		const entry = this.pending.get(requestId);
+		if (entry === void 0) return;
+		this.takePending(requestId);
+		this.notifyDeadlineExpiry({
+			requestId,
+			deadlineMs
+		});
+		entry.reject(new TransportTimeoutError(requestId, deadlineMs));
+	}
+	/**
+	* Bootstrap-class budget (W1): the Ready frame must arrive within
+	* `BOOTSTRAP_CALL_DEADLINE_MS` or init settles with the typed timeout
+	* rejection. Like per-call expiry this never marks the transport dead —
+	* `connectLocalBroker`'s error path performs the bounded close.
+	*/
+	raceBootstrapDeadline(ready) {
+		return new Promise((resolve, reject) => {
+			let bootstrapTimer = setTimeout(() => {
+				bootstrapTimer = void 0;
+				this.notifyDeadlineExpiry({
+					requestId: INIT_REQUEST_ID,
+					deadlineMs: BOOTSTRAP_CALL_DEADLINE_MS
+				});
+				reject(new TransportTimeoutError(INIT_REQUEST_ID, BOOTSTRAP_CALL_DEADLINE_MS));
+			}, BOOTSTRAP_CALL_DEADLINE_MS);
+			bootstrapTimer.unref();
+			const settle = (settleFn) => {
+				if (bootstrapTimer !== void 0) {
+					clearTimeout(bootstrapTimer);
+					bootstrapTimer = void 0;
+				}
+				settleFn();
+			};
+			ready.then((frame) => settle(() => resolve(frame)), (error) => settle(() => reject(error)));
+		});
+	}
+	notifyDeadlineExpiry(expiry) {
+		for (const listener of [...this.deadlineExpiryListeners]) try {
+			listener(expiry);
+		} catch {}
+	}
 	rejectAll(error) {
 		this.ready?.reject(error);
 		this.ready = void 0;
-		for (const pending of this.pending.values()) pending.reject(error);
+		for (const pending of this.pending.values()) {
+			this.clearDeadline(pending);
+			pending.reject(error);
+		}
 		this.pending.clear();
 		this.deferredOperations.clear();
 	}
@@ -1858,7 +1999,10 @@ var LocalBrokerConnection = class {
 		this.deadError = error;
 		this.ready?.reject(error);
 		this.ready = void 0;
-		for (const pending of this.pending.values()) pending.reject(pending.deferredOperation === void 0 ? error : extensionTransportClosedError(error));
+		for (const pending of this.pending.values()) {
+			this.clearDeadline(pending);
+			pending.reject(pending.deferredOperation === void 0 ? error : extensionTransportClosedError(error));
+		}
 		this.pending.clear();
 		this.deferredOperations.clear();
 		for (const listener of [...this.deadListeners]) try {
@@ -1897,6 +2041,729 @@ const resolveCliEntrypoint = () => {
 	const suffix = fileURLToPath(import.meta.url).endsWith(".ts") ? "cli.ts" : "cli.mjs";
 	return fileURLToPath(new URL(`./${suffix}`, import.meta.url));
 };
+/**
+* Typed fail-fast rejection for every call issued after supervision reached
+* its terminal `abandoned` state: the recovery budget is exhausted and the
+* runtime stays headless by design (the consumer process keeps running).
+* Consumers match on `code` (`transport_abandoned`); `details` carries the
+* budget facts `{ recoveries, windowMs }`.
+*/
+var TransportAbandonedError = class extends Error {
+	code = "transport_abandoned";
+	details;
+	constructor(recoveries, windowMs) {
+		super(`transport abandoned: ${recoveries} recovery attempts within ${windowMs}ms exhausted the budget; every later call fails fast`);
+		this.name = "TransportAbandonedError";
+		this.details = {
+			recoveries,
+			windowMs
+		};
+	}
+};
+const journalKeyOf = (entry) => {
+	switch (entry.kind) {
+		case "resolve-default-app": return "resolve-default-app";
+		case "create-tray": return;
+		case "set-tray-menu":
+		case "set-tray-icon":
+		case "set-tray-tooltip": return `${entry.kind}:${entry.appId}:${entry.trayId}`;
+		case "set-app-name":
+		case "set-app-icon":
+		case "set-app-icon-variant": return `${entry.kind}:${entry.appId}`;
+		case "load-ext": return `load-ext:${entry.appId}:${entry.mountId ?? entry.name}`;
+	}
+};
+const isDeadlineExpirySource = (connection) => "onDeadlineExpiry" in connection && typeof connection.onDeadlineExpiry === "function";
+const isConnectionDeadSource = (connection) => "onConnectionDead" in connection && typeof connection.onConnectionDead === "function";
+const sleepUnref = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms).unref();
+});
+/**
+* Supervised transport (W2/W4/W5/W6): a stable `OpenTrayConnection`-shaped
+* proxy for the layers above (createClient, tray handles) that owns one
+* broker connection per generation underneath. Consumer event subscriptions
+* and the supervision state machine survive generation changes;
+* per-connection surfaces (`onConnectionDead`) stay per-generation truth.
+*/
+var SupervisedLocalBrokerConnection = class {
+	connectFactory;
+	heartbeatIntervalMs;
+	probeDeadlineMs;
+	heartbeatFailureThreshold;
+	recoveryEnabled;
+	maxRestarts;
+	recoveryWindowMs;
+	cooldownMs;
+	backoffFactor;
+	backoffCapMs;
+	connectTimeoutMs;
+	restartApp;
+	connection;
+	generation = 0;
+	state = "healthy";
+	journal = [];
+	eventListeners = /* @__PURE__ */ new Set();
+	deadListeners = /* @__PURE__ */ new Set();
+	stateListeners = /* @__PURE__ */ new Set();
+	rebuildCallbacks = [];
+	unwireGeneration = noop$1;
+	heartbeatTimer;
+	heartbeatOrdinal = 0;
+	heartbeatInFlight = false;
+	consecutiveHeartbeatFailures = 0;
+	lastSettledAt = 0;
+	restartTimestamps = [];
+	callerInitiated = false;
+	/**
+	* Monotonic teardown epoch: `shutdown()` bumps it so an in-flight recovery
+	* attempt can detect that it raced caller-initiated teardown and abort
+	* instead of resurrecting a destroyed runtime (no candidate adoption, no
+	* `healthy` transition, no restarted heartbeat).
+	*/
+	teardownEpoch = 0;
+	shutdownPromise;
+	constructor(connectFactory, options) {
+		this.connectFactory = connectFactory;
+		this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 3e4;
+		this.probeDeadlineMs = options.probeDeadlineMs ?? 3e3;
+		this.heartbeatFailureThreshold = options.heartbeatFailureThreshold ?? 3;
+		const recovery = options.recovery ?? {};
+		this.recoveryEnabled = recovery.enabled ?? true;
+		this.maxRestarts = recovery.maxRestarts ?? 3;
+		this.recoveryWindowMs = recovery.windowMs ?? 6e5;
+		this.cooldownMs = recovery.cooldownMs ?? 1e3;
+		this.backoffFactor = recovery.backoffFactor ?? 2;
+		this.backoffCapMs = recovery.backoffCapMs ?? 3e4;
+		this.connectTimeoutMs = recovery.connectTimeoutMs ?? 1e4;
+		this.restartApp = recovery.restartApp;
+	}
+	/** Current supervision state; edge events go to {@link onTransportStateChange}. */
+	get transportState() {
+		return this.state;
+	}
+	/** Monotonic generation counter; each respawn/replay increments it once. */
+	get transportGeneration() {
+		return this.generation;
+	}
+	/** Current generation's endpoint (proxy; absent before the first connect). */
+	get endpoint() {
+		return this.connection?.endpoint ?? "";
+	}
+	/** Current generation's caller label (proxy; absent before the first connect). */
+	get callerLabel() {
+		return this.connection?.callerLabel ?? "";
+	}
+	/**
+	* Current generation's broker session id. Read dynamically so extension
+	* contexts and rebuild callbacks can attribute session-owned state to the
+	* live generation (the id changes on every respawn).
+	*/
+	get sessionId() {
+		return this.connection?.sessionId ?? "";
+	}
+	/** True once the current generation's connection died (or none exists). */
+	get connectionDead() {
+		return this.connection === void 0 || this.connection.connectionDead;
+	}
+	/**
+	* Establishes generation 0. A failure here propagates to the caller
+	* unchanged — supervision (heartbeat, recovery) only guards a connection
+	* that once existed; an app that never started is a plain startup failure.
+	*/
+	async connect() {
+		const connection = await this.connectFactory();
+		this.connection = connection;
+		this.unwireGeneration = this.wireGeneration(connection);
+		this.lastSettledAt = Date.now();
+		this.consecutiveHeartbeatFailures = 0;
+		this.startHeartbeat();
+	}
+	/**
+	* Forwards one request to the current generation. After the terminal
+	* `abandoned` state every call fails fast with {@link TransportAbandonedError}.
+	* A teardown-budget call (`deadlineMs === TEARDOWN_CALL_DEADLINE_MS`) marks
+	* the supervision caller-initiated: Phase A froze the budget class as the
+	* caller-intent channel, so a socket close racing caller-initiated destroy
+	* can never be misread as uninvited death.
+	*/
+	async request(frame, options = {}) {
+		if (this.state === "abandoned") throw new TransportAbandonedError(this.restartTimestamps.length, this.recoveryWindowMs);
+		if (options.deadlineMs === 2e3) this.callerInitiated = true;
+		const connection = this.connection;
+		if (connection === void 0) throw new Error(BROKER_CONNECTION_CLOSED_MESSAGE);
+		const candidate = journalCandidateFrom(frame);
+		const response = await connection.request(frame, options);
+		this.noteSuccessfulSettlement();
+		if (candidate !== void 0) this.commitJournalEntry(candidate, response);
+		if (frame.type === "destroy-tray") this.evictJournalTray(frame.appId, frame.trayId);
+		return response;
+	}
+	/**
+	* Consumer event subscription that survives generation changes: each new
+	* generation's event stream fans out to the same listeners.
+	*/
+	onEvent(listener) {
+		this.eventListeners.add(listener);
+		return () => {
+			this.eventListeners.delete(listener);
+		};
+	}
+	/**
+	* Per-connection death notification, forwarded for every generation (D3
+	* semantics preserved: consumers using it for per-connection cleanup keep
+	* working; the supervision state machine is the new higher-level truth).
+	*/
+	onConnectionDead(listener) {
+		this.deadListeners.add(listener);
+		return () => {
+			this.deadListeners.delete(listener);
+		};
+	}
+	/**
+	* Tier 1 health projection (W6): edge-triggered `healthy | recovering |
+	* abandoned` transitions. The initial `healthy` state never fires —
+	* consumers reading the current state use `transportState`.
+	*/
+	onTransportStateChange(listener) {
+		this.stateListeners.add(listener);
+		return () => {
+			this.stateListeners.delete(listener);
+		};
+	}
+	/**
+	* Registers one facade rebuild callback (W4). Callbacks run in
+	* registration order after the core journal replay on every successful
+	* recovery, receiving the fresh generation number and session id so
+	* session-attributed native state can be re-created against the live
+	* broker session.
+	*/
+	registerTransportRebuild(rebuild) {
+		this.rebuildCallbacks.push(rebuild);
+	}
+	/**
+	* Graceful teardown channel (W4/W3): idempotent, marks the supervision
+	* caller-initiated synchronously (so the close-driven death event can
+	* never trigger recovery), bumps the teardown epoch (so an in-flight
+	* recovery attempt aborts instead of resurrecting the runtime), stops the
+	* heartbeat, then closes the current generation — including an
+	* adoption-in-progress candidate routed through `this.connection` —
+	* within its bounded graceful-close budget.
+	*/
+	async shutdown() {
+		this.callerInitiated = true;
+		this.teardownEpoch += 1;
+		this.shutdownPromise ??= (async () => {
+			this.stopHeartbeat();
+			this.unwireGeneration();
+			this.unwireGeneration = noop$1;
+			const connection = this.connection;
+			this.connection = void 0;
+			if (connection !== void 0) await connection.close().catch(noopAsync);
+		})();
+		await this.shutdownPromise;
+	}
+	/** LocalBrokerClient structural compatibility: graceful close == shutdown. */
+	close() {
+		return this.shutdown();
+	}
+	startHeartbeat() {
+		if (this.heartbeatTimer !== void 0) return;
+		this.heartbeatTimer = setInterval(() => {
+			this.heartbeatTick();
+		}, this.heartbeatIntervalMs);
+		this.heartbeatTimer.unref();
+	}
+	stopHeartbeat() {
+		if (this.heartbeatTimer !== void 0) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = void 0;
+		}
+	}
+	/**
+	* Idle-gated heartbeat (W2): a transport that keeps settling requests
+	* proves its own liveness, so the probe budget is spent only on silence.
+	* A probe failure of any rejection class (typed timeout, transport-lost,
+	* broker error frame) counts; a successful settlement resets the streak.
+	* Single-flight with a generation token: at most one probe per generation
+	* is outstanding (a configured interval shorter than the probe deadline
+	* must not run concurrent probes whose completions double-count), and a
+	* probe that outlives its generation settles nothing.
+	*/
+	async heartbeatTick() {
+		if (this.heartbeatInFlight) return;
+		const connection = this.connection;
+		const probeGeneration = this.generation;
+		if (connection === void 0 || this.state !== "healthy" || this.callerInitiated) return;
+		if (Date.now() - this.lastSettledAt < this.heartbeatIntervalMs) return;
+		this.heartbeatInFlight = true;
+		const requestId = `supervisor-heartbeat-${this.generation}-${this.heartbeatOrdinal += 1}`;
+		try {
+			await connection.request({
+				type: "health",
+				requestId
+			}, { deadlineMs: this.probeDeadlineMs });
+			if (this.generation === probeGeneration && this.state === "healthy") {
+				this.consecutiveHeartbeatFailures = 0;
+				this.noteSuccessfulSettlement();
+			}
+		} catch (error) {
+			if (this.generation !== probeGeneration || this.state !== "healthy") return;
+			this.consecutiveHeartbeatFailures += 1;
+			if (this.consecutiveHeartbeatFailures < this.heartbeatFailureThreshold) return;
+			const death = new Error(BROKER_CONNECTION_CLOSED_MESSAGE, { cause: `heartbeat declared death after ${this.consecutiveHeartbeatFailures} consecutive probe failures (${String(error)})` });
+			this.handleGenerationDeath(death);
+			connection.close().catch(noopAsync);
+		} finally {
+			this.heartbeatInFlight = false;
+		}
+	}
+	noteSuccessfulSettlement() {
+		this.lastSettledAt = Date.now();
+		this.consecutiveHeartbeatFailures = 0;
+	}
+	/**
+	* Subscribes this supervisor's stable listener sets to one generation.
+	* Event fanout and the death/expiry seams are wired before the generation
+	* becomes `this.connection` (recovery candidates are wired before replay)
+	* so no observable event window opens between adoption steps.
+	*/
+	wireGeneration(connection) {
+		const unwires = [];
+		const unlistenEvents = connection.onEvent((frame) => {
+			for (const listener of [...this.eventListeners]) try {
+				listener(frame);
+			} catch {}
+		});
+		unwires.push(unlistenEvents);
+		if (isConnectionDeadSource(connection)) {
+			const unlistenDead = connection.onConnectionDead((error) => {
+				this.handleGenerationDeath(error);
+			});
+			unwires.push(unlistenDead);
+		}
+		if (isDeadlineExpirySource(connection)) {
+			const unlistenExpiry = connection.onDeadlineExpiry((expiry) => {
+				if (expiry.requestId.startsWith("supervisor-heartbeat-")) return;
+				this.consecutiveHeartbeatFailures += 1;
+				if (this.consecutiveHeartbeatFailures >= this.heartbeatFailureThreshold && this.state === "healthy" && !this.callerInitiated) {
+					const connectionAtDeath = this.connection;
+					this.handleGenerationDeath(new Error(BROKER_CONNECTION_CLOSED_MESSAGE, { cause: `heartbeat declared death after ${this.consecutiveHeartbeatFailures} consecutive deadline expiries` }));
+					if (connectionAtDeath !== void 0) connectionAtDeath.close().catch(noopAsync);
+				}
+			});
+			unwires.push(unlistenExpiry);
+		}
+		return () => {
+			for (const unwire of unwires.splice(0)) unwire();
+		};
+	}
+	/**
+	* Death funnel: forwards the per-connection event first (D3 truth), stops
+	* this generation's wiring, then decides the supervision reaction. The
+	* state guard makes the reaction single-flight — deaths of candidates
+	* during an ongoing recovery only forward, they never nest recoveries.
+	*/
+	handleGenerationDeath(error) {
+		for (const listener of [...this.deadListeners]) try {
+			listener(error);
+		} catch {}
+		if (this.callerInitiated || this.state !== "healthy") return;
+		this.unwireGeneration();
+		this.unwireGeneration = noop$1;
+		if (this.restartApp !== void 0) {
+			this.handOverToRestartApp();
+			return;
+		}
+		if (!this.recoveryEnabled) return;
+		this.runRecovery();
+	}
+	/**
+	* Tier 2 hand-over: bounded teardown of the current generation, the app's
+	* restart vector invoked exactly once, then terminal. No in-process
+	* rebuild, no loop — restart ownership belongs to the callback.
+	*/
+	async handOverToRestartApp() {
+		this.setState("recovering");
+		this.callerInitiated = true;
+		this.stopHeartbeat();
+		const connection = this.connection;
+		if (connection !== void 0 && !connection.connectionDead) await connection.close().catch(noopAsync);
+		try {
+			await this.restartApp?.();
+		} catch (error) {
+			console.error("OpenTray recovery.restartApp callback failed:", error);
+		}
+		this.setState("abandoned");
+	}
+	/**
+	* In-process recovery (W4/W5): cooldown backoff → reconnect through the
+	* original connect options → journal replay → facade rebuilds → healthy.
+	* Every attempt consumes budget up front; a failed attempt (connect,
+	* replay, or rebuild — including artifact identity mismatches) retries
+	* inside the remaining budget until exhaustion abandons the runtime. Each
+	* reconnect attempt is bounded by the connect budget, and every step
+	* re-checks the teardown epoch so a shutdown racing the loop aborts it
+	* instead of resurrecting the runtime.
+	*/
+	async runRecovery() {
+		this.setState("recovering");
+		let backoffOrdinal = 0;
+		while (true) {
+			if (this.callerInitiated) return;
+			if (!this.consumeRestartBudget()) {
+				this.setState("abandoned");
+				return;
+			}
+			await sleepUnref(this.cooldownForBackoff(backoffOrdinal));
+			if (this.callerInitiated) return;
+			const attemptEpoch = this.teardownEpoch;
+			try {
+				const candidate = await this.connectWithBudget();
+				if (this.teardownEpoch !== attemptEpoch || this.callerInitiated) {
+					await candidate.close().catch(noopAsync);
+					return;
+				}
+				await this.adoptGeneration(candidate, attemptEpoch);
+				if (this.teardownEpoch !== attemptEpoch || this.callerInitiated) return;
+				this.setState("healthy");
+				return;
+			} catch {
+				backoffOrdinal += 1;
+			}
+		}
+	}
+	/**
+	* One reconnect attempt under the connect budget. A factory that never
+	* settles counts as a failed attempt; a connection arriving after the
+	* budget expired is closed on arrival so no orphan generation leaks.
+	*/
+	async connectWithBudget() {
+		let settled = false;
+		return new Promise((resolve, reject) => {
+			const late = (candidate) => {
+				candidate.close().catch(noopAsync);
+			};
+			const timer = setTimeout(() => {
+				if (settled) return;
+				settled = true;
+				reject(/* @__PURE__ */ new Error(`recovery connect exceeded ${this.connectTimeoutMs}ms`));
+			}, this.connectTimeoutMs);
+			timer.unref();
+			this.connectFactory().then((candidate) => {
+				if (settled) {
+					late(candidate);
+					return;
+				}
+				settled = true;
+				clearTimeout(timer);
+				resolve(candidate);
+			}, (error) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				reject(error instanceof Error ? error : new Error(String(error)));
+			});
+		});
+	}
+	cooldownForBackoff(backoffOrdinal) {
+		return Math.min(this.cooldownMs * this.backoffFactor ** backoffOrdinal, this.backoffCapMs);
+	}
+	/**
+	* Sliding-window budget: one timestamp per respawn attempt (successful or
+	* not — both are respawns the consumer experienced). In-memory per
+	* supervisor by ruling; a fresh `createTray` starts a fresh budget.
+	*/
+	consumeRestartBudget() {
+		const windowStart = Date.now() - this.recoveryWindowMs;
+		this.restartTimestamps = this.restartTimestamps.filter((timestamp) => timestamp > windowStart);
+		if (this.restartTimestamps.length >= this.maxRestarts) return false;
+		this.restartTimestamps.push(Date.now());
+		return true;
+	}
+	/**
+	* Wires the candidate generation, replays the journal, and runs the
+	* facade rebuild callbacks. The candidate becomes `this.connection` for
+	* the adoption's duration — facade rebuild callbacks route their
+	* re-creation commands through this supervisor, so they must reach the
+	* candidate, not the dead generation (the rebuild-routing law). A failure
+	* rolls the candidate back out (unwired, closed) and restores the dead
+	* previous connection so consumer calls keep failing fast; a teardown
+	* racing the adoption aborts without resurrecting anything.
+	*/
+	async adoptGeneration(candidate, attemptEpoch) {
+		const previousConnection = this.connection;
+		this.generation += 1;
+		this.unwireGeneration = this.wireGeneration(candidate);
+		this.connection = candidate;
+		try {
+			await this.replayJournal(candidate);
+			for (const rebuild of [...this.rebuildCallbacks]) await rebuild({
+				generation: this.generation,
+				sessionId: candidate.sessionId.length > 0 ? candidate.sessionId : void 0
+			});
+			if (this.teardownEpoch !== attemptEpoch || this.callerInitiated) {
+				this.rollbackAdoption(candidate, previousConnection);
+				throw new Error("recovery aborted by caller-initiated teardown");
+			}
+		} catch (error) {
+			this.rollbackAdoption(candidate, previousConnection);
+			throw error;
+		}
+		this.consecutiveHeartbeatFailures = 0;
+		this.noteSuccessfulSettlement();
+	}
+	/**
+	* Removes a failed (or torn-down) adoption candidate: stop its wiring,
+	* close it bounded, and restore the previous dead connection unless a
+	* caller-initiated shutdown already dissolved the runtime (shutdown's own
+	* close handled the candidate in that window; the restore must not undo
+	* the torn-down state).
+	*/
+	rollbackAdoption(candidate, previousConnection) {
+		this.unwireGeneration();
+		this.unwireGeneration = noop$1;
+		if (this.connection === candidate) this.connection = this.callerInitiated ? void 0 : previousConnection;
+		candidate.close().catch(noopAsync);
+	}
+	/**
+	* Replays the declarative journal in record order with fresh request ids
+	* under the bootstrap deadline class. The resolved default app of the new
+	* generation becomes the appId authority: replayed frames are rewritten
+	* onto it, so app-scoped state follows broker truth instead of a stale
+	* generation's identity.
+	*/
+	async replayJournal(connection) {
+		let ordinal = 0;
+		const appIdRewrites = /* @__PURE__ */ new Map();
+		const rewriteAppId = (appId) => appIdRewrites.get(appId) ?? appId;
+		for (const entry of this.journal) {
+			ordinal += 1;
+			const requestId = `supervisor-replay-${this.generation}-${ordinal}`;
+			let frame;
+			switch (entry.kind) {
+				case "resolve-default-app":
+					frame = {
+						type: "resolve-default-app",
+						requestId
+					};
+					break;
+				case "create-tray":
+					frame = {
+						type: "create-tray",
+						requestId,
+						app: { appId: rewriteAppId(entry.app.appId) },
+						tray: {
+							...entry.tray,
+							id: entry.trayId
+						}
+					};
+					break;
+				case "set-tray-menu":
+					frame = {
+						type: "set-tray-menu",
+						requestId,
+						appId: rewriteAppId(entry.appId),
+						trayId: entry.trayId,
+						menu: entry.menu
+					};
+					break;
+				case "set-tray-icon":
+					frame = {
+						type: "set-tray-icon",
+						requestId,
+						appId: rewriteAppId(entry.appId),
+						trayId: entry.trayId,
+						icon: entry.icon
+					};
+					break;
+				case "set-tray-tooltip":
+					frame = {
+						type: "set-tray-tooltip",
+						requestId,
+						appId: rewriteAppId(entry.appId),
+						trayId: entry.trayId,
+						tooltip: entry.tooltip
+					};
+					break;
+				case "set-app-name":
+					frame = {
+						type: "set-app-name",
+						requestId,
+						appId: rewriteAppId(entry.appId),
+						name: entry.name
+					};
+					break;
+				case "set-app-icon":
+					frame = {
+						type: "set-app-icon",
+						requestId,
+						appId: rewriteAppId(entry.appId),
+						appIcon: entry.appIcon
+					};
+					break;
+				case "set-app-icon-variant":
+					frame = {
+						type: "set-app-icon-variant",
+						requestId,
+						appId: rewriteAppId(entry.appId),
+						variant: entry.variant
+					};
+					break;
+				case "load-ext":
+					frame = {
+						type: "load-ext",
+						requestId,
+						appId: rewriteAppId(entry.appId),
+						name: entry.name,
+						path: entry.path,
+						expectedIdentity: entry.expectedIdentity,
+						...entry.mountId === void 0 ? {} : { mountId: entry.mountId }
+					};
+					break;
+			}
+			const response = await connection.request(frame, { deadlineMs: BOOTSTRAP_CALL_DEADLINE_MS });
+			if (response.type === "error") throw new BrokerServerError(response.code, response.message, { details: response.details });
+			if (entry.kind === "resolve-default-app" && response.type === "default-app") appIdRewrites.set(entry.appId, response.app.appId);
+		}
+	}
+	setState(state) {
+		if (this.state === state) return;
+		this.state = state;
+		if (state === "abandoned") this.stopHeartbeat();
+		for (const listener of [...this.stateListeners]) try {
+			listener(state);
+		} catch {}
+	}
+	commitJournalEntry(frame, response) {
+		switch (frame.type) {
+			case "resolve-default-app":
+				if (response.type === "default-app") this.upsertJournal({
+					kind: "resolve-default-app",
+					appId: response.app.appId
+				});
+				return;
+			case "create-tray": {
+				const trayId = response.type === "tray-created" && typeof response.trayId === "string" ? response.trayId : frame.tray.id;
+				this.journal.push({
+					kind: "create-tray",
+					app: frame.app,
+					tray: frame.tray,
+					trayId
+				});
+				return;
+			}
+			case "set-tray-menu":
+				this.upsertJournal({
+					kind: "set-tray-menu",
+					appId: frame.appId,
+					trayId: frame.trayId,
+					menu: frame.menu
+				});
+				return;
+			case "set-tray-icon":
+				this.upsertJournal({
+					kind: "set-tray-icon",
+					appId: frame.appId,
+					trayId: frame.trayId,
+					icon: frame.icon
+				});
+				return;
+			case "set-tray-tooltip":
+				this.upsertJournal({
+					kind: "set-tray-tooltip",
+					appId: frame.appId,
+					trayId: frame.trayId,
+					tooltip: frame.tooltip
+				});
+				return;
+			case "set-app-name":
+				this.upsertJournal({
+					kind: "set-app-name",
+					appId: frame.appId,
+					name: frame.name
+				});
+				return;
+			case "set-app-icon":
+				this.upsertJournal({
+					kind: "set-app-icon",
+					appId: frame.appId,
+					appIcon: frame.appIcon
+				});
+				return;
+			case "set-app-icon-variant":
+				this.upsertJournal({
+					kind: "set-app-icon-variant",
+					appId: frame.appId,
+					variant: frame.variant
+				});
+				return;
+			case "load-ext":
+				this.upsertJournal({
+					kind: "load-ext",
+					appId: frame.appId,
+					name: frame.name,
+					path: frame.path,
+					expectedIdentity: frame.expectedIdentity,
+					...frame.mountId === void 0 ? {} : { mountId: frame.mountId }
+				});
+				return;
+			default: return;
+		}
+	}
+	/**
+	* Keyed entries replace in place at first-occurrence position (last-write-
+	* wins value, stable ordering); first occurrences append. Tray creations
+	* and mount declarations keep their creation order by construction.
+	*/
+	upsertJournal(entry) {
+		const key = journalKeyOf(entry);
+		if (key === void 0) {
+			this.journal.push(entry);
+			return;
+		}
+		const existing = this.journal.findIndex((candidate) => journalKeyOf(candidate) === key);
+		if (existing < 0) {
+			this.journal.push(entry);
+			return;
+		}
+		this.journal[existing] = entry;
+	}
+	evictJournalTray(appId, trayId) {
+		this.journal = this.journal.filter((entry) => {
+			switch (entry.kind) {
+				case "create-tray": return !(entry.app.appId === appId && entry.trayId === trayId);
+				case "set-tray-menu":
+				case "set-tray-icon":
+				case "set-tray-tooltip": return !(entry.appId === appId && entry.trayId === trayId);
+				default: return true;
+			}
+		});
+	}
+};
+/**
+* Snapshot candidate for the declarative journal: a defensive clone of every
+* journalable mutating frame, taken before the await so later caller
+* mutation of the frame object cannot corrupt the recorded state. The entry
+* is committed only after the frame settles successfully.
+*/
+const journalCandidateFrom = (frame) => {
+	switch (frame.type) {
+		case "resolve-default-app":
+		case "create-tray":
+		case "set-tray-menu":
+		case "set-tray-icon":
+		case "set-tray-tooltip":
+		case "set-app-name":
+		case "set-app-icon":
+		case "set-app-icon-variant":
+		case "load-ext": return structuredClone(frame);
+		default: return;
+	}
+};
+/** Constructs a supervised transport around one connect factory. */
+const createTransportSupervisor = (options) => new SupervisedLocalBrokerConnection(options.connect, options);
+const noop$1 = () => {};
+const noopAsync = () => {};
 //#endregion
 //#region src/menu-input.ts
 const normalizeCreateTrayMenu = (menu) => {
@@ -2054,23 +2921,28 @@ const createTray = async (options, runtimeOptions = {}) => {
 	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 },
-		appLaunch
+	const { recovery, ...brokerOptions } = runtimeOptions;
+	const supervisor = createTransportSupervisor({
+		connect: () => connectLocalBroker({
+			...brokerOptions,
+			...appIcon === void 0 ? {} : { appIcon },
+			appLaunch
+		}),
+		...recovery === void 0 ? {} : { recovery }
 	});
 	try {
-		const tray = await createClient(connection, { appOptions: {
+		await supervisor.connect();
+		const tray = await createClient(supervisor, { appOptions: {
 			...runtimeOptions.appName === void 0 ? {} : { name: runtimeOptions.appName },
 			...appIcon === void 0 ? {} : { appIcon }
 		} }).createTray(normalized.options);
 		return wrapCreateTrayHandle(tray, {
-			closeConnection: () => connection.close(),
+			shutdown: () => supervisor.shutdown(),
 			destroyPromise: void 0,
 			menuUnsubscribe: bindMenuClickHandlers(tray, normalized.menuHandlers)
 		});
 	} catch (error) {
-		await connection.close().catch(noop);
+		await supervisor.shutdown().catch(noop);
 		throw error;
 	}
 };
@@ -2117,7 +2989,7 @@ const wrapCreateTrayHandle = (tray, state) => {
 					if (!isTransportClosed(error)) throw error;
 				} finally {
 					try {
-						await state.closeConnection();
+						await state.shutdown();
 					} catch (error) {
 						if (!isTransportClosed(error)) throw error;
 					}
@@ -2135,6 +3007,6 @@ const bindMenuClickHandlers = (tray, handlers) => {
 };
 const noop = () => {};
 //#endregion
-export { AppIconVariantNotFoundError, BROKER_CONNECTION_CLOSED_MESSAGE, BrokerProtocolVersionError, BrokerServerError, DEFAULT_APP_ICON_VARIANT, EMBEDDED_STAGING_MANIFEST_PATH, EXTENSION_EVENT_RECORD_MAX_BYTES, EXTENSION_TRANSPORT_CLOSED_CODE, ExtensionOperationError, InvalidAppIconError, NATIVE_EXTENSION_EMBEDDED_ERROR_CODES, NATIVE_EXTENSION_EMBEDDED_TARGET_MATRIX, NativeExtensionArtifactResolutionError, NativeExtensionEmbeddedArtifactError, PROTOCOL_VERSION, createBrokerEndpointIdentity, createClient, createInitFrame, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveNativeExtensionArtifact, validateAppIcon };
+export { AppIconVariantNotFoundError, BOOTSTRAP_CALL_DEADLINE_MS, BROKER_CONNECTION_CLOSED_MESSAGE, BrokerProtocolVersionError, BrokerServerError, DEFAULT_APP_ICON_VARIANT, EMBEDDED_STAGING_MANIFEST_PATH, EXTENSION_EVENT_RECORD_MAX_BYTES, EXTENSION_TRANSPORT_CLOSED_CODE, ExtensionOperationError, INTERACTIVE_CALL_DEADLINE_MS, InvalidAppIconError, NATIVE_EXTENSION_EMBEDDED_ERROR_CODES, NATIVE_EXTENSION_EMBEDDED_TARGET_MATRIX, NativeExtensionArtifactResolutionError, NativeExtensionEmbeddedArtifactError, PROTOCOL_VERSION, TEARDOWN_CALL_DEADLINE_MS, TransportAbandonedError, TransportTimeoutError, createBrokerEndpointIdentity, createClient, createInitFrame, createTransportSupervisor, createTray, createTrayHandle, formatBrokerEndpointName, formatBrokerStateRoot, formatUnixSocketPath, formatWindowsPipeName, isSupportedProtocolVersion, resolveNativeExtensionArtifact, validateAppIcon };
 
 //# sourceMappingURL=index.mjs.map