@band-ai/sdk 0.3.4 → 0.4.1

package/dist/runtime.cjs

@@ -41,11 +41,11 @@ __export(runtime_exports, {
   MCP_TOOL_PREFIX: () => MCP_TOOL_PREFIX,
   MEMORY_SECTION: () => MEMORY_SECTION,
   MEMORY_TOOL_NAMES: () => MEMORY_TOOL_NAMES,
-  ParticipantRoster: () => import_band_sdk_core6.ParticipantRoster,
+  ParticipantRoster: () => import_band_sdk_core10.ParticipantRoster,
   PlatformRuntime: () => PlatformRuntime,
-  RetryTracker: () => import_band_sdk_core6.RetryTracker,
+  RetryTracker: () => import_band_sdk_core10.RetryTracker,
   RoomPresence: () => RoomPresence,
-  RoomRoster: () => import_band_sdk_core6.RoomRoster,
+  RoomRoster: () => import_band_sdk_core10.RoomRoster,
   SYNTHETIC_CONTACT_EVENTS_SENDER_ID: () => SYNTHETIC_CONTACT_EVENTS_SENDER_ID,
   SYNTHETIC_CONTACT_EVENTS_SENDER_NAME: () => SYNTHETIC_CONTACT_EVENTS_SENDER_NAME,
   SYNTHETIC_SENDER_TYPE: () => SYNTHETIC_SENDER_TYPE,
@@ -89,14 +89,175 @@ function ensureHandlePrefix(handle) {
   return handle.startsWith("@") ? handle : `@${handle}`;
 }
 
+// src/core/sensitiveTerms.ts
+var SENSITIVE_KEY_TERMS = "authorization|api[-_ ]?key|token|secret|password|cookie";
+var GATEWAY_FREE_TEXT_SENSITIVE_KEY_TERMS = `${SENSITIVE_KEY_TERMS}|session`;
+
 // src/core/logger.ts
 var noop = () => void 0;
+var SENSITIVE_KEY_PATTERN = new RegExp(`(${SENSITIVE_KEY_TERMS})`, "i");
 var NoopLogger = class {
   debug = noop;
   info = noop;
   warn = noop;
   error = noop;
 };
+function resolveLogger(logger) {
+  if (!logger) {
+    return new NoopLogger();
+  }
+  return logger instanceof GuardedLogger ? logger : new GuardedLogger(logger);
+}
+var GuardedLogger = class {
+  constructor(inner) {
+    this.inner = inner;
+  }
+  debug(message, context) {
+    return this.emit("debug", message, context);
+  }
+  info(message, context) {
+    return this.emit("info", message, context);
+  }
+  warn(message, context) {
+    return this.emit("warn", message, context);
+  }
+  error(message, context) {
+    return this.emit("error", message, context);
+  }
+  emit(level, message, context) {
+    try {
+      const result = this.inner[level](message, context);
+      if (result instanceof Promise) {
+        result.catch(noop);
+      }
+      return result;
+    } catch {
+    }
+  }
+};
+
+// src/core/coercion.ts
+var MAX_ERROR_CAUSE_DEPTH = 5;
+var MAX_ERROR_DETAIL_LENGTH = 500;
+var LENGTH_TRUNCATED_MARKER = "... (truncated)";
+var DEPTH_TRUNCATED_MARKER = "... (cause chain truncated)";
+function asOptionalRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function asNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function toDisplayText(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value == null) {
+    return "";
+  }
+  try {
+    const json = JSON.stringify(value);
+    return typeof json === "string" ? json : String(value);
+  } catch {
+    return String(value);
+  }
+}
+function asErrorMessage(error) {
+  return formatCaughtError(error, 0);
+}
+function formatCaughtError(error, depth) {
+  if (typeof error !== "object" || error === null) {
+    return truncate(String(error));
+  }
+  const message = truncate(asNestedMessage(error) ?? String(error));
+  const detail = selectDetail(asOptionalRecord(error));
+  if (detail === void 0) {
+    return message;
+  }
+  if (depth >= MAX_ERROR_CAUSE_DEPTH) {
+    return `${message} (${DEPTH_TRUNCATED_MARKER})`;
+  }
+  return `${message} (${formatErrorDetail(detail, depth + 1)})`;
+}
+function selectDetail(record) {
+  if (isPresentDetail(record?.data)) {
+    return record?.data;
+  }
+  if (isPresentDetail(record?.cause)) {
+    return record?.cause;
+  }
+  return void 0;
+}
+function isPresentDetail(value) {
+  if (value === void 0 || value === null) {
+    return false;
+  }
+  if (typeof value === "string") {
+    return asNonEmptyString(value) !== null;
+  }
+  if (value instanceof Error) {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  if (typeof value === "object") {
+    return isPlainObject(value) ? Object.keys(value).length > 0 : true;
+  }
+  return true;
+}
+function isPlainObject(value) {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function formatErrorDetail(detail, depth) {
+  if (detail instanceof Error || selectDetail(asOptionalRecord(detail)) !== void 0) {
+    return formatCaughtError(detail, depth);
+  }
+  return truncate(formatLeafDetail(detail));
+}
+function formatLeafDetail(detail) {
+  if (typeof detail === "string") {
+    return detail;
+  }
+  if (typeof detail === "number" && !Number.isFinite(detail)) {
+    return String(detail);
+  }
+  const builtin = formatNonEnumerableDetail(detail);
+  if (builtin !== null) {
+    return builtin;
+  }
+  const nested = asNestedMessage(detail);
+  if (nested !== null) {
+    return nested;
+  }
+  return toDisplayText(detail);
+}
+function formatNonEnumerableDetail(detail) {
+  if (detail instanceof RegExp) {
+    return detail.toString();
+  }
+  if (detail instanceof Map) {
+    return `Map ${toDisplayText([...detail])}`;
+  }
+  if (detail instanceof Set) {
+    return `Set ${toDisplayText([...detail])}`;
+  }
+  return null;
+}
+function truncate(text) {
+  return text.length > MAX_ERROR_DETAIL_LENGTH ? `${text.slice(0, MAX_ERROR_DETAIL_LENGTH)}${LENGTH_TRUNCATED_MARKER}` : text;
+}
+function asNestedMessage(value) {
+  const record = asOptionalRecord(value);
+  return asNonEmptyString(record?.message);
+}
 
 // src/client/rest/requestOptions.ts
 var DEFAULT_REQUEST_OPTIONS = {
@@ -135,6 +296,80 @@ var RuntimeStateError = class extends BandSdkError {
     this.name = "RuntimeStateError";
   }
 };
+var RecoverableTurnError = class extends BandSdkError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "RecoverableTurnError";
+  }
+};
+
+// src/contracts/chatEvents.ts
+var CHAT_EVENT_TYPES = ["tool_call", "tool_result", "thought", "error", "task"];
+var CHAT_MESSAGE_TYPES = ["text", ...CHAT_EVENT_TYPES];
+function isChatEventType(value) {
+  return CHAT_EVENT_TYPES.includes(value);
+}
+function assertChatEventType(value) {
+  if (!isChatEventType(value)) {
+    throw new ValidationError(
+      `Invalid event message_type '${value}'. Expected one of: ${CHAT_EVENT_TYPES.join(", ")}`
+    );
+  }
+}
+var VISIBLE_CONTENT_PATTERN = /[\p{L}\p{N}\p{P}\p{S}]/u;
+function isBlankEventContent(content) {
+  return !VISIBLE_CONTENT_PATTERN.test(content);
+}
+
+// src/contracts/protocols.ts
+var FAILURE_EVENT_TYPE = "error";
+var FAILURE_METADATA_KEY = "failure";
+function sendFailureViaEvent(sendEvent, failure) {
+  const { content, messageType, metadata } = toFailureEvent(failure);
+  return sendEvent(content, messageType, metadata);
+}
+function toFailureEvent(failure) {
+  const content = isBlankEventContent(failure.message) ? `${failure.provider} failed without an error message.` : failure.message;
+  return {
+    content,
+    messageType: FAILURE_EVENT_TYPE,
+    metadata: { [FAILURE_METADATA_KEY]: failure.toObject() }
+  };
+}
+var TOOL_EXECUTOR_ERROR_TYPES = [
+  "ToolArgumentsValidationError",
+  "ToolNotFoundError",
+  "ToolExecutionError"
+];
+function createToolExecutorError(input) {
+  return {
+    ok: false,
+    errorType: input.errorType,
+    toolName: input.toolName,
+    message: input.message,
+    legacyMessage: input.legacyMessage ?? input.message,
+    ...input.details ? { details: input.details } : {}
+  };
+}
+function isToolExecutorError(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return candidate.ok === false && typeof candidate.errorType === "string" && TOOL_EXECUTOR_ERROR_TYPES.includes(candidate.errorType) && typeof candidate.toolName === "string" && typeof candidate.message === "string" && typeof candidate.legacyMessage === "string";
+}
+function isStructuredToolFailure(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const payload = value;
+  return payload.ok === false && typeof payload.message === "string";
+}
+var DEFAULT_AGENT_TOOLS_CAPABILITIES = {
+  peers: true,
+  contacts: true,
+  memory: true
+};
 
 // src/runtime/formatters.ts
 function isMetadataMap(value) {
@@ -338,9 +573,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
     );
@@ -375,14 +612,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");
@@ -613,7 +858,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;
@@ -663,7 +908,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) {
@@ -748,7 +993,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": {
@@ -767,7 +1013,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":
@@ -779,7 +1026,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`;
@@ -910,6 +1157,254 @@ function normalizeHandle(handle) {
   if (!handle) return "@unknown";
   return handle.startsWith("@") ? handle : `@${handle}`;
 }
+function displayName(name) {
+  return name?.trim() || "Unknown contact";
+}
+
+// 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;
+    }
+    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 SingleFlight = 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();
+    }
+  }
+};
 
 // src/runtime/Execution.ts
 function toMessageEvent(message) {
@@ -941,13 +1436,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 SingleFlight();
+  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;
@@ -955,27 +1455,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()) {
@@ -1010,27 +1544,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;
       }
@@ -1055,7 +1620,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)) {
@@ -1066,20 +1631,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;
@@ -1090,25 +1652,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) {
@@ -1145,6 +1701,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 {
@@ -1154,7 +1718,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;
@@ -1169,13 +1733,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;
@@ -1205,7 +1777,7 @@ var Execution = class {
 };
 
 // src/runtime/tools/AgentTools.ts
-var import_band_sdk_core = require("@band-ai/band-sdk-core");
+var import_band_sdk_core2 = require("@band-ai/band-sdk-core");
 
 // src/contracts/capabilities.ts
 var CAPABILITY_LABELS = {
@@ -1219,64 +1791,15 @@ function assertCapability(capabilities, capability, label = CAPABILITY_LABELS[ca
   }
 }
 
-// src/contracts/chatEvents.ts
-var CHAT_EVENT_TYPES = ["tool_call", "tool_result", "thought", "error", "task"];
-var CHAT_MESSAGE_TYPES = ["text", ...CHAT_EVENT_TYPES];
-function isChatEventType(value) {
-  return CHAT_EVENT_TYPES.includes(value);
-}
-function assertChatEventType(value) {
-  if (!isChatEventType(value)) {
-    throw new ValidationError(
-      `Invalid event message_type '${value}'. Expected one of: ${CHAT_EVENT_TYPES.join(", ")}`
-    );
-  }
-}
-
-// src/contracts/protocols.ts
-var TOOL_EXECUTOR_ERROR_TYPES = [
-  "ToolArgumentsValidationError",
-  "ToolNotFoundError",
-  "ToolExecutionError"
-];
-function createToolExecutorError(input) {
-  return {
-    ok: false,
-    errorType: input.errorType,
-    toolName: input.toolName,
-    message: input.message,
-    legacyMessage: input.legacyMessage ?? input.message,
-    ...input.details ? { details: input.details } : {}
-  };
-}
-function isToolExecutorError(value) {
-  if (!value || typeof value !== "object") {
-    return false;
-  }
-  const candidate = value;
-  return candidate.ok === false && typeof candidate.errorType === "string" && TOOL_EXECUTOR_ERROR_TYPES.includes(candidate.errorType) && typeof candidate.toolName === "string" && typeof candidate.message === "string" && typeof candidate.legacyMessage === "string";
-}
-function isStructuredToolFailure(value) {
-  if (!value || typeof value !== "object") {
-    return false;
-  }
-  const payload = value;
-  return payload.ok === false && typeof payload.message === "string";
-}
-var DEFAULT_AGENT_TOOLS_CAPABILITIES = {
-  peers: true,
-  contacts: true,
-  memory: true
-};
-
-// src/contracts/memory.ts
-var SENSORY_MEMORY_TYPES = [
-  "iconic",
-  // Visual input
-  "echoic",
-  // Auditory input
-  "haptic"
-  // Tactile input
+// src/contracts/memory.ts
+var import_band_sdk_core = require("@band-ai/band-sdk-core");
+var SENSORY_MEMORY_TYPES = [
+  "iconic",
+  // Visual input
+  "echoic",
+  // Auditory input
+  "haptic"
+  // Tactile input
 ];
 var COGNITIVE_MEMORY_TYPES = [
   "episodic",
@@ -1313,18 +1836,22 @@ var MEMORY_SEGMENTS = [
   // Behavioral rules or policies
 ];
 var MEMORY_STORE_SCOPES = [
+  "agent",
+  // Private to the storing agent; omit subject_id
   "subject",
   // About one person/agent; requires subject_id
   "organization"
   // Shared org-wide
 ];
 var MEMORY_LIST_SCOPES = [
+  "agent",
+  // Caller's private agent-scoped memories only
   "subject",
   // Subject-scoped memories only
   "organization",
   // Organization-scoped memories only
   "all"
-  // Both scopes (no scope filter)
+  // All scopes (no scope filter)
 ];
 var MEMORY_STATUSES = [
   "active",
@@ -1347,7 +1874,15 @@ function isMemoryType(value) {
   return MEMORY_TYPES.includes(value);
 }
 function isMemoryTypeForSystem(system, type) {
-  return MEMORY_SYSTEM_TYPES[system].includes(type);
+  try {
+    (0, import_band_sdk_core.validateMemoryTypeForSystem)(system, type);
+    return true;
+  } catch (err) {
+    if (err instanceof Error && "issues" in err) {
+      return false;
+    }
+    throw err;
+  }
 }
 function isMemorySegment(value) {
   return MEMORY_SEGMENTS.includes(value);
@@ -1550,7 +2085,7 @@ var TOOL_MODELS = {
     required: ["action"]
   },
   band_list_memories: {
-    description: "List memories accessible to the agent. Returns memories about the specified subject (cross-agent sharing) and organization-wide shared memories.",
+    description: `List memories accessible to the agent. Use scope="agent" for the caller's private memories, scope="subject" for memories about a specific person or agent, and scope="organization" for org-wide shared memories. Omit scope or use scope="all" to search across scopes.`,
     properties: {
       subject_id: {
         type: "string",
@@ -1559,7 +2094,7 @@ var TOOL_MODELS = {
       scope: {
         type: "string",
         enum: [...MEMORY_LIST_SCOPES],
-        description: "Filter by scope."
+        description: `Filter by scope. "agent" returns the caller's private memories; "subject" and "organization" filter to those audiences; "all" omits the filter.`
       },
       system: {
         type: "string",
@@ -1595,7 +2130,7 @@ var TOOL_MODELS = {
     required: []
   },
   band_store_memory: {
-    description: "Store a new memory entry. The memory will be associated with the authenticated agent as the source. For subject-scoped memories, provide a subject_id. For organization-scoped memories, omit subject_id.",
+    description: 'Store a new memory entry. The memory will be associated with the authenticated agent as the source. Use scope="agent" for information private to this agent (no subject_id). Use scope="subject" with a subject_id for memories about a specific person or agent. Use scope="organization" for knowledge genuinely shared across the organization.',
     properties: {
       content: {
         type: "string",
@@ -1623,11 +2158,11 @@ var TOOL_MODELS = {
       scope: {
         type: "string",
         enum: [...MEMORY_STORE_SCOPES],
-        description: "Visibility scope."
+        description: 'Visibility scope. "agent" is private to this agent; "subject" requires subject_id; "organization" is shared org-wide.'
       },
       subject_id: {
         type: "string",
-        description: "UUID of the subject this memory is about (required for subject scope)."
+        description: "UUID of the subject this memory is about (required for subject scope; omit for agent scope)."
       },
       metadata: {
         type: "object",
@@ -1699,34 +2234,29 @@ function getToolDescription(name) {
 }
 
 // src/runtime/tools/AgentTools.ts
-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",
@@ -1744,8 +2274,8 @@ var AgentTools = class {
   constructor(options) {
     this.roomId = options.roomId;
     this.rest = options.rest;
-    this.roster = options.roster ?? new import_band_sdk_core.ParticipantRoster();
-    this.logger = options.logger ?? new NoopLogger();
+    this.roster = options.roster ?? new import_band_sdk_core2.ParticipantRoster();
+    this.logger = resolveLogger(options.logger);
     this.capabilities = {
       ...DEFAULT_AGENT_TOOLS_CAPABILITIES,
       ...options.capabilities
@@ -1785,14 +2315,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;
@@ -1916,6 +2446,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",
@@ -2202,16 +2733,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);
   }
@@ -2359,9 +2885,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 {
@@ -2539,22 +3065,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({
@@ -2569,7 +3079,7 @@ function validateToolArgs(toolName, args) {
 }
 
 // src/runtime/ExecutionContext.ts
-var import_band_sdk_core2 = require("@band-ai/band-sdk-core");
+var import_band_sdk_core3 = require("@band-ai/band-sdk-core");
 var DEDUP_CACHE_MAX = 500;
 var ExecutionContext = class {
   roomId;
@@ -2581,7 +3091,7 @@ var ExecutionContext = class {
   history = [];
   messageIds = /* @__PURE__ */ new Set();
   dedupCache = /* @__PURE__ */ new Map();
-  roster = new import_band_sdk_core2.ParticipantRoster();
+  roster = new import_band_sdk_core3.ParticipantRoster();
   tools;
   adapterTools;
   participantsMessage = null;
@@ -2599,16 +3109,27 @@ var ExecutionContext = class {
     this.enableContextCache = options.enableContextCache ?? true;
     this.contextCacheTtlMs = Math.max(0, (options.contextCacheTtlSeconds ?? 300) * 1e3);
     this.enableContextHydration = options.enableContextHydration ?? true;
-    this.retryTrackerInstance = new import_band_sdk_core2.RetryTracker(options.maxMessageRetries ?? 1);
+    this.retryTrackerInstance = new import_band_sdk_core3.RetryTracker(options.maxMessageRetries ?? 1);
     this.tools = new AgentTools({
       roomId: this.roomId,
       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;
   }
@@ -2853,22 +3374,43 @@ var ExecutionContext = class {
   }
 };
 
+// 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/runtime/rooms/RoomPresence.ts
-var import_band_sdk_core3 = require("@band-ai/band-sdk-core");
+var import_band_sdk_core4 = require("@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) {
@@ -2882,9 +3424,68 @@ async function hydrateExistingRooms(options) {
   }
 }
 
+// src/core/singleFlight.ts
+var SingleFlight2 = 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 SingleFlight2();
+      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/runtime/rooms/RoomPresence.ts
 var RoomPresence = class {
-  roster = new import_band_sdk_core3.RoomRoster();
+  roster = new import_band_sdk_core4.RoomRoster();
   onRoomJoined = null;
   onRoomLeft = null;
   onRoomEvent = null;
@@ -2896,7 +3497,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
@@ -2906,13 +3507,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();
@@ -2977,14 +3578,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");
@@ -2992,14 +3585,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();
     }
@@ -3007,7 +3594,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;
     }
@@ -3015,9 +3612,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() {
@@ -3071,6 +3666,9 @@ var RoomPresence = class {
             await this.onRoomEvent?.(event.roomId, event);
           }
           break;
+        case "reconnected":
+          await this.handleReconnected(event);
+          break;
         default:
           assertNever2(event);
       }
@@ -3089,14 +3687,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);
@@ -3141,9 +3799,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 SingleFlight();
+  stopGate = new SingleFlight();
   constructor(options) {
     this.link = options.link;
     this.agentId = options.agentId;
@@ -3152,7 +3811,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;
@@ -3164,6 +3823,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,
@@ -3199,6 +3871,7 @@ var AgentRuntime = class {
           return;
         }
         case "message_created":
+        case "reconnected":
           await this.getOrCreateExecution(roomId).enqueue(event);
           return;
         default:
@@ -3207,65 +3880,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()];
@@ -3278,14 +4024,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) {
@@ -3346,15 +4101,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();
   }
@@ -3394,6 +4154,55 @@ function syntheticRuntimeFailureEvent(agentId) {
   };
 }
 
+// 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/client/rest/pagination.ts
 var DEFAULT_PAGE_SIZE = 100;
 var DEFAULT_MAX_PAGES = 100;
@@ -3567,7 +4376,7 @@ function toNonNegativeInteger(value) {
 }
 
 // src/adapters/shared/coercion.ts
-function asOptionalRecord(value) {
+function asOptionalRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return void 0;
   }
@@ -3588,7 +4397,7 @@ function asNullableString(value) {
 
 // src/client/rest/responseNormalization.ts
 function asMetadataMap(value) {
-  return asOptionalRecord(value);
+  return asOptionalRecord2(value);
 }
 function normalizeContactRequestDirection(value) {
   const direction = asMetadataMap(value);
@@ -3623,7 +4432,7 @@ function mergeOptions(options, maxRetries) {
   };
 }
 function asMetadataMap2(value) {
-  return asOptionalRecord(value);
+  return asOptionalRecord2(value);
 }
 function requireNonEmptyStringField(value, field, source) {
   if (typeof value !== "string" || value.trim().length === 0) {
@@ -3679,7 +4488,7 @@ function asRecordArray(value) {
   if (!Array.isArray(value)) {
     return void 0;
   }
-  return value.filter((entry) => asOptionalRecord(entry) !== void 0);
+  return value.filter((entry) => asOptionalRecord2(entry) !== void 0);
 }
 function extractEnvelopeData(value) {
   const record = asMetadataMap2(value);
@@ -4176,107 +4985,213 @@ var FernRestAdapter = class {
   }
 };
 
-// src/platform/streaming/payloadSchemas.ts
-var import_zod = require("zod");
-var mentionSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  handle: import_zod.z.string().nullish(),
-  name: import_zod.z.string().nullish(),
-  username: import_zod.z.string().nullish()
-}).passthrough();
-var messageMetadataSchema = import_zod.z.object({
-  mentions: import_zod.z.array(mentionSchema).nullish()
-}).passthrough();
-var messageCreatedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  content: import_zod.z.string(),
-  message_type: import_zod.z.string(),
-  metadata: messageMetadataSchema.nullish(),
-  sender_id: import_zod.z.string(),
-  sender_type: import_zod.z.string(),
-  sender_name: import_zod.z.string().nullish(),
-  chat_room_id: import_zod.z.string().nullish(),
-  inserted_at: import_zod.z.string(),
-  updated_at: import_zod.z.string()
-}).passthrough();
-var roomOwnerSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  name: import_zod.z.string(),
-  type: import_zod.z.string()
-}).passthrough();
-var roomAddedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  title: import_zod.z.string().nullish(),
-  task_id: import_zod.z.string().nullish(),
-  inserted_at: import_zod.z.string().nullish(),
-  updated_at: import_zod.z.string().nullish(),
-  owner: roomOwnerSchema.nullish(),
-  status: import_zod.z.string().nullish(),
-  type: import_zod.z.string().nullish(),
-  created_at: import_zod.z.string().nullish(),
-  participant_role: import_zod.z.string().nullish()
-}).passthrough();
-var roomRemovedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  status: import_zod.z.string(),
-  type: import_zod.z.string(),
-  title: import_zod.z.string(),
-  removed_at: import_zod.z.string()
-}).passthrough();
-var participantAddedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  name: import_zod.z.string(),
-  type: import_zod.z.string(),
-  handle: import_zod.z.string().nullish()
-}).passthrough();
-var participantRemovedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string()
-}).passthrough();
-var roomDeletedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string()
-}).passthrough();
-var contactRequestReceivedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  from_handle: import_zod.z.string(),
-  from_name: import_zod.z.string(),
-  message: import_zod.z.string().nullish(),
-  status: import_zod.z.string(),
-  inserted_at: import_zod.z.string()
-}).passthrough();
-var contactRequestUpdatedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  status: import_zod.z.string()
-}).passthrough();
-var contactAddedPayloadSchema = import_zod.z.object({
-  id: import_zod.z.string(),
-  handle: import_zod.z.string(),
-  name: import_zod.z.string(),
-  type: import_zod.z.string(),
-  description: import_zod.z.string().nullish(),
-  is_external: import_zod.z.boolean().nullish(),
-  inserted_at: import_zod.z.string()
-}).passthrough();
-var contactRemovedPayloadSchema = import_zod.z.object({
-  id: import_zod.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
+var import_phoenix2 = require("phoenix");
+
+// src/core/deferred.ts
+function createDeferred() {
+  let resolve;
+  const promise = new Promise((innerResolve) => {
+    resolve = innerResolve;
+  });
+  return { promise, resolve };
+}
+
+// src/platform/streaming/ChannelRegistry.ts
 var import_phoenix = require("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/disconnectReason.ts
-var import_zod2 = require("zod");
+var import_zod = require("zod");
+var import_band_sdk_core5 = require("@band-ai/band-sdk-core");
 var UPGRADE_CODES = [
   "invalid_on_conflict",
   "connection_conflict",
@@ -4305,9 +5220,9 @@ var UPGRADE_REASONS = {
     retryable: true
   }
 };
-var upgradeErrorSchema = import_zod2.z.object({
-  status: import_zod2.z.number(),
-  body: import_zod2.z.preprocess(
+var upgradeErrorSchema = import_zod.z.object({
+  status: import_zod.z.number(),
+  body: import_zod.z.preprocess(
     (body) => {
       if (typeof body !== "string") {
         return body;
@@ -4318,16 +5233,16 @@ var upgradeErrorSchema = import_zod2.z.object({
         return null;
       }
     },
-    import_zod2.z.object({
-      error: import_zod2.z.object({
-        code: import_zod2.z.enum(UPGRADE_CODES),
-        message: import_zod2.z.string().optional(),
-        retry_after: import_zod2.z.number().nullable().optional(),
-        request_id: import_zod2.z.string().nullable().optional()
+    import_zod.z.object({
+      error: import_zod.z.object({
+        code: import_zod.z.enum(UPGRADE_CODES),
+        message: import_zod.z.string().optional(),
+        retry_after: import_zod.z.number().nullable().optional(),
+        request_id: import_zod.z.string().nullable().optional()
       })
     })
   ),
-  headers: import_zod2.z.record(import_zod2.z.unknown()).optional()
+  headers: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
 });
 var WebSocketDisconnectError = class extends Error {
   reason;
@@ -4338,18 +5253,20 @@ var WebSocketDisconnectError = class extends Error {
   }
 };
 function parseSupersedeDisconnectReason(payload) {
-  if (typeof payload.reason !== "string" || typeof payload.message !== "string") {
+  try {
+    const normalized = (0, import_band_sdk_core5.validateEventPayload)("supersede", payload);
+    return {
+      source: "agent_control",
+      code: normalized.reason,
+      message: normalized.message,
+      retryable: normalized.retryable,
+      retryAfter: normalized.retry_after ?? null,
+      targetSocketId: normalized.target_socket_id ?? null,
+      correlationId: normalized.correlation_id
+    };
+  } catch {
     return null;
   }
-  return {
-    source: "agent_control",
-    code: payload.reason,
-    message: payload.message,
-    retryable: false,
-    retryAfter: typeof payload.retry_after === "number" ? payload.retry_after : null,
-    targetSocketId: typeof payload.target_socket_id === "string" ? payload.target_socket_id : null,
-    correlationId: typeof payload.correlation_id === "string" ? payload.correlation_id : null
-  };
 }
 function parseUpgradeDisconnectReason(event) {
   const parsed = upgradeErrorSchema.safeParse(event);
@@ -4434,19 +5351,90 @@ async function readResponseBody(response) {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-// src/platform/streaming/PhoenixChannelsTransport.ts
-var import_band_sdk_core4 = require("@band-ai/band-sdk-core");
+// 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
+var import_band_sdk_core6 = require("@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 SingleFlight2();
   connectResolve = null;
   connectReject = null;
   lastDisconnectReason = null;
@@ -4455,7 +5443,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;
@@ -4463,7 +5451,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 import_phoenix.Socket(wsUrl, {
+    this.socket = new import_phoenix2.Socket(wsUrl, {
       params: {
         agent_id: options.agentId,
         ...options.conflictPolicy ? { on_conflict: options.conflictPolicy } : {}
@@ -4477,6 +5465,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();
     });
@@ -4513,42 +5530,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() {
@@ -4557,79 +5557,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) {
@@ -4667,7 +5616,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) {
@@ -4689,6 +5652,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;
@@ -4702,18 +5699,23 @@ var PhoenixChannelsTransport = class {
     if (!this.agentId) {
       return;
     }
-    await this.join((0, import_band_sdk_core4.agentControlTopic)(this.agentId), {
-      supersede: (payload) => {
-        const reason = parseSupersedeDisconnectReason(payload);
-        if (!reason) {
-          this.logger.warn("Invalid agent_control supersede payload", {
-            payload
-          });
-          return;
+    const topic = (0, import_band_sdk_core6.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;
@@ -4789,10 +5791,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)) {
@@ -4803,19 +5801,412 @@ function getSocketChannelCount(socket) {
 
 // src/platform/BandLink.ts
 var import_rest_client = require("@band-ai/rest-client");
-var import_band_sdk_core5 = require("@band-ai/band-sdk-core");
+var import_band_sdk_core9 = require("@band-ai/band-sdk-core");
+
+// src/platform/SubscriptionManager.ts
+var import_band_sdk_core8 = require("@band-ai/band-sdk-core");
+
+// src/platform/roomTopics.ts
+var import_band_sdk_core7 = require("@band-ai/band-sdk-core");
+function roomTopics(roomId) {
+  return { chat: (0, import_band_sdk_core7.chatRoomTopic)(roomId), participants: (0, import_band_sdk_core7.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 import_band_sdk_core8.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: (0, import_band_sdk_core5.chatRoomTopic)(roomId),
-    participants: (0, import_band_sdk_core5.roomParticipantsTopic)(roomId)
-  };
-}
 function toPlatformMessage(roomId, message) {
   return {
     id: message.id,
@@ -4829,6 +6220,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;
@@ -4838,18 +6242,21 @@ var BandLink = class {
   capabilities;
   logger;
   transport;
-  subscribedRooms = /* @__PURE__ */ new Set();
+  subscriptionManager;
   eventQueue = [];
   waiters = [];
   connected = false;
   lastDisconnectReason = null;
   terminalDisconnectError = null;
+  connectFlight = new SingleFlight2();
+  disconnectFlight = new SingleFlight2();
+  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
@@ -4871,6 +6278,10 @@ var BandLink = class {
         this.recordDisconnectReason(reason);
       }
     });
+    this.subscriptionManager = new SubscriptionManager({
+      transport: this.transport,
+      logger: this.logger
+    });
   }
   isConnected() {
     return this.connected;
@@ -4879,12 +6290,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;
@@ -4897,14 +6331,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) {
@@ -4933,7 +6374,7 @@ var BandLink = class {
     this.eventQueue.push(event);
   }
   async subscribeAgentRooms() {
-    await this.transport.join((0, import_band_sdk_core5.agentRoomsTopic)(this.agentId), {
+    await this.subscriptionManager.subscribeAgentTopic((0, import_band_sdk_core9.agentRoomsTopic)(this.agentId), {
       room_added: (payload) => {
         const roomId = typeof payload.id === "string" ? payload.id : "";
         this.emit("room_added", payload, roomId);
@@ -4945,30 +6386,13 @@ var BandLink = class {
     });
   }
   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);
-      }
-    });
-    try {
-      await this.transport.join(topics.participants, {
+    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);
         },
@@ -4978,15 +6402,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((0, import_band_sdk_core5.agentContactsTopic)(this.agentId), {
+    await this.subscriptionManager.subscribeAgentTopic((0, import_band_sdk_core9.agentContactsTopic)(this.agentId), {
       contact_request_received: (payload) => {
         this.emit("contact_request_received", payload, null);
       },
@@ -5002,7 +6426,7 @@ var BandLink = class {
     });
   }
   async unsubscribeAgentContacts() {
-    await this.transport.leave((0, import_band_sdk_core5.agentContactsTopic)(this.agentId));
+    await this.subscriptionManager.unsubscribeAgentTopic((0, import_band_sdk_core9.agentContactsTopic)(this.agentId));
   }
   async nextEvent(signal) {
     if (this.terminalDisconnectError) {
@@ -5158,21 +6582,20 @@ var BandLink = class {
     });
   }
   emit(eventType, payload, roomId) {
-    const schema = payloadSchemas[eventType];
-    const parsed = schema.safeParse(payload);
-    if (!parsed.success) {
+    try {
+      const normalizedPayload = (0, import_band_sdk_core9.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
       });
-      return;
     }
-    this.queueEvent({
-      type: eventType,
-      roomId,
-      payload: parsed.data,
-      raw: payload
-    });
   }
 };
 
@@ -5230,6 +6653,7 @@ var DefaultPreprocessor = class {
 // 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;
@@ -5246,12 +6670,14 @@ var PlatformRuntime = class {
   _onParticipantRemoved;
   _roomFilter;
   _contextFactory;
+  lifecycle;
   linkInstance;
   initPromise = null;
   runtime;
   contactHandler;
   activeAdapter;
-  stopping = false;
+  startGate = new SingleFlight();
+  stopGate = new SingleFlight();
   _agentName = "";
   _agentDescription = "";
   contactsSubscribed = false;
@@ -5277,17 +6703,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) {
@@ -5307,6 +6746,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;
   }
@@ -5329,8 +6776,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) {
@@ -5342,11 +6788,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,
@@ -5360,7 +6844,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;
@@ -5383,10 +6878,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],
@@ -5396,49 +6895,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");
@@ -5490,7 +7003,7 @@ var PlatformRuntime = class {
 };
 
 // src/runtime/index.ts
-var import_band_sdk_core6 = require("@band-ai/band-sdk-core");
+var import_band_sdk_core10 = require("@band-ai/band-sdk-core");
 
 // src/runtime/prompts/base.ts
 var ENVIRONMENT_SECTION = `
@@ -5590,6 +7103,7 @@ function longTermPattern(label, type, segment, scope) {
   };
 }
 var COMMON_MEMORY_PATTERNS = [
+  longTermPattern("Private notes for this agent only", MEMORY_TYPE.semantic, MEMORY_SEGMENT.guideline, MEMORY_STORE_SCOPE.agent),
   longTermPattern("Facts learned about a specific agent/entity", MEMORY_TYPE.semantic, MEMORY_SEGMENT.agent, MEMORY_STORE_SCOPE.subject),
   longTermPattern("Events involving a specific person/agent", MEMORY_TYPE.episodic, MEMORY_SEGMENT.agent, MEMORY_STORE_SCOPE.subject),
   longTermPattern("A user's preferences or profile info", MEMORY_TYPE.semantic, MEMORY_SEGMENT.user, MEMORY_STORE_SCOPE.subject),
@@ -5602,7 +7116,9 @@ var MEMORY_COMMON_PATTERNS = [
   "Common patterns:",
   ...COMMON_MEMORY_PATTERNS.map(renderMemoryPattern)
 ].join("\n");
-var MEMORY_SCOPE_GUIDANCE = `Prefer \`scope="${MEMORY_STORE_SCOPE.subject}"\` whenever the memory is about a specific person or agent, so it
+var MEMORY_SCOPE_GUIDANCE = `Use \`scope="${MEMORY_STORE_SCOPE.agent}"\` for information private to this agent that is not about an
+identified subject. Omitting \`scope\` and \`subject_id\` on store defaults to agent scope on the platform.
+Prefer \`scope="${MEMORY_STORE_SCOPE.subject}"\` whenever the memory is about a specific person or agent, so it
 stays attached to that subject rather than leaking org-wide. Storing with \`scope="${MEMORY_STORE_SCOPE.subject}"\` requires a
 real \`subject_id\` UUID, so resolve it first via \`band_lookup_peers\` or the participant list.
 Reserve \`scope="${MEMORY_STORE_SCOPE.organization}"\` for knowledge that is genuinely shared across the whole organization and