@band-ai/sdk 0.3.4 → 0.4.1

package/dist/{chunk-U6AFCLYZ.js → chunk-6TGXV5TE.js}

@@ -4,21 +4,22 @@ import {
   SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
   SYNTHETIC_SENDER_TYPE,
   buildParticipantsMessage,
+  createDeferred,
   toParticipantRecord,
   toParticipantRecordFromRest
-} from "./chunk-OH6VVVKT.js";
+} from "./chunk-CBCHTTUY.js";
 import {
   CHAT_TOOL_NAMES,
   MEMORY_LIST_SCOPES,
   MEMORY_SEGMENTS,
   MEMORY_STATUSES,
+  MEMORY_STORE_SCOPE,
   MEMORY_STORE_SCOPES,
   MEMORY_SYSTEMS,
   MEMORY_TOOL_NAMES,
   MEMORY_TYPES,
   TOOL_MODELS,
   expectedList,
-  expectedMemoryTypesForSystem,
   getToolDescription,
   isMemoryListScope,
   isMemorySegment,
@@ -28,37 +29,148 @@ import {
   isMemoryType,
   isMemoryTypeForSystem,
   memoryTypeForSystemError
-} from "./chunk-MQY74R7D.js";
-import {
-  CHAT_EVENT_TYPES,
-  assertChatEventType
-} from "./chunk-F63TPOI3.js";
+} from "./chunk-SHZBLLDQ.js";
 import {
   WebSocketDisconnectError,
   genericCloseReason,
   parseSupersedeDisconnectReason,
   parseUpgradeDisconnectReason
-} from "./chunk-US226AS4.js";
+} from "./chunk-UENIC5FJ.js";
 import {
   DEFAULT_REQUEST_OPTIONS,
   FernRestAdapter,
   fetchPaginated
-} from "./chunk-W5IAI6Z4.js";
+} from "./chunk-OVXVZUPO.js";
+import {
+  asErrorMessage
+} from "./chunk-6BE2EG5P.js";
 import {
+  CHAT_EVENT_TYPES,
   DEFAULT_AGENT_TOOLS_CAPABILITIES,
+  assertChatEventType,
   createToolExecutorError,
   isStructuredToolFailure,
-  isToolExecutorError
-} from "./chunk-JADCAMZY.js";
+  isToolExecutorError,
+  sendFailureViaEvent
+} from "./chunk-TGDDFBYS.js";
 import {
-  NoopLogger
-} from "./chunk-OD2G5LFQ.js";
+  resolveLogger
+} from "./chunk-ZYOXI4JL.js";
 import {
+  RecoverableTurnError,
   RuntimeStateError,
   TransportError,
   UnsupportedFeatureError,
   ValidationError
-} from "./chunk-JY75VSQK.js";
+} from "./chunk-4OVNFDD7.js";
+
+// src/core/singleFlight.ts
+var SingleFlight = class {
+  pending = null;
+  /** The currently in-flight operation's promise, if any is running. */
+  get current() {
+    return this.pending;
+  }
+  run(start) {
+    if (!this.pending) {
+      const promise = start();
+      this.pending = promise;
+      const clear = () => {
+        if (this.pending === promise) {
+          this.pending = null;
+        }
+      };
+      void promise.then(clear, clear);
+    }
+    return this.pending;
+  }
+};
+var KeyedSingleFlight = class {
+  flights = /* @__PURE__ */ new Map();
+  /** The currently in-flight operation's promise for `key`, if any is running. */
+  current(key) {
+    return this.flights.get(key)?.current ?? null;
+  }
+  run(key, start) {
+    let flight = this.flights.get(key);
+    if (!flight) {
+      flight = new SingleFlight();
+      this.flights.set(key, flight);
+    }
+    const promise = flight.run(start);
+    const forget = () => {
+      if (this.flights.get(key) === flight && !flight.current) {
+        this.flights.delete(key);
+      }
+    };
+    void promise.then(forget, forget);
+    return promise;
+  }
+  /** Drops every key without waiting for its in-flight operation to settle. */
+  clear() {
+    this.flights.clear();
+  }
+};
+var Serializer = class {
+  tail = Promise.resolve();
+  run(body) {
+    const run = this.tail.then(body, body);
+    this.tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+};
+
+// src/core/epoch.ts
+var Epoch = class {
+  value = 0;
+  get current() {
+    return this.value;
+  }
+  /** Advances to the next generation and returns it. */
+  bump() {
+    this.value += 1;
+    return this.value;
+  }
+  isStale(captured) {
+    return captured !== this.value;
+  }
+};
+
+// src/platform/Session.ts
+var Session = class {
+  epoch = new Epoch();
+  active = false;
+  /**
+   * Teardown for whatever reconnect observer this session registered on the
+   * transport — a plain field since a caller just assigns whatever
+   * `onReconnected()` handed back (or `null` if the transport has none).
+   */
+  reconnectObserverTeardown = null;
+  get isActive() {
+    return this.active;
+  }
+  isStale(epoch) {
+    return this.epoch.isStale(epoch);
+  }
+  /** Starts a new session and returns its epoch. */
+  begin() {
+    const epoch = this.epoch.bump();
+    this.active = true;
+    return epoch;
+  }
+  /** Marks the session inactive and advances the epoch, so any work still in flight for it is now stale. */
+  deactivate() {
+    this.active = false;
+    this.epoch.bump();
+  }
+  clearReconnectObserver() {
+    this.reconnectObserverTeardown?.();
+    this.reconnectObserverTeardown = null;
+  }
+};
 
 // src/contracts/capabilities.ts
 var CAPABILITY_LABELS = {
@@ -72,104 +184,213 @@ function assertCapability(capabilities, capability, label = CAPABILITY_LABELS[ca
   }
 }
 
-// src/platform/streaming/payloadSchemas.ts
-import { z } from "zod";
-var mentionSchema = z.object({
-  id: z.string(),
-  handle: z.string().nullish(),
-  name: z.string().nullish(),
-  username: z.string().nullish()
-}).passthrough();
-var messageMetadataSchema = z.object({
-  mentions: z.array(mentionSchema).nullish()
-}).passthrough();
-var messageCreatedPayloadSchema = z.object({
-  id: z.string(),
-  content: z.string(),
-  message_type: z.string(),
-  metadata: messageMetadataSchema.nullish(),
-  sender_id: z.string(),
-  sender_type: z.string(),
-  sender_name: z.string().nullish(),
-  chat_room_id: z.string().nullish(),
-  inserted_at: z.string(),
-  updated_at: z.string()
-}).passthrough();
-var roomOwnerSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  type: z.string()
-}).passthrough();
-var roomAddedPayloadSchema = z.object({
-  id: z.string(),
-  title: z.string().nullish(),
-  task_id: z.string().nullish(),
-  inserted_at: z.string().nullish(),
-  updated_at: z.string().nullish(),
-  owner: roomOwnerSchema.nullish(),
-  status: z.string().nullish(),
-  type: z.string().nullish(),
-  created_at: z.string().nullish(),
-  participant_role: z.string().nullish()
-}).passthrough();
-var roomRemovedPayloadSchema = z.object({
-  id: z.string(),
-  status: z.string(),
-  type: z.string(),
-  title: z.string(),
-  removed_at: z.string()
-}).passthrough();
-var participantAddedPayloadSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  type: z.string(),
-  handle: z.string().nullish()
-}).passthrough();
-var participantRemovedPayloadSchema = z.object({
-  id: z.string()
-}).passthrough();
-var roomDeletedPayloadSchema = z.object({
-  id: z.string()
-}).passthrough();
-var contactRequestReceivedPayloadSchema = z.object({
-  id: z.string(),
-  from_handle: z.string(),
-  from_name: z.string(),
-  message: z.string().nullish(),
-  status: z.string(),
-  inserted_at: z.string()
-}).passthrough();
-var contactRequestUpdatedPayloadSchema = z.object({
-  id: z.string(),
-  status: z.string()
-}).passthrough();
-var contactAddedPayloadSchema = z.object({
-  id: z.string(),
-  handle: z.string(),
-  name: z.string(),
-  type: z.string(),
-  description: z.string().nullish(),
-  is_external: z.boolean().nullish(),
-  inserted_at: z.string()
-}).passthrough();
-var contactRemovedPayloadSchema = z.object({
-  id: z.string()
-}).passthrough();
-var payloadSchemas = {
-  message_created: messageCreatedPayloadSchema,
-  room_added: roomAddedPayloadSchema,
-  room_removed: roomRemovedPayloadSchema,
-  participant_added: participantAddedPayloadSchema,
-  participant_removed: participantRemovedPayloadSchema,
-  room_deleted: roomDeletedPayloadSchema,
-  contact_request_received: contactRequestReceivedPayloadSchema,
-  contact_request_updated: contactRequestUpdatedPayloadSchema,
-  contact_added: contactAddedPayloadSchema,
-  contact_removed: contactRemovedPayloadSchema
-};
-
 // src/platform/streaming/PhoenixChannelsTransport.ts
-import { Socket } from "phoenix";
+import { Socket as Socket2 } from "phoenix";
+
+// src/core/teardown.ts
+async function isolateTeardown(errors, step) {
+  try {
+    await step();
+  } catch (error) {
+    errors.push(error);
+  }
+}
+function combineTeardownErrors(errors, message) {
+  const distinct = [...new Set(errors)];
+  return distinct.length === 1 ? distinct[0] : new AggregateError(distinct, message);
+}
+
+// src/platform/streaming/ChannelRegistry.ts
+import "phoenix";
+function supersededJoinError(topic) {
+  return new TransportError(`Join superseded by transport disconnect for topic ${topic}`);
+}
+var ChannelRegistry = class {
+  constructor(socket, epoch, logger, hooks) {
+    this.socket = socket;
+    this.epoch = epoch;
+    this.logger = logger;
+    this.hooks = hooks;
+  }
+  channels = /* @__PURE__ */ new Map();
+  // A join's Channel and handler bindings, tracked from the moment doJoin
+  // creates them — before the join Push settles — so a teardown mid-join can
+  // find and detach it too, not only joins already promoted into `channels`.
+  // Left untracked here, the underlying Phoenix Channel would survive
+  // teardown unnoticed, keep its handlers bound, and could later be
+  // resurrected by Phoenix's own reconnect machinery, redelivering live
+  // events with no dedup anywhere upstream.
+  pendingChannels = /* @__PURE__ */ new Map();
+  joinFlights = new KeyedSingleFlight();
+  leaveFlights = new KeyedSingleFlight();
+  topics() {
+    return this.channels.keys();
+  }
+  isJoined(topic) {
+    return this.channels.has(topic);
+  }
+  /**
+   * A promise for `topic` if it's already joined or has a join in flight,
+   * without starting a new one. A topic mid-leave is never reported as
+   * already joined — `channels` still holds it until the leave's Push
+   * settles, but its handlers are already unbound and the channel is about
+   * to be removed, so treating that window as "joined" would hand the
+   * caller a promise that resolves into a channel already gone.
+   */
+  existingJoin(topic) {
+    if (this.channels.has(topic) && !this.leaveFlights.current(topic)) {
+      return Promise.resolve();
+    }
+    return this.joinFlights.current(topic) ?? void 0;
+  }
+  /**
+   * Starts a new join for `topic`. Callers check `existingJoin()` first.
+   * Waits out a leave already in flight for the same topic before starting,
+   * so the new join's channel is never raced by the old one's teardown.
+   */
+  async join(topic, handlers) {
+    const pendingLeave = this.leaveFlights.current(topic);
+    if (pendingLeave) {
+      await pendingLeave.catch(() => void 0);
+    }
+    return this.joinFlights.run(topic, () => this.doJoin(topic, handlers));
+  }
+  async doJoin(topic, handlers) {
+    const epoch = this.epoch.current;
+    const channel = this.socket.channel(topic, {});
+    const refs = [];
+    for (const [event, handler] of Object.entries(handlers)) {
+      const ref = channel.on(event, this.hooks.wrapHandler(topic, event, handler));
+      refs.push([event, ref]);
+    }
+    const joinPush = channel.join();
+    try {
+      await new Promise((resolve, reject) => {
+        this.pendingChannels.set(topic, { channel, refs, reject });
+        joinPush.receive("ok", () => {
+          this.hooks.onJoinSettled(topic, true);
+          resolve();
+        }).receive("error", (error) => {
+          this.hooks.onJoinSettled(topic, false);
+          reject(new TransportError(`Failed to join topic ${topic}`, error));
+        }).receive("timeout", () => {
+          this.hooks.onJoinSettled(topic, false);
+          reject(new TransportError(`Timeout joining topic ${topic}`));
+        });
+      });
+    } catch (error) {
+      const pending2 = this.forgetPendingChannel(topic, channel);
+      if (pending2) {
+        this.abandonChannel(topic, pending2);
+      }
+      throw error;
+    }
+    const pending = this.forgetPendingChannel(topic, channel);
+    if (!pending || this.epoch.isStale(epoch)) {
+      if (pending) {
+        this.abandonChannel(topic, pending);
+      }
+      this.logger.debug("Join superseded by transport disconnect/reconnect", { topic });
+      throw supersededJoinError(topic);
+    }
+    this.channels.set(topic, { channel, refs });
+    this.logger.debug("Joined topic", { topic });
+  }
+  /**
+   * Removes and returns `topic`'s pendingChannels entry only if it still
+   * points at `channel`. A topic-keyed delete without this identity check
+   * can drop a *different*, still-genuinely-pending join for the same topic
+   * — reachable because a teardown clears `joinFlights`, so a later join for
+   * a topic whose earlier join is still unsettled is possible, and that
+   * earlier join's eventual (stale) settlement must not touch a slot it no
+   * longer owns.
+   */
+  forgetPendingChannel(topic, channel) {
+    const pending = this.pendingChannels.get(topic);
+    if (pending?.channel !== channel) {
+      return void 0;
+    }
+    this.pendingChannels.delete(topic);
+    return pending;
+  }
+  /**
+   * Detaches a join's channel and — via `pending.reject` — settles its
+   * still-outstanding join promise directly, so abandoning it can never
+   * leave `doJoin()`'s awaiter hanging on a Phoenix reply that a `leave()`
+   * just made unroutable.
+   */
+  abandonChannel(topic, pending) {
+    for (const [event, ref] of pending.refs) {
+      pending.channel.off(event, ref);
+    }
+    pending.channel.leave();
+    removeSocketChannel(this.socket, pending.channel);
+    pending.reject(supersededJoinError(topic));
+  }
+  async leave(topic) {
+    const pendingLeave = this.leaveFlights.current(topic);
+    if (pendingLeave) {
+      return pendingLeave;
+    }
+    const tracked = this.channels.get(topic);
+    if (!tracked) {
+      return;
+    }
+    return this.leaveFlights.run(topic, () => this.doLeave(topic, tracked));
+  }
+  async doLeave(topic, tracked) {
+    const { channel, refs } = tracked;
+    for (const [event, ref] of refs) {
+      channel.off(event, ref);
+    }
+    await new Promise((resolve, reject) => {
+      channel.leave().receive("ok", () => resolve()).receive(
+        "error",
+        (error) => reject(new TransportError(`Failed to leave topic ${topic}`, error))
+      ).receive(
+        "timeout",
+        () => reject(new TransportError(`Timeout leaving topic ${topic}`))
+      );
+    });
+    this.channels.delete(topic);
+    this.hooks.onLeft(topic);
+    this.logger.debug("Left topic", { topic });
+  }
+  /**
+   * Attempts a graceful leave for every currently joined topic. A leave that
+   * fails leaves its channel registered until `forceTeardown()` sweeps it.
+   * Returns the rejection reasons of any leaves that failed.
+   */
+  async leaveAll() {
+    const topics = [...this.channels.keys()];
+    const results = await Promise.allSettled(topics.map((topic) => this.leave(topic)));
+    return results.filter((result) => result.status === "rejected").map((result) => result.reason);
+  }
+  /**
+   * Forcibly detaches anything still registered — a leave that failed above,
+   * or a join still in flight — and clears all coalescing state. Call after
+   * `leaveAll()` has settled.
+   */
+  forceTeardown() {
+    for (const { channel, refs } of this.channels.values()) {
+      for (const [event, ref] of refs) {
+        channel.off(event, ref);
+      }
+      removeSocketChannel(this.socket, channel);
+    }
+    this.channels.clear();
+    for (const [topic, pending] of this.pendingChannels) {
+      this.abandonChannel(topic, pending);
+    }
+    this.pendingChannels.clear();
+    this.joinFlights.clear();
+    this.leaveFlights.clear();
+  }
+};
+function removeSocketChannel(socket, channel) {
+  const candidate = socket;
+  candidate.remove?.(channel);
+}
 
 // src/platform/streaming/nodeWebSocketFactory.ts
 import { WebSocket as NodeWebSocket } from "ws";
@@ -206,19 +427,90 @@ async function readResponseBody(response) {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+// src/platform/streaming/ReconnectGenerationTracker.ts
+var ReconnectGenerationTracker = class {
+  constructor(onSettled, onGenerationDropped) {
+    this.onSettled = onSettled;
+    this.onGenerationDropped = onGenerationDropped;
+  }
+  generations = /* @__PURE__ */ new Map();
+  currentGeneration = 0;
+  beginGeneration(topics) {
+    const generation = ++this.currentGeneration;
+    const attempted = new Set(topics);
+    for (const staleGeneration of this.generations.keys()) {
+      if (staleGeneration < generation) {
+        const stale = this.generations.get(staleGeneration);
+        if (stale) {
+          this.onGenerationDropped?.(staleGeneration, stale.pending.size);
+          this.generations.delete(staleGeneration);
+        }
+      }
+    }
+    this.generations.set(generation, { pending: new Set(attempted), attempted, joined: /* @__PURE__ */ new Set() });
+    this.maybeFinalize(generation);
+    return generation;
+  }
+  recordSettled(topic, joined) {
+    const record = this.generations.get(this.currentGeneration);
+    if (!record?.pending.delete(topic)) {
+      return;
+    }
+    if (joined) {
+      record.joined.add(topic);
+    }
+    this.maybeFinalize(this.currentGeneration);
+  }
+  removeTopic(topic) {
+    for (const [generation, record] of this.generations) {
+      if (record.pending.delete(topic)) {
+        this.maybeFinalize(generation);
+      }
+    }
+  }
+  reset() {
+    this.generations.clear();
+    this.currentGeneration = 0;
+  }
+  maybeFinalize(generation) {
+    const record = this.generations.get(generation);
+    if (!record || record.pending.size > 0) {
+      return;
+    }
+    this.generations.delete(generation);
+    this.onSettled({ generation, attemptedTopics: record.attempted, joinedTopics: record.joined });
+  }
+};
+
 // src/platform/streaming/PhoenixChannelsTransport.ts
 import { agentControlTopic } from "@band-ai/band-sdk-core";
 var PhoenixChannelsTransport = class {
   socket;
   agentId;
-  channels = /* @__PURE__ */ new Map();
-  channelRefs = /* @__PURE__ */ new Map();
-  pendingJoins = /* @__PURE__ */ new Map();
+  registry;
+  reconnectObservers = /* @__PURE__ */ new Set();
+  // Topics joined with `{ exemptFromBuffering: true }`, recorded here so
+  // `wrapHandler` can check by name on every delivered event rather than
+  // threading the flag through the channel/handler plumbing.
+  bufferingExemptTopics = /* @__PURE__ */ new Set();
+  generationTracker = new ReconnectGenerationTracker(
+    (snapshot) => this.notifyReconnectObservers(snapshot),
+    (generation, pendingTopics) => this.logger.debug("Superseded reconnect generation before it fully settled", {
+      generation,
+      pendingTopics
+    })
+  );
+  bufferedTopicEvents = [];
+  hasOpenedOnce = false;
+  epoch = new Epoch();
+  bufferingGeneration = null;
+  reconnectBarrier = null;
+  observerChain = new Serializer();
   logger;
   onTerminalDisconnect;
   onHandlerError;
   connected = false;
-  connectPromise = null;
+  connectFlight = new SingleFlight();
   connectResolve = null;
   connectReject = null;
   lastDisconnectReason = null;
@@ -227,7 +519,7 @@ var PhoenixChannelsTransport = class {
   stoppingReconnect = false;
   suppressNextCloseReason = false;
   constructor(options) {
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
     this.agentId = options.agentId;
     this.onTerminalDisconnect = options.onTerminalDisconnect;
     let wsUrl = options.wsUrl;
@@ -235,7 +527,7 @@ var PhoenixChannelsTransport = class {
       wsUrl = wsUrl.slice(0, -"/websocket".length);
     }
     const reconnectAfterMs = options.reconnectAfterMs ?? ((tries) => [1e3, 2e3, 5e3, 1e4, 3e4][tries - 1] ?? 3e4);
-    this.socket = new Socket(wsUrl, {
+    this.socket = new Socket2(wsUrl, {
       params: {
         agent_id: options.agentId,
         ...options.conflictPolicy ? { on_conflict: options.conflictPolicy } : {}
@@ -249,6 +541,35 @@ var PhoenixChannelsTransport = class {
       },
       transport: options.websocketFactory ?? resolveWebSocketFactory(options.apiKey)
     });
+    this.registry = new ChannelRegistry(this.socket, this.epoch, this.logger, {
+      wrapHandler: (topic, event, handler) => (payload) => {
+        const reportError = (error) => {
+          this.logger.error("Unhandled topic handler error", { topic, event, error });
+          this.onHandlerError?.(error);
+        };
+        const deliver = () => {
+          try {
+            void Promise.resolve(handler(payload)).catch(reportError);
+          } catch (error) {
+            reportError(error);
+          }
+        };
+        if (this.bufferingGeneration !== null && !this.bufferingExemptTopics.has(topic)) {
+          this.bufferedTopicEvents.push({ topic, deliver });
+        } else {
+          deliver();
+        }
+      },
+      onJoinSettled: (topic, joined) => this.generationTracker.recordSettled(topic, joined),
+      onLeft: (topic) => {
+        this.generationTracker.removeTopic(topic);
+        for (let index = this.bufferedTopicEvents.length - 1; index >= 0; index -= 1) {
+          if (this.bufferedTopicEvents[index]?.topic === topic) {
+            this.bufferedTopicEvents.splice(index, 1);
+          }
+        }
+      }
+    });
     this.socket.onOpen(() => {
       void this.handleOpen();
     });
@@ -285,42 +606,25 @@ var PhoenixChannelsTransport = class {
     if (this.connected) {
       return;
     }
-    if (!this.connectPromise) {
+    await this.connectFlight.run(() => {
       this.socket.connect();
-      const pending = this.waitForConnection();
-      this.connectPromise = pending;
-      void pending.then(
-        () => {
-          if (this.connectPromise === pending) {
-            this.connectPromise = null;
-          }
-        },
-        () => {
-          if (this.connectPromise === pending) {
-            this.connectPromise = null;
-          }
-        }
-      );
-    }
-    await this.connectPromise;
+      return this.waitForConnection();
+    });
   }
   async disconnect() {
-    const results = await Promise.allSettled(
-      [...this.channels.keys()].map((topic) => this.leave(topic))
-    );
+    this.epoch.bump();
+    const failures = await this.registry.leaveAll();
     this.socket.disconnect();
     this.connected = false;
-    const failures = [];
-    for (const result of results) {
-      if (result.status === "rejected") {
-        failures.push(result.reason);
-      }
-    }
+    this.registry.forceTeardown();
+    this.hasOpenedOnce = false;
+    this.bufferingGeneration = null;
+    this.reconnectBarrier?.resolve();
+    this.reconnectBarrier = null;
+    this.bufferedTopicEvents.splice(0);
+    this.generationTracker.reset();
     if (failures.length > 0) {
-      throw new AggregateError(
-        failures,
-        "Failed to leave one or more Phoenix topics during disconnect"
-      );
+      throw combineTeardownErrors(failures, "Failed to leave one or more Phoenix topics during disconnect");
     }
   }
   isConnected() {
@@ -329,79 +633,28 @@ var PhoenixChannelsTransport = class {
   getDisconnectReason() {
     return this.lastDisconnectReason;
   }
-  async join(topic, handlers) {
-    if (this.channels.has(topic)) {
-      return;
+  async join(topic, handlers, options) {
+    if (options?.exemptFromBuffering) {
+      this.bufferingExemptTopics.add(topic);
     }
-    const pendingJoin = this.pendingJoins.get(topic);
-    if (pendingJoin) {
-      return pendingJoin;
+    const existing = this.registry.existingJoin(topic);
+    if (existing) {
+      return existing;
     }
-    const joinPromise = this.doJoin(topic, handlers).finally(() => {
-      this.pendingJoins.delete(topic);
-    });
-    this.pendingJoins.set(topic, joinPromise);
-    return joinPromise;
-  }
-  async doJoin(topic, handlers) {
-    const channel = this.socket.channel(topic, {});
-    const refs = [];
-    for (const [event, handler] of Object.entries(handlers)) {
-      const ref = channel.on(event, (payload) => {
-        Promise.resolve(handler(payload)).catch((error) => {
-          this.logger.error("Unhandled topic handler error", {
-            topic,
-            event,
-            error
-          });
-          this.onHandlerError?.(error);
-        });
-      });
-      refs.push([event, ref]);
+    const epoch = this.epoch.current;
+    await this.reconnectBarrier?.promise;
+    if (this.epoch.isStale(epoch)) {
+      this.logger.debug("Join superseded by transport disconnect/reconnect", { topic });
+      throw supersededJoinError(topic);
     }
-    try {
-      await new Promise((resolve, reject) => {
-        channel.join().receive("ok", () => resolve()).receive(
-          "error",
-          (error) => reject(new TransportError(`Failed to join topic ${topic}`, error))
-        ).receive(
-          "timeout",
-          () => reject(new TransportError(`Timeout joining topic ${topic}`))
-        );
-      });
-    } catch (error) {
-      for (const [event, ref] of refs) {
-        channel.off(event, ref);
-      }
-      channel.leave();
-      removeSocketChannel(this.socket, channel);
-      throw error;
+    const resumed = this.registry.existingJoin(topic);
+    if (resumed) {
+      return resumed;
     }
-    this.channels.set(topic, channel);
-    this.channelRefs.set(topic, refs);
-    this.logger.debug("Joined topic", { topic });
+    return this.registry.join(topic, handlers);
   }
   async leave(topic) {
-    const channel = this.channels.get(topic);
-    if (!channel) {
-      return;
-    }
-    const refs = this.channelRefs.get(topic) ?? [];
-    for (const [event, ref] of refs) {
-      channel.off(event, ref);
-    }
-    this.channelRefs.delete(topic);
-    await new Promise((resolve, reject) => {
-      channel.leave().receive("ok", () => resolve()).receive(
-        "error",
-        (error) => reject(new TransportError(`Failed to leave topic ${topic}`, error))
-      ).receive(
-        "timeout",
-        () => reject(new TransportError(`Timeout leaving topic ${topic}`))
-      );
-    });
-    this.channels.delete(topic);
-    this.logger.debug("Left topic", { topic });
+    return this.registry.leave(topic);
   }
   async runForever(signal) {
     if (this.terminalDisconnectError) {
@@ -439,7 +692,21 @@ var PhoenixChannelsTransport = class {
       );
     });
   }
+  onReconnected(observer) {
+    this.reconnectObservers.add(observer);
+    return () => {
+      this.reconnectObservers.delete(observer);
+    };
+  }
   async handleOpen() {
+    if (this.hasOpenedOnce) {
+      this.bufferingGeneration = this.generationTracker.beginGeneration(this.registry.topics());
+      if (!this.reconnectBarrier) {
+        this.reconnectBarrier = createDeferred();
+      }
+    } else {
+      this.hasOpenedOnce = true;
+    }
     try {
       await this.subscribeAgentControl();
     } catch (error) {
@@ -461,6 +728,40 @@ var PhoenixChannelsTransport = class {
       channels: getSocketChannelCount(this.socket)
     });
   }
+  notifyReconnectObservers(snapshot) {
+    const epoch = this.epoch.current;
+    const observers = [...this.reconnectObservers];
+    void this.observerChain.run(async () => {
+      if (this.epoch.isStale(epoch)) {
+        return;
+      }
+      for (const observer of observers) {
+        if (this.epoch.isStale(epoch)) {
+          return;
+        }
+        if (!this.reconnectObservers.has(observer)) {
+          continue;
+        }
+        try {
+          await observer(snapshot);
+        } catch (error) {
+          this.logger.error("Reconnect observer failed", {
+            generation: snapshot.generation,
+            error
+          });
+        }
+      }
+      if (!this.epoch.isStale(epoch) && snapshot.generation === this.bufferingGeneration) {
+        this.bufferingGeneration = null;
+        const events = this.bufferedTopicEvents.splice(0);
+        for (const { deliver } of events) {
+          deliver();
+        }
+        this.reconnectBarrier?.resolve();
+        this.reconnectBarrier = null;
+      }
+    });
+  }
   stopReconnectIfNoChannels(options = {}) {
     if (this.stoppingReconnect || getSocketChannelCount(this.socket) !== 0) {
       return;
@@ -474,18 +775,23 @@ var PhoenixChannelsTransport = class {
     if (!this.agentId) {
       return;
     }
-    await this.join(agentControlTopic(this.agentId), {
-      supersede: (payload) => {
-        const reason = parseSupersedeDisconnectReason(payload);
-        if (!reason) {
-          this.logger.warn("Invalid agent_control supersede payload", {
-            payload
-          });
-          return;
+    const topic = agentControlTopic(this.agentId);
+    await this.join(
+      topic,
+      {
+        supersede: (payload) => {
+          const reason = parseSupersedeDisconnectReason(payload);
+          if (!reason) {
+            this.logger.warn("Invalid agent_control supersede payload", {
+              payload
+            });
+            return;
+          }
+          this.recordTerminalDisconnect(reason);
         }
-        this.recordTerminalDisconnect(reason);
-      }
-    });
+      },
+      { exemptFromBuffering: true }
+    );
   }
   recordSocketClose(event) {
     this.connected = false;
@@ -561,10 +867,6 @@ function unwrapErrorEvent(event) {
 function isErrorEvent(event) {
   return typeof event === "object" && event !== null && "error" in event;
 }
-function removeSocketChannel(socket, channel) {
-  const candidate = socket;
-  candidate.remove?.(channel);
-}
 function getSocketChannelCount(socket) {
   const candidate = socket;
   if (!Array.isArray(candidate.channels)) {
@@ -578,21 +880,413 @@ import { BandClient } from "@band-ai/rest-client";
 import {
   agentContactsTopic,
   agentRoomsTopic,
-  chatRoomTopic,
-  roomParticipantsTopic
+  validateEventPayload
 } from "@band-ai/band-sdk-core";
+
+// src/platform/SubscriptionManager.ts
+import { SubscriptionTracker } from "@band-ai/band-sdk-core";
+
+// src/platform/roomTopics.ts
+import { chatRoomTopic, roomParticipantsTopic } from "@band-ai/band-sdk-core";
+function roomTopics(roomId) {
+  return { chat: chatRoomTopic(roomId), participants: roomParticipantsTopic(roomId) };
+}
+function isRejected(result) {
+  return result.status === "rejected";
+}
+async function settleRoomLeaves(transport, roomId) {
+  const { chat: chatTopic, participants: participantsTopic } = roomTopics(roomId);
+  const results = await Promise.allSettled([
+    transport.leave(chatTopic),
+    transport.leave(participantsTopic)
+  ]);
+  return results.filter(isRejected);
+}
+
+// src/platform/ReconciliationCoordinator.ts
+var ReconciliationCoordinator = class {
+  constructor(tracker, transport, logger, epoch) {
+    this.tracker = tracker;
+    this.transport = transport;
+    this.logger = logger;
+    this.epoch = epoch;
+  }
+  roomsNeedingReconciliation = /* @__PURE__ */ new Set();
+  agentTopicsNeedingReconciliation = /* @__PURE__ */ new Set();
+  reconcileTail = new Serializer();
+  lastReconciledGeneration = 0;
+  markRoomNeedsReconciliation(roomId) {
+    this.roomsNeedingReconciliation.add(roomId);
+  }
+  markAgentTopicNeedsReconciliation(topic) {
+    this.agentTopicsNeedingReconciliation.add(topic);
+  }
+  /** Called on session end: every pending sweep is moot against a tracker that has itself just been reset. */
+  reset() {
+    this.roomsNeedingReconciliation.clear();
+    this.agentTopicsNeedingReconciliation.clear();
+    this.lastReconciledGeneration = 0;
+  }
+  /** Serialized: each generation's reconciliation completes before the next begins. */
+  reconcileReconnect(snapshot) {
+    if (snapshot.generation <= this.lastReconciledGeneration) {
+      this.logger.debug("Ignoring stale or duplicate reconnect snapshot", {
+        generation: snapshot.generation,
+        lastReconciledGeneration: this.lastReconciledGeneration
+      });
+      return Promise.resolve();
+    }
+    this.lastReconciledGeneration = snapshot.generation;
+    const epoch = this.epoch.current;
+    this.tracker.onReconnected();
+    const work = {
+      snapshot,
+      epoch,
+      roomCandidates: this.tracker.roomRejoinCandidates(),
+      agentTopicCandidates: this.tracker.agentTopicRejoinCandidates()
+    };
+    return this.reconcileTail.run(() => this.runReconcile(work));
+  }
+  async runReconcile(work) {
+    const { snapshot, epoch, roomCandidates, agentTopicCandidates } = work;
+    if (this.epoch.isStale(epoch)) {
+      this.logger.debug("Reconnect reconciliation settled after session ended, skipping rejoin evaluation", {
+        generation: snapshot.generation
+      });
+      return;
+    }
+    for (const [roomId, ticket] of roomCandidates) {
+      const { chat: chatTopic, participants: participantsTopic } = roomTopics(roomId);
+      if (!snapshot.attemptedTopics.has(chatTopic) || !snapshot.attemptedTopics.has(participantsTopic)) {
+        continue;
+      }
+      const present = snapshot.joinedTopics.has(chatTopic) && snapshot.joinedTopics.has(participantsTopic);
+      if (present) {
+        continue;
+      }
+      if (this.tracker.markRoomRejoinFailed(roomId, ticket)) {
+        this.markRoomNeedsReconciliation(roomId);
+      }
+    }
+    for (const [topic, ticket] of agentTopicCandidates) {
+      if (!snapshot.attemptedTopics.has(topic)) {
+        continue;
+      }
+      if (snapshot.joinedTopics.has(topic)) {
+        continue;
+      }
+      if (this.tracker.markAgentTopicRejoinFailed(topic, ticket)) {
+        this.markAgentTopicNeedsReconciliation(topic);
+      }
+    }
+    if (this.epoch.isStale(epoch)) {
+      this.logger.debug("Reconnect reconciliation settled after session ended, skipping cleanup drain", {
+        generation: snapshot.generation
+      });
+      return;
+    }
+    await this.drainReconciliation(epoch);
+  }
+  async drainReconciliation(epoch) {
+    const rooms = [...this.roomsNeedingReconciliation];
+    const topics = [...this.agentTopicsNeedingReconciliation];
+    const [roomLeaveResults, topicLeaveResults] = await Promise.all([
+      Promise.allSettled(rooms.map((roomId) => this.leaveRoomTopicsCleanly(roomId))),
+      Promise.allSettled(topics.map((topic) => this.transport.leave(topic)))
+    ]);
+    if (this.epoch.isStale(epoch)) {
+      this.logger.debug("Reconnect reconciliation cleanup settled after session ended, leaving tracker acknowledgements pending for next reconnect", {
+        rooms: rooms.length,
+        topics: topics.length
+      });
+      return;
+    }
+    this.acknowledgeCleanup({
+      ids: rooms,
+      results: roomLeaveResults,
+      pending: this.roomsNeedingReconciliation,
+      acknowledge: (roomId) => this.tracker.acknowledgeRoomReconciled(roomId),
+      failureMessage: "Room reconciliation cleanup failed, retrying on next reconnect",
+      logContext: (roomId) => ({ roomId })
+    });
+    this.acknowledgeCleanup({
+      ids: topics,
+      results: topicLeaveResults,
+      pending: this.agentTopicsNeedingReconciliation,
+      acknowledge: (topic) => this.tracker.acknowledgeAgentTopicReconciled(topic),
+      failureMessage: "Agent topic reconciliation cleanup failed, retrying on next reconnect",
+      logContext: (topic) => ({ topic })
+    });
+  }
+  acknowledgeCleanup(options) {
+    options.ids.forEach((id, index) => {
+      if (options.results[index]?.status !== "fulfilled") {
+        this.logger.warn(options.failureMessage, options.logContext(id));
+        return;
+      }
+      if (options.acknowledge(id)) {
+        options.pending.delete(id);
+      }
+    });
+  }
+  async leaveRoomTopicsCleanly(roomId) {
+    const failures = await settleRoomLeaves(this.transport, roomId);
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures.map((failure) => failure.reason),
+        `Failed to clean up room ${roomId} during reconnect reconciliation`
+      );
+    }
+  }
+};
+
+// src/platform/SubscriptionManager.ts
+function roomOperationKey(roomId) {
+  return `room:${roomId}`;
+}
+function topicOperationKey(topic) {
+  return `topic:${topic}`;
+}
+var SubscriptionManager = class {
+  tracker = new SubscriptionTracker();
+  transport;
+  logger;
+  operations = /* @__PURE__ */ new Map();
+  epoch = new Epoch();
+  reconciliation;
+  constructor(options) {
+    this.transport = options.transport;
+    this.logger = resolveLogger(options.logger);
+    this.reconciliation = new ReconciliationCoordinator(
+      this.tracker,
+      this.transport,
+      this.logger,
+      this.epoch
+    );
+  }
+  subscribeRoom(roomId, handlers) {
+    return this.runOperation(
+      roomOperationKey(roomId),
+      "up",
+      () => this.claimRoomSubscribe(roomId, handlers)
+    );
+  }
+  unsubscribeRoom(roomId) {
+    return this.runOperation(
+      roomOperationKey(roomId),
+      "down",
+      () => this.claimRoomUnsubscribe(roomId)
+    );
+  }
+  subscribeAgentTopic(topic, handlers) {
+    return this.runOperation(
+      topicOperationKey(topic),
+      "up",
+      () => this.claimAgentTopicJoin(topic, handlers)
+    );
+  }
+  unsubscribeAgentTopic(topic) {
+    return this.runOperation(
+      topicOperationKey(topic),
+      "down",
+      () => this.claimAgentTopicLeave(topic)
+    );
+  }
+  /** Serialized: each generation's reconciliation completes before the next begins. */
+  reconcileReconnect(snapshot) {
+    return this.reconciliation.reconcileReconnect(snapshot);
+  }
+  /**
+   * Ends this session: every ticket issued so far goes stale, every in-flight
+   * operation's late completion becomes a no-op, and both reconciliation sets
+   * start empty for the next session. The epoch guards host-side async work
+   * and transport effects that can outlive the core session they started in.
+   */
+  endSession() {
+    this.epoch.bump();
+    this.tracker.endSession();
+    this.operations.clear();
+    this.reconciliation.reset();
+  }
+  leaveOutcome(epoch, succeeded) {
+    return this.epoch.isStale(epoch) ? "unknown" : succeeded ? "left" : "failed";
+  }
+  // ---- generic operation coalescing -------------------------------------
+  runOperation(key, kind, claim) {
+    const existing = this.operations.get(key);
+    if (existing?.kind === kind) {
+      return existing.promise;
+    }
+    const promise = existing ? existing.promise.then(claim, claim) : claim();
+    const operation = { kind, promise };
+    this.operations.set(key, operation);
+    const cleanup = () => {
+      if (this.operations.get(key) === operation) {
+        this.operations.delete(key);
+      }
+    };
+    promise.then(cleanup, cleanup);
+    return promise;
+  }
+  // ---- room subscribe/unsubscribe ----------------------------------------
+  async claimRoomSubscribe(roomId, handlers) {
+    const epoch = this.epoch.current;
+    const ticket = this.tracker.beginRoomSubscribe(roomId);
+    if (ticket === void 0) {
+      return this.settleIdempotentRoomClaim(roomId);
+    }
+    const { chat: chatTopic, participants: participantsTopic } = roomTopics(roomId);
+    try {
+      await this.transport.join(chatTopic, handlers.chat);
+    } catch (error) {
+      if (!this.epoch.isStale(epoch)) {
+        this.tracker.recordChatRoomJoinFailed(roomId, ticket);
+      } else {
+        this.logger.debug("Room chat-topic join settled after session ended, ignoring stale ticket", {
+          roomId
+        });
+      }
+      throw error;
+    }
+    try {
+      await this.transport.join(participantsTopic, handlers.participants);
+    } catch (participantError) {
+      if (this.epoch.isStale(epoch)) {
+        this.logger.debug(
+          "Room participants-topic join settled after session ended, ignoring stale ticket",
+          { roomId }
+        );
+        throw participantError;
+      }
+      let chatRoomLeft = false;
+      let rollbackError;
+      try {
+        await this.transport.leave(chatTopic);
+        chatRoomLeft = true;
+      } catch (error) {
+        rollbackError = error;
+      }
+      const result = this.tracker.recordRoomParticipantsJoinFailed(roomId, ticket, chatRoomLeft);
+      if (result === "rollback_failed") {
+        this.reconciliation.markRoomNeedsReconciliation(roomId);
+        throw new AggregateError(
+          [
+            participantError,
+            rollbackError ?? new TransportError(`Failed to roll back chat_room join for room ${roomId}`)
+          ],
+          `Failed to subscribe to room ${roomId} and roll back its chat_room join`
+        );
+      }
+      throw participantError;
+    }
+    if (!this.epoch.isStale(epoch)) {
+      this.tracker.recordBothRoomTopicsJoined(roomId, ticket);
+    } else {
+      this.logger.debug("Room subscribe settled after session ended, discarding stale success", {
+        roomId
+      });
+    }
+  }
+  /** Resolves or rejects an idempotent no-op claim (the tracker reported no new ticket to act on). */
+  settleIdempotentClaim(matched, describe) {
+    return matched ? Promise.resolve() : Promise.reject(new RuntimeStateError(describe()));
+  }
+  settleIdempotentRoomClaim(roomId) {
+    const status = this.tracker.roomStatus(roomId);
+    return this.settleIdempotentClaim(
+      status === "subscribed",
+      () => `Room ${roomId} cannot be subscribed while it is "${status}"`
+    );
+  }
+  async claimRoomUnsubscribe(roomId) {
+    const epoch = this.epoch.current;
+    const ticket = this.tracker.unsubscribeRoom(roomId);
+    if (ticket === void 0) {
+      return;
+    }
+    const failures = await settleRoomLeaves(this.transport, roomId);
+    const outcome = this.leaveOutcome(epoch, failures.length === 0);
+    if (outcome === "unknown") {
+      this.logger.debug("Room unsubscribe settled after session ended, outcome ambiguous", { roomId });
+    }
+    if (this.tracker.markRoomLeaveComplete(roomId, ticket, outcome) && outcome !== "left") {
+      this.reconciliation.markRoomNeedsReconciliation(roomId);
+    }
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures.map((failure) => failure.reason),
+        `Failed to fully unsubscribe from room ${roomId}`
+      );
+    }
+  }
+  // ---- agent topic join/leave (agent_rooms, agent_contacts) --------------
+  async claimAgentTopicJoin(topic, handlers) {
+    const epoch = this.epoch.current;
+    const ticket = this.tracker.beginAgentTopicJoin(topic);
+    if (ticket === void 0) {
+      return this.settleIdempotentTopicClaim(topic);
+    }
+    let joined = false;
+    let joinError;
+    try {
+      await this.transport.join(topic, handlers);
+      joined = true;
+    } catch (error) {
+      joinError = error;
+    }
+    if (this.epoch.isStale(epoch)) {
+      this.tracker.recordAgentTopicJoinAmbiguous(topic, ticket);
+      this.logger.debug("Agent topic join settled after session ended, marking ambiguous for reconciliation", {
+        topic
+      });
+    } else {
+      this.tracker.recordAgentTopicJoin(topic, ticket, joined);
+    }
+    if (!joined) {
+      throw joinError;
+    }
+  }
+  settleIdempotentTopicClaim(topic) {
+    const status = this.tracker.agentTopicStatus(topic);
+    return this.settleIdempotentClaim(
+      status === "joined",
+      () => `Topic ${topic} cannot be joined while it is "${status}"`
+    );
+  }
+  async claimAgentTopicLeave(topic) {
+    const epoch = this.epoch.current;
+    const ticket = this.tracker.leaveAgentTopic(topic);
+    if (ticket === void 0) {
+      return;
+    }
+    let left = true;
+    let leaveError;
+    try {
+      await this.transport.leave(topic);
+    } catch (error) {
+      left = false;
+      leaveError = error;
+    }
+    const outcome = this.leaveOutcome(epoch, left);
+    if (outcome === "unknown") {
+      this.logger.debug("Agent topic unsubscribe settled after session ended, outcome ambiguous", { topic });
+    }
+    if (this.tracker.markAgentTopicLeaveComplete(topic, ticket, outcome) && outcome !== "left") {
+      this.reconciliation.markAgentTopicNeedsReconciliation(topic);
+    }
+    if (!left) {
+      throw leaveError;
+    }
+  }
+};
+
+// src/platform/BandLink.ts
 var DEFAULT_WS_URL = "wss://app.band.ai/api/v1/socket";
 function deriveDefaultRestUrl(wsUrl) {
   const parsed = new URL(wsUrl);
   const protocol = parsed.protocol === "ws:" ? "http:" : "https:";
   return `${protocol}//${parsed.host}`;
 }
-function roomTopics(roomId) {
-  return {
-    chat: chatRoomTopic(roomId),
-    participants: roomParticipantsTopic(roomId)
-  };
-}
 function toPlatformMessage(roomId, message) {
   return {
     id: message.id,
@@ -606,6 +1300,19 @@ function toPlatformMessage(roomId, message) {
     createdAt: new Date(message.inserted_at)
   };
 }
+function validationErrorDetails(error) {
+  if (typeof error !== "object" || error === null) {
+    return {};
+  }
+  const details = {};
+  if ("issues" in error) {
+    details.issues = error.issues;
+  }
+  if ("traceContext" in error) {
+    details.traceContext = error.traceContext;
+  }
+  return details;
+}
 var BandLink = class {
   agentId;
   apiKey;
@@ -615,18 +1322,21 @@ var BandLink = class {
   capabilities;
   logger;
   transport;
-  subscribedRooms = /* @__PURE__ */ new Set();
+  subscriptionManager;
   eventQueue = [];
   waiters = [];
   connected = false;
   lastDisconnectReason = null;
   terminalDisconnectError = null;
+  connectFlight = new SingleFlight();
+  disconnectFlight = new SingleFlight();
+  session = new Session();
   constructor(options) {
     this.agentId = options.agentId;
     this.apiKey = options.apiKey;
     this.wsUrl = options.wsUrl ?? DEFAULT_WS_URL;
     this.restUrl = options.restUrl ?? deriveDefaultRestUrl(this.wsUrl);
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
     this.capabilities = {
       ...DEFAULT_AGENT_TOOLS_CAPABILITIES,
       ...options.capabilities
@@ -648,6 +1358,10 @@ var BandLink = class {
         this.recordDisconnectReason(reason);
       }
     });
+    this.subscriptionManager = new SubscriptionManager({
+      transport: this.transport,
+      logger: this.logger
+    });
   }
   isConnected() {
     return this.connected;
@@ -656,12 +1370,35 @@ var BandLink = class {
     return this.lastDisconnectReason;
   }
   async connect() {
+    if (this.disconnectFlight.current) {
+      await this.disconnectFlight.current.catch(() => void 0);
+    }
     if (this.connected) {
       return;
     }
+    await this.connectFlight.run(() => {
+      const epoch = this.session.begin();
+      return this.connectSession(epoch);
+    });
+  }
+  async connectSession(epoch) {
+    this.session.reconnectObserverTeardown = this.transport.onReconnected?.(async (snapshot) => {
+      await this.subscriptionManager.reconcileReconnect(snapshot);
+      if (this.session.isStale(epoch)) {
+        this.logger.debug(
+          "Reconnect reconciliation settled after session ended, discarding reconnected event"
+        );
+        return;
+      }
+      this.queueEvent({ type: "reconnected", roomId: null, payload: {} });
+    }) ?? null;
     try {
       await this.transport.connect();
     } catch (error) {
+      this.session.clearReconnectObserver();
+      this.session.deactivate();
+      await this.transport.disconnect().catch(() => void 0);
+      this.subscriptionManager.endSession();
       if (error instanceof WebSocketDisconnectError) {
         if (error.reason.retryable) {
           this.lastDisconnectReason = error.reason;
@@ -674,14 +1411,21 @@ var BandLink = class {
     this.connected = true;
   }
   async disconnect() {
-    if (!this.connected) {
+    await this.disconnectFlight.run(() => this.disconnectSession());
+  }
+  async disconnectSession() {
+    await this.connectFlight.current?.catch(() => void 0);
+    if (!this.session.isActive) {
       return;
     }
-    await Promise.allSettled(
-      [...this.subscribedRooms].map((roomId) => this.unsubscribeRoom(roomId))
-    );
-    await this.transport.disconnect();
-    this.connected = false;
+    this.session.deactivate();
+    try {
+      await this.transport.disconnect();
+    } finally {
+      this.connected = false;
+      this.session.clearReconnectObserver();
+      this.subscriptionManager.endSession();
+    }
   }
   async runForever(signal) {
     if (this.terminalDisconnectError) {
@@ -710,42 +1454,25 @@ var BandLink = class {
     this.eventQueue.push(event);
   }
   async subscribeAgentRooms() {
-    await this.transport.join(agentRoomsTopic(this.agentId), {
+    await this.subscriptionManager.subscribeAgentTopic(agentRoomsTopic(this.agentId), {
       room_added: (payload) => {
         const roomId = typeof payload.id === "string" ? payload.id : "";
-        this.emit("room_added", payload, roomId);
-      },
-      room_removed: (payload) => {
-        const roomId = typeof payload.id === "string" ? payload.id : "";
-        this.emit("room_removed", payload, roomId);
-      }
-    });
-  }
-  async subscribeRoom(roomId) {
-    if (this.subscribedRooms.has(roomId)) {
-      return;
-    }
-    await this.joinRoomTopics(roomId);
-    this.subscribedRooms.add(roomId);
-  }
-  async unsubscribeRoom(roomId) {
-    if (!this.subscribedRooms.has(roomId)) {
-      return;
-    }
-    const topics = roomTopics(roomId);
-    await this.transport.leave(topics.chat);
-    await this.transport.leave(topics.participants);
-    this.subscribedRooms.delete(roomId);
-  }
-  async joinRoomTopics(roomId) {
-    const topics = roomTopics(roomId);
-    await this.transport.join(topics.chat, {
-      message_created: (payload) => {
-        this.emit("message_created", payload, roomId);
+        this.emit("room_added", payload, roomId);
+      },
+      room_removed: (payload) => {
+        const roomId = typeof payload.id === "string" ? payload.id : "";
+        this.emit("room_removed", payload, roomId);
       }
     });
-    try {
-      await this.transport.join(topics.participants, {
+  }
+  async subscribeRoom(roomId) {
+    await this.subscriptionManager.subscribeRoom(roomId, {
+      chat: {
+        message_created: (payload) => {
+          this.emit("message_created", payload, roomId);
+        }
+      },
+      participants: {
         participant_added: (payload) => {
           this.emit("participant_added", payload, roomId);
         },
@@ -755,15 +1482,15 @@ var BandLink = class {
         room_deleted: (payload) => {
           this.emit("room_deleted", payload, roomId);
         }
-      });
-    } catch (error) {
-      await this.transport.leave(topics.chat);
-      throw error;
-    }
+      }
+    });
+  }
+  async unsubscribeRoom(roomId) {
+    await this.subscriptionManager.unsubscribeRoom(roomId);
   }
   async subscribeAgentContacts() {
     assertCapability(this.capabilities, "contacts", "Contacts streaming");
-    await this.transport.join(agentContactsTopic(this.agentId), {
+    await this.subscriptionManager.subscribeAgentTopic(agentContactsTopic(this.agentId), {
       contact_request_received: (payload) => {
         this.emit("contact_request_received", payload, null);
       },
@@ -779,7 +1506,7 @@ var BandLink = class {
     });
   }
   async unsubscribeAgentContacts() {
-    await this.transport.leave(agentContactsTopic(this.agentId));
+    await this.subscriptionManager.unsubscribeAgentTopic(agentContactsTopic(this.agentId));
   }
   async nextEvent(signal) {
     if (this.terminalDisconnectError) {
@@ -935,21 +1662,265 @@ var BandLink = class {
     });
   }
   emit(eventType, payload, roomId) {
-    const schema = payloadSchemas[eventType];
-    const parsed = schema.safeParse(payload);
-    if (!parsed.success) {
+    try {
+      const normalizedPayload = validateEventPayload(eventType, payload);
+      this.queueEvent({
+        type: eventType,
+        roomId,
+        payload: normalizedPayload,
+        raw: payload
+      });
+    } catch (error) {
       this.logger.warn(`Invalid ${eventType} payload, dropping event`, {
-        error: parsed.error.message,
+        ...validationErrorDetails(error),
         roomId
       });
+    }
+  }
+};
+
+// src/runtime/lifecycle.ts
+var RUNTIME_LIFECYCLE_TRANSITIONS = {
+  not_started: ["starting"],
+  starting: ["running", "stopping", "stopped", "failed"],
+  running: ["stopping", "failed"],
+  stopping: ["stopped", "failed"],
+  stopped: ["starting"],
+  failed: ["starting", "stopping", "failed"]
+};
+function isLegalRuntimeTransition(from, to) {
+  return RUNTIME_LIFECYCLE_TRANSITIONS[from].includes(to);
+}
+var EXECUTION_LIFECYCLE_TRANSITIONS = {
+  running: ["stopping", "failed"],
+  stopping: ["stopped", "failed"],
+  stopped: [],
+  failed: []
+};
+function isLegalExecutionTransition(from, to) {
+  return EXECUTION_LIFECYCLE_TRANSITIONS[from].includes(to);
+}
+function toLifecycleError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+var TerminalSignal = class {
+  waiters = /* @__PURE__ */ new Set();
+  outcome = null;
+  /**
+   * Resolves once {@link settle} has been called with `null`, rejects once it has
+   * been called with an error — including for callers that arrive afterwards.
+   */
+  async wait() {
+    if (this.outcome) {
+      if (this.outcome.error) {
+        throw this.outcome.error;
+      }
       return;
     }
-    this.queueEvent({
-      type: eventType,
-      roomId,
-      payload: parsed.data,
-      raw: payload
+    await new Promise((resolve, reject) => {
+      this.waiters.add({ resolve, reject });
+    });
+  }
+  /**
+   * Forget the recorded outcome so a restarted owner can settle again.
+   *
+   * Callers already parked in {@link wait} stay parked — a wait started before a
+   * restart still resolves only when the owner actually stops or fails.
+   */
+  rearm() {
+    this.outcome = null;
+  }
+  /** First settle wins; later ones are ignored, so a terminal state stays terminal. */
+  settle(error) {
+    if (this.outcome) {
+      return;
+    }
+    this.outcome = { error };
+    const pending = [...this.waiters];
+    this.waiters.clear();
+    for (const waiter of pending) {
+      if (error) {
+        waiter.reject(error);
+      } else {
+        waiter.resolve();
+      }
+    }
+  }
+};
+var SingleFlight2 = class {
+  operation = null;
+  /** The in-flight (or last latched) operation, if any. */
+  get pending() {
+    return this.operation;
+  }
+  /** Forget the latched operation so the next {@link run}/{@link runOrRetry} starts fresh. */
+  reset() {
+    this.operation = null;
+  }
+  /**
+   * Runs `factory()` once; concurrent and later callers get the same promise.
+   * The result — success or failure — stays latched until {@link reset}.
+   */
+  run(factory) {
+    if (this.operation) {
+      return this.operation;
+    }
+    const operation = factory();
+    this.operation = operation;
+    return operation;
+  }
+  /**
+   * Like {@link run}, but unlatches on rejection so the next call retries
+   * instead of replaying the same failure. Only unlatches its own operation —
+   * one already replaced by a {@link reset} or a subsequent call is left alone.
+   */
+  async runOrRetry(factory) {
+    if (this.operation) {
+      return this.operation;
+    }
+    const operation = factory();
+    this.operation = operation;
+    try {
+      return await operation;
+    } catch (error) {
+      if (this.operation === operation) {
+        this.operation = null;
+      }
+      throw error;
+    }
+  }
+};
+var LifecycleTracker = class {
+  options;
+  current;
+  constructor(initial, options) {
+    this.options = options;
+    Object.freeze(initial);
+    this.current = initial;
+  }
+  /** The current state. Frozen, so callers cannot mutate the instance's lifecycle. */
+  get state() {
+    return this.current;
+  }
+  /**
+   * Whether `state` is still the instance this tracker holds.
+   *
+   * Every accepted {@link transition} installs a *new* frozen object, so an
+   * async operation that captured the state it began under can ask whether the
+   * lifecycle moved on while it was awaiting — "was I superseded?" — without a
+   * second, parallel generation counter living outside the tracker. A status
+   * comparison cannot answer it: a `stop()` followed by a fresh `start()`
+   * returns to `"starting"`, but not to the *same* `"starting"`.
+   */
+  isCurrent(state) {
+    return this.current === state;
+  }
+  /** Records `next` as the state. Callers pass a fresh object — see {@link isCurrent}. */
+  transition(next, trigger) {
+    const from = this.current.status;
+    if (!this.options.isLegalTransition(from, next.status)) {
+      throw new RuntimeStateError(
+        `${this.options.owner} cannot transition from "${from}" to "${next.status}" (trigger: ${trigger})`
+      );
+    }
+    Object.freeze(next);
+    this.current = next;
+    this.options.logger?.debug(`${this.options.owner} lifecycle transition`, {
+      ...this.options.logContext,
+      from,
+      to: next.status,
+      trigger
     });
+    this.options.onTransition?.(next);
+  }
+  /**
+   * Type-guard check against the current status: narrows `this` (and so
+   * `this.state`) to the matching union member on success, e.g.
+   * `if (tracker.is("failed")) { tracker.state.error }`.
+   *
+   * Prefer this over a raw `tracker.state.status === "..."` comparison —
+   * same check, but the payload stays reachable without a separate
+   * destructured snapshot.
+   */
+  is(status) {
+    return this.current.status === status;
+  }
+  /**
+   * Transition to a `"failed"` state carrying `error`, unless already
+   * terminal (`"stopped"` or `"failed"`), in which case this is a no-op.
+   * Returns whether the transition happened.
+   *
+   * Assumes `S` has a `{ status: "failed", error: Error }` member — true for
+   * both `RuntimeLifecycleState` and `ExecutionLifecycleState`, the only two
+   * states this tracker is used with.
+   */
+  fail(error, trigger) {
+    if (this.is("stopped") || this.is("failed")) {
+      return false;
+    }
+    this.transition({ status: "failed", error: toLifecycleError(error) }, trigger);
+    return true;
+  }
+};
+async function startWithGate(options) {
+  if (options.lifecycle.state.status === "stopping") {
+    throw new RuntimeStateError(`${options.ownerName} cannot start while a stop is in progress`);
+  }
+  if (options.startGate.pending) {
+    return await options.startGate.pending;
+  }
+  options.stopGate.reset();
+  options.stoppedSignal?.rearm();
+  options.lifecycle.transition({ status: "starting" }, "start");
+  await options.startGate.runOrRetry(options.runStart);
+}
+
+// src/runtime/SyncBoundaryTracker.ts
+var SyncBoundaryTracker = class {
+  // Every message id a sync scan has ever executed. Entries are never
+  // removed: evicting on a message's own live redelivery was tried and
+  // proved unsafe, because the backend can still return that same id from
+  // `getNextMessage()` on a *later* reconnect's scan before its
+  // mark-as-processed effect has propagated — an eviction keyed on "we saw
+  // it once already" reopens exactly that race, just on a different
+  // trigger. Permanent membership is what makes "already executed"
+  // unconditional, at the cost of one entry per message ever synced via a
+  // backlog scan for the life of this tracker — a real, bounded quantity.
+  executedMessageIds = /* @__PURE__ */ new Set();
+  initial = { messageId: null };
+  // Ordered, oldest first, matching the order scans run in.
+  queue = [this.initial];
+  /** Whether every queued boundary's scan has finished. */
+  get isComplete() {
+    return this.queue.length === 0;
+  }
+  recordExecuted(messageId) {
+    this.executedMessageIds.add(messageId);
+  }
+  isExecuted(messageId) {
+    return this.executedMessageIds.has(messageId);
+  }
+  isSyncPoint(boundary, messageId) {
+    return boundary.messageId !== null && messageId === boundary.messageId;
+  }
+  /** Anchors the oldest not-yet-anchored boundary to a live message's id, if one is open. */
+  anchor(messageId) {
+    const openBoundary = this.queue.find((boundary) => boundary.messageId === null);
+    if (openBoundary) {
+      openBoundary.messageId = messageId;
+    }
+  }
+  /** Starts a new scan boundary for a reconnect and returns it. */
+  beginBoundary() {
+    const boundary = { messageId: null };
+    this.queue.push(boundary);
+    return boundary;
+  }
+  /** Marks `boundary`'s scan finished, dequeuing it only if it's still the oldest. */
+  completeBoundary(boundary) {
+    if (this.queue[0] === boundary) {
+      this.queue.shift();
+    }
   }
 };
 
@@ -983,13 +1954,18 @@ var Execution = class {
   eventQueue = [];
   waiters = [];
   idleWaiters = /* @__PURE__ */ new Set();
-  drainedWsMessageIds = /* @__PURE__ */ new Set();
-  syncProcessedIds = /* @__PURE__ */ new Set();
+  stoppedSignal = new TerminalSignal();
+  lifecycle;
   processTask;
-  firstWsMessageId = null;
-  syncComplete = false;
-  running = true;
+  stopGate = new SingleFlight2();
+  syncBoundaries = new SyncBoundaryTracker();
   inFlight = 0;
+  /**
+   * Set once the queue stops accepting new events, ahead of the lifecycle
+   * itself reporting `"stopped"` (see {@link runStop}) — closing the queue
+   * cannot wait on the drain it is closing for.
+   */
+  closed = false;
   constructor(options) {
     this.roomId = options.roomId;
     this.link = options.link;
@@ -997,27 +1973,61 @@ var Execution = class {
     this.retryTracker = this.context.getRetryTracker();
     this.onExecute = options.onExecute;
     this.onFailure = options.onFailure;
-    this.logger = options.logger ?? new NoopLogger();
-    this.processTask = this.processLoop();
+    this.logger = resolveLogger(options.logger);
+    this.lifecycle = new LifecycleTracker({ status: "running" }, {
+      owner: "Execution",
+      logContext: { roomId: this.roomId },
+      logger: this.logger,
+      isLegalTransition: isLegalExecutionTransition,
+      onTransition: (state) => {
+        if (state.status === "stopped") {
+          this.stoppedSignal.settle(null);
+        } else if (state.status === "failed") {
+          this.stoppedSignal.settle(state.error);
+        }
+      }
+    });
+    this.processTask = this.runProcessLoop();
+    void this.processTask.catch(() => void 0);
+  }
+  /**
+   * Whether this `Execution` is still alive, and if not, why it ended.
+   *
+   * This is the *lifecycle* axis. For "is this turn's handler currently
+   * executing" read `ExecutionContext.state` instead, which reports
+   * `"starting" | "idle" | "processing"` for the room's context.
+   *
+   * @see ExecutionContext.state
+   */
+  get state() {
+    return this.lifecycle.state;
   }
-  enqueue(event) {
-    if (event.type === "message_created" && !this.syncComplete && this.firstWsMessageId === null) {
-      this.firstWsMessageId = event.payload.id;
+  async enqueue(event) {
+    if (this.lifecycle.is("stopped") || this.lifecycle.is("failed") || this.closed) {
+      throw new RuntimeStateError(
+        `Execution for room ${this.roomId} has already ended or is stopping (status: ${this.lifecycle.state.status}); enqueue() is a no-op after stop()`
+      );
     }
+    let syncBoundary = null;
+    if (event.type === "reconnected") {
+      syncBoundary = this.syncBoundaries.beginBoundary();
+    } else if (event.type === "message_created") {
+      this.syncBoundaries.anchor(event.payload.id);
+    }
+    const queued = { event, syncBoundary };
     const waiter = this.waiters.shift();
     if (waiter) {
-      waiter(event);
+      waiter(queued);
     } else {
-      this.eventQueue.push(event);
+      this.eventQueue.push(queued);
     }
-    return Promise.resolve();
   }
   async bootstrapMessage(message) {
-    this.syncProcessedIds.add(message.id);
+    this.syncBoundaries.recordExecuted(message.id);
     await this.executeSyncMessage(toMessageEvent(message), message.id);
   }
   isIdle() {
-    return this.syncComplete && this.inFlight === 0 && this.eventQueue.length === 0;
+    return this.syncBoundaries.isComplete && this.inFlight === 0 && this.eventQueue.length === 0;
   }
   async waitForIdle(timeoutMs) {
     if (this.isIdle()) {
@@ -1052,27 +2062,58 @@ var Execution = class {
     });
   }
   async stop(timeoutMs) {
+    return await this.stopGate.run(() => this.runStop(timeoutMs));
+  }
+  async runStop(timeoutMs) {
+    if (this.lifecycle.is("failed")) {
+      throw this.lifecycle.state.error;
+    }
+    if (this.lifecycle.is("stopped")) {
+      return this.lifecycle.state.graceful;
+    }
+    this.lifecycle.transition({ status: "stopping" }, "stop");
     const graceful = await this.waitForIdle(timeoutMs);
-    this.running = false;
+    if (this.lifecycle.is("failed")) {
+      throw this.lifecycle.state.error;
+    }
+    this.closed = true;
     this.resolveEventWaiters(null);
     if (graceful || timeoutMs === void 0) {
       await this.processTask;
     }
+    this.lifecycle.transition({ status: "stopped", graceful }, graceful ? "stopped" : "stopped-forced");
     return graceful;
   }
+  /**
+   * Resolve once this `Execution` has reached a terminal state — including a
+   * forced, non-graceful stop that detached the process loop — or reject with
+   * the error that ended it.
+   */
   async waitUntilStopped() {
-    await this.processTask;
+    await this.stoppedSignal.wait();
+  }
+  async runProcessLoop() {
+    try {
+      await this.processLoop();
+    } catch (error) {
+      this.markFailed(error, "process-loop-failed");
+      throw error;
+    }
   }
   async processLoop() {
     await this.recoverStaleProcessingMessages();
-    await this.synchronizeWithNext();
-    while (this.running) {
-      const event = await this.nextQueuedEvent();
-      if (!event) {
+    await this.synchronizeWithNext(this.syncBoundaries.initial);
+    while (this.isActive()) {
+      const queued = await this.nextQueuedEvent();
+      if (!queued) {
         return;
       }
-      if (event.type === "message_created" && this.drainedWsMessageIds.has(event.payload.id)) {
-        this.drainedWsMessageIds.delete(event.payload.id);
+      const { event } = queued;
+      if (event.type === "reconnected") {
+        await this.synchronizeWithNext(queued.syncBoundary ?? { messageId: null });
+        continue;
+      }
+      if (event.type === "message_created" && this.syncBoundaries.isExecuted(event.payload.id)) {
         this.notifyIfIdle();
         continue;
       }
@@ -1097,7 +2138,7 @@ var Execution = class {
       count: staleMessages.length
     });
     for (const message of staleMessages) {
-      if (!this.running) {
+      if (!this.isActive()) {
         break;
       }
       if (this.retryTracker.isPermanentlyFailed(message.id)) {
@@ -1108,20 +2149,17 @@ var Execution = class {
         continue;
       }
       await this.executeSyncMessage(toMessageEvent(message), message.id);
-      this.syncProcessedIds.add(message.id);
+      this.syncBoundaries.recordExecuted(message.id);
     }
   }
-  async synchronizeWithNext() {
-    while (this.running) {
+  async synchronizeWithNext(boundary) {
+    while (this.isActive()) {
       const nextMessage = await this.link.getNextMessage(this.roomId);
       if (!nextMessage) {
         break;
       }
-      if (this.syncProcessedIds.has(nextMessage.id)) {
-        const isSyncPoint2 = this.firstWsMessageId !== null && nextMessage.id === this.firstWsMessageId;
-        if (isSyncPoint2) {
-          this.drainedWsMessageIds.add(nextMessage.id);
-          this.firstWsMessageId = null;
+      if (this.syncBoundaries.isExecuted(nextMessage.id)) {
+        if (this.syncBoundaries.isSyncPoint(boundary, nextMessage.id)) {
           break;
         }
         continue;
@@ -1132,25 +2170,19 @@ var Execution = class {
           messageId: nextMessage.id
         });
         await this.markMessageFailed(nextMessage.id, "Message permanently failed after max retries");
-        const isSyncPoint2 = this.firstWsMessageId !== null && nextMessage.id === this.firstWsMessageId;
-        if (isSyncPoint2) {
-          this.drainedWsMessageIds.add(nextMessage.id);
-          this.firstWsMessageId = null;
+        this.syncBoundaries.recordExecuted(nextMessage.id);
+        if (this.syncBoundaries.isSyncPoint(boundary, nextMessage.id)) {
           break;
         }
         continue;
       }
-      const isSyncPoint = this.firstWsMessageId !== null && nextMessage.id === this.firstWsMessageId;
       await this.executeSyncMessage(toMessageEvent(nextMessage), nextMessage.id);
-      this.syncProcessedIds.add(nextMessage.id);
-      if (isSyncPoint) {
-        this.drainedWsMessageIds.add(nextMessage.id);
-        this.firstWsMessageId = null;
+      this.syncBoundaries.recordExecuted(nextMessage.id);
+      if (this.syncBoundaries.isSyncPoint(boundary, nextMessage.id)) {
         break;
       }
     }
-    this.syncProcessedIds.clear();
-    this.syncComplete = true;
+    this.syncBoundaries.completeBoundary(boundary);
     this.notifyIfIdle();
   }
   async executeSyncMessage(event, messageId) {
@@ -1187,6 +2219,14 @@ var Execution = class {
     try {
       await this.onExecute(this.context, event);
     } catch (error) {
+      if (error instanceof RecoverableTurnError) {
+        this.logger.warn("Turn failed without stopping the room", {
+          roomId: this.roomId,
+          eventType: event.type,
+          error
+        });
+        return;
+      }
       if (this.onFailure) {
         await this.onFailure(error, event);
       } else {
@@ -1196,7 +2236,7 @@ var Execution = class {
           error
         });
       }
-      this.running = false;
+      this.markFailed(error, "execution-failed");
       this.eventQueue.splice(0, this.eventQueue.length);
       this.resolveEventWaiters(null);
       throw error;
@@ -1211,13 +2251,21 @@ var Execution = class {
     if (queued) {
       return queued;
     }
-    if (!this.running) {
+    if (this.closed || !this.isActive()) {
       return null;
     }
     return new Promise((resolve) => {
       this.waiters.push(resolve);
     });
   }
+  /** True while the process loop should keep draining (`running` or mid-`stop()`). */
+  isActive() {
+    const status = this.lifecycle.state.status;
+    return status === "running" || status === "stopping";
+  }
+  markFailed(error, trigger) {
+    this.lifecycle.fail(error, trigger);
+  }
   notifyIfIdle() {
     if (!this.isIdle()) {
       return;
@@ -1248,34 +2296,29 @@ var Execution = class {
 
 // src/runtime/tools/AgentTools.ts
 import { ParticipantRoster } from "@band-ai/band-sdk-core";
-var REQUIRED_ADAPTER_TOOL_METHODS = [
-  "sendMessage",
-  "sendEvent",
-  "addParticipant",
-  "removeParticipant",
-  "getParticipants",
-  "createChatroom",
-  "getToolSchemas",
-  "getAnthropicToolSchemas",
-  "getOpenAIToolSchemas",
-  "executeToolCall"
-];
-var OPTIONAL_ADAPTER_TOOL_METHODS = {
-  peers: ["lookupPeers"],
-  contacts: [
-    "listContacts",
-    "addContact",
-    "removeContact",
-    "listContactRequests",
-    "respondContactRequest"
-  ],
-  memory: [
-    "listMemories",
-    "storeMemory",
-    "getMemory",
-    "supersedeMemory",
-    "archiveMemory"
-  ]
+var ADAPTER_TOOL_METHODS = {
+  sendMessage: null,
+  sendEvent: null,
+  sendFailure: null,
+  addParticipant: null,
+  removeParticipant: null,
+  getParticipants: null,
+  createChatroom: null,
+  getToolSchemas: null,
+  getAnthropicToolSchemas: null,
+  getOpenAIToolSchemas: null,
+  executeToolCall: null,
+  lookupPeers: "peers",
+  listContacts: "contacts",
+  addContact: "contacts",
+  removeContact: "contacts",
+  listContactRequests: "contacts",
+  respondContactRequest: "contacts",
+  listMemories: "memory",
+  storeMemory: "memory",
+  getMemory: "memory",
+  supersedeMemory: "memory",
+  archiveMemory: "memory"
 };
 var CONTACT_REQUEST_ACTIONS = /* @__PURE__ */ new Set([
   "approve",
@@ -1294,7 +2337,7 @@ var AgentTools = class {
     this.roomId = options.roomId;
     this.rest = options.rest;
     this.roster = options.roster ?? new ParticipantRoster();
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
     this.capabilities = {
       ...DEFAULT_AGENT_TOOLS_CAPABILITIES,
       ...options.capabilities
@@ -1334,14 +2377,14 @@ var AgentTools = class {
         }
       );
     } catch (error) {
-      try {
-        this.logger.warn("chat event send failed", { roomId: this.roomId, messageType, error });
-      } catch {
-      }
+      this.logger.warn("chat event send failed", { roomId: this.roomId, messageType, error });
       const message = error instanceof Error ? error.message : String(error);
       return { ok: false, status: "failed", message };
     }
   }
+  async sendFailure(failure) {
+    return sendFailureViaEvent(this.sendEvent.bind(this), failure);
+  }
   async createChatroom(taskId) {
     const room = await this.rest.createChat(taskId, DEFAULT_REQUEST_OPTIONS);
     return room.id;
@@ -1465,6 +2508,7 @@ var AgentTools = class {
           legacyMessage: `Invalid arguments for ${toolName}: ${error.message}`
         });
       }
+      this.logger.error("unexpected tool execution error", { toolName, error });
       const message = error instanceof Error ? error.message : String(error);
       return createToolExecutorError({
         errorType: "ToolExecutionError",
@@ -1751,16 +2795,11 @@ var AgentTools = class {
     const tools = {
       capabilities: this.capabilities
     };
-    for (const methodName of REQUIRED_ADAPTER_TOOL_METHODS) {
-      tools[methodName] = this.bindAdapterToolMethod(methodName);
-    }
-    for (const [capabilityKey, methodNames] of Object.entries(OPTIONAL_ADAPTER_TOOL_METHODS)) {
-      if (!this.capabilities[capabilityKey]) {
+    for (const [methodName, capability] of Object.entries(ADAPTER_TOOL_METHODS)) {
+      if (capability !== null && !this.capabilities[capability]) {
         continue;
       }
-      for (const methodName of methodNames) {
-        tools[methodName] = this.bindAdapterToolMethod(methodName);
-      }
+      tools[methodName] = this.bindAdapterToolMethod(methodName);
     }
     return Object.freeze(tools);
   }
@@ -1908,9 +2947,9 @@ var AgentTools = class {
     if (!segment) {
       throw new ValidationError(`segment must be one of: ${expectedList(MEMORY_SEGMENTS)}`);
     }
-    if (scope === "subject" && !subjectId) {
+    if (scope === MEMORY_STORE_SCOPE.subject && !subjectId) {
       throw new ValidationError(
-        'scope="subject" requires a subject_id (the UUID of the person or agent the memory is about). If you do not have a concrete subject UUID, retry with scope="organization" and omit subject_id. Do not invent a UUID.'
+        `scope="${MEMORY_STORE_SCOPE.subject}" requires a subject_id (the UUID of the person or agent the memory is about). If you do not have a concrete subject UUID, retry with scope="${MEMORY_STORE_SCOPE.agent}" and omit subject_id. Do not invent a UUID.`
       );
     }
     return {
@@ -2088,22 +3127,6 @@ function validateToolArgs(toolName, args) {
       );
     }
   }
-  if (toolName === "band_store_memory") {
-    if (typeof args.system === "string" && !isMemorySystem(args.system)) {
-      errors.push(`system: Invalid value '${args.system}'. Expected one of: ${expectedList(MEMORY_SYSTEMS)}`);
-    }
-    if (typeof args.type === "string" && !isMemoryType(args.type)) {
-      errors.push(`type: Invalid value '${args.type}'. Expected one of: ${expectedList(MEMORY_TYPES)}`);
-    }
-    if (typeof args.system === "string" && isMemorySystem(args.system) && typeof args.type === "string" && isMemoryType(args.type) && !isMemoryTypeForSystem(args.system, args.type)) {
-      errors.push(
-        `type: Invalid value '${args.type}' for system '${args.system}'. Expected one of: ${expectedMemoryTypesForSystem(args.system)}`
-      );
-    }
-    if (typeof args.segment === "string" && !isMemorySegment(args.segment)) {
-      errors.push(`segment: Invalid value '${args.segment}'. Expected one of: ${expectedList(MEMORY_SEGMENTS)}`);
-    }
-  }
   if (errors.length > 0) {
     const message = `Invalid arguments for ${toolName}: ${errors.join("; ")}`;
     return createToolExecutorError({
@@ -2154,10 +3177,21 @@ var ExecutionContext = class {
       rest: this.link.rest,
       roster: this.roster,
       capabilities: this.link.capabilities,
-      logger: options.logger ?? new NoopLogger()
+      logger: resolveLogger(options.logger)
     });
     this.adapterTools = this.tools.getAdapterTools();
   }
+  /**
+   * What this room's turn handler is currently doing.
+   *
+   * This is the *per-turn activity* axis, not a lifecycle: it flips to
+   * `"processing"` while the adapter handles an event and back to `"idle"`
+   * afterwards. To ask whether the room's `Execution` is still alive at all,
+   * read `Execution.state` instead, which reports
+   * `"running" | "stopping" | "stopped" | "failed"`.
+   *
+   * @see Execution.state
+   */
   get state() {
     return this._state;
   }
@@ -2406,18 +3440,26 @@ var ExecutionContext = class {
 import { RoomRoster } from "@band-ai/band-sdk-core";
 
 // src/runtime/rooms/subscriptions.ts
+async function listExistingRooms(options) {
+  const rooms = await options.link.listAllChats(void 0, options.requestOptions);
+  const accepted = /* @__PURE__ */ new Map();
+  for (const room of rooms) {
+    const roomId = typeof room.id === "string" ? room.id : null;
+    if (!roomId) {
+      continue;
+    }
+    if (options.roomFilter && !options.roomFilter(room)) {
+      continue;
+    }
+    accepted.set(roomId, room);
+  }
+  return accepted;
+}
 async function hydrateExistingRooms(options) {
   try {
-    const rooms = await options.link.listAllChats(void 0, options.requestOptions);
-    for (const room of rooms) {
-      const roomId = typeof room.id === "string" ? room.id : null;
-      if (!roomId) {
-        continue;
-      }
-      if (options.roomFilter && !options.roomFilter(room)) {
-        continue;
-      }
-      await options.onRoom(roomId, room);
+    const rooms = await listExistingRooms(options);
+    for (const [roomId, payload] of rooms) {
+      await options.onRoom(roomId, payload);
     }
   } catch (error) {
     if (error instanceof UnsupportedFeatureError) {
@@ -2445,7 +3487,7 @@ var RoomPresence = class {
   eventController = null;
   eventTask = null;
   contactsSubscribed = false;
-  lifecycle = Promise.resolve();
+  lifecycle = new Serializer();
   admissionInFlight = /* @__PURE__ */ new Map();
   // Read once by `admitRoomOrThrow` right after a failed admission; a
   // subsequent successful subscribe clears it so a caller never attributes
@@ -2455,13 +3497,13 @@ var RoomPresence = class {
     this.link = options.link;
     this.roomFilter = options.roomFilter;
     this.autoSubscribeExistingRooms = options.autoSubscribeExistingRooms ?? true;
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
   }
   async start() {
-    return this.serialize(() => this.startBody());
+    return this.lifecycle.run(() => this.startBody());
   }
   async stop() {
-    return this.serialize(() => this.stopBody());
+    return this.lifecycle.run(() => this.stopBody());
   }
   async [Symbol.asyncDispose]() {
     await this.stop();
@@ -2526,14 +3568,6 @@ var RoomPresence = class {
     }
     return roomIsAdmitted;
   }
-  async serialize(body) {
-    const run = this.lifecycle.then(body, body);
-    this.lifecycle = run.then(
-      () => void 0,
-      () => void 0
-    );
-    return run;
-  }
   async startBody() {
     if (this.eventTask) {
       throw new RuntimeStateError("RoomPresence is already started");
@@ -2541,14 +3575,8 @@ var RoomPresence = class {
     if (!this.link.isConnected()) {
       await this.link.connect();
     }
-    const contactsReady = this.subscribeContacts();
-    try {
-      await this.link.subscribeAgentRooms();
-    } catch (error) {
-      this.logger.warn("RoomPresence failed to subscribe agent_rooms channel, continuing without it", {
-        error
-      });
-    }
+    const contactsReady = this.subscribeContacts("start");
+    await this.subscribeAgentRoomsChannel("start");
     if (this.autoSubscribeExistingRooms) {
       await this.subscribeExistingRooms();
     }
@@ -2556,7 +3584,17 @@ var RoomPresence = class {
     this.eventController = new AbortController();
     this.eventTask = this.consumeEvents(this.eventController.signal);
   }
-  async subscribeContacts() {
+  contextualWarnMessage(channel, context) {
+    return context === "reconnect" ? `RoomPresence failed to resubscribe ${channel} channel after reconnect` : `RoomPresence failed to subscribe ${channel} channel, continuing without it`;
+  }
+  async subscribeAgentRoomsChannel(context) {
+    try {
+      await this.link.subscribeAgentRooms();
+    } catch (error) {
+      this.logger.warn(this.contextualWarnMessage("agent_rooms", context), { error });
+    }
+  }
+  async subscribeContacts(context) {
     if (!this.link.capabilities.contacts) {
       return;
     }
@@ -2564,9 +3602,7 @@ var RoomPresence = class {
       await this.link.subscribeAgentContacts();
       this.contactsSubscribed = true;
     } catch (error) {
-      this.logger.warn("RoomPresence failed to subscribe agent_contacts channel, continuing without it", {
-        error
-      });
+      this.logger.warn(this.contextualWarnMessage("agent_contacts", context), { error });
     }
   }
   async stopBody() {
@@ -2620,6 +3656,9 @@ var RoomPresence = class {
             await this.onRoomEvent?.(event.roomId, event);
           }
           break;
+        case "reconnected":
+          await this.handleReconnected(event);
+          break;
         default:
           assertNever(event);
       }
@@ -2638,14 +3677,74 @@ var RoomPresence = class {
     if (!roomId) {
       return;
     }
-    await this.unsubscribeRoom(roomId);
-    this.lastSubscribeError.delete(roomId);
+    await this.leaveRoomTracking(roomId);
     if (!this.roster.recordRoomRemoved(roomId)) {
       this.logger.debug("RoomPresence ignoring removal for untracked room", { roomId });
       return;
     }
     await this.onRoomLeft?.(roomId);
   }
+  /** Unsubscribes the transport topic and clears any remembered subscribe failure for `roomId`. */
+  async leaveRoomTracking(roomId) {
+    await this.unsubscribeRoom(roomId);
+    this.lastSubscribeError.delete(roomId);
+  }
+  /**
+   * A REST fetch failure here must not blank the roster — it forwards the
+   * reconnect to every currently tracked room regardless, so each room's
+   * `Execution` can still re-run its `/next` synchronization even when
+   * membership reconciliation itself has to wait for the next reconnect.
+   */
+  async handleReconnected(event) {
+    const [, , accepted] = await Promise.all([
+      this.subscribeAgentRoomsChannel("reconnect"),
+      this.subscribeContacts("reconnect"),
+      listExistingRooms({
+        link: this.link,
+        roomFilter: this.roomFilter,
+        requestOptions: DEFAULT_REQUEST_OPTIONS
+      }).catch((error) => {
+        this.logger.warn("RoomPresence failed to fetch room snapshot after reconnect", { error });
+        return null;
+      })
+    ]);
+    if (accepted) {
+      await this.reconcileRoomsWithSnapshot(accepted);
+    }
+    await Promise.all(
+      this.roster.trackedRoomIds().map((roomId) => this.onRoomEvent?.(roomId, event) ?? Promise.resolve())
+    );
+  }
+  async reconcileRoomsWithSnapshot(accepted) {
+    const acceptedIds = this.autoSubscribeExistingRooms ? [...accepted.keys()] : this.roster.trackedRoomIds().filter((roomId) => accepted.has(roomId));
+    const reconciliation = this.roster.reconcile(acceptedIds);
+    await Promise.all(
+      reconciliation.removed.map(async (roomId) => {
+        await this.leaveRoomTracking(roomId);
+        await this.onRoomLeft?.(roomId);
+      })
+    );
+    await Promise.all(
+      reconciliation.admitting.map(async ([roomId, ticket]) => {
+        const admitted = await this.performAdmission(roomId, ticket);
+        if (admitted) {
+          await this.onRoomJoined?.(roomId, accepted.get(roomId) ?? {});
+        }
+      })
+    );
+    await Promise.all(
+      reconciliation.resync.map(async (roomId) => {
+        try {
+          await this.link.subscribeRoom(roomId);
+        } catch (error) {
+          this.logger.warn("RoomPresence failed to resubscribe surviving room after reconnect", {
+            roomId,
+            error
+          });
+        }
+      })
+    );
+  }
   async unsubscribeRoom(roomId) {
     try {
       await this.link.unsubscribeRoom(roomId);
@@ -2690,9 +3789,10 @@ var AgentRuntime = class {
   executions = /* @__PURE__ */ new Map();
   executionWatchers = /* @__PURE__ */ new Map();
   logger;
-  running = false;
-  stopping = false;
-  fatalError = null;
+  stoppedSignal = new TerminalSignal();
+  lifecycle;
+  startGate = new SingleFlight2();
+  stopGate = new SingleFlight2();
   constructor(options) {
     this.link = options.link;
     this.agentId = options.agentId;
@@ -2701,7 +3801,7 @@ var AgentRuntime = class {
     this.onRoomJoined = options.onRoomJoined;
     this.onRoomLeft = options.onRoomLeft;
     this.onError = options.onError;
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
     this.onContactEvent = options.onContactEvent;
     this.onParticipantAdded = options.onParticipantAdded;
     this.onParticipantRemoved = options.onParticipantRemoved;
@@ -2713,6 +3813,19 @@ var AgentRuntime = class {
       maxMessageRetries: options.sessionConfig?.maxMessageRetries ?? 1,
       enableContextHydration: options.sessionConfig?.enableContextHydration ?? true
     };
+    this.lifecycle = new LifecycleTracker({ status: "not_started" }, {
+      owner: "AgentRuntime",
+      logContext: { agentId: this.agentId },
+      logger: this.logger,
+      isLegalTransition: isLegalRuntimeTransition,
+      onTransition: (state) => {
+        if (state.status === "stopped") {
+          this.stoppedSignal.settle(null);
+        } else if (state.status === "failed") {
+          this.stoppedSignal.settle(state.error);
+        }
+      }
+    });
     this.presence = new RoomPresence({
       link: this.link,
       roomFilter: options.roomFilter,
@@ -2748,6 +3861,7 @@ var AgentRuntime = class {
           return;
         }
         case "message_created":
+        case "reconnected":
           await this.getOrCreateExecution(roomId).enqueue(event);
           return;
         default:
@@ -2756,65 +3870,138 @@ var AgentRuntime = class {
     };
     this.presence.onContactEvent = this.onContactEvent ?? null;
   }
+  /** Current lifecycle state of this runtime. */
+  get state() {
+    return this.lifecycle.state;
+  }
+  /**
+   * Connect, subscribe, and begin consuming platform events.
+   *
+   * Repeated or concurrent calls join the in-flight start instead of starting a
+   * second consume loop. Calling `start()` while a `stop()` is still in flight
+   * rejects with a `RuntimeStateError`.
+   */
   async start() {
-    if (this.running) {
-      return;
-    }
-    this.running = true;
-    this.stopping = false;
-    this.fatalError = null;
+    await startWithGate({
+      lifecycle: this.lifecycle,
+      startGate: this.startGate,
+      stopGate: this.stopGate,
+      stoppedSignal: this.stoppedSignal,
+      ownerName: "AgentRuntime",
+      runStart: () => this.runStart()
+    });
+  }
+  async runStart() {
     try {
       await this.presence.start();
     } catch (error) {
-      await this.handleStartFailure();
+      await this.finishFailedStart();
       throw error;
     }
+    if (this.lifecycle.is("starting")) {
+      this.lifecycle.transition({ status: "running" }, "started");
+    }
     void this.presence.waitUntilStopped().catch((error) => this.failRuntime(error, syntheticRuntimeFailureEvent(this.agentId)));
   }
+  async finishFailedStart() {
+    try {
+      await this.handleStartFailure();
+    } catch (cleanupError) {
+      this.markFailed(cleanupError, "start-cleanup-failed");
+      throw cleanupError;
+    }
+    if (this.lifecycle.is("starting")) {
+      this.lifecycle.transition({ status: "stopped" }, "start-failed");
+    }
+  }
   async handleStartFailure() {
-    this.running = false;
-    this.stopping = false;
+    this.presence.abortEventLoop();
     await this.link.disconnect();
   }
+  /**
+   * Tear the runtime down.
+   *
+   * A concurrent second call joins the in-flight teardown and mirrors its
+   * outcome — including rejecting with the *same* `Error` instance — instead of
+   * reporting a shutdown it did not perform.
+   */
   async stop(timeoutMs) {
-    if (this.stopping || !this.running && !this.fatalError) {
+    return await this.stopGate.run(() => this.runStop(timeoutMs));
+  }
+  async runStop(timeoutMs) {
+    const pendingStart = this.lifecycle.is("starting") ? this.startGate.pending : null;
+    if (pendingStart) {
+      try {
+        await pendingStart;
+      } catch (error) {
+        this.logger.debug("AgentRuntime stop is proceeding after the in-flight start failed", { error });
+      }
+    }
+    if (this.lifecycle.is("not_started") || this.lifecycle.is("stopped")) {
       return true;
     }
-    this.stopping = true;
-    this.running = false;
+    const fatalError = this.lifecycle.is("failed") ? this.lifecycle.state.error : null;
+    this.startGate.reset();
+    this.lifecycle.transition({ status: "stopping" }, "stop");
+    try {
+      return await this.performStop(timeoutMs, fatalError);
+    } catch (error) {
+      this.markFailed(error, "stop-failed");
+      throw error;
+    }
+  }
+  async performStop(timeoutMs, fatalError) {
+    const errors = [];
     this.presence.abortEventLoop();
-    await this.presence.waitUntilStopped().catch(() => void 0);
+    await isolateTeardown(errors, () => this.presence.waitUntilStopped());
     let graceful = true;
     await Promise.all(
       [...this.executions].map(async ([roomId, execution]) => {
-        const stopped = await execution.stop(timeoutMs);
-        if (!stopped) {
-          graceful = false;
-        }
+        await isolateTeardown(errors, async () => {
+          graceful = await execution.stop(timeoutMs) && graceful;
+        });
         this.executions.delete(roomId);
       })
     );
-    await this.presence.stop();
+    await isolateTeardown(errors, () => this.presence.stop());
     for (const roomId of [...this.contexts.keys()]) {
-      await this.onSessionCleanup(roomId);
+      await isolateTeardown(errors, () => this.onSessionCleanup(roomId));
     }
     this.contexts.clear();
     this.executions.clear();
     this.executionWatchers.clear();
-    await this.link.disconnect();
-    if (this.fatalError) {
-      throw this.fatalError instanceof Error ? this.fatalError : new Error(String(this.fatalError));
+    await isolateTeardown(errors, () => this.link.disconnect());
+    const failure = this.lifecycle.is("failed") ? this.lifecycle.state.error : fatalError;
+    if (failure) {
+      if (!this.lifecycle.is("failed")) {
+        this.lifecycle.transition({ status: "failed", error: failure }, "stopped-after-failure");
+      }
+      errors.unshift(failure);
+    }
+    if (errors.length > 0) {
+      throw combineTeardownErrors(errors, "AgentRuntime failed to tear down cleanly");
     }
+    this.lifecycle.transition({ status: "stopped" }, "stopped");
     return graceful;
   }
   getContext(roomId) {
     return this.contexts.get(roomId);
   }
+  /**
+   * Resolve once the runtime has actually stopped, or reject with the fatal
+   * error that ended it.
+   *
+   * A runtime that was never started stays pending until it stops or fails;
+   * starting it does not resolve a pending wait.
+   */
   async waitUntilStopped() {
-    await this.presence.waitUntilStopped().catch(() => void 0);
-    if (this.fatalError) {
-      throw this.fatalError instanceof Error ? this.fatalError : new Error(String(this.fatalError));
+    await this.stoppedSignal.wait();
+  }
+  markFailed(error, trigger) {
+    if (this.lifecycle.is("not_started")) {
+      return false;
     }
+    return this.lifecycle.fail(error, trigger);
   }
   getContexts() {
     return [...this.contexts.values()];
@@ -2827,14 +4014,23 @@ var AgentRuntime = class {
     await this.getOrCreateExecution(roomId).bootstrapMessage(message);
   }
   async resetRoomSession(roomId, timeoutMs) {
-    return this.teardownExecution(roomId, timeoutMs);
+    return await this.teardownExecution(roomId, timeoutMs);
   }
   async teardownExecution(roomId, timeoutMs) {
     const execution = this.executions.get(roomId);
-    const graceful = execution ? await execution.stop(timeoutMs) : true;
+    const errors = [];
+    let graceful = true;
+    if (execution) {
+      await isolateTeardown(errors, async () => {
+        graceful = await execution.stop(timeoutMs);
+      });
+    }
     this.executions.delete(roomId);
     this.contexts.delete(roomId);
-    await this.onSessionCleanup(roomId);
+    await isolateTeardown(errors, () => this.onSessionCleanup(roomId));
+    if (errors.length > 0) {
+      throw combineTeardownErrors(errors, "AgentRuntime failed to tear down cleanly");
+    }
     return graceful;
   }
   getOrCreateExecution(roomId) {
@@ -2895,15 +4091,20 @@ var AgentRuntime = class {
     return context;
   }
   async failRuntime(error, event) {
-    if (!this.fatalError) {
-      this.fatalError = error;
-      this.running = false;
+    if (this.markFailed(error, "runtime-error")) {
       this.logger.error("Fatal runtime error handling platform event", {
         eventType: event.type,
         roomId: event.roomId,
         error
       });
       this.notifyOnError(error, event);
+    } else {
+      this.logger.debug("Runtime error after the lifecycle already ended", {
+        status: this.lifecycle.state.status,
+        eventType: event.type,
+        roomId: event.roomId,
+        error
+      });
     }
     this.presence.abortEventLoop();
   }
@@ -3104,9 +4305,11 @@ var ContactCallbackTools = class {
   rest;
   roomId;
   contactTools;
-  constructor(rest, roomId) {
+  logger;
+  constructor(rest, roomId, logger) {
     this.rest = rest;
     this.roomId = roomId;
+    this.logger = resolveLogger(logger);
     const hasContactMethods = Boolean(
       rest.listContacts || rest.addContact || rest.removeContact || rest.listContactRequests || rest.respondContactRequest
     );
@@ -3141,14 +4344,22 @@ var ContactCallbackTools = class {
     if (!this.rest.createChatEvent) {
       throw new UnsupportedFeatureError("Event sending is not available in current REST adapter");
     }
-    return this.rest.createChatEvent(
-      roomId,
-      {
-        content,
-        messageType,
-        ...metadata ? { metadata } : {}
-      }
-    );
+    try {
+      return await this.rest.createChatEvent(
+        roomId,
+        {
+          content,
+          messageType,
+          ...metadata ? { metadata } : {}
+        }
+      );
+    } catch (error) {
+      this.logger.warn("contact callback chat event send failed", { roomId, messageType, error });
+      return { ok: false, status: "failed", message: asErrorMessage(error) };
+    }
+  }
+  async sendFailure(failure) {
+    return sendFailureViaEvent(this.sendEvent.bind(this), failure);
   }
   async addParticipant() {
     throw new UnsupportedFeatureError("addParticipant is unavailable for contact callbacks");
@@ -3379,7 +4590,7 @@ var ContactEventHandler = class {
   constructor(options) {
     this.config = options.config;
     this.rest = options.rest;
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
     this.onBroadcast = options.onBroadcast;
     this.onHubEvent = options.onHubEvent;
     this.onHubInit = options.onHubInit;
@@ -3429,7 +4640,7 @@ var ContactEventHandler = class {
       this.logger.warn("Contact event callback strategy configured but no onEvent callback provided");
       return;
     }
-    const callbackTools = tools ?? new ContactCallbackTools(this.rest, event.roomId);
+    const callbackTools = tools ?? new ContactCallbackTools(this.rest, event.roomId, this.logger);
     try {
       await callback(event, callbackTools);
     } catch (error) {
@@ -3514,7 +4725,8 @@ var ContactEventHandler = class {
         const msg = event.payload.message ? `
 Message: "${event.payload.message}"` : "";
         const handle = normalizeHandle(event.payload.from_handle);
-        return `[Contact Request] ${event.payload.from_name} (${handle}) wants to connect.${msg}
+        const name = displayName(event.payload.from_name);
+        return `[Contact Request] ${name} (${handle}) wants to connect.${msg}
 Request ID: ${event.payload.id}`;
       }
       case "contact_request_updated": {
@@ -3533,7 +4745,8 @@ Request ID: ${event.payload.id}`;
       }
       case "contact_added": {
         const handle = normalizeHandle(event.payload.handle);
-        return `[Contact Added] ${event.payload.name} (${handle}) is now a contact.
+        const name = displayName(event.payload.name);
+        return `[Contact Added] ${name} (${handle}) is now a contact.
 Type: ${event.payload.type}, ID: ${event.payload.id}`;
       }
       case "contact_removed":
@@ -3545,7 +4758,7 @@ Type: ${event.payload.type}, ID: ${event.payload.id}`;
     switch (event.type) {
       case "contact_added": {
         const handle = normalizeHandle(event.payload.handle);
-        return `[Contacts]: ${handle} (${event.payload.name}) is now a contact`;
+        return `[Contacts]: ${handle} (${displayName(event.payload.name)}) is now a contact`;
       }
       case "contact_removed":
         return `[Contacts]: Contact ${event.payload.id} was removed`;
@@ -3676,10 +4889,14 @@ function normalizeHandle(handle) {
   if (!handle) return "@unknown";
   return handle.startsWith("@") ? handle : `@${handle}`;
 }
+function displayName(name) {
+  return name?.trim() || "Unknown contact";
+}
 
 // src/runtime/PlatformRuntime.ts
 var MAX_MESSAGE_RETRIES = 4294967295;
 var isValidRetryCount = (value) => Number.isInteger(value) && value >= 0 && value <= MAX_MESSAGE_RETRIES;
+var START_CLEANUP_TRIGGER = "start-failed";
 var PlatformRuntime = class {
   _agentId;
   _apiKey;
@@ -3696,12 +4913,14 @@ var PlatformRuntime = class {
   _onParticipantRemoved;
   _roomFilter;
   _contextFactory;
+  lifecycle;
   linkInstance;
   initPromise = null;
   runtime;
   contactHandler;
   activeAdapter;
-  stopping = false;
+  startGate = new SingleFlight2();
+  stopGate = new SingleFlight2();
   _agentName = "";
   _agentDescription = "";
   contactsSubscribed = false;
@@ -3727,17 +4946,30 @@ var PlatformRuntime = class {
     this._wsUrl = options.wsUrl;
     this._restUrl = options.restUrl;
     this.linkInstance = options.link;
-    this.linkOptions = options.linkOptions;
+    this.linkOptions = {
+      ...options.linkOptions,
+      logger: options.logger ?? options.linkOptions?.logger
+    };
     this.preprocessor = options.preprocessor ?? new DefaultPreprocessor();
     this.sessionConfig = options.sessionConfig;
     this.contactConfig = options.contactConfig;
     this.agentConfig = options.agentConfig;
-    this.logger = options.logger ?? new NoopLogger();
+    this.logger = resolveLogger(options.logger);
     this.configuredIdentity = options.identity;
     this._onParticipantAdded = options.onParticipantAdded;
     this._onParticipantRemoved = options.onParticipantRemoved;
     this._roomFilter = options.roomFilter;
     this._contextFactory = options.contextFactory;
+    this.lifecycle = new LifecycleTracker({ status: "not_started" }, {
+      owner: "PlatformRuntime",
+      logContext: { agentId: this._agentId },
+      logger: this.logger,
+      isLegalTransition: isLegalRuntimeTransition
+    });
+  }
+  /** Current lifecycle state of this runtime. */
+  get state() {
+    return this.lifecycle.state;
   }
   get link() {
     if (!this.linkInstance) {
@@ -3757,6 +4989,14 @@ var PlatformRuntime = class {
   get contactConfiguration() {
     return this.contactConfig;
   }
+  /**
+   * Whether the contacts channel subscription is currently held.
+   *
+   * @deprecated Read {@link PlatformRuntime.state} for lifecycle questions: this
+   * flag is only ever `true` while the runtime is running and is cleared on
+   * teardown, so it conflates "contacts are subscribed" with "the runtime is
+   * alive".
+   */
   get isContactsSubscribed() {
     return this.contactsSubscribed;
   }
@@ -3779,8 +5019,7 @@ var PlatformRuntime = class {
         agentId: this._agentId,
         apiKey: this._apiKey,
         wsUrl: this._wsUrl,
-        restUrl: this._restUrl,
-        logger: this.logger
+        restUrl: this._restUrl
       });
     }
     if (this.configuredIdentity) {
@@ -3792,11 +5031,49 @@ var PlatformRuntime = class {
     this._agentName = me.name;
     this._agentDescription = me.description ?? "";
   }
+  /**
+   * Connect the adapter to the platform.
+   *
+   * Repeated or concurrent calls join the in-flight start. Calling `start()`
+   * while a `stop()` is still in flight rejects with a {@link RuntimeStateError}.
+   * A successful start also re-arms teardown, so a runtime whose previous
+   * `stop()` failed can be shut down properly on the next attempt.
+   */
   async start(adapter) {
+    await startWithGate({
+      lifecycle: this.lifecycle,
+      startGate: this.startGate,
+      stopGate: this.stopGate,
+      ownerName: "PlatformRuntime",
+      runStart: () => this.runStart(adapter)
+    });
+  }
+  async runStart(adapter) {
+    const startState = this.lifecycle.state;
+    try {
+      await this.doStart(adapter, startState);
+    } catch (error) {
+      if (this.lifecycle.isCurrent(startState)) {
+        this.lifecycle.fail(error, START_CLEANUP_TRIGGER);
+      }
+      throw error;
+    }
+    if (this.lifecycle.isCurrent(startState)) {
+      this.lifecycle.transition({ status: "running" }, "started");
+    }
+  }
+  async doStart(adapter, startState) {
+    const assertNotSuperseded = () => {
+      if (!this.lifecycle.isCurrent(startState)) {
+        throw new RuntimeStateError("PlatformRuntime start was superseded by stop()");
+      }
+    };
     await this.initialize();
-    await adapter.onStarted(this._agentName, this._agentDescription);
+    assertNotSuperseded();
     this.activeAdapter = adapter;
     try {
+      await adapter.onStarted(this._agentName, this._agentDescription);
+      assertNotSuperseded();
       this.contactHandler = new ContactEventHandler({
         config: this.contactConfig ?? { strategy: "disabled" },
         rest: this.link.rest,
@@ -3810,7 +5087,18 @@ var PlatformRuntime = class {
         onHubEvent: async (roomId, event) => {
           const runtime = this.runtime;
           if (!runtime) return;
-          await runtime.enqueueEvent(roomId, event);
+          try {
+            await runtime.enqueueEvent(roomId, event);
+          } catch (error) {
+            if (!(error instanceof RuntimeStateError)) {
+              throw error;
+            }
+            this.logger.error("Dropped contact hub event for a stopped room execution", {
+              roomId,
+              eventType: event.type,
+              error: error.message
+            });
+          }
         },
         onHubInit: async (roomId, systemPrompt) => {
           const runtime = this.runtime;
@@ -3833,10 +5121,14 @@ var PlatformRuntime = class {
         contextFactory: this._contextFactory
       });
       await this.runtime.start();
+      assertNotSuperseded();
       this.contactsSubscribed = Boolean(this.link.capabilities.contacts);
     } catch (error) {
+      if (!this.lifecycle.isCurrent(startState)) {
+        throw error;
+      }
       try {
-        await this.stop();
+        await this.beginStop(void 0, START_CLEANUP_TRIGGER);
       } catch (stopError) {
         throw new AggregateError(
           [error, stopError],
@@ -3846,49 +5138,63 @@ var PlatformRuntime = class {
       throw error;
     }
   }
+  /**
+   * Tear the runtime down and release the platform connection.
+   *
+   * A concurrent second call joins the in-flight teardown and mirrors its
+   * outcome — including rejecting with the *same* `Error` instance — rather than
+   * reporting a graceful shutdown it did not perform. A failed teardown does not
+   * disable future ones: a subsequent `start()` re-arms `stop()`.
+   */
   async stop(timeoutMs) {
-    if (this.stopping) {
-      return true;
-    }
+    return await this.beginStop(timeoutMs, "stop");
+  }
+  async beginStop(timeoutMs, trigger) {
+    return await this.stopGate.run(() => this.runStop(timeoutMs, trigger));
+  }
+  async runStop(timeoutMs, trigger) {
+    this.startGate.reset();
     const runtime = this.runtime;
     const adapter = this.activeAdapter;
     if (!runtime && !adapter) {
+      if (this.lifecycle.is("failed")) {
+        this.logger.debug("PlatformRuntime stop is resurfacing the recorded start failure", { error: this.lifecycle.state.error });
+        throw this.lifecycle.state.error;
+      }
+      if (this.lifecycle.is("starting")) {
+        this.lifecycle.transition({ status: "stopped" }, trigger);
+      }
       return true;
     }
-    this.stopping = true;
+    this.lifecycle.transition({ status: "stopping" }, trigger);
     this.runtime = void 0;
     this.contactHandler = void 0;
     this.contactsSubscribed = false;
     this.activeAdapter = void 0;
     let graceful = true;
-    let runtimeError = null;
+    const errors = [];
     if (runtime) {
-      try {
+      await isolateTeardown(errors, async () => {
         graceful = await runtime.stop(timeoutMs);
-      } catch (error) {
-        runtimeError = error;
-      }
-    }
-    try {
-      await adapter?.onRuntimeStop?.();
-    } catch (error) {
-      if (runtimeError) {
-        throw new AggregateError(
-          [runtimeError, error],
-          "PlatformRuntime stop failed and adapter cleanup also failed"
-        );
-      }
-      throw error;
+      });
     }
-    if (runtimeError) {
-      throw runtimeError instanceof Error ? runtimeError : new Error(String(runtimeError));
+    await isolateTeardown(errors, () => Promise.resolve(adapter?.onRuntimeStop?.()));
+    if (errors.length > 0) {
+      throw this.recordStopFailure(
+        combineTeardownErrors(errors, "PlatformRuntime stop failed and adapter cleanup also failed")
+      );
     }
-    this.stopping = false;
+    this.lifecycle.transition({ status: "stopped" }, "stopped");
     return graceful;
   }
   async [Symbol.asyncDispose]() {
     await this.stop();
   }
+  recordStopFailure(error) {
+    const failure = toLifecycleError(error);
+    this.lifecycle.fail(failure, "stop-failed");
+    return failure;
+  }
   async runForever() {
     if (!this.runtime) {
       throw new RuntimeStateError("Runtime not started");
@@ -4002,6 +5308,10 @@ async function runWithGracefulShutdown(agent, options) {
 export {
   deriveDefaultRestUrl,
   BandLink,
+  isLegalRuntimeTransition,
+  SingleFlight2 as SingleFlight,
+  LifecycleTracker,
+  startWithGate,
   Execution,
   AgentTools,
   ExecutionContext,