sen-ether-client 0.1.0 → 0.1.2

package/API.md

@@ -45,14 +45,21 @@ Connection options:
 - `timeout`: discovery and operation timeout in ms.
 - `discoverySettleMs`: discovery settle time after the first process is found.
   Defaults to `100`.
+- `busDiscoverySettleMs`: max wait after a lightweight session connection while
+  bus announcements arrive. Defaults to at least `300`.
 - `reconnect`: whether to reconnect and restart interests.
 - `reconnectDelayMs`: delay between reconnect attempts.
-- `maxReconnectAttempts`: maximum reconnect attempts.
+- `maxReconnectAttempts`: maximum reconnect attempts. Defaults to `0`, which
+  means unlimited retries.
 - `participantReadyTimeoutMs`: short non-fatal grace timeout for bus
   participant acknowledgements. Defaults to `1000`.
 - `socketKeepAlive`: enable TCP keepalive. Defaults to `true`.
 - `socketIdleTimeoutMs`: optional TCP idle timeout. Defaults to `0` because
   valid SEN connections can be quiet on TCP while bus data flows separately.
+- `presenceTimeoutMs`: close and reconnect when the connected SEN process stops
+  announcing ether presence beams. Defaults to `5000`; set `0` to disable.
+- `presenceCheckIntervalMs`: presence watchdog check interval. Defaults to
+  `1000`.
 
 `Sen.connect()` uses multicast discovery. `sen-ether-client` reads this SEN environment
 variable as its multicast default:
@@ -104,6 +111,7 @@ Main methods:
 - `await sen.connect(options)`
 - `await sen.interest(query, options)`
 - `await sen.session(name)`
+- `await sen.discoverBuses(options)`
 - `sen.listSessions()`
 - `sen.listBuses(options)`
 - `await sen.bus(name, options)`
@@ -117,6 +125,9 @@ Session and bus navigation:
 ```js
 const sen = await Sen.connect();
 
+console.log(await sen.discoverBuses());
+// [{ session: 'hmi', bus: 'diagnostics', qualified: 'hmi.diagnostics' }]
+
 for (const sessionName of sen.listSessions()) {
   const session = await sen.session(sessionName);
   console.log(sessionName, session.listBuses());
@@ -125,6 +136,10 @@ for (const sessionName of sen.listSessions()) {
 const diagnostics = await sen.session('hmi').then(hmi => hmi.bus('diagnostics'));
 ```
 
+`discoverBuses()` does not create interests and does not join any SEN bus. It
+does open a lightweight process connection per discovered session, because SEN
+presence beams announce sessions/processes but not the bus list.
+
 Main events:
 
 - `connect`

package/README.md

@@ -84,6 +84,11 @@ const sen = await Sen.connect({
 });
 ```
 
+Connected sessions are monitored through SEN ether presence beams. If the
+remote process stops announcing itself for `presenceTimeoutMs` milliseconds
+(default `5000`), the client closes the stale connection and restarts the
+configured interests.
+
 `sen-ether-client` can work with several SEN sessions from the same client. The session
 is inferred from the query:
 
@@ -98,6 +103,8 @@ You can also navigate explicitly through sessions and buses:
 const sen = await Sen.connect();
 
 console.log(sen.listSessions());
+console.log(await sen.discoverBuses());
+// [{ session: 'hmi', bus: 'diagnostics', qualified: 'hmi.diagnostics' }]
 
 const hmi = await sen.session('hmi');
 console.log(hmi.listBuses());
@@ -106,6 +113,11 @@ const diagnostics = await hmi.bus('diagnostics');
 const probe = await diagnostics.waitFor('EtherProbe');
 ```
 
+`discoverBuses()` does not create interests and does not join any SEN bus. It
+uses discovery to find sessions and opens lightweight process connections only
+to read bus announcements. If buses are not announced immediately after the
+process connection, it waits up to `busDiscoverySettleMs` milliseconds.
+
 You can also connect to one explicit session:
 
 ```js

package/bin/node-sen-probe.js

@@ -254,7 +254,9 @@ try {
 
   const client = new EtherClient({
     sessionName: target.session.name,
-    appName: 'sen-ether-probe'
+    appName: 'sen-ether-probe',
+    interfaceAddress: options.interfaceAddress,
+    discoveryPort: options.port
   });
   const remoteBuses = new Set();
   const requestedTypeHashes = new Set();
@@ -405,7 +407,7 @@ try {
     });
   }
 
-  client.joinBus(bus);
+  await client.joinBus(bus);
   await waitForEvent(client, 'busParticipantReady', 5000).catch(error => {
     console.warn(`[warn] ${error.message}; starting interest anyway`);
   });

package/index.js

@@ -34,13 +34,16 @@
  * @property {string} [app] Remote process appName substring filter.
  * @property {number} [timeout=3000] Discovery and operation timeout in ms.
  * @property {number} [discoverySettleMs=100] Discovery settle time after the first process is found.
+ * @property {number} [busDiscoverySettleMs=300] Max wait after lightweight session connect before reading bus announcements.
  * @property {number} [participantReadyTimeoutMs=1000] Short grace timeout for non-fatal bus participant acknowledgements.
  * @property {boolean} [reconnect=true] Reconnect and restart interests after disconnection.
  * @property {number} [reconnectDelayMs=500] Delay between reconnect attempts.
- * @property {number} [maxReconnectAttempts=10] Maximum reconnect attempts.
+ * @property {number} [maxReconnectAttempts=0] Maximum reconnect attempts. `0` means unlimited.
  * @property {boolean} [socketKeepAlive=true] Enable TCP keepalive on SEN ether connections.
  * @property {number} [socketKeepAliveInitialDelayMs=1000] TCP keepalive initial delay.
  * @property {number} [socketIdleTimeoutMs=0] Optional transport idle timeout in ms. `0` disables it.
+ * @property {number} [presenceTimeoutMs=5000] Close and reconnect when the connected SEN process stops announcing presence beams. `0` disables it.
+ * @property {number} [presenceCheckIntervalMs=1000] Presence watchdog check interval in ms.
  * @property {string} [interfaceAddress] Local interface address or interface name for multicast discovery.
  * @property {object} [target] Already discovered/direct SEN target.
  */
@@ -64,6 +67,13 @@
  * @property {boolean} [qualified=false] Return session-qualified bus names.
  */
 
+/**
+ * @typedef {object} SenBusSummary
+ * @property {string} session SEN session name.
+ * @property {string} bus Bus name local to the session.
+ * @property {string} qualified Session-qualified bus name usable in `SELECT * FROM <qualified>`.
+ */
+
 /**
  * @typedef {string | number | ((object: SenRemoteObject) => boolean)} SenObjectSelector
  */

package/lib/client.js

@@ -24,6 +24,18 @@ import { crc32 } from './crc32.js';
 
 const LINUX_OS_KIND = 1;
 const X64_CPU_ARCH = 1;
+const DEFAULT_DISCOVERY_PORT = 60543;
+const DEFAULT_BUS_MULTICAST_PORT = 50985;
+const BUS_HASH_SEED = 15071983;
+const FNV1A_OFFSET_BASIS = 0x811c9dc5;
+const FNV1A_PRIME = 0x01000193;
+const HASH_COMBINE_MAGIC = 0x9e3779b9;
+const DEFAULT_MULTICAST_RANGE = Object.freeze([
+  { min: 224, max: 239 },
+  { min: 0, max: 255 },
+  { min: 0, max: 255 },
+  { min: 0, max: 255 }
+]);
 
 function randomUInt32() {
   return randomBytes(4).readUInt32LE(0);
@@ -57,6 +69,87 @@ function detectCpuArch() {
   }
 }
 
+function discoveryPortFromEnv() {
+  const value = process.env.SEN_ETHER_DISCOVERY_PORT;
+  if (!value) {
+    return undefined;
+  }
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`invalid SEN discovery port in environment: ${value}`);
+  }
+  return port;
+}
+
+function resolveInterfaceAddress(value) {
+  const text = String(value || '').trim();
+  if (!text) {
+    return undefined;
+  }
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(text)) {
+    return text;
+  }
+
+  const interfaces = os.networkInterfaces();
+  const candidates = interfaces[text];
+  if (!candidates) {
+    return text;
+  }
+
+  const ipv4 = candidates.find(item => (item.family === 'IPv4' || item.family === 4) && !item.internal);
+  if (!ipv4) {
+    throw new Error(`network interface "${text}" has no non-internal IPv4 address`);
+  }
+  return ipv4.address;
+}
+
+function normalizeMulticastRange(value) {
+  const ranges = Array.isArray(value) && value.length === 4 ? value : DEFAULT_MULTICAST_RANGE;
+  return ranges.map((range, index) => {
+    const fallback = DEFAULT_MULTICAST_RANGE[index];
+    const min = Number(range?.min ?? fallback.min);
+    const max = Number(range?.max ?? fallback.max);
+    if (!Number.isInteger(min) || !Number.isInteger(max) || min < 0 || max > 255 || min > max) {
+      throw new Error(`invalid SEN bus multicast range at byte ${index}`);
+    }
+    return { min, max };
+  });
+}
+
+function computeByte(range, hashByte) {
+  const length = range.max - range.min;
+  return length !== 0 ? range.min + (hashByte % length) : range.min;
+}
+
+function hashIntegral(value, byteSize) {
+  let hash = FNV1A_OFFSET_BASIS;
+  for (let shift = (byteSize - 1) * 8; shift >= 0; shift -= 8) {
+    hash ^= (value >>> shift) & 0xff;
+    hash = Math.imul(hash, FNV1A_PRIME) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+function combineHashed(seed, hashed) {
+  return (seed ^ (
+    (hashed + HASH_COMBINE_MAGIC + ((seed << 6) >>> 0) + (seed >>> 2)) >>> 0
+  )) >>> 0;
+}
+
+function computeBusMulticastGroup(sessionId, busId, discoveryPort, ranges) {
+  let hash = BUS_HASH_SEED;
+  hash = combineHashed(hash, hashIntegral(sessionId >>> 0, 4));
+  hash = combineHashed(hash, hashIntegral(busId >>> 0, 4));
+  hash = combineHashed(hash, hashIntegral(discoveryPort >>> 0, 2));
+  const bytes = [
+    computeByte(ranges[0], hash & 0xff),
+    computeByte(ranges[1], (hash >>> 8) & 0xff),
+    computeByte(ranges[2], (hash >>> 16) & 0xff),
+    computeByte(ranges[3], (hash >>> 24) & 0xff)
+  ];
+  return bytes.map((byte, index) => Math.min(Math.max(byte, ranges[index].min), ranges[index].max)).join('.');
+}
+
 /**
  * Create a ProcessInfo compatible with sen::kernel::getOwnProcessInfo.
  *
@@ -139,9 +232,14 @@ export class EtherClient extends EventEmitter {
       socketKeepAlive: true,
       socketKeepAliveInitialDelayMs: 1000,
       socketIdleTimeoutMs: 0,
+      discoveryPort: discoveryPortFromEnv() ?? DEFAULT_DISCOVERY_PORT,
+      busMulticastPort: DEFAULT_BUS_MULTICAST_PORT,
+      busMulticastRange: DEFAULT_MULTICAST_RANGE,
       ...options
     };
     this.processInfo = createProcessInfo(this.options);
+    this.interfaceAddress = resolveInterfaceAddress(this.options.interfaceAddress);
+    this.busMulticastRange = normalizeMulticastRange(this.options.busMulticastRange);
     this.socket = undefined;
     this.udpSocket = undefined;
     this.receiveBuffer = Buffer.alloc(0);
@@ -242,6 +340,14 @@ export class EtherClient extends EventEmitter {
         udpSocket.close(resolve);
       }));
     }
+    for (const busState of this.buses.values()) {
+      if (busState.multicastSocket) {
+        closing.push(new Promise(resolve => {
+          busState.multicastSocket.close(resolve);
+        }));
+      }
+    }
+    this.buses.clear();
 
     await Promise.allSettled(closing);
   }
@@ -252,7 +358,7 @@ export class EtherClient extends EventEmitter {
    * @param {string} busName
    * @param {{ participantId?: number }} [options]
    */
-  joinBus(busName, options = {}) {
+  async joinBus(busName, options = {}) {
     if (!this.socket) {
       throw new Error('EtherClient is not connected');
     }
@@ -264,10 +370,21 @@ export class EtherClient extends EventEmitter {
       busId,
       participantId,
       readyRemoteParticipants: new Set(),
-      interests: new Map()
+      interests: new Map(),
+      multicastSocket: undefined,
+      multicastGroup: undefined
     };
 
     this.buses.set(busId, bus);
+    try {
+      if (this.options.busMulticast !== false) {
+        await this.#openBusMulticastSocket(bus);
+      }
+    } catch (error) {
+      this.buses.delete(busId);
+      throw error;
+    }
+
     this.#sendControlPayload(encodeEtherControlMessage({
       type: 'BusJoined',
       value: {
@@ -277,8 +394,20 @@ export class EtherClient extends EventEmitter {
       }
     }));
 
-    this.emit('busJoinedLocal', { busName, busId, participantId });
-    return { busName, busId, participantId };
+    this.emit('busJoinedLocal', {
+      busName,
+      busId,
+      participantId,
+      multicastGroup: bus.multicastGroup,
+      multicastPort: this.options.busMulticastPort
+    });
+    return {
+      busName,
+      busId,
+      participantId,
+      multicastGroup: bus.multicastGroup,
+      multicastPort: this.options.busMulticastPort
+    };
   }
 
   /**
@@ -426,6 +555,10 @@ export class EtherClient extends EventEmitter {
       }
     }));
     this.buses.delete(busState.busId);
+    if (busState.multicastSocket) {
+      busState.multicastSocket.close();
+      busState.multicastSocket = undefined;
+    }
     this.emit('busLeftLocal', {
       busName: busState.busName,
       busId: busState.busId,
@@ -573,6 +706,81 @@ export class EtherClient extends EventEmitter {
     }
   }
 
+  #onMulticastBusDatagram(busState, message, remote) {
+    try {
+      if (message.length < 8) {
+        throw new RangeError(`SEN multicast bus datagram too small: ${message.length}`);
+      }
+      const processId = message.readUInt32LE(0);
+      const payloadSize = message.readUInt32LE(4);
+      if (processId === this.processInfo.processId) {
+        return;
+      }
+      if (payloadSize !== message.length - 8) {
+        throw new RangeError(
+          `SEN multicast bus payload size mismatch: expected ${payloadSize}, got ${message.length - 8}`
+        );
+      }
+
+      const frame = {
+        to: busState.participantId,
+        busId: busState.busId,
+        message: message.subarray(8)
+      };
+      const busMessage = decodeBusMessage(frame.message);
+      this.emit('busFrame', { ...frame, busMessage, remote, multicast: true });
+      if (busMessage.categoryName === 'controlMessage') {
+        this.emit('busControlMessage', { ...frame, control: busMessage.control, remote, multicast: true });
+        return;
+      }
+      this.emit(busMessage.categoryName, { ...frame, ...busMessage, remote, multicast: true });
+    } catch (error) {
+      this.emit('error', error);
+    }
+  }
+
+  async #openBusMulticastSocket(busState) {
+    const group = computeBusMulticastGroup(
+      this.processInfo.sessionId,
+      busState.busId,
+      this.options.discoveryPort,
+      this.busMulticastRange
+    );
+    const port = this.options.busMulticastPort;
+    const bindAddress = process.platform === 'win32' ? undefined : group;
+    const socket = dgram.createSocket({ type: 'udp4', reuseAddr: true });
+    busState.multicastSocket = socket;
+    busState.multicastGroup = group;
+
+    socket.on('message', (message, remote) => this.#onMulticastBusDatagram(busState, message, remote));
+    socket.on('error', error => this.emit('error', error));
+
+    await new Promise((resolve, reject) => {
+      const onError = error => {
+        socket.off('listening', onListening);
+        reject(error);
+      };
+      const onListening = () => {
+        socket.off('error', onError);
+        try {
+          socket.addMembership(group, this.interfaceAddress);
+          socket.setMulticastLoopback(true);
+          if (this.interfaceAddress) {
+            socket.setMulticastInterface(this.interfaceAddress);
+          }
+        } catch (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      };
+
+      socket.once('error', onError);
+      socket.once('listening', onListening);
+      socket.bind(port, bindAddress);
+    });
+  }
+
   #onRemoteParticipantReady(busState, frame, value) {
     if (value.id !== busState.participantId) {
       return;

package/lib/sen.js

@@ -2,7 +2,7 @@ import { once } from 'node:events';
 import { EventEmitter } from 'node:events';
 import { decodePropertyValues, decodeValue, encodeArguments, decodeArguments } from './values.js';
 import { EtherClient } from './client.js';
-import { scan, scanTcpDiscoveryHub } from './discovery.js';
+import { EtherDiscoveryScanner, TcpDiscoveryHubScanner, scan, scanTcpDiscoveryHub } from './discovery.js';
 import { methodHash } from './hash32.js';
 
 function wait(ms) {
@@ -48,15 +48,24 @@ function queryBusName(sessionName, bus) {
   return text.includes('.') || !session ? text : `${session}.${text}`;
 }
 
-function findTarget(processes, options) {
-  let candidates = processes;
+function targetSessionName(target) {
+  return target?.session?.name ?? target?.info?.sessionName ?? '';
+}
+
+function filterTargets(processes, options = {}) {
+  let candidates = [...processes];
   if (options.session) {
-    candidates = candidates.filter(item => item.session?.name === options.session);
+    candidates = candidates.filter(item => targetSessionName(item) === options.session);
   }
   if (options.app) {
     const app = String(options.app).toLowerCase();
     candidates = candidates.filter(item => String(item.process?.appName || '').toLowerCase().includes(app));
   }
+  return candidates;
+}
+
+function findTarget(processes, options) {
+  const candidates = filterTargets(processes, options);
   if (!candidates.length) {
     return null;
   }
@@ -107,6 +116,19 @@ function sessionNameFromBusName(busName) {
   return idx > 0 ? text.slice(0, idx) : '';
 }
 
+function busSummary(sessionName, busName) {
+  const session = String(sessionName || '').trim();
+  const bus = etherBusName(session, busName);
+  if (!session || !bus) {
+    return null;
+  }
+  return {
+    session,
+    bus,
+    qualified: queryBusName(session, bus)
+  };
+}
+
 function selectorDescription(selector) {
   return typeof selector === 'function' ? '<predicate>' : String(selector);
 }
@@ -129,6 +151,24 @@ function normalizeTimestampNs(value) {
   return typeof value === 'bigint' ? value : BigInt(value);
 }
 
+function stateRequestKey(interestId, objectId) {
+  return `${interestId >>> 0}:${objectId >>> 0}`;
+}
+
+async function waitForSessionBuses(session, timeoutMs) {
+  let buses = session.listBuses();
+  if (buses.length || timeoutMs <= 0) {
+    return buses;
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  while (!buses.length && Date.now() < deadline) {
+    await wait(Math.min(50, Math.max(1, deadline - Date.now())));
+    buses = session.listBuses();
+  }
+  return buses;
+}
+
 class ChangeBatcher {
   constructor(interest, options = {}) {
     this.interest = interest;
@@ -251,19 +291,40 @@ export class Sen extends EventEmitter {
     return await sen.connect(options);
   }
 
+  /**
+   * Discover visible SEN buses without creating interests or joining buses.
+   *
+   * SEN discovery beams expose sessions/processes. Bus names are announced only
+   * after a lightweight process connection, so this method connects to each
+   * discovered session long enough to read its remote bus announcements.
+   *
+   * @param {object} [options]
+   * @returns {Promise<Array<{session:string,bus:string,qualified:string}>>}
+   */
+  static async discoverBuses(options = {}) {
+    const sen = new Sen(options);
+    try {
+      return await sen.discoverBuses(options);
+    } finally {
+      await sen.close().catch(() => {});
+    }
+  }
+
   constructor(options = {}) {
     super();
     this.options = {
       appName: 'sen-ether-client',
       reconnect: true,
       reconnectDelayMs: 500,
-      maxReconnectAttempts: 10,
+      maxReconnectAttempts: 0,
       timeout: 3000,
       discoverySettleMs: 100,
       participantReadyTimeoutMs: 1000,
       socketKeepAlive: true,
       socketKeepAliveInitialDelayMs: 1000,
       socketIdleTimeoutMs: 0,
+      presenceTimeoutMs: 5000,
+      presenceCheckIntervalMs: 1000,
       ...options
     };
     this.target = undefined;
@@ -271,9 +332,13 @@ export class Sen extends EventEmitter {
     this.connectOptions = undefined;
     this.manualClose = false;
     this.reconnecting = false;
+    this.presenceScanner = undefined;
+    this.presenceTimer = undefined;
+    this.presenceLastSeen = 0;
     this.remoteBuses = new Set();
     this.buses = new Map();
     this.sessions = new Map();
+    this.targets = [];
     this.targetsBySession = new Map();
   }
 
@@ -298,8 +363,9 @@ export class Sen extends EventEmitter {
       if (!targets.length) {
         throw new Error('no SEN ether processes discovered');
       }
+      this.targets = targets;
       for (const target of targets) {
-        const sessionName = target.session?.name ?? target.info?.sessionName;
+        const sessionName = targetSessionName(target);
         if (sessionName && !this.targetsBySession.has(sessionName)) {
           this.targetsBySession.set(sessionName, target);
         }
@@ -324,22 +390,43 @@ export class Sen extends EventEmitter {
     if (!sessionName) {
       throw new Error('cannot connect without a SEN session name');
     }
+    if (!this.targets.includes(target)) {
+      this.targets.push(target);
+    }
+    if (!this.targetsBySession.has(sessionName)) {
+      this.targetsBySession.set(sessionName, target);
+    }
 
     const client = new EtherClient({
       sessionName,
       appName: config.appName,
       socketKeepAlive: config.socketKeepAlive,
       socketKeepAliveInitialDelayMs: config.socketKeepAliveInitialDelayMs,
-      socketIdleTimeoutMs: config.socketIdleTimeoutMs
+      socketIdleTimeoutMs: config.socketIdleTimeoutMs,
+      interfaceAddress: config.interfaceAddress,
+      discoveryPort: config.port,
+      busMulticast: config.busMulticast,
+      busMulticastPort: config.busMulticastPort,
+      busMulticastRange: config.busMulticastRange
     });
     this.client = client;
     this.target = target;
     this.#wireClient(client);
 
-    await client.connect(target);
-    await waitForEvent(client, 'ready', config.timeout ?? 3000);
-    this.emit('connect', { target, sessionName });
-    return this;
+    try {
+      await client.connect(target);
+      await waitForEvent(client, 'ready', config.timeout ?? 3000);
+      this.#startPresenceWatchdog(target, config);
+      this.emit('connect', { target, sessionName });
+      return this;
+    } catch (error) {
+      await client.close().catch(closeError => this.emit('warning', closeError));
+      if (this.client === client) {
+        this.client = undefined;
+        this.target = undefined;
+      }
+      throw error;
+    }
   }
 
   /**
@@ -375,7 +462,7 @@ export class Sen extends EventEmitter {
 
     let senBus = this.buses.get(bus);
     if (!senBus) {
-      const joined = this.client.joinBus(bus);
+      const joined = await this.client.joinBus(bus);
       const participantReadyTimeoutMs = this.#participantReadyTimeout(options, timeout);
       await waitForEvent(this.client, 'busParticipantReady', participantReadyTimeoutMs).catch(error => {
         this.emit('warning', error);
@@ -429,7 +516,7 @@ export class Sen extends EventEmitter {
 
     let senBus = this.buses.get(bus);
     if (!senBus) {
-      const joined = this.client.joinBus(bus);
+      const joined = await this.client.joinBus(bus);
       const participantReadyTimeoutMs = this.#participantReadyTimeout(options, timeout);
       await waitForEvent(this.client, 'busParticipantReady', participantReadyTimeoutMs).catch(error => {
         this.emit('warning', error);
@@ -501,9 +588,10 @@ export class Sen extends EventEmitter {
     }
 
     return [...new Set([
+      ...this.targets.map(targetSessionName),
       ...this.targetsBySession.keys(),
       ...this.sessions.keys()
-    ])].sort();
+    ].filter(Boolean))].sort();
   }
 
   listBuses(options = {}) {
@@ -519,6 +607,104 @@ export class Sen extends EventEmitter {
       .map(busName => options.qualified ? queryBusName(sessionName, busName) : busName);
   }
 
+  /**
+   * Discover visible SEN buses without creating interests or joining buses.
+   *
+   * @param {object} [options]
+   * @param {string} [options.session] Optional session filter.
+   * @param {number} [options.busDiscoverySettleMs] Delay after lightweight session connect before reading announced buses.
+   * @returns {Promise<Array<{session:string,bus:string,qualified:string}>>}
+   */
+  async discoverBuses(options = {}) {
+    const config = { ...this.options, ...options };
+    const settleMs = Math.max(0, Number(config.busDiscoverySettleMs ?? Math.max(config.discoverySettleMs ?? 100, 1000)) || 0);
+
+    if (this.client) {
+      const sessionName = this.target?.session?.name ?? this.client.processInfo.sessionName;
+      return (await waitForSessionBuses(this, settleMs))
+        .map(busName => busSummary(sessionName, busName))
+        .filter(Boolean)
+        .sort((a, b) => a.qualified.localeCompare(b.qualified));
+    }
+
+    if (!this.targets.length && !this.sessions.size) {
+      const targets = await this.#discoverTargets(config);
+      if (!targets.length) {
+        throw new Error('no SEN ether processes discovered');
+      }
+      this.targets = targets;
+      for (const target of targets) {
+        const sessionName = targetSessionName(target);
+        if (sessionName && !this.targetsBySession.has(sessionName)) {
+          this.targetsBySession.set(sessionName, target);
+        }
+      }
+    }
+
+    const summaries = new Map();
+    const addBus = (sessionName, busName) => {
+      const summary = busSummary(sessionName, busName);
+      if (summary) {
+        summaries.set(summary.qualified, summary);
+      }
+    };
+
+    for (const session of this.sessions.values()) {
+      const sessionName = session.target?.session?.name ?? session.client?.processInfo?.sessionName;
+      for (const busName of await waitForSessionBuses(session, settleMs)) {
+        addBus(sessionName, busName);
+      }
+    }
+
+    const targets = filterTargets(this.targets, config);
+    const discoveries = targets.map(async target => {
+      const sessionName = targetSessionName(target);
+      if (!sessionName) {
+        return;
+      }
+
+      const session = new Sen({
+        ...config,
+        session: sessionName,
+        reconnect: false
+      });
+      session.on('warning', error => this.emit('warning', error));
+      session.on('error', error => this.emit('warning', error));
+      try {
+        await session.connect({
+          ...config,
+          session: sessionName,
+          target,
+          reconnect: false
+        });
+        for (const busName of await waitForSessionBuses(session, settleMs)) {
+          addBus(sessionName, busName);
+        }
+      } finally {
+        await session.close().catch(error => this.emit('warning', error));
+      }
+    });
+
+    const results = await Promise.allSettled(discoveries);
+    const failures = [];
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        failures.push(result.reason);
+        this.emit('warning', result.reason);
+      }
+    }
+
+    if (!summaries.size && targets.length && failures.length === targets.length) {
+      const sessions = [...new Set(targets.map(targetSessionName).filter(Boolean))].join(', ');
+      const error = new Error(`could not read SEN bus announcements from any discovered target${sessions ? ` in sessions: ${sessions}` : ''}`);
+      error.code = 'SEN_BUS_DISCOVERY_FAILED';
+      error.cause = failures[0];
+      throw error;
+    }
+
+    return [...summaries.values()].sort((a, b) => a.qualified.localeCompare(b.qualified));
+  }
+
   objects() {
     if (!this.client) {
       return [...this.sessions.values()].flatMap(session => session.objects());
@@ -561,13 +747,14 @@ export class Sen extends EventEmitter {
   async close() {
     this.manualClose = true;
     for (const session of this.sessions.values()) {
-      await session.close();
+      await session.close().catch(error => this.emit('warning', error));
     }
     for (const bus of this.buses.values()) {
       bus.close();
     }
+    this.#stopPresenceWatchdog();
     await wait(50);
-    await this.client?.close();
+    await this.client?.close().catch(error => this.emit('warning', error));
     this.client = undefined;
     this.sessions.clear();
     this.buses.clear();
@@ -675,9 +862,10 @@ export class Sen extends EventEmitter {
       this.emit('error', error);
     });
     client.on('close', hadError => {
+      this.#stopPresenceWatchdog();
       this.emit('close', hadError);
       if (!this.manualClose && this.options.reconnect !== false) {
-        this.#reconnect().catch(error => this.emit('error', error));
+        this.#reconnect().catch(error => this.emit('warning', error));
       }
     });
   }
@@ -688,12 +876,15 @@ export class Sen extends EventEmitter {
     }
 
     this.reconnecting = true;
+    this.#stopPresenceWatchdog();
     await this.client?.close().catch(error => this.emit('warning', error));
     this.emit('reconnecting');
-    const maxAttempts = this.connectOptions.maxReconnectAttempts ?? this.options.maxReconnectAttempts ?? 10;
+    const configuredMaxAttempts = this.connectOptions.maxReconnectAttempts ?? this.options.maxReconnectAttempts ?? 0;
+    const maxAttempts = Number(configuredMaxAttempts);
+    const unlimited = !Number.isFinite(maxAttempts) || maxAttempts <= 0;
     const delayMs = this.connectOptions.reconnectDelayMs ?? this.options.reconnectDelayMs ?? 500;
 
-    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    for (let attempt = 1; unlimited || attempt <= maxAttempts; attempt += 1) {
       let client;
       try {
         await wait(delayMs);
@@ -727,6 +918,7 @@ export class Sen extends EventEmitter {
 
         await client.connect(target);
         await waitForEvent(client, 'ready', config.timeout ?? 3000);
+        this.#startPresenceWatchdog(target, config);
 
         for (const bus of this.buses.values()) {
           await bus.rejoin(config.timeout ?? 3000);
@@ -737,6 +929,10 @@ export class Sen extends EventEmitter {
         return;
       } catch (error) {
         await client?.close().catch(closeError => this.emit('warning', closeError));
+        if (this.client === client) {
+          this.client = undefined;
+          this.target = undefined;
+        }
         if (this.manualClose) {
           this.reconnecting = false;
           return;
@@ -754,6 +950,74 @@ export class Sen extends EventEmitter {
     throw new Error(`failed to reconnect SEN ether after ${maxAttempts} attempt(s)`);
   }
 
+  #startPresenceWatchdog(target, config) {
+    this.#stopPresenceWatchdog();
+    const key = target?.key;
+    if (!key) {
+      return;
+    }
+
+    const timeoutMs = Number(config.presenceTimeoutMs ?? this.options.presenceTimeoutMs ?? 0);
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      return;
+    }
+
+    const intervalMs = Math.max(
+      250,
+      Number(config.presenceCheckIntervalMs ?? this.options.presenceCheckIntervalMs ?? 1000) || 1000
+    );
+
+    const scanner = config.tcpHub
+      ? new TcpDiscoveryHubScanner(parseHostPort(config.tcpHub))
+      : new EtherDiscoveryScanner(config);
+
+    this.presenceScanner = scanner;
+    this.presenceLastSeen = Date.now();
+
+    scanner.on('beam', process => {
+      if (process.key === key) {
+        this.presenceLastSeen = Date.now();
+      }
+    });
+    scanner.on('error', error => this.emit('warning', error));
+    scanner.on('close', hadError => {
+      if (!this.manualClose && !this.reconnecting) {
+        this.emit('warning', new Error(`SEN ether discovery watchdog closed${hadError ? ' with error' : ''}`));
+      }
+    });
+    scanner.start().catch(error => this.emit('warning', error));
+
+    this.presenceTimer = setInterval(() => {
+      if (this.manualClose || this.reconnecting || !this.client) {
+        return;
+      }
+      const elapsedMs = Date.now() - this.presenceLastSeen;
+      if (elapsedMs <= timeoutMs) {
+        return;
+      }
+      const error = new Error(`SEN ether presence timeout after ${elapsedMs}ms without beam from ${key}`);
+      error.code = 'SEN_PRESENCE_TIMEOUT';
+      this.emit('warning', error);
+      this.client.socket?.destroy(error);
+    }, intervalMs);
+    this.presenceTimer.unref?.();
+  }
+
+  #stopPresenceWatchdog() {
+    if (this.presenceTimer) {
+      clearInterval(this.presenceTimer);
+      this.presenceTimer = undefined;
+    }
+
+    const scanner = this.presenceScanner;
+    this.presenceScanner = undefined;
+    this.presenceLastSeen = 0;
+    if (scanner) {
+      scanner.removeAllListeners();
+      scanner.stop().catch(error => this.emit('warning', error));
+    }
+  }
+
   #busForEvent(event) {
     if (event.bus?.busName) {
       return this.buses.get(event.bus.busName);
@@ -814,18 +1078,29 @@ export class SenBus extends EventEmitter {
     const interestId = typeof id === 'object' ? id.id : id;
     this.sen.client.stopInterest(this.name, interestId);
     const interest = this.interests.get(interestId);
+    this.#detachInterestObjects(interestId, interest);
     this.interests.delete(interestId);
     interest?.closeLocal();
     interest?.emit('close');
   }
 
   close() {
-    for (const interest of this.interests.values()) {
-      interest.closeLocal();
-      this.sen.client.stopInterest(this.name, interest.id);
+    for (const interest of [...this.interests.values()]) {
+      try {
+        this.stopInterest(interest.id);
+      } catch (error) {
+        this.#detachInterestObjects(interest.id, interest);
+        this.interests.delete(interest.id);
+        interest.closeLocal();
+        interest.emit('close');
+        this.sen.emit('warning', error);
+      }
+    }
+    try {
+      this.sen.client.leaveBus(this.name);
+    } catch (error) {
+      this.sen.emit('warning', error);
     }
-    this.interests.clear();
-    this.sen.client.leaveBus(this.name);
   }
 
   prepareReconnect() {
@@ -854,7 +1129,7 @@ export class SenBus extends EventEmitter {
     await this.sen.waitForRemoteBus(this.name, busReadyTimeoutMs).catch(error => {
       this.sen.emit('warning', error);
     });
-    const joined = this.sen.client.joinBus(this.name);
+    const joined = await this.sen.client.joinBus(this.name);
     this.id = joined.busId;
     const participantReadyTimeoutMs = Math.min(timeoutMs, this.sen.options.participantReadyTimeoutMs ?? 1000);
     await waitForEvent(this.sen.client, 'busParticipantReady', participantReadyTimeoutMs).catch(error => {
@@ -884,24 +1159,36 @@ export class SenBus extends EventEmitter {
     const newTypeHashes = new Set();
     for (const discovery of event.discoveries ?? []) {
       for (const info of discovery.objects ?? []) {
-        const object = new SenRemoteObject(this, {
-          ...info,
-          ownerId: event.ownerId,
-          interestId: discovery.interestId
-        });
-        this.objectsById.set(object.id, object);
+        let object = this.objectsById.get(info.id);
+        const isNewObject = !object;
+        if (!object) {
+          object = new SenRemoteObject(this, {
+            ...info,
+            ownerId: event.ownerId,
+            interestId: discovery.interestId
+          });
+          this.objectsById.set(object.id, object);
+        } else {
+          object.attachInterest(discovery.interestId);
+          object.updateDiscoveryInfo({
+            ...info,
+            ownerId: event.ownerId
+          });
+        }
         const interest = this.interests.get(discovery.interestId);
         interest?.objectsById.set(object.id, object);
         if (info.state?.length) {
-          object.applyState(info.state, 'state', info.time);
+          object.applyState(info.state, 'state', info.time, { interestId: discovery.interestId });
         }
         if (!this.requestedTypeHashes.has(info.typeHash)) {
           this.requestedTypeHashes.add(info.typeHash);
           newTypeHashes.add(info.typeHash);
         }
         interest?.emit('object', object);
-        this.emit('object', object);
-        this.sen.emit('object', object);
+        if (isNewObject) {
+          this.emit('object', object);
+          this.sen.emit('object', object);
+        }
       }
     }
     if (newTypeHashes.size) {
@@ -914,20 +1201,47 @@ export class SenBus extends EventEmitter {
     for (const removal of event.removals ?? []) {
       for (const id of removal.ids ?? []) {
         const object = this.objectsById.get(id);
-        this.objectsById.delete(id);
-        this.stateRequestedObjectIds.delete(id);
         const interest = this.interests.get(removal.interestId);
         interest?.objectsById.delete(id);
+        this.stateRequestedObjectIds.delete(stateRequestKey(removal.interestId, id));
         if (object) {
-          object.emit('remove');
+          object.detachInterest(removal.interestId);
+          object.emit('remove', { interestId: removal.interestId });
           interest?.emit('remove', object);
-          this.emit('remove', object);
-          this.sen.emit('remove', object);
+          if (object.interestIds.size === 0) {
+            this.objectsById.delete(id);
+            this.requestedTypeHashes.delete(object.typeHash);
+            this.emit('remove', object);
+            this.sen.emit('remove', object);
+          }
         }
       }
     }
   }
 
+  #detachInterestObjects(interestId, interest) {
+    const normalizedInterestId = interestId >>> 0;
+    const keyPrefix = `${normalizedInterestId}:`;
+    for (const key of [...this.stateRequestedObjectIds]) {
+      if (key.startsWith(keyPrefix)) {
+        this.stateRequestedObjectIds.delete(key);
+      }
+    }
+
+    if (!interest) {
+      return;
+    }
+
+    for (const object of interest.objectsById.values()) {
+      object.detachInterest(normalizedInterestId);
+      if (object.interestIds.size === 0) {
+        this.objectsById.delete(object.id);
+        this.requestedTypeHashes.delete(object.typeHash);
+      }
+    }
+    interest.objectsById.clear();
+  }
+
   handleTypesInfoResponse(event) {
     const dependentTypeHashes = new Set();
     for (const type of event.types ?? []) {
@@ -962,7 +1276,7 @@ export class SenBus extends EventEmitter {
         if (!object) {
           continue;
         }
-        object.applyState(state.state, 'state', state.timestamp);
+        object.applyState(state.state, 'state', state.timestamp, { interestId: response.interestId });
       }
     }
   }
@@ -1042,14 +1356,20 @@ export class SenBus extends EventEmitter {
 
   #requestReadyObjectStates() {
     const requestsByInterest = new Map();
-    for (const object of this.objectsById.values()) {
-      if (this.stateRequestedObjectIds.has(object.id) || !object.spec) {
-        continue;
+    for (const interest of this.interests.values()) {
+      for (const object of interest.objectsById.values()) {
+        if (!object.spec) {
+          continue;
+        }
+        const key = stateRequestKey(interest.id, object.id);
+        if (this.stateRequestedObjectIds.has(key)) {
+          continue;
+        }
+        this.stateRequestedObjectIds.add(key);
+        const ids = requestsByInterest.get(interest.id) ?? [];
+        ids.push(object.id);
+        requestsByInterest.set(interest.id, ids);
       }
-      this.stateRequestedObjectIds.add(object.id);
-      const ids = requestsByInterest.get(object.interestId) ?? [];
-      ids.push(object.id);
-      requestsByInterest.set(object.interestId, ids);
     }
 
     if (requestsByInterest.size) {
@@ -1066,7 +1386,8 @@ export class SenBus extends EventEmitter {
         object.applyState(
           object.pendingState.buffer,
           object.pendingState.source,
-          object.pendingState.timestampNs
+          object.pendingState.timestampNs,
+          { interestId: object.pendingState.interestId }
         );
       }
     }
@@ -1164,6 +1485,10 @@ export class SenRemoteObject extends EventEmitter {
     this.typeHash = info.typeHash;
     this.ownerId = info.ownerId;
     this.interestId = info.interestId;
+    this.interestIds = new Set();
+    if (info.interestId !== undefined) {
+      this.interestIds.add(info.interestId);
+    }
     this.snapshot = {};
     this.spec = undefined;
     this.pendingState = undefined;
@@ -1186,6 +1511,29 @@ export class SenRemoteObject extends EventEmitter {
     return this.name === selector || this.className === selector || String(this.id) === String(selector);
   }
 
+  attachInterest(interestId) {
+    if (interestId !== undefined) {
+      this.interestIds.add(interestId);
+      this.interestId = interestId;
+    }
+  }
+
+  detachInterest(interestId) {
+    if (interestId !== undefined) {
+      this.interestIds.delete(interestId);
+      if (this.interestId === interestId) {
+        this.interestId = this.interestIds.values().next().value;
+      }
+    }
+  }
+
+  updateDiscoveryInfo(info) {
+    this.name = info.name ?? this.name;
+    this.className = info.className ?? this.className;
+    this.typeHash = info.typeHash ?? this.typeHash;
+    this.ownerId = info.ownerId ?? this.ownerId;
+  }
+
   property(name) {
     return findByName(collectClassMembers(this.spec, this.bus.typeRegistry, 'properties'), name);
   }
@@ -1259,17 +1607,18 @@ export class SenRemoteObject extends EventEmitter {
     return await this.bus.callObjectMethod(this, method, args, options);
   }
 
-  applyState(buffer, source, timestamp) {
+  applyState(buffer, source, timestamp, options = {}) {
     const timestampNs = normalizeTimestampNs(timestamp);
     this.#rememberObjectTimestamp(source, timestampNs);
 
     if (!this.spec) {
-      this.pendingState = { buffer, source, timestampNs };
+      this.pendingState = { buffer, source, timestampNs, interestId: options.interestId };
       return;
     }
 
-    const interest = this.bus.interests.get(this.interestId);
-    const values = decodePropertyValues(buffer, this.spec, this.bus.typeRegistry, interest?.decodeOptions());
+    const interests = this.#targetInterests(options.interestId);
+    const decodeInterest = options.interestId !== undefined || interests.length === 1 ? interests[0] : undefined;
+    const values = decodePropertyValues(buffer, this.spec, this.bus.typeRegistry, decodeInterest?.decodeOptions());
     let complete = true;
     for (const value of values) {
       if (!value.decoded) {
@@ -1292,9 +1641,10 @@ export class SenRemoteObject extends EventEmitter {
         previous,
         property: value.property
       };
-      if (interest) {
+      for (const interest of interests) {
         interest.publishChange(change);
-      } else {
+      }
+      if (!interests.length) {
         this.emit('change', change);
         this.emit(`change:${value.name}`, change);
         this.bus.emit('change', change);
@@ -1302,7 +1652,22 @@ export class SenRemoteObject extends EventEmitter {
       }
     }
 
-    this.pendingState = complete ? undefined : { buffer, source, timestampNs };
+    this.pendingState = complete ? undefined : { buffer, source, timestampNs, interestId: options.interestId };
+  }
+
+  #targetInterests(interestId) {
+    if (interestId !== undefined) {
+      const interest = this.bus.interests.get(interestId);
+      return interest ? [interest] : [];
+    }
+
+    const interests = [];
+    for (const interest of this.bus.interests.values()) {
+      if (interest.objectsById.has(this.id)) {
+        interests.push(interest);
+      }
+    }
+    return interests;
   }
 
   #rememberObjectTimestamp(source, timestampNs) {

package/lib/values.js

@@ -70,9 +70,7 @@ function collectClassProperties(spec, typeRegistry, seen = new Set()) {
 
 function decodeEnum(reader, spec) {
   const storage = spec.data.value.storageType;
-  const key = decodeValueFromReader(reader, storage);
-  const item = spec.data.value.enums.find(candidate => candidate.key === key);
-  return item?.name ?? key;
+  return decodeValueFromReader(reader, storage);
 }
 
 function decodeStruct(reader, spec, typeRegistry) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sen-ether-client",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pure JavaScript SEN client for existing kernels over ether",
   "senCompatibility": {
     "kernelProtocolVersion": 9,