@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/homeassistant/homeassistant.classes.client.ts

@@ -1,10 +1,14 @@
 import * as plugins from '../../plugins.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
 import type * as homeAssistantWebsocket from 'home-assistant-js-websocket';
 import type {
   IHomeAssistantHomeassistantConfig,
   IHomeAssistantClient,
   IHomeAssistantEntityRegistryForDisplay,
   IHomeAssistantNormalizedConfig,
+  IHomeAssistantOperationSession,
   IHomeAssistantServiceCall,
   IHomeAssistantWebsocketApi,
   IHomeAssistantTargetScope,
@@ -18,6 +22,27 @@ const maximumTimerMs = 2_147_483_647;
 const reconnectRefreshBackoffBaseMs = 1000;
 const reconnectRefreshBackoffMaximumMs = 30_000;
 
+interface IHomeAssistantClientOwnership {
+  readonly owner: NativeIntegrationOwner;
+  readonly lease: INativeSetupLease;
+}
+
+interface IHomeAssistantCleanup {
+  readonly close: () => Promise<void>;
+  readonly connection: boolean;
+  status: 'idle' | 'pending' | 'closed' | 'failed';
+  promise?: Promise<void>;
+}
+
+interface IHomeAssistantSubscription {
+  readonly handler: () => void | Promise<void>;
+  readonly pending: Set<Promise<unknown>>;
+  readonly failures: Set<unknown>;
+  readonly removeAbortListener: () => void;
+  active: boolean;
+  closePromise?: Promise<void>;
+}
+
 type TConnectionGenerationResult<TResult> =
   | { status: 'completed'; value: TResult }
   | { status: 'changed' };
@@ -148,7 +173,13 @@ export const normalizeHomeAssistantConfig = (
 
 export class HomeAssistantClient implements IHomeAssistantClient {
   private readonly config: IHomeAssistantNormalizedConfig;
-  private readonly handlers = new Set<() => void>();
+  private readonly context: INativeAdmissionContext;
+  private readonly owner: NativeIntegrationOwner;
+  private readonly standalone: boolean;
+  private lease?: INativeSetupLease;
+  private initStarted = false;
+  private ownedDestroyPromise?: Promise<void>;
+  private readonly handlers = new Set<IHomeAssistantSubscription>();
   private readonly lifetimeAbortController = new AbortController();
   private readonly ownedSockets = new Set<homeAssistantWebsocket.HaWebSocket>();
   private connection?: homeAssistantWebsocket.Connection;
@@ -158,7 +189,9 @@ export class HomeAssistantClient implements IHomeAssistantClient {
   private entityPlatforms: Record<string, string> = {};
   private services = new Set<string>();
   private readonly catalogueUnsubscribes = new Set<() => Promise<void>>();
-  private readonly serviceSettlements = new Set<Promise<void>>();
+  private readonly actualWork = new Set<Promise<unknown>>();
+  private readonly cleanup = new Set<IHomeAssistantCleanup>();
+  private retryPromise?: Promise<void>;
   private connectionReady = false;
   private snapshotReady = false;
   private requiredEntitiesPresent = true;
@@ -192,12 +225,12 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       return;
     }
     const initializationDeadline = Date.now() + this.config.initialSnapshotTimeoutMs;
-    void this.refreshAuthoritativeSnapshot(
+    void this.trackWork(this.refreshAuthoritativeSnapshot(
       connection,
       generation,
       this.lifetimeAbortController.signal,
       initializationDeadline
-    ).then((refreshedArg) => {
+    )).then((refreshedArg) => {
       if (
         refreshedArg
         && !this.isStopping()
@@ -228,22 +261,70 @@ export class HomeAssistantClient implements IHomeAssistantClient {
 
   constructor(
     configArg: IHomeAssistantHomeassistantConfig,
-    private readonly api: IHomeAssistantWebsocketApi,
-    private readonly webSocketFactory?: THomeAssistantWebSocketFactory
+    contextArg: INativeIntegrationSetupContext,
+    private readonly api: IHomeAssistantWebsocketApi = plugins.homeAssistantWebsocket,
+    private readonly webSocketFactory?: THomeAssistantWebSocketFactory,
+    ownershipArg?: IHomeAssistantClientOwnership
   ) {
     this.config = normalizeHomeAssistantConfig(configArg);
+    this.context = new NativeHomeAdmission('homeassistant').admit(contextArg, this.config.homeId);
+    if (ownershipArg && !(ownershipArg.owner instanceof NativeIntegrationOwner)) throw new TypeError('Home Assistant requires an actual native owner.');
+    this.standalone = ownershipArg === undefined;
+    this.owner = ownershipArg?.owner ?? new NativeIntegrationOwner('homeassistant', { homeId: this.context.homeId });
+    this.owner.admission.admit(this.context, this.config.homeId);
+    if (ownershipArg) {
+      ownershipArg.lease.assertOpen();
+      if (ownershipArg.lease.context.homeId !== this.context.homeId || ownershipArg.lease.context.configStore !== this.context.configStore) {
+        throw new Error('Home Assistant client ownership conflicts with its admitted context.');
+      }
+      this.lease = ownershipArg.lease;
+    }
     this.requiredEntitiesPresent = !this.config.requireEntityIds;
   }
 
   public get connected(): boolean {
-    return this.connectionReady
+    return !this.lease?.signal.aborted
+      && !this.isStopping()
+      && this.connectionReady
       && this.snapshotReady
       && this.requiredEntitiesPresent
       && (!this.config.requireEntityRegistry || [...this.config.entityIds!]
         .every((entityIdArg) => Boolean(this.entityPlatforms[entityIdArg])));
   }
 
-  public async init(abortSignalArg?: AbortSignal): Promise<void> {
+  public init(abortSignalArg?: AbortSignal): Promise<void> {
+    try {
+      if (this.initStarted || this.lifecycle !== 'idle') throw new Error('Home Assistant client cannot initialize again.');
+      if (abortSignalArg !== undefined && !(abortSignalArg instanceof AbortSignal)) throw new TypeError('Home Assistant cancellation must be an AbortSignal.');
+      this.initStarted = true;
+      if (!this.standalone) return this.initializeOwned(AbortSignal.any([this.lease!.signal, ...(abortSignalArg ? [abortSignalArg] : [])]));
+      const signal = AbortSignal.any([...(this.context.abortSignal ? [this.context.abortSignal] : []), ...(abortSignalArg ? [abortSignalArg] : [])]);
+      return this.owner.runSetup({ ...this.context, abortSignal: signal }, this.config.homeId, async (leaseArg) => {
+        this.lease = leaseArg;
+        let cleanupStarted = false;
+        leaseArg.own(() => {
+          const retry = cleanupStarted;
+          cleanupStarted = true;
+          return retry ? this.retryOwnedCleanup() : this.destroyOwned();
+        });
+        await this.initializeOwned(leaseArg.signal);
+        leaseArg.assertOpen();
+        leaseArg.promoteToRuntime();
+      });
+    } catch (errorArg) { return Promise.reject(errorArg); }
+  }
+
+  private initializeOwned(signalArg: AbortSignal): Promise<void> {
+    // Cleanup runs after actual initialization settles, avoiding setup/close self-wait.
+    const work = this.trackWork(Promise.resolve().then(() => this.initialize(signalArg)));
+    return work.catch(async (errorArg: unknown) => {
+      try { await this.destroyOwned(); }
+      catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'Home Assistant initialization and cleanup both failed.'); }
+      throw errorArg;
+    });
+  }
+
+  private async initialize(abortSignalArg?: AbortSignal): Promise<void> {
     if (this.lifecycle !== 'idle') {
       throw new Error(
         'Home Assistant client cannot initialize from lifecycle state '
@@ -314,16 +395,6 @@ export class HomeAssistantClient implements IHomeAssistantClient {
         }
         throw new Error('Home Assistant client was destroyed during initialization.');
       }
-    } catch (errorArg) {
-      try {
-        await this.destroy();
-      } catch (cleanupErrorArg) {
-        throw new AggregateError(
-          [errorArg, cleanupErrorArg],
-          'Home Assistant initialization and cleanup both failed.'
-        );
-      }
-      throw errorArg;
     } finally {
       abortSignalArg?.removeEventListener('abort', propagateAbort);
       if (this.setupAbortController === setupAbortController) {
@@ -348,25 +419,106 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     return { homeId: this.config.homeId, instanceId: this.config.instanceId };
   }
 
-  public subscribe(handlerArg: () => void): () => void {
+  public subscribe(handlerArg: () => void | Promise<void>, abortSignalArg?: AbortSignal): () => Promise<void> {
+    this.lease?.assertOpen();
     if (this.isStopping()) {
       throw new Error('Home Assistant client is destroyed.');
     }
-    this.handlers.add(handlerArg);
-    let subscribed = true;
-    return () => {
-      if (!subscribed) {
-        return;
+    if (typeof handlerArg !== 'function' || (abortSignalArg !== undefined && !(abortSignalArg instanceof AbortSignal))) {
+      throw new TypeError('Home Assistant subscriber and cancellation must be a function and AbortSignal.');
+    }
+    abortSignalArg?.throwIfAborted();
+    const onAbort = (): void => { void unsubscribe().catch(() => undefined); };
+    const subscription: IHomeAssistantSubscription = {
+      handler: handlerArg, active: true, pending: new Set(), failures: new Set(),
+      removeAbortListener: () => abortSignalArg?.removeEventListener('abort', onAbort),
+    };
+    const unsubscribe = (): Promise<void> => {
+      if (!subscription.closePromise) {
+        subscription.active = false;
+        subscription.removeAbortListener();
+        subscription.closePromise = Promise.resolve().then(async () => {
+          await Promise.allSettled([...subscription.pending]);
+          if (subscription.failures.size) throw new AggregateError([...subscription.failures], 'Home Assistant subscriber cleanup failed.');
+          this.handlers.delete(subscription);
+        });
       }
-      subscribed = false;
-      this.handlers.delete(handlerArg);
+      return subscription.closePromise;
     };
+    this.handlers.add(subscription);
+    abortSignalArg?.addEventListener('abort', onAbort, { once: true });
+    if (abortSignalArg?.aborted) onAbort();
+    return unsubscribe;
   }
 
-  public async callService(
+  /** Caller cancellation may settle first; the owner retains the actual continuation. */
+  public withOperation<TResult>(
+    workArg: (sessionArg: IHomeAssistantOperationSession) => Promise<TResult>,
+    abortSignalArg?: AbortSignal
+  ): Promise<TResult> {
+    try {
+      const admitted = this.admitOperation(workArg, abortSignalArg);
+      return this.raceAbort(admitted.promise, admitted.signal);
+    } catch (errorArg) { return Promise.reject(errorArg); }
+  }
+
+  private admitOperation<TResult>(
+    workArg: (sessionArg: IHomeAssistantOperationSession) => Promise<TResult>,
+    abortSignalArg?: AbortSignal
+  ): { promise: Promise<TResult>; signal: AbortSignal } {
+    this.lease?.assertOpen();
+    if (this.isStopping()) throw new Error('Home Assistant client is destroyed.');
+    if (typeof workArg !== 'function' || (abortSignalArg !== undefined && !(abortSignalArg instanceof AbortSignal))) {
+      throw new TypeError('Home Assistant operation and cancellation must be a function and AbortSignal.');
+    }
+    const cancellation = new AbortController();
+    const signal = AbortSignal.any([this.lifetimeAbortController.signal, cancellation.signal,
+      ...(this.lease ? [this.lease.signal] : []), ...(this.context.abortSignal ? [this.context.abortSignal] : []),
+      ...(abortSignalArg ? [abortSignalArg] : [])]);
+    signal.throwIfAborted();
+    const operation = this.owner.runOperation({ ...this.context, abortSignal: signal }, this.config.homeId, async (leaseArg) => {
+      const pending = new Set<Promise<unknown>>();
+      let active = true;
+      const session: IHomeAssistantOperationSession = Object.freeze({
+        signal: leaseArg.signal,
+        callService: (requestArg: IHomeAssistantServiceCall): Promise<unknown> => {
+          try {
+            leaseArg.assertOpen();
+            if (!active) throw new Error('Home Assistant service session is closed.');
+            return this.dispatchService(requestArg, leaseArg.signal, pending, (reasonArg) => cancellation.abort(reasonArg));
+          } catch (errorArg) { return Promise.reject(errorArg); }
+        },
+      });
+      try { return await workArg(session); }
+      finally {
+        active = false;
+        // An abort race is not settlement of the effect dispatched to the foreign API.
+        await Promise.allSettled([...pending]);
+      }
+    });
+    return { promise: this.trackWork(operation), signal };
+  }
+
+  public callService(
     requestArg: IHomeAssistantServiceCall,
     abortSignalArg?: AbortSignal
   ): Promise<unknown> {
+    try {
+      homeAssistantRecord(requestArg);
+      homeAssistantRecord(requestArg.target);
+      if (requestArg.data !== undefined) homeAssistantRecord(requestArg.data);
+      const request = structuredClone(requestArg);
+      return this.withOperation((sessionArg) => sessionArg.callService(request), abortSignalArg);
+    } catch (errorArg) { return Promise.reject(errorArg); }
+  }
+
+  private async dispatchService(
+    requestArg: IHomeAssistantServiceCall,
+    abortSignalArg: AbortSignal,
+    pendingArg: Set<Promise<unknown>>,
+    cancelOperationArg: (reasonArg: Error) => void
+  ): Promise<unknown> {
+    this.lease?.assertOpen();
     if (abortSignalArg?.aborted) {
       throw abortError(abortSignalArg);
     }
@@ -410,26 +562,28 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       throw abortError(operationAbortController.signal);
     }
     let timeout: ReturnType<typeof setTimeout> | undefined;
-    let resolveSettlement!: () => void;
-    const settlement = new Promise<void>((resolve) => { resolveSettlement = resolve; });
-    this.serviceSettlements.add(settlement);
     this.activeServiceCallCount++;
     try {
-      const operationPromise = this.api.callService(
+      const operationPromise = this.trackWork(this.api.callService(
         connection,
         request.domain,
         request.service,
         request.data,
         request.target
-      );
+      ));
+      pendingArg.add(operationPromise);
+      const settled = (): void => { pendingArg.delete(operationPromise); };
+      void operationPromise.then(settled, settled);
       operationAbortController.signal.addEventListener('abort', cancelPendingCommand, { once: true });
       if (operationAbortController.signal.aborted) {
         cancelPendingCommand();
       }
       timeout = setTimeout(() => {
-        operationAbortController.abort(new Error(
+        const reason = new Error(
           `Home Assistant service call did not complete within ${this.config.serviceCallTimeoutMs} ms.`
-        ));
+        );
+        operationAbortController.abort(reason);
+        cancelOperationArg(reason);
       }, this.config.serviceCallTimeoutMs);
       return await this.raceAbort(operationPromise, operationAbortController.signal);
     } finally {
@@ -440,38 +594,73 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       abortSignalArg?.removeEventListener('abort', propagateAbort);
       operationAbortController.signal.removeEventListener('abort', cancelPendingCommand);
       this.lifetimeAbortController.signal.removeEventListener('abort', propagateLifetimeAbort);
-      resolveSettlement();
-      this.serviceSettlements.delete(settlement);
     }
   }
 
   public destroy(): Promise<void> {
-    if (this.destroyPromise) {
-      return this.destroyPromise;
-    }
-    if (this.lifecycle === 'destroyed' && !this.stateUnsubscribe && this.catalogueUnsubscribes.size === 0 && this.ownedSockets.size === 0) {
-      return Promise.resolve();
-    }
-    this.lifecycle = 'destroying';
-    const destroyPromise = this.performDestroy();
-    this.destroyPromise = destroyPromise;
-    void destroyPromise.finally(() => {
-      if (this.destroyPromise === destroyPromise) {
-        this.destroyPromise = undefined;
-      }
-      this.lifecycle = 'destroyed';
-    }).catch(() => undefined);
-    return destroyPromise;
+    if (!this.destroyPromise) {
+      this.lifecycle = 'destroying';
+      this.destroyPromise = Promise.resolve().then(() => this.standalone ? this.owner.close() : this.destroyOwned());
+      this.fenceSubscribers();
+      this.setupAbortController?.abort(new Error('Home Assistant client was destroyed.'));
+      this.lifetimeAbortController.abort(new Error('Home Assistant client was destroyed.'));
+    }
+    return this.destroyPromise;
+  }
+
+  private destroyOwned(): Promise<void> {
+    if (!this.ownedDestroyPromise) {
+      this.lifecycle = 'destroying';
+      this.ownedDestroyPromise = Promise.resolve().then(() => this.performDestroy(false));
+      this.fenceSubscribers();
+      this.setupAbortController?.abort(new Error('Home Assistant client was destroyed.'));
+      this.lifetimeAbortController.abort(new Error('Home Assistant client was destroyed.'));
+    }
+    return this.ownedDestroyPromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.destroyPromise && !this.ownedDestroyPromise) return Promise.reject(new Error('Home Assistant cleanup retry requires destruction.'));
+    return this.standalone ? this.owner.retryCleanup() : this.retryOwnedCleanup();
   }
 
-  private async performDestroy(): Promise<void> {
+  private retryOwnedCleanup(): Promise<void> {
+    if (!this.retryPromise) {
+      const retry = Promise.resolve().then(async () => {
+        await this.ownedDestroyPromise?.catch(() => undefined);
+        await this.performDestroy(true);
+      });
+      this.retryPromise = retry;
+      const settled = (): void => { this.retryPromise = undefined; };
+      void retry.then(settled, settled);
+    }
+    return this.retryPromise;
+  }
+
+  private trackWork<TResult>(promiseArg: Promise<TResult>): Promise<TResult> {
+    this.actualWork.add(promiseArg);
+    const settled = (): void => { this.actualWork.delete(promiseArg); };
+    void promiseArg.then(settled, settled);
+    return promiseArg;
+  }
+
+  private ownCleanup(closeArg: () => Promise<void>, connectionArg = false): void {
+    this.cleanup.add({ close: closeArg, connection: connectionArg, status: 'idle' });
+  }
+
+  private closeResource(resourceArg: IHomeAssistantCleanup, retryArg: boolean): Promise<void> {
+    if (retryArg && resourceArg.status === 'failed') resourceArg.promise = undefined;
+    if (!resourceArg.promise) {
+      resourceArg.status = 'pending';
+      resourceArg.promise = this.trackWork(Promise.resolve().then(resourceArg.close));
+      void resourceArg.promise.then(() => { resourceArg.status = 'closed'; }, () => { resourceArg.status = 'failed'; });
+    }
+    return resourceArg.promise;
+  }
+
+  private async performDestroy(retryArg: boolean): Promise<void> {
     this.clearReconnectRefreshTimer();
     this.reconnectRefreshFailureCount = 0;
-    this.setupAbortController?.abort(new Error('Home Assistant client was destroyed.'));
-    this.setupAbortController = undefined;
-    this.lifetimeAbortController.abort(new Error('Home Assistant client was destroyed.'));
-
-    const unsubscribe = this.stateUnsubscribe;
     const connection = this.connection;
     const connectionSocket = connection?.socket;
     this.connection = undefined;
@@ -479,40 +668,56 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       connection.removeEventListener('ready', this.handleReady);
       connection.removeEventListener('disconnected', this.handleDisconnected);
     }
+    this.advanceConnectionGeneration();
+    this.connectionReady = false;
+    this.snapshotReady = false;
+    this.requiredEntitiesPresent = false;
+    this.bufferedStateEvents.clear();
+    this.upstreamSnapshot = {};
+    this.snapshot = {};
+    this.entityPlatforms = {};
+    this.services.clear();
+    this.fenceSubscribers();
+    if (retryArg) for (const subscription of this.handlers) subscription.failures.clear();
+
+    const failures: unknown[] = [];
+    const attempted = new Set<IHomeAssistantCleanup>();
+    const closeGroup = async (connectionsArg: boolean): Promise<void> => {
+      const entries = [...this.cleanup].filter((entry) => entry.connection === connectionsArg && !attempted.has(entry));
+      entries.forEach((entry) => attempted.add(entry));
+      const results = await Promise.allSettled(entries.map((entry) => {
+        const actual = this.closeResource(entry, retryArg);
+        // A missing unsubscribe acknowledgement must not prevent sibling socket close.
+        // The actual promise remains in the ledger after the deadline rejects.
+        return connectionsArg ? actual : this.settleStateUnsubscribe(() => actual);
+      }));
+      for (const result of results) if (result.status === 'rejected') failures.push(result.reason as unknown);
+    };
     try {
-      await Promise.all([...this.serviceSettlements]);
-      for (const unsubscribeCatalogue of [...this.catalogueUnsubscribes]) {
-        await this.settleStateUnsubscribe(unsubscribeCatalogue);
-        this.catalogueUnsubscribes.delete(unsubscribeCatalogue);
-      }
-      if (unsubscribe) {
-        await this.settleStateUnsubscribe(unsubscribe);
-        if (this.stateUnsubscribe === unsubscribe) {
-          this.stateUnsubscribe = undefined;
-        }
+      await closeGroup(false);
+      await closeGroup(true);
+      const sockets = await Promise.allSettled([this.drainOwnedSockets(connectionSocket)]);
+      for (const result of sockets) if (result.status === 'rejected') failures.push(result.reason as unknown);
+      // Foreign continuations can produce late connections or unsubscribe handles.
+      // Join real settlement, then close every newly adopted handle, without replay.
+      while (this.actualWork.size || [...this.cleanup].some((entry) => !attempted.has(entry))) {
+        await Promise.allSettled([...this.actualWork]);
+        await closeGroup(false);
+        await closeGroup(true);
+        const lateSockets = await Promise.allSettled([this.drainOwnedSockets()]);
+        for (const result of lateSockets) if (result.status === 'rejected') failures.push(result.reason as unknown);
       }
-    } finally {
-      if (connection) {
-        if (this.activeServiceCallCount > 0) {
-          connection.reconnect(true);
-        }
-        connection.close();
+      for (const entry of [...this.cleanup]) if (entry.status === 'closed') this.cleanup.delete(entry);
+      if (!this.cleanup.size) {
+        this.stateUnsubscribe = undefined;
+        this.catalogueUnsubscribes.clear();
       }
-      try {
-        await this.drainOwnedSockets(connectionSocket);
-      } finally {
-        this.advanceConnectionGeneration();
-        this.connectionReady = false;
-        this.snapshotReady = false;
-        this.requiredEntitiesPresent = false;
-        this.bufferedStateEvents.clear();
-        this.upstreamSnapshot = {};
-        this.snapshot = {};
-        this.entityPlatforms = {};
-        this.services.clear();
-        this.handlers.clear();
+      for (const subscription of [...this.handlers]) {
+        failures.push(...subscription.failures);
+        if (!subscription.failures.size) this.handlers.delete(subscription);
       }
-    }
+      if (failures.length) throw new AggregateError([...new Set(failures)], 'Home Assistant cleanup failed; handles remain owned for explicit retry.');
+    } finally { this.lifecycle = 'destroyed'; }
   }
 
   private async createConnection(
@@ -526,7 +731,7 @@ export class HomeAssistantClient implements IHomeAssistantClient {
         throw abortError(abortSignalArg);
       }
       try {
-        const connectionPromise = this.api.createConnection({
+        const connectionPromise = this.trackWork(this.api.createConnection({
           auth: authArg,
           setupRetry: 0,
           createSocket: (optionsArg) => this.createManagedSocket(
@@ -535,7 +740,10 @@ export class HomeAssistantClient implements IHomeAssistantClient {
             abortSignalArg,
             initializationDeadlineArg
           ),
-        });
+        }).then((connectionArg) => {
+          this.ownCleanup(async () => { connectionArg.close(); }, true);
+          return connectionArg;
+        }));
         try {
           return await this.raceAbortWithDeadline(
             connectionPromise,
@@ -545,9 +753,6 @@ export class HomeAssistantClient implements IHomeAssistantClient {
           );
         } catch (errorArg) {
           this.closeOwnedSockets();
-          void connectionPromise.then((connectionArg) => {
-            connectionArg.close();
-          }).catch(() => undefined);
           throw errorArg;
         }
       } catch (errorArg) {
@@ -584,14 +789,16 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       ? `Home Assistant connection and authentication did not complete within ${this.config.initialSnapshotTimeoutMs} ms.`
       : `Home Assistant reconnect authentication did not complete within ${this.config.initialSnapshotTimeoutMs} ms.`;
 
+    abortSignal.throwIfAborted();
+    if (this.isStopping()) throw new Error('Home Assistant client was destroyed.');
     if (this.webSocketFactory) {
       return this.createOwnedSocket(authArg, abortSignal, deadline, timeoutMessage);
     }
 
-    const socketPromise = this.api.createSocket({
+    const socketPromise = this.trackWork(this.api.createSocket({
       ...optionsArg,
       setupRetry: 0,
-    });
+    }).then((socketArg) => { this.trackOwnedSocket(socketArg); return socketArg; }));
     try {
       const socket = await this.raceAbortWithDeadline(
         socketPromise,
@@ -606,12 +813,8 @@ export class HomeAssistantClient implements IHomeAssistantClient {
         }
         throw new Error('Home Assistant client discarded a late socket after destruction.');
       }
-      this.trackOwnedSocket(socket);
       return socket;
     } catch (errorArg) {
-      void socketPromise.then((socketArg) => {
-        socketArg.close();
-      }).catch(() => undefined);
       throw errorArg;
     }
   }
@@ -763,7 +966,7 @@ export class HomeAssistantClient implements IHomeAssistantClient {
   private async drainOwnedSockets(connectionSocketArg?: homeAssistantWebsocket.HaWebSocket): Promise<void> {
     const sockets = new Set(this.ownedSockets);
     if (connectionSocketArg) sockets.add(connectionSocketArg);
-    await Promise.all([...sockets].map((socket) => new Promise<void>((resolve, reject) => {
+    const results = await Promise.allSettled([...sockets].map((socket) => new Promise<void>((resolve, reject) => {
       if (socket.readyState === 3) { this.ownedSockets.delete(socket); resolve(); return; }
       const finish = (error?: Error): void => {
         clearTimeout(timeout);
@@ -777,6 +980,8 @@ export class HomeAssistantClient implements IHomeAssistantClient {
       try { if (socket.readyState !== 2) socket.close(); }
       catch (error) { finish(error instanceof Error ? error : new Error('Home Assistant socket close failed.')); }
     })));
+    const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected').map((result) => result.reason as unknown);
+    if (failures.length) throw new AggregateError(failures, 'Home Assistant socket cleanup failed.');
   }
 
   private async raceAbort<T>(
@@ -904,34 +1109,29 @@ export class HomeAssistantClient implements IHomeAssistantClient {
     abortSignalArg: AbortSignal,
     initializationDeadlineArg: number
   ): Promise<void> {
+    const adopt = (promiseArg: Promise<() => Promise<void>>): Promise<() => Promise<void>> => this.trackWork(promiseArg.then((unsubscribeArg) => {
+      this.ownCleanup(unsubscribeArg);
+      return unsubscribeArg;
+    }));
     const unsubscribe = await this.raceAbortWithDeadline(
-      connectionArg.subscribeEvents<homeAssistantWebsocket.StateChangedEvent>((eventArg) => {
+      adopt(connectionArg.subscribeEvents<homeAssistantWebsocket.StateChangedEvent>((eventArg) => {
         this.handleStateChangedEvent(eventArg);
-      }, 'state_changed'),
+      }, 'state_changed')),
       abortSignalArg,
       initializationDeadlineArg,
       `Home Assistant did not acknowledge the state subscription within ${this.config.initialSnapshotTimeoutMs} ms.`
     );
-    if (this.wasDestroyed() || abortSignalArg.aborted) {
-      await this.settleStateUnsubscribe(unsubscribe).catch(() => undefined);
-      if (abortSignalArg.aborted) {
-        throw abortError(abortSignalArg);
-      }
-      throw new Error('Home Assistant client was destroyed during state subscription.');
-    }
+    abortSignalArg.throwIfAborted();
+    if (this.wasDestroyed()) throw new Error('Home Assistant client was destroyed during state subscription.');
     this.stateUnsubscribe = unsubscribe;
     for (const eventType of ['service_registered', 'service_removed', 'entity_registry_updated']) {
-      const unsubscribePromise = connectionArg.subscribeEvents(() => this.handleReady(), eventType);
-      try {
-        const unsubscribeCatalogue = await this.raceAbortWithDeadline(
-          unsubscribePromise, abortSignalArg, initializationDeadlineArg,
-          'Home Assistant did not acknowledge its catalogue subscription before the startup deadline.'
-        );
-        this.catalogueUnsubscribes.add(unsubscribeCatalogue);
-      } catch (errorArg) {
-        void unsubscribePromise.then((lateUnsubscribe) => this.settleStateUnsubscribe(lateUnsubscribe)).catch(() => undefined);
-        throw errorArg;
-      }
+      abortSignalArg.throwIfAborted();
+      const unsubscribeCatalogue = await this.raceAbortWithDeadline(
+        adopt(connectionArg.subscribeEvents(() => this.handleReady(), eventType)),
+        abortSignalArg, initializationDeadlineArg,
+        'Home Assistant did not acknowledge its catalogue subscription before the startup deadline.'
+      );
+      this.catalogueUnsubscribes.add(unsubscribeCatalogue);
     }
   }
 
@@ -1266,7 +1466,7 @@ export class HomeAssistantClient implements IHomeAssistantClient {
         return { status: 'changed' } as const;
       }
       try {
-        const value = await operationArg();
+        const value = await this.trackWork(operationArg());
         if (generationArg !== this.connectionGeneration || !this.connectionReady) {
           return { status: 'changed' } as const;
         }
@@ -1333,12 +1533,40 @@ export class HomeAssistantClient implements IHomeAssistantClient {
   }
 
   private emitChange(): void {
-    for (const handler of [...this.handlers]) {
+    if (this.isStopping()) return;
+    for (const subscription of this.handlers) {
+      if (!subscription.active) continue;
       try {
-        handler();
-      } catch {
-        // Subscriber failures must not break connection lifecycle or other subscribers.
+        const notification = this.admitOperation(async (sessionArg) => {
+          if (!subscription.active || sessionArg.signal.aborted) return;
+          try { await subscription.handler(); }
+          catch (errorArg) {
+            subscription.failures.add(errorArg);
+            subscription.active = false;
+          }
+        }).promise;
+        subscription.pending.add(notification);
+        const settled = (): void => { subscription.pending.delete(notification); };
+        void notification.then(settled, (errorArg: unknown) => {
+          if (!this.isStopping() && !this.lease?.signal.aborted) {
+            subscription.failures.add(errorArg);
+            subscription.active = false;
+          }
+          settled();
+        });
+      } catch (errorArg) {
+        if (!this.isStopping() && !this.lease?.signal.aborted) {
+          subscription.failures.add(errorArg);
+          subscription.active = false;
+        }
       }
     }
   }
+
+  private fenceSubscribers(): void {
+    for (const subscription of this.handlers) {
+      subscription.active = false;
+      subscription.removeAbortListener();
+    }
+  }
 }