@vibevibes/runtime 0.2.0

package/src/server.ts

@@ -0,0 +1,3738 @@
+/**
+ * @vibevibes/runtime — the server engine for vibevibes experiences.
+ *
+ * Single-experience architecture with tool gate, WebSocket broadcasts, and room spawning.
+ *
+ * The server loads one experience from the project root (manifest.json for protocol
+ * experiences, or src/index.tsx for TypeScript experiences). Multiple rooms can be
+ * spawned, all running the same experience.
+ *
+ * AI agents join rooms via MCP or HTTP.
+ */
+
+import express from "express";
+import { WebSocketServer, WebSocket } from "ws";
+import http from "http";
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { z, ZodError } from "zod";
+import { EventEmitter } from "events";
+import { bundleForServer, bundleForClient, evalServerBundle, validateClientBundle } from "./bundler.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { TickEngine } from "./tick-engine.js";
+import { isProtocolExperience, loadProtocolManifest, createProtocolModule, SubprocessExecutor } from "./protocol.js";
+import type { ExperienceModule, ToolDef, StreamDef, ToolCtx, ParticipantSlot } from "@vibevibes/sdk";
+import { createChatTools } from "@vibevibes/sdk";
+
+// ── Server config ─────────────────────────────────────────────
+export interface ServerConfig {
+  /** Absolute path to the experience project root (where manifest.json or src/index.tsx lives). */
+  projectRoot: string;
+  /** Port to listen on. Defaults to 4321 or PORT env var. */
+  port?: number;
+}
+
+// ── Error formatting ──────────────────────────────────────────
+
+/** Subset of zodToJsonSchema output used for error formatting. */
+interface JsonSchemaObject {
+  properties?: Record<string, { type?: string }>;
+  required?: string[];
+}
+
+function formatZodError(err: ZodError, toolName: string, tool?: ToolDef): string {
+  const issues = err.issues.map((issue) => {
+    const path = issue.path.length > 0 ? `'${issue.path.join(".")}'` : "input";
+    const extra: string[] = [];
+    const detail = issue as { expected?: string; received?: string };
+    if (detail.expected) extra.push(`expected ${detail.expected}`);
+    if (detail.received && detail.received !== "undefined") extra.push(`got ${detail.received}`);
+    const suffix = extra.length > 0 ? ` (${extra.join(", ")})` : "";
+    return `  ${path}: ${issue.message}${suffix}`;
+  });
+  let msg = `Invalid input for '${toolName}':\n${issues.join("\n")}`;
+
+  if (tool?.input_schema) {
+    try {
+      const schema = ((tool.input_schema as any)._jsonSchema || zodToJsonSchema(tool.input_schema)) as JsonSchemaObject;
+      const props = schema.properties;
+      const req = schema.required || [];
+      if (props) {
+        const fields = Object.entries(props).map(([k, v]) => {
+          const optional = !req.includes(k);
+          return `${k}${optional ? "?" : ""}: ${v.type || "any"}`;
+        });
+        msg += `\n\nExpected schema: { ${fields.join(", ")} }`;
+      }
+    } catch {}
+  }
+  if (tool?.description) msg += `\nTool description: ${tool.description}`;
+  msg += `\n\nHint: Provide all required fields with correct types.`;
+  return msg;
+}
+
+function formatHandlerError(err: Error, toolName: string, tool?: ToolDef, input?: unknown): string {
+  const message = err.message || String(err);
+  let msg = `Tool '${toolName}' failed: ${message}`;
+
+  if (input !== undefined) {
+    try { msg += `\n\nInput provided: ${JSON.stringify(input)}`; } catch {}
+  }
+  if (tool?.input_schema) {
+    try {
+      const schema = ((tool.input_schema as any)._jsonSchema || zodToJsonSchema(tool.input_schema)) as JsonSchemaObject;
+      const props = schema.properties;
+      const req = schema.required || [];
+      if (props) {
+        const fields = Object.entries(props).map(([k, v]) => {
+          const optional = !req.includes(k);
+          return `${k}${optional ? "?" : ""}: ${v.type || "any"}`;
+        });
+        msg += `\nTool expects: { ${fields.join(", ")} }`;
+      }
+    } catch {}
+  }
+
+  // Pattern-match common errors for specific hints
+  if (message.includes("Cannot read properties of undefined") || message.includes("Cannot read property")) {
+    msg += `\n\nHint: The handler accessed a property that doesn't exist on the current state. Check that initialState includes all fields your tools read from.`;
+  } else if (message.includes("is not a function")) {
+    msg += `\n\nHint: Something expected to be a function is not. Check for missing imports or incorrect variable types in the tool handler.`;
+  } else if (message.includes("Maximum call stack")) {
+    msg += `\n\nHint: Infinite recursion detected. A tool handler or function is calling itself without a base case.`;
+  } else {
+    msg += `\n\nHint: The tool handler threw an error. Check the handler logic and ensure the current state matches what the handler expects.`;
+  }
+  return msg;
+}
+
+/** Safely extract an error message from an unknown thrown value. */
+function toErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Safely extract a string from an Express query parameter value. */
+function queryString(val: unknown): string | undefined {
+  return typeof val === "string" ? val : undefined;
+}
+
+/** Safely parse an Express query parameter as an integer (returns 0 if absent/invalid). */
+function queryInt(val: unknown, radix = 10): number {
+  return typeof val === "string" ? (parseInt(val, radix) || 0) : 0;
+}
+
+const __runtimeDir = path.dirname(fileURLToPath(import.meta.url));
+
+// PROJECT_ROOT is set by startServer() from ServerConfig.projectRoot.
+// It points to the experience project root (where src/, experiences/, registry live).
+let PROJECT_ROOT = "";
+
+// ── Custom error types ───────────────────────────────────────
+
+class ToolNotFoundError extends Error {
+  constructor(message: string) { super(message); this.name = "ToolNotFoundError"; }
+}
+
+class ToolForbiddenError extends Error {
+  constructor(message: string) { super(message); this.name = "ToolForbiddenError"; }
+}
+
+// ── Types ──────────────────────────────────────────────────
+
+interface ToolEvent {
+  id: string;
+  ts: number;
+  actorId: string;
+  owner?: string;
+  role?: string;
+  tool: string;
+  input: Record<string, unknown>;
+  output?: unknown;
+  error?: string;
+  observation?: Record<string, unknown>;
+}
+
+/** Server-side extension of ToolCtx with runtime-only fields. */
+interface ServerToolCtx extends ToolCtx {
+}
+
+/** WebSocket with heartbeat tracking. */
+interface HeartbeatWebSocket extends WebSocket {
+  isAlive: boolean;
+}
+
+interface RoomLink {
+  parentRoomId: string;
+  childRoomId: string;
+  linkType: "spawned" | "referenced" | "forked";
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+
+/** The full module shape returned by evalServerBundle (ExperienceModule + optional extras from defineExperience). */
+type LoadedModule = ExperienceModule & {
+  initialState?: Record<string, unknown> | ((config: Record<string, unknown>) => Record<string, unknown>);
+  /** Extra `participants` field (sugar from defineExperience, normalized into manifest.participantSlots). */
+  participants?: import("@vibevibes/sdk").ParticipantSlot[];
+  /** Extra `agents` field (legacy sugar from defineExperience). */
+  agents?: Array<{ role: string; systemPrompt: string; allowedTools?: string[]; autoSpawn?: boolean; maxInstances?: number }>;
+};
+
+/** A loaded and cached experience (host or external). */
+interface LoadedExperience {
+  module: LoadedModule;
+  clientBundle: string;  // ESM bundle for the browser
+  serverCode: string;    // CJS bundle (kept for hot-reload re-eval)
+  loadedAt: number;
+  sourcePath: string;    // Absolute path to the entry file
+}
+
+// ── Room class ─────────────────────────────────────────────
+
+/** A participant's server-side record (stored in Room.participants). */
+interface ParticipantRecord {
+  type: "human" | "ai";
+  joinedAt: number;
+  owner: string;
+  role?: string;
+  systemPrompt?: string;
+  allowedTools?: string[];
+  lastPollAt?: number;
+  eventCursor?: number;
+  /** Agent operating mode: "behavior" | "manual" | "hybrid". Only for AI participants. */
+  agentMode?: string;
+  /** Arbitrary metadata from join request (model, team, tags, etc.). */
+  metadata?: Record<string, string>;
+}
+
+// ── WebSocket message types (discriminated union) ───────────
+
+/** Broadcast: participant list changed. */
+type WsPresenceUpdate = {
+  type: "presence_update";
+  participants: string[];
+  participantDetails: Array<{ actorId: string; type: string; role?: string; owner?: string; agentMode?: string; metadata?: Record<string, string> }>;
+};
+
+/** Broadcast: shared state changed (via tool, stream, reset, or tick).
+ *  Supports two modes:
+ *  - Full state: `state` is present (used on reset, first broadcast, or recovery)
+ *  - Delta: `delta` + optional `deletedKeys` (only changed top-level keys sent) */
+type WsStateUpdate = {
+  type: "shared_state_update";
+  roomId: string;
+  stateVersion: number;
+  changedBy: string;
+  /** Full state snapshot (mutually exclusive with delta). */
+  state?: Record<string, unknown>;
+  /** Changed top-level keys only (mutually exclusive with state). */
+  delta?: Record<string, unknown>;
+  /** Top-level keys removed from state since last broadcast. */
+  deletedKeys?: string[];
+  event?: ToolEvent;
+  tool?: string;
+  observation?: Record<string, unknown>;
+  stream?: string;
+  tick?: unknown;
+};
+
+/** Broadcast: experience code hot-reloaded successfully. */
+type WsExperienceUpdated = {
+  type: "experience_updated";
+};
+
+/** Broadcast: experience build failed during hot-reload. */
+type WsBuildError = {
+  type: "build_error";
+  error: string;
+};
+
+/** All message types sent via Room.broadcastToAll(). */
+type BroadcastMessage =
+  | WsPresenceUpdate
+  | WsStateUpdate
+  | WsExperienceUpdated
+  | WsBuildError;
+
+class Room {
+  readonly id: string;
+  readonly experienceId: string;
+  sharedState: Record<string, unknown> = {};
+  readonly participants = new Map<string, ParticipantRecord>();
+  readonly events: ToolEvent[] = [];
+  readonly wsConnections = new Map<WebSocket, string>(); // ws → actorId
+  readonly kickedActors = new Set<string>();
+  readonly kickedOwners = new Set<string>();
+  parentRoomId?: string;
+  readonly childRoomIds: string[] = [];
+  /** Immutable config set at spawn time. Defines this room's modality/parameters. */
+  readonly config: Record<string, unknown>;
+  /** Pre-created rooms (from registry) are exempt from empty-room GC. */
+  preCreated = false;
+  /** Per-room promise chain to serialize tool execution and prevent state interleaving. */
+  private _executionQueue: Promise<void> = Promise.resolve();
+  /** Monotonically increasing version counter for delta broadcasting. */
+  stateVersion = 0;
+  /** Previous state snapshot for computing deltas. null = first broadcast sends full state. */
+  private _prevState: Record<string, unknown> | null = null;
+
+  constructor(id: string, experienceId: string, initialState?: Record<string, unknown>, config?: Record<string, unknown>) {
+    this.id = id;
+    this.experienceId = experienceId;
+    this.config = Object.freeze(config || {});
+    if (initialState) {
+      this.sharedState = initialState;
+    }
+  }
+
+  broadcastToAll(message: BroadcastMessage): void {
+    const data = JSON.stringify(message);
+    for (const ws of this.wsConnections.keys()) {
+      if (ws.readyState === WebSocket.OPEN) {
+        try { ws.send(data); } catch { /* client disconnected mid-send */ }
+      }
+    }
+  }
+
+  /**
+   * Broadcast a state update using delta compression.
+   * Compares current sharedState to _prevState using top-level key reference equality.
+   * Sends only changed/deleted keys (delta mode), or full state if no previous snapshot.
+   * @param forceFullState - If true, always sends full state (used for reset).
+   */
+  broadcastStateUpdate(extra: {
+    changedBy: string;
+    event?: ToolEvent;
+    tool?: string;
+    observation?: Record<string, unknown>;
+    stream?: string;
+    tick?: unknown;
+  }, forceFullState = false): void {
+    this.stateVersion++;
+    const prev = this._prevState;
+    this._prevState = this.sharedState;
+
+    // First broadcast or forced full state — send everything
+    if (!prev || forceFullState) {
+      this.broadcastToAll({
+        type: "shared_state_update",
+        roomId: this.id,
+        stateVersion: this.stateVersion,
+        state: this.sharedState,
+        ...extra,
+      });
+      return;
+    }
+
+    // Compute delta: compare top-level keys by reference equality (===)
+    const changed: Record<string, unknown> = {};
+    const deleted: string[] = [];
+    let changeCount = 0;
+
+    for (const key of Object.keys(this.sharedState)) {
+      if (this.sharedState[key] !== prev[key]) {
+        changed[key] = this.sharedState[key];
+        changeCount++;
+      }
+    }
+    for (const key of Object.keys(prev)) {
+      if (!(key in this.sharedState)) {
+        deleted.push(key);
+        changeCount++;
+      }
+    }
+
+    // No state changes — still broadcast if there's an event (tools that don't modify state)
+    if (changeCount === 0 && !extra.event) return;
+
+    if (changeCount === 0) {
+      // Event-only broadcast (tool ran but didn't change state)
+      this.broadcastToAll({
+        type: "shared_state_update",
+        roomId: this.id,
+        stateVersion: this.stateVersion,
+        delta: {},
+        ...extra,
+      });
+    } else {
+      this.broadcastToAll({
+        type: "shared_state_update",
+        roomId: this.id,
+        stateVersion: this.stateVersion,
+        delta: changed,
+        ...(deleted.length > 0 ? { deletedKeys: deleted } : {}),
+        ...extra,
+      });
+    }
+  }
+
+  /** Reset delta tracking (call after room reset to force full state on next broadcast). */
+  resetDeltaTracking(): void {
+    this._prevState = null;
+  }
+
+  participantList(): string[] {
+    return Array.from(this.participants.keys());
+  }
+
+  /** Returns participant objects with actorId, type, owner, agentMode, and metadata (for WebSocket broadcasts and stop hook discovery). */
+  participantDetails(): Array<{ actorId: string; type: string; role?: string; owner?: string; agentMode?: string; metadata?: Record<string, string> }> {
+    return Array.from(this.participants.entries()).map(([actorId, p]) => {
+      const detail: { actorId: string; type: string; role?: string; owner?: string; agentMode?: string; metadata?: Record<string, string> } = {
+        actorId,
+        type: p.type,
+        role: p.role,
+        owner: p.owner,
+      };
+      if (p.agentMode) detail.agentMode = p.agentMode;
+      if (p.metadata && Object.keys(p.metadata).length > 0) detail.metadata = p.metadata;
+      return detail;
+    });
+  }
+
+  appendEvent(event: ToolEvent): void {
+    this.events.push(event);
+    if (this.events.length > MAX_EVENTS_PER_ROOM) {
+      this.events.splice(0, this.events.length - MAX_EVENTS_PER_ROOM);
+    }
+  }
+
+  /** Serialize an async operation against this room's tool execution queue.
+   *  Prevents concurrent tool calls from interleaving on shared state. */
+  enqueueExecution<T>(fn: () => Promise<T>): Promise<T> {
+    const next = this._executionQueue.then(() => fn());
+    // Swallow rejections on the chain so one failed tool doesn't block the next
+    this._executionQueue = next.then(() => {}, () => {});
+    return next;
+  }
+}
+
+// ── Constants ─────────────────────────────────────────────
+
+const DEFAULT_PORT = 4321;
+const MAX_EVENTS_PER_ROOM = 200;
+const JOIN_EVENT_HISTORY = 20;
+const ROOM_STATE_EVENT_HISTORY = 50;
+const HISTORY_DEFAULT_LIMIT = 50;
+const HISTORY_MAX_LIMIT = 200;
+const DEFAULT_STREAM_RATE_LIMIT = 60;
+const STREAM_RATE_WINDOW_MS = 1000;
+const EVENT_BATCH_DEBOUNCE_MS = 50;
+const DEFAULT_TICK_RATE_MS = 50;
+const MAX_BATCH_CALLS = 10;
+const LONG_POLL_MAX_TIMEOUT_MS = 55000;
+const AGENT_CONTEXT_MAX_TIMEOUT_MS = 10000;
+const WS_MAX_PAYLOAD_BYTES = 1024 * 1024; // 1MB
+const WS_EPHEMERAL_MAX_BYTES = 65536; // 64KB
+const WS_HEARTBEAT_INTERVAL_MS = 30000;
+const ROOM_GC_INTERVAL_MS = 60_000;
+const IDEMPOTENCY_CLEANUP_INTERVAL_MS = 60000;
+const SCREENSHOT_DEFAULT_TIMEOUT_MS = 10000;
+const SCREENSHOT_MAX_TIMEOUT_MS = 30000;
+const HOT_RELOAD_DEBOUNCE_MS = 300;
+const WS_CLOSE_GRACE_MS = 3000; // Grace period before deleting participant on WS close (allows reconnect on refresh)
+const JSON_BODY_LIMIT = "256kb";
+const TOOL_HTTP_TIMEOUT_MS = 30_000;
+const TOOL_REGEX_MAX_LENGTH = 100;
+const ROOM_EVENTS_MAX_LISTENERS = 200;
+const STREAM_RATE_LIMIT_STALE_MS = 5000;
+const STREAM_RATE_LIMIT_CLEANUP_INTERVAL_MS = 10000;
+const BLOB_CACHE_MAX_AGE_SECONDS = 300; // 5 minutes — blobs can be overwritten
+
+// ── Default observe (used when experience has no observe function) ─────
+
+function defaultObserve(state: Record<string, any>, _event: unknown, _actorId: string): Record<string, any> {
+  const result: Record<string, any> = {};
+  for (const [k, v] of Object.entries(state)) {
+    if (!k.startsWith("_")) result[k] = v;
+  }
+  const phase = typeof state.phase === "string" ? state.phase : null;
+  result.directive = phase ? `Current phase: ${phase}` : "Observe the current state and act accordingly.";
+  return result;
+}
+
+// ── Global state ──────────────────────────────────────────
+
+const DEFAULT_ROOM_ID = "local";
+let PORT = parseInt(process.env.PORT || String(DEFAULT_PORT), 10);
+
+let publicUrl: string | null = null;
+
+const rooms = new Map<string, Room>();
+const tickEngines = new Map<string, TickEngine>();
+const roomLinks: RoomLink[] = [];
+let _actorCounter = 0;
+const agentMemory = new Map<string, Record<string, unknown>>();
+const roomEmptySince = new Map<string, number>(); // roomId → timestamp when first noticed empty (for GC)
+const roomEvents = new EventEmitter();
+roomEvents.setMaxListeners(ROOM_EVENTS_MAX_LISTENERS);
+
+/** Remove all parent-child room links involving the given roomId and update parent's childRoomIds. */
+function cleanupRoomLinks(roomId: string, room: Room): void {
+  for (let i = roomLinks.length - 1; i >= 0; i--) {
+    if (roomLinks[i].childRoomId === roomId || roomLinks[i].parentRoomId === roomId) {
+      roomLinks.splice(i, 1);
+    }
+  }
+  if (room.parentRoomId) {
+    const parent = rooms.get(room.parentRoomId);
+    if (parent) {
+      const idx = parent.childRoomIds.indexOf(roomId);
+      if (idx !== -1) parent.childRoomIds.splice(idx, 1);
+    }
+  }
+}
+
+function roomNotFoundError(roomId: string): string {
+  return `Room '${roomId}' not found. Use list_rooms to see available rooms.`;
+}
+
+/** Set no-cache response headers for dynamic content. */
+function setNoCacheHeaders(res: express.Response): void {
+  res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
+  res.setHeader("Pragma", "no-cache");
+  res.setHeader("Expires", "0");
+}
+
+/** Broadcast a presence update to all WebSocket clients in a room. */
+function broadcastPresenceUpdate(room: Room): void {
+  room.broadcastToAll({
+    type: "presence_update",
+    participants: room.participantList(),
+    participantDetails: room.participantDetails(),
+  });
+}
+
+// ── Blob store ──────────────────────────────────────────
+const blobStore = new Map<string, Buffer>();
+const blobMeta = new Map<string, { size: number; createdAt: number; roomId: string }>();
+const MAX_BLOB_SIZE = 10 * 1024 * 1024; // 10MB per blob
+const MAX_TOTAL_BLOBS = 50 * 1024 * 1024; // 50MB total
+
+// ── Experience cache (replaces single global `experience`) ──
+const experienceCache = new Map<string, LoadedExperience>();
+const experienceErrors = new Map<string, string>(); // Last build error per experience ID
+let hostExperienceId: string = "";
+
+// Hot-reload rebuild gate — bundle endpoints await this during in-progress rebuilds
+let rebuildingResolve: (() => void) | null = null;
+let rebuildingPromise: Promise<void> | null = null;
+
+// Spawn rate limiting: max 5 spawns per source room per 5 minutes
+const spawnCounts = new Map<string, { count: number; windowStart: number }>();
+const SPAWN_WINDOW_MS = 5 * 60 * 1000;
+const MAX_SPAWNS_PER_WINDOW = 5;
+const MAX_ROOMS = 100; // Hard cap on total rooms to prevent resource exhaustion
+const pendingSpawns = new Set<string>(); // Room IDs currently being spawned (TOCTOU guard)
+const RESERVED_ROOM_IDS = new Set(["spawn", "config-schema", "local", "library", "rooms", "participants", "events", "memory", "agent-context", "screenshot", "blob", "__proto__", "constructor", "prototype"]);
+
+// Stream rate limiting: per actor, per stream, per room
+const streamRateLimits = new Map<string, { count: number; windowStart: number }>();
+
+// Periodic cleanup for stream rate limits (every 10 seconds)
+const _streamRateCleanupTimer = setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of streamRateLimits) {
+    if (now - entry.windowStart > STREAM_RATE_LIMIT_STALE_MS) streamRateLimits.delete(key);
+  }
+}, STREAM_RATE_LIMIT_CLEANUP_INTERVAL_MS);
+
+// Periodic cleanup for spawn rate limits (every 5 minutes)
+const _spawnRateCleanupTimer = setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of spawnCounts) {
+    if (now - entry.windowStart > SPAWN_WINDOW_MS) spawnCounts.delete(key);
+  }
+}, SPAWN_WINDOW_MS);
+
+/** Set the public tunnel URL (called from dev.ts when --share is active). */
+export function setPublicUrl(url: string): void {
+  publicUrl = url;
+}
+
+/** Get the base URL clients should use (tunnel URL if sharing, localhost otherwise). */
+export function getBaseUrl(): string {
+  return publicUrl || `http://localhost:${PORT}`;
+}
+
+// ── Helpers ────────────────────────────────────────────────
+
+const FORBIDDEN_MERGE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...target };
+  for (const key of Object.keys(source)) {
+    if (FORBIDDEN_MERGE_KEYS.has(key)) continue;
+    const sv = source[key];
+    const tv = target[key];
+    if (sv !== null && typeof sv === "object" && !Array.isArray(sv) &&
+        tv !== null && typeof tv === "object" && !Array.isArray(tv)) {
+      result[key] = deepMerge(tv as Record<string, unknown>, sv as Record<string, unknown>);
+    } else {
+      result[key] = sv;
+    }
+  }
+  return result;
+}
+
+function assignActorId(username: string, type: "human" | "ai", owner?: string): string {
+  // Use owner as prefix when available (agents pass unique owner like "agent-abc123")
+  // This ensures two agents get truly distinct actorIds instead of "agent-ai-1" / "agent-ai-2"
+  const base = owner || `${username}-${type}`;
+  _actorCounter++;
+  return `${base}-${_actorCounter}`;
+}
+
+/** JSON-safe tool descriptor sent to agents/clients. */
+interface ToolListEntry {
+  name: string;
+  description: string;
+  risk: string;
+  input_schema: Record<string, unknown>;
+}
+
+function getToolList(mod: LoadedModule, allowedTools?: string[]): ToolListEntry[] {
+  if (!mod?.tools) return [];
+  let tools: ToolDef[] = mod.tools;
+  if (allowedTools) tools = tools.filter((t) => allowedTools.includes(t.name));
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    risk: t.risk || "low",
+    input_schema: (t.input_schema as any)?._jsonSchema
+      ? (t.input_schema as any)._jsonSchema as Record<string, unknown>
+      : t.input_schema ? zodToJsonSchema(t.input_schema) as Record<string, unknown> : {},
+  }));
+}
+
+function getRoom(roomId: string): Room | undefined {
+  return rooms.get(roomId);
+}
+
+function getDefaultRoom(): Room {
+  const room = rooms.get(DEFAULT_ROOM_ID);
+  if (!room) throw new Error(`Default room '${DEFAULT_ROOM_ID}' not found. Server may still be starting up.`);
+  return room;
+}
+
+/** Get the loaded experience for a room. Returns undefined if not loaded. */
+function getExperienceForRoom(room: Room): LoadedExperience | undefined {
+  return experienceCache.get(room.experienceId);
+}
+
+/** Get the host experience module (convenience). */
+function getHostExperience(): LoadedModule | undefined {
+  return experienceCache.get(hostExperienceId)?.module;
+}
+
+function generateRoomId(): string {
+  return `room-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function checkSpawnRate(sourceRoomId: string): boolean {
+  const now = Date.now();
+  const entry = spawnCounts.get(sourceRoomId);
+  if (!entry || now - entry.windowStart > SPAWN_WINDOW_MS) {
+    spawnCounts.set(sourceRoomId, { count: 1, windowStart: now });
+    return true;
+  }
+  if (entry.count >= MAX_SPAWNS_PER_WINDOW) {
+    return false;
+  }
+  entry.count++;
+  return true;
+}
+
+/**
+ * Resolve room config against a specific experience's roomConfig definition.
+ * Handles: preset names, explicit config objects, defaults, and validation.
+ */
+function resolveRoomConfig(
+  experienceModule: LoadedModule,
+  configInput: Record<string, unknown> | string | undefined,
+): Record<string, unknown> {
+  const roomConfigDef = experienceModule?.roomConfig;
+  if (!roomConfigDef) {
+    // No config schema defined — shallow-copy (don't hold caller's reference) and reject arrays/null
+    return (typeof configInput === "object" && configInput !== null && !Array.isArray(configInput))
+      ? { ...configInput } : {};
+  }
+
+  let resolved: Record<string, unknown>;
+
+  if (typeof configInput === "string") {
+    // Preset name
+    const preset = roomConfigDef.presets?.[configInput];
+    if (!preset) {
+      const available = Object.keys(roomConfigDef.presets || {}).join(", ");
+      throw new Error(`Unknown config preset '${configInput}'. Available: ${available || "(none)"}`);
+    }
+    resolved = { ...roomConfigDef.defaults, ...preset };
+  } else if (configInput && Object.keys(configInput).length > 0) {
+    // Explicit config values merged over defaults
+    resolved = { ...roomConfigDef.defaults, ...configInput };
+  } else {
+    // No config provided — use defaults
+    resolved = roomConfigDef.defaults ? { ...roomConfigDef.defaults } : {};
+  }
+
+  // Validate against schema if available
+  if (roomConfigDef.schema?.parse) {
+    try {
+      resolved = roomConfigDef.schema.parse(resolved);
+    } catch (err: unknown) {
+      if (err instanceof ZodError) {
+        const issues = err.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+        throw new Error(`Invalid room config:\n${issues}`);
+      }
+      throw err;
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve the initial state for a room from its experience module.
+ * Checks for `initialState` (function or object) on the module.
+ * Falls back to empty object if not defined.
+ */
+function resolveInitialState(
+  experienceModule: LoadedModule,
+  config: Record<string, unknown>,
+): Record<string, unknown> {
+  const init = experienceModule?.initialState;
+  if (typeof init === "function") {
+    try { return init(config) || {}; } catch (err: unknown) {
+      console.warn(`[resolveInitialState] initialState(config) threw:`, err);
+      return {};
+    }
+  }
+  if (init && typeof init === "object") {
+    return { ...init };
+  }
+  // Auto-generate initial state from stateSchema defaults (Zod .default() values)
+  const schema = experienceModule?.stateSchema;
+  if (schema && typeof schema.parse === "function") {
+    try { return schema.parse({}); } catch { /* schema has required fields without defaults */ }
+  }
+  return {};
+}
+
+// ── Experience discovery ────────────────────────────────────
+
+/** Discover the experience entry point in the project root. */
+function discoverEntryPath(): string {
+  // Protocol experience: manifest.json in project root
+  const manifestPath = path.join(PROJECT_ROOT, "manifest.json");
+  if (fs.existsSync(manifestPath)) return manifestPath;
+
+  // TypeScript experience: src/index.tsx
+  const tsxPath = path.join(PROJECT_ROOT, "src", "index.tsx");
+  if (fs.existsSync(tsxPath)) return tsxPath;
+
+  // TypeScript experience: index.tsx in root
+  const rootTsx = path.join(PROJECT_ROOT, "index.tsx");
+  if (fs.existsSync(rootTsx)) return rootTsx;
+
+  throw new Error(
+    `No experience found in ${PROJECT_ROOT}. ` +
+    `Create a manifest.json (protocol) or src/index.tsx (TypeScript).`
+  );
+}
+
+// ── Experience loading ─────────────────────────────────────
+
+/**
+ * Load an experience from an arbitrary entry path.
+ * Bundles server + client, evals server bundle, caches the result.
+ */
+async function loadExperienceFromPath(entryPath: string): Promise<LoadedExperience> {
+  // Protocol-based experience (manifest.json + subprocess)
+  if (isProtocolExperience(entryPath)) {
+    return loadProtocolExperienceFromPath(entryPath);
+  }
+
+  const [sCode, cCode] = await Promise.all([
+    bundleForServer(entryPath),
+    bundleForClient(entryPath),
+  ]);
+
+  const mod = await evalServerBundle(sCode) as LoadedModule;
+
+  if (!mod?.manifest || !mod?.tools) {
+    throw new Error(`Experience at ${entryPath} missing manifest or tools`);
+  }
+
+  // Auto-inject chat tools (_chat.send, _chat.team, _chat.clear) if not already present
+  if (!mod.tools.some((t: ToolDef) => t.name === '_chat.send')) {
+    mod.tools.push(...createChatTools(z));
+  }
+
+
+  // Validate client bundle for syntax errors and unresolved references
+  const clientError = validateClientBundle(cCode);
+  if (clientError) {
+    throw new Error(`Client bundle validation failed for ${entryPath}: ${clientError}`);
+  }
+
+  const loaded: LoadedExperience = {
+    module: mod,
+    clientBundle: cCode,
+    serverCode: sCode,
+    loadedAt: Date.now(),
+    sourcePath: entryPath,
+  };
+
+  experienceCache.set(mod.manifest.id, loaded);
+  experienceErrors.delete(mod.manifest.id); // Clear any previous build error
+  return loaded;
+}
+
+// Track protocol executors for cleanup
+const protocolExecutors = new Map<string, SubprocessExecutor>();
+
+async function loadProtocolExperienceFromPath(manifestPath: string): Promise<LoadedExperience> {
+  const manifestDir = path.dirname(manifestPath);
+  const manifest = loadProtocolManifest(manifestPath);
+
+  // Stop existing executor if reloading
+  const existing = protocolExecutors.get(manifest.id);
+  if (existing) existing.stop();
+
+  // Spawn the tool process
+  const executor = new SubprocessExecutor(
+    manifest.toolProcess.command,
+    manifest.toolProcess.args || [],
+    manifestDir,
+  );
+  executor.start();
+  protocolExecutors.set(manifest.id, executor);
+
+  // Send init
+  try {
+    await executor.send("init", { experienceId: manifest.id }, 5000);
+  } catch {
+    // init is optional — process may not implement it
+  }
+
+  const mod = createProtocolModule(manifest, executor, manifestDir);
+
+  // Auto-inject chat tools if not present
+  if (!mod.tools.some((t: ToolDef) => t.name === '_chat.send')) {
+    mod.tools.push(...createChatTools(z));
+  }
+
+  // For protocol experiences, clientBundle is empty (HTML canvas served separately)
+  // and serverCode is the manifest JSON (for reference)
+  const loaded: LoadedExperience = {
+    module: mod as unknown as LoadedModule,
+    clientBundle: "", // No JS bundle — HTML canvas served directly
+    serverCode: JSON.stringify(manifest),
+    loadedAt: Date.now(),
+    sourcePath: manifestPath,
+  };
+
+  experienceCache.set(manifest.id, loaded);
+  experienceErrors.delete(manifest.id);
+  console.log(`[protocol] Loaded ${manifest.title} (${manifest.id}) — ${manifest.tools.length} tools, process: ${manifest.toolProcess.command}`);
+  return loaded;
+}
+
+/**
+ * Get the loaded experience. Returns cached if available.
+ */
+async function getLoadedExperience(): Promise<LoadedExperience> {
+  const cached = experienceCache.get(hostExperienceId);
+  if (cached) return cached;
+  return loadHost();
+}
+
+/**
+ * Load the experience from the project root.
+ */
+async function loadHost(): Promise<LoadedExperience> {
+  const entryPath = discoverEntryPath();
+  const loaded = await loadExperienceFromPath(entryPath);
+  hostExperienceId = loaded.module.manifest.id;
+  return loaded;
+}
+
+// ── Spawn room (async — can load external experiences) ─────
+
+async function spawnRoom(
+  sourceRoomId: string,
+  opts: { experienceId: string; name?: string; initialState?: Record<string, unknown>; linkBack?: boolean; config?: Record<string, unknown> | string; skipRateLimit?: boolean },
+): Promise<{ roomId: string; url: string; config: Record<string, unknown> }> {
+  if (!opts.skipRateLimit && !checkSpawnRate(sourceRoomId)) {
+    throw new Error(`Rate limited: max ${MAX_SPAWNS_PER_WINDOW} spawns per ${SPAWN_WINDOW_MS / 60000} minutes`);
+  }
+
+  let roomId = opts.name || generateRoomId();
+  // Sanitize room name: strip path traversal and unsafe characters
+  if (opts.name) {
+    roomId = roomId.replace(/[^a-zA-Z0-9._\-]/g, "-");
+    if (!roomId || roomId.length > 128) throw new Error("Invalid room name");
+  }
+
+  // Reject reserved room IDs that would shadow API route segments or cause prototype pollution
+  if (RESERVED_ROOM_IDS.has(roomId)) {
+    throw new Error(`Room name '${roomId}' is reserved and cannot be used`);
+  }
+
+  // TOCTOU guard: check both committed and pending rooms atomically (single-threaded JS)
+  if (rooms.has(roomId) || pendingSpawns.has(roomId)) {
+    throw new Error(`Room '${roomId}' already exists`);
+  }
+  if (rooms.size + pendingSpawns.size >= MAX_ROOMS) {
+    throw new Error(`Room limit reached (${MAX_ROOMS}). Delete unused rooms before spawning new ones.`);
+  }
+
+  // Reserve the room ID before async work to prevent concurrent spawns
+  pendingSpawns.add(roomId);
+
+  let room: Room;
+  try {
+    // Always use the host experience (single-experience server)
+    const targetExperienceLoaded = await getLoadedExperience();
+
+    // Resolve and validate config against the TARGET experience's schema
+    const config = resolveRoomConfig(targetExperienceLoaded.module, opts.config);
+
+    // Resolve initial state: experience default, merged with explicit initialState, plus linkBack
+    const expInitialState = resolveInitialState(targetExperienceLoaded.module, config);
+    // Filter FORBIDDEN_MERGE_KEYS from initialState to prevent prototype pollution
+    const safeInitialState: Record<string, unknown> = {};
+    if (opts.initialState && typeof opts.initialState === "object" && !Array.isArray(opts.initialState)) {
+      for (const [k, v] of Object.entries(opts.initialState)) {
+        if (!FORBIDDEN_MERGE_KEYS.has(k)) safeInitialState[k] = v;
+      }
+    }
+    const mergedState = { ...expInitialState, ...safeInitialState };
+    const initialState = opts.linkBack
+      ? { ...mergedState, _parentRoom: sourceRoomId }
+      : mergedState;
+
+    room = new Room(roomId, opts.experienceId, initialState, config);
+    room.parentRoomId = sourceRoomId;
+    rooms.set(roomId, room);
+    pendingSpawns.delete(roomId);
+  } catch (err: unknown) {
+    pendingSpawns.delete(roomId);
+    throw err;
+  }
+
+  // Track parent-child link
+  const sourceRoom = rooms.get(sourceRoomId);
+  if (sourceRoom) {
+    sourceRoom.childRoomIds.push(roomId);
+  }
+
+  // Store RoomLink (include config in metadata)
+  // Cap roomLinks to prevent unbounded growth under rapid spawn/GC cycling
+  if (roomLinks.length >= 1000) {
+    roomLinks.splice(0, roomLinks.length - 999);
+  }
+  roomLinks.push({
+    parentRoomId: sourceRoomId,
+    childRoomId: roomId,
+    linkType: "spawned",
+    metadata: { experienceId: opts.experienceId, config: room.config },
+    createdAt: new Date().toISOString(),
+  });
+
+  // Start tick engine if experience uses tick netcode
+  const loadedExp = experienceCache.get(opts.experienceId);
+  if (loadedExp) maybeStartTickEngine(room, loadedExp);
+
+  const url = `${getBaseUrl()}/room/${roomId}`;
+  return { roomId, url, config: room.config };
+}
+
+// ── Tick Engine lifecycle ──────────────────────────────────
+
+/** Start a tick engine for a room if its experience uses tick netcode. */
+function maybeStartTickEngine(room: Room, loaded: LoadedExperience): void {
+  const manifest = loaded.module?.manifest;
+  if (manifest?.netcode !== "tick") return;
+
+  // Stop existing engine first to prevent ghost intervals on hot-reload
+  stopTickEngine(room.id);
+
+  const tickRateMs = manifest.tickRateMs || DEFAULT_TICK_RATE_MS;
+
+  const engine = new TickEngine(room, loaded, roomEvents, tickRateMs);
+  engine.start();
+  tickEngines.set(room.id, engine);
+}
+
+/** Stop and remove the tick engine for a room. */
+function stopTickEngine(roomId: string): void {
+  const engine = tickEngines.get(roomId);
+  if (engine) {
+    engine.stop();
+    tickEngines.delete(roomId);
+  }
+}
+
+// ── Express app ────────────────────────────────────────────
+
+const app = express();
+app.use(express.json({ limit: JSON_BODY_LIMIT }));
+
+// CORS for local development
+app.use((_req, res, next) => {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type,Authorization,X-Idempotency-Key");
+  if (_req.method === "OPTIONS") { res.sendStatus(200); return; }
+  next();
+});
+
+// Serve viewer (no-cache so changes are picked up immediately)
+app.get("/", (_req, res) => {
+  setNoCacheHeaders(res);
+  res.sendFile(path.join(__runtimeDir, "viewer", "index.html"));
+});
+app.use("/viewer", express.static(path.join(__runtimeDir, "viewer")));
+
+// Serve SDK ESM bundle (for scene engine and other SDK features in browser)
+app.get("/sdk.js", (_req, res) => {
+  const sdkPath = path.join(PROJECT_ROOT, "node_modules", "@vibevibes", "sdk", "dist", "index.js");
+  if (fs.existsSync(sdkPath)) {
+    res.setHeader("Content-Type", "application/javascript");
+    res.sendFile(sdkPath);
+  } else {
+    res.status(404).send("// SDK not found");
+  }
+});
+
+// ── Room state endpoint (flat = default room) ──────────────
+
+app.get("/state", (req, res) => {
+  const room = getDefaultRoom();
+  const exp = getExperienceForRoom(room);
+  let observation: Record<string, unknown> | undefined;
+  const observeFn = exp?.module?.observe ?? defaultObserve;
+  const observeActorId = typeof req.query.actorId === "string" ? req.query.actorId : "viewer";
+  try { observation = observeFn(room.sharedState, null, observeActorId); } catch (err: unknown) { console.warn(`[observe] Error: ${toErrorMessage(err)}`); }
+  res.json({
+    roomId: room.id,
+    experienceId: exp?.module?.manifest?.id ?? room.experienceId,
+    sharedState: room.sharedState,
+    stateVersion: room.stateVersion,
+    participants: room.participantList(),
+    events: room.events.slice(-ROOM_STATE_EVENT_HISTORY),
+    config: room.config,
+    observation,
+  });
+});
+
+// ── Slots endpoint (default room) ───────────────────────────
+app.get("/slots", (_req, res) => {
+  const room = getDefaultRoom();
+  const exp = getExperienceForRoom(room);
+  const slots = exp?.module?.manifest?.participantSlots || exp?.module?.participants || [];
+  res.json({ slots, participantDetails: room.participantDetails() });
+});
+
+// ── Participants endpoint ──────────────────────────────────
+
+app.get("/participants", (_req, res) => res.json({ participants: getDefaultRoom().participantDetails() }));
+app.get("/rooms/:roomId/participants", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+  res.json({ participants: room.participantDetails() });
+});
+
+// ── Tools list endpoint (structured tool discovery for agents) ──
+
+function handleToolsList(room: Room, req: express.Request, res: express.Response): void {
+  const exp = getExperienceForRoom(room);
+  if (!exp) {
+    res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+    return;
+  }
+
+  // If actorId is provided, filter tools by the participant's allowedTools
+  const actorId = queryString(req.query.actorId);
+  let allowedTools: string[] | undefined;
+  if (actorId) {
+    const participant = room.participants.get(actorId);
+    allowedTools = participant?.allowedTools;
+  }
+
+  const tools = getToolList(exp.module, allowedTools);
+
+  // Also return stream definitions if the experience defines them
+  const streams = exp.module.streams
+    ? exp.module.streams.map((s) => ({
+        name: s.name,
+        description: s.description || "",
+        rateLimit: s.rateLimit || DEFAULT_STREAM_RATE_LIMIT,
+        input_schema: s.input_schema ? zodToJsonSchema(s.input_schema) : {},
+      }))
+    : [];
+
+  res.json({
+    roomId: room.id,
+    experienceId: exp.module.manifest?.id || room.experienceId,
+    tools,
+    streams,
+    toolCount: tools.length,
+    streamCount: streams.length,
+  });
+}
+
+app.get("/tools-list", (req, res) => handleToolsList(getDefaultRoom(), req, res));
+app.get("/rooms/:roomId/tools-list", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+  handleToolsList(room, req, res);
+});
+
+// ── History endpoint (filtered event log) ────────────────────
+
+function handleHistory(room: Room, req: express.Request, res: express.Response): void {
+  const limit = Math.min(queryInt(req.query.limit) || HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT);
+  const since = queryInt(req.query.since);
+  const actor = queryString(req.query.actor);
+  const tool = queryString(req.query.tool);
+  const owner = queryString(req.query.owner);
+
+  let events = room.events;
+
+  // Filter by timestamp
+  if (since > 0) {
+    events = events.filter(e => e.ts > since);
+  }
+
+  // Filter by actor
+  if (actor) {
+    events = events.filter(e => e.actorId === actor);
+  }
+
+  // Filter by owner
+  if (owner) {
+    events = events.filter(e => e.owner === owner);
+  }
+
+  // Filter by tool name — only allow safe literal characters (no regex metacharacters)
+  // This prevents user-controlled ReDoS via crafted patterns
+  if (tool) {
+    const SAFE_TOOL_REGEX = /^[a-zA-Z0-9._:\-]+$/;
+    if (tool.length <= TOOL_REGEX_MAX_LENGTH && SAFE_TOOL_REGEX.test(tool)) {
+      // Safe literal pattern — escape dots (regex metachar) for exact matching
+      try {
+        const escaped = tool.replace(/\./g, '\\.');
+        const toolRegex = new RegExp('^' + escaped + '$');
+        events = events.filter(e => toolRegex.test(e.tool));
+      } catch {
+        events = events.filter(e => e.tool === tool);
+      }
+    } else {
+      events = events.filter(e => e.tool === tool);
+    }
+  }
+
+  // Take last N events
+  const filteredTotal = events.length;
+  const result = events.slice(-limit);
+
+  res.json({
+    roomId: room.id,
+    events: result,
+    total: room.events.length,
+    filtered: filteredTotal,
+    returned: result.length,
+    hasMore: filteredTotal > limit,
+  });
+}
+
+app.get("/history", (req, res) => handleHistory(getDefaultRoom(), req, res));
+app.get("/rooms/:roomId/history", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+  handleHistory(room, req, res);
+});
+
+// ── Who endpoint (rich participant info) ─────────────────────
+
+function handleWho(room: Room, _req: express.Request, res: express.Response): void {
+  const participants = Array.from(room.participants.entries()).map(([actorId, p]) => {
+    // Find this participant's last action
+    let lastAction: { tool: string; ts: number } | undefined;
+    for (let i = room.events.length - 1; i >= 0; i--) {
+      if (room.events[i].actorId === actorId) {
+        lastAction = { tool: room.events[i].tool, ts: room.events[i].ts };
+        break;
+      }
+    }
+
+    return {
+      actorId,
+      owner: p.owner,
+      type: p.type,
+      role: p.role,
+      joinedAt: p.joinedAt,
+      lastAction,
+      allowedTools: p.allowedTools,
+    };
+  });
+
+  res.json({
+    roomId: room.id,
+    participants,
+    count: participants.length,
+    humans: participants.filter(p => p.type === "human").length,
+    agents: participants.filter(p => p.type === "ai").length,
+  });
+}
+
+app.get("/who", (req, res) => handleWho(getDefaultRoom(), req, res));
+app.get("/rooms/:roomId/who", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+  handleWho(room, req, res);
+});
+
+// ── Join (flat = default room) ─────────────────────────────
+
+function experienceNotLoadedError(experienceId: string): string {
+  const lastError = experienceErrors.get(experienceId);
+  const hint = lastError
+    ? `\nLast build error: ${lastError}\nFix the source and save to hot-reload.`
+    : `\nCheck that src/index.tsx exists and exports a valid experience.`;
+  return `Experience '${experienceId}' not loaded.${hint}`;
+}
+
+function handleJoin(room: Room, req: express.Request, res: express.Response): void {
+  const exp = getExperienceForRoom(room);
+  if (!exp) {
+    res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+    return;
+  }
+
+  const { username = "user", actorType: rawActorType = "human", owner, role: requestedRole, agentMode: rawAgentMode, metadata: rawMetadata } = req.body;
+  const actorType: "human" | "ai" = rawActorType === "ai" ? "ai" : "human";
+  const resolvedOwner: string = owner || username;
+
+  // Validate agentMode (only for AI participants)
+  const VALID_AGENT_MODES = ["behavior", "manual", "hybrid"];
+  const agentMode: string | undefined = actorType === "ai" && typeof rawAgentMode === "string" && VALID_AGENT_MODES.includes(rawAgentMode) ? rawAgentMode : undefined;
+
+  // Validate metadata (string→string record, max 20 keys, max 200 chars per value)
+  let metadata: Record<string, string> | undefined;
+  if (rawMetadata && typeof rawMetadata === "object" && !Array.isArray(rawMetadata)) {
+    metadata = {};
+    let keyCount = 0;
+    for (const [k, v] of Object.entries(rawMetadata as Record<string, unknown>)) {
+      if (keyCount >= 20) break;
+      if (typeof k === "string" && typeof v === "string" && k.length <= 50) {
+        metadata[k] = String(v).slice(0, 200);
+        keyCount++;
+      }
+    }
+    if (Object.keys(metadata).length === 0) metadata = undefined;
+  }
+
+  // Reject empty owner — would bypass kick enforcement
+  if (!resolvedOwner) {
+    res.status(400).json({ error: "owner or username required" });
+    return;
+  }
+
+  // Dedup: if same owner already has a participant in this room, reuse the existing entry
+  if (resolvedOwner) {
+    // Check kick status before allowing reconnect
+    if (room.kickedOwners.has(resolvedOwner)) {
+      res.status(403).json({ error: "You have been kicked from this room." });
+      return;
+    }
+
+    for (const [existingId, existingP] of room.participants.entries()) {
+      if (existingP.owner === resolvedOwner) {
+        // Check if this specific actorId was kicked
+        if (room.kickedActors.has(existingId)) {
+          res.status(403).json({ error: "You have been kicked from this room." });
+          return;
+        }
+
+        // Same owner reconnecting — return existing identity (preserves actorId continuity)
+        existingP.joinedAt = Date.now();
+        // Ensure _agentRoles stays current on reconnect
+        if (existingP.type === "ai" && existingP.role) {
+          room.sharedState = {
+            ...room.sharedState,
+            _agentRoles: { ...(room.sharedState._agentRoles as Record<string, string> ?? {}), [existingId]: existingP.role },
+          };
+        }
+        // Clean up stale WS mapping and close the old WebSocket if still alive
+        for (const [ws, wsActor] of room.wsConnections.entries()) {
+          if (wsActor === existingId) {
+            room.wsConnections.delete(ws);
+            try { ws.close(1000, "Replaced by reconnect"); } catch {}
+            break;
+          }
+        }
+
+        // Broadcast presence update
+        broadcastPresenceUpdate(room);
+
+        // Compute observation for the reconnected agent
+        let observation: Record<string, unknown> | undefined;
+        let observeError: string | undefined;
+        const reconnectObserve = exp.module.observe ?? defaultObserve;
+        try { observation = reconnectObserve(room.sharedState, null, existingId); } catch (e: unknown) {
+          console.error(`[observe] Error in ${exp.module.manifest.id}:`, toErrorMessage(e));
+          observeError = toErrorMessage(e);
+        }
+
+        res.json({
+          roomId: room.id,
+          actorId: existingId,
+          owner: resolvedOwner,
+          role: existingP.role,
+          systemPrompt: existingP.systemPrompt,
+          reconnected: true,
+          observation,
+          observeError,
+          tools: getToolList(exp.module, existingP.allowedTools),
+        });
+        return;
+      }
+    }
+  }
+
+  // Unified participant slot matching — works for BOTH humans and AI.
+  // Resolution: (1) manifest.participantSlots, (2) module.participants, (3) legacy agentSlots.
+  const participantSlots: ParticipantSlot[] | undefined =
+    exp.module.manifest?.participantSlots || exp.module.participants;
+  const agentSlots = exp.module.agents || exp.module.manifest?.agentSlots;
+  let slotRole: string | undefined;
+  let slotAllowedTools: string[] | undefined;
+  let actorIdBase: string | undefined;
+  let slotSystemPrompt: string | undefined;
+
+  if (participantSlots?.length) {
+    // Count occupants per role (respecting maxInstances)
+    const roleOccupancy = new Map<string, number>();
+    for (const [, p] of room.participants) {
+      if (p.role) roleOccupancy.set(p.role, (roleOccupancy.get(p.role) || 0) + 1);
+    }
+
+    // Match: (1) requested role → (2) first open slot matching type → (3) "any" slots
+    const typeMatches = (slotType: string | undefined, joinType: string) => {
+      if (!slotType || slotType === "any") return true;
+      return slotType === joinType;
+    };
+    const hasCapacity = (slot: ParticipantSlot) => {
+      const max = slot.maxInstances ?? 1;
+      const current = roleOccupancy.get(slot.role) || 0;
+      return current < max;
+    };
+
+    let matched: ParticipantSlot | undefined;
+    if (requestedRole) {
+      matched = participantSlots.find((s) =>
+        s.role === requestedRole && typeMatches(s.type, actorType) && hasCapacity(s)
+      );
+    }
+    if (!matched) {
+      matched = participantSlots.find((s) =>
+        s.type === actorType && hasCapacity(s)
+      );
+    }
+    if (!matched) {
+      matched = participantSlots.find((s) =>
+        typeMatches(s.type, actorType) && hasCapacity(s)
+      );
+    }
+    // Fallback: if all matching slots are full, use the first type-compatible slot anyway
+    // (matches old behavior where agents overflow to agentSlots[0])
+    if (!matched) {
+      matched = participantSlots.find((s) => typeMatches(s.type, actorType));
+    }
+
+    if (matched) {
+      slotRole = matched.role;
+      slotAllowedTools = matched.allowedTools;
+      slotSystemPrompt = matched.systemPrompt;
+      // actorId uses the owner name, not the role — role lives in participant record
+    }
+  } else if (actorType === "ai" && agentSlots && agentSlots.length > 0) {
+    // Legacy fallback: agentSlots only match AI joins
+    const occupiedRoles = new Set<string>();
+    for (const [, p] of room.participants) {
+      if (p.type === "ai" && p.role) occupiedRoles.add(p.role);
+    }
+    const slot = agentSlots.find((s) => !occupiedRoles.has(s.role)) || agentSlots[0];
+    slotRole = slot.role;
+    slotAllowedTools = slot.allowedTools;
+    slotSystemPrompt = slot.systemPrompt;
+  }
+
+  const actorId = assignActorId(username, actorType, actorIdBase || resolvedOwner);
+  const participant: ParticipantRecord = {
+    type: actorType, joinedAt: Date.now(), owner: resolvedOwner,
+  };
+
+  if (slotRole) {
+    participant.role = slotRole;
+  }
+  if (slotAllowedTools) {
+    participant.allowedTools = slotAllowedTools;
+  }
+  if (slotSystemPrompt) {
+    participant.systemPrompt = slotSystemPrompt;
+  }
+  if (!slotRole && requestedRole) {
+    participant.role = requestedRole;
+  }
+  if (agentMode) {
+    participant.agentMode = agentMode;
+  }
+  if (metadata) {
+    participant.metadata = metadata;
+  }
+
+  room.participants.set(actorId, participant);
+
+  // Auto-populate _agentRoles when an AI participant joins with a role
+  if (actorType === "ai" && participant.role) {
+    room.sharedState = {
+      ...room.sharedState,
+      _agentRoles: { ...(room.sharedState._agentRoles as Record<string, string> ?? {}), [actorId]: participant.role },
+    };
+  }
+
+  // Broadcast presence update
+  broadcastPresenceUpdate(room);
+
+  // Compute observation so agents get a curated view from the start
+  let observation: Record<string, unknown> | undefined;
+  let observeError: string | undefined;
+  const joinObserve = exp.module.observe ?? defaultObserve;
+  try { observation = joinObserve(room.sharedState, null, actorId); } catch (e: unknown) {
+    console.error(`[observe] Error in ${exp.module.manifest.id}:`, toErrorMessage(e));
+    observeError = toErrorMessage(e);
+  }
+
+  res.json({
+    roomId: room.id,
+    actorId,
+    owner: resolvedOwner,
+    experienceId: exp.module.manifest.id,
+    sharedState: room.sharedState,
+    participants: room.participantList(),
+    events: room.events.slice(-JOIN_EVENT_HISTORY),
+    tools: getToolList(exp.module, participant.allowedTools),
+    browserUrl: getBaseUrl(),
+    config: room.config,
+    hasRoomConfig: !!exp.module.roomConfig,
+    observation,
+    role: participant.role,
+    allowedTools: participant.allowedTools,
+    systemPrompt: slotSystemPrompt,
+  });
+}
+
+app.post("/join", (req, res) => handleJoin(getDefaultRoom(), req, res));
+
+// ── Leave (flat = default room) ────────────────────────────
+
+function handleLeave(room: Room, req: express.Request, res: express.Response): void {
+  const { actorId } = req.body;
+  if (!actorId || typeof actorId !== "string") {
+    res.status(400).json({ error: "actorId required" });
+    return;
+  }
+  if (!room.participants.has(actorId)) {
+    res.status(404).json({ error: `Participant '${actorId}' not found in room '${room.id}'` });
+    return;
+  }
+  room.participants.delete(actorId);
+  // Clean up agent memory for this actor (key must match executeTool's memoryKey format)
+  const exp = getExperienceForRoom(room);
+  const memKey = exp ? `${exp.module.manifest.id}:${actorId}` : `${room.id}:${actorId}`;
+  agentMemory.delete(memKey);
+  // Clean up any associated WebSocket connections
+  for (const [ws, wsActorId] of room.wsConnections.entries()) {
+    if (wsActorId === actorId) {
+      room.wsConnections.delete(ws);
+      try { ws.close(); } catch {}
+    }
+  }
+  broadcastPresenceUpdate(room);
+  res.json({ left: true, actorId });
+}
+
+app.post("/leave", (req, res) => handleLeave(getDefaultRoom(), req, res));
+
+// ── Kick (remove participant from room) ──────────────────────
+
+interface KickResult {
+  error?: string;
+  kicked?: boolean;
+  actorId?: string;
+}
+
+function handleKick(
+  room: Room,
+  kickerActorId: string,
+  targetActorId: string,
+): KickResult {
+  if (kickerActorId === targetActorId) return { error: "Cannot kick yourself" };
+
+  const kicker = room.participants.get(kickerActorId);
+  if (!kicker || kicker.type !== "human") return { error: "Only human participants can kick" };
+
+  if (!room.participants.has(targetActorId)) return { error: "Participant not found" };
+
+  // Remove participant and mark as kicked (track both actorId and owner)
+  const targetParticipant = room.participants.get(targetActorId);
+  room.participants.delete(targetActorId);
+  // Cap kicked sets to prevent unbounded growth on long-running rooms
+  if (room.kickedActors.size >= 500) {
+    const oldest = room.kickedActors.values().next().value;
+    if (oldest) room.kickedActors.delete(oldest);
+  }
+  room.kickedActors.add(targetActorId);
+  if (targetParticipant?.owner) {
+    if (room.kickedOwners.size >= 500) {
+      const oldest = room.kickedOwners.values().next().value;
+      if (oldest) room.kickedOwners.delete(oldest);
+    }
+    room.kickedOwners.add(targetParticipant.owner);
+  }
+
+  // Close their WS if connected
+  for (const [targetWs, wsActorId] of room.wsConnections.entries()) {
+    if (wsActorId === targetActorId) {
+      try { targetWs.send(JSON.stringify({ type: "kicked", by: kickerActorId })); targetWs.close(); } catch {}
+      room.wsConnections.delete(targetWs);
+      break;
+    }
+  }
+
+  // Broadcast updated presence
+  broadcastPresenceUpdate(room);
+
+  // Wake up any long-polling agent-context for the kicked agent
+  roomEvents.emit(`room:${room.id}`);
+
+  return { kicked: true, actorId: targetActorId };
+}
+
+app.post("/kick", (req, res) => {
+  const result = handleKick(getDefaultRoom(), req.body.kickerActorId, req.body.targetActorId);
+  res.status(result.error ? 400 : 200).json(result);
+});
+
+// ── Idempotency cache ────────────────────────────────────────
+
+const idempotencyCache = new Map<string, { output: unknown; ts: number }>();
+const IDEMPOTENCY_TTL = 30000; // 30 seconds
+
+// Cleanup expired entries every 60 seconds
+const _idempotencyCleanupTimer = setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of idempotencyCache) {
+    if (now - entry.ts > IDEMPOTENCY_TTL) idempotencyCache.delete(key);
+  }
+}, IDEMPOTENCY_CLEANUP_INTERVAL_MS);
+
+// ── Execute tool (core) ─────────────────────────────────────
+// Internal function that executes a single tool call and returns the result.
+// Used by both the single-tool HTTP endpoint and the batch endpoint.
+
+interface ToolCallResult {
+  tool: string;
+  output?: unknown;
+  observation?: Record<string, unknown>;
+  error?: string;
+}
+
+async function executeTool(
+  room: Room,
+  toolName: string,
+  actorId: string,
+  input: Record<string, unknown> = {},
+  owner?: string,
+  expiredFlag?: { value: boolean },
+): Promise<ToolCallResult> {
+  const exp = getExperienceForRoom(room);
+  if (!exp) throw new Error(experienceNotLoadedError(room.experienceId));
+
+  // Handle scoped tool calls from embedded experiences
+  let scopeKey: string | undefined;
+  let resolvedToolName = toolName;
+  if (toolName.includes(':')) {
+    const colonIdx = toolName.indexOf(':');
+    scopeKey = toolName.slice(0, colonIdx);
+    resolvedToolName = toolName.slice(colonIdx + 1);
+    // Validate scopeKey against safe identifier pattern and forbidden keys
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(scopeKey) || FORBIDDEN_MERGE_KEYS.has(scopeKey)) {
+      throw new Error(`Invalid scope key in tool name: '${scopeKey}'`);
+    }
+  }
+
+  // Find tool from the room's experience
+  const tool = exp.module.tools.find((t) => t.name === resolvedToolName);
+  if (!tool) {
+    const available = exp.module.tools.map((t) => t.name).join(", ");
+    throw new ToolNotFoundError(`Tool '${resolvedToolName}' not found. Available tools: ${available}`);
+  }
+
+  // Check role-based tool restrictions for AI actors
+  // Check both bare name and fully-scoped name (e.g. "hero.move" and "scope:hero.move")
+  const callingParticipant = room.participants.get(actorId);
+  if (callingParticipant?.allowedTools &&
+      !callingParticipant.allowedTools.includes(resolvedToolName) &&
+      !callingParticipant.allowedTools.includes(toolName)) {
+    const role = callingParticipant.role || "ai";
+    const allowed = callingParticipant.allowedTools.join(", ");
+    throw new ToolForbiddenError(`Tool '${resolvedToolName}' is not allowed for role '${role}'. Allowed tools: ${allowed}`);
+  }
+
+  // Validate input
+  let validatedInput = input;
+  if (tool.input_schema?.parse) {
+    validatedInput = tool.input_schema.parse(input);
+  }
+
+  // Build ToolCtx
+  const participant = room.participants.get(actorId);
+  const resolvedOwner: string = participant?.owner || owner || actorId;
+  const memoryKey = `${exp.module.manifest.id}:${actorId}`;
+  const ctx: ServerToolCtx = {
+    roomId: room.id,
+    actorId,
+    owner: resolvedOwner,
+    get state() { return room.sharedState; },
+    setState: (newState: Record<string, unknown>) => {
+      if (expiredFlag?.value) return; // Tool timed out — discard late writes
+      room.sharedState = newState;
+      // Warn if state is getting large (>1MB serialized)
+      if (process.env.NODE_ENV !== "test") {
+        try {
+          const size = JSON.stringify(newState).length;
+          if (size > 1_000_000) {
+            console.warn(`[room:${room.id}] State size warning: ${(size / 1_000_000).toFixed(1)}MB. Consider pruning old data.`);
+          }
+        } catch {}
+      }
+    },
+    timestamp: Date.now(),
+    memory: agentMemory.get(memoryKey) || {},
+    setMemory: (updates: Record<string, unknown>) => {
+      const current = agentMemory.get(memoryKey) || {};
+      const merged = deepMerge(current, updates);
+      // Cap per-actor memory at 100 keys to prevent unbounded growth
+      const keys = Object.keys(merged);
+      if (keys.length > 100) {
+        for (const k of keys.slice(0, keys.length - 100)) delete merged[k];
+      }
+      agentMemory.set(memoryKey, merged);
+    },
+    roomConfig: room.config,
+  };
+
+  // Scope state for embedded experience tool calls
+  if (scopeKey) {
+    Object.defineProperty(ctx, 'state', {
+      get() { return room.sharedState[scopeKey!] || {}; },
+      configurable: true,
+    });
+    ctx.setState = (newState: Record<string, unknown>) => {
+      if (expiredFlag?.value) return; // Tool timed out — discard late writes
+      room.sharedState = { ...room.sharedState, [scopeKey!]: newState };
+    };
+  }
+
+  // Wire spawnRoom if experience requests the capability
+  const capabilities = exp.module.manifest.requested_capabilities || [];
+  if (capabilities.includes("room.spawn")) {
+    ctx.spawnRoom = async (opts: { experienceId: string; name?: string; initialState?: Record<string, unknown>; linkBack?: boolean; config?: Record<string, unknown> | string }) => {
+      return spawnRoom(room.id, opts);
+    };
+  }
+
+  // Wire blob operations
+  ctx.setBlob = (key: string, data: ArrayBuffer): string => {
+    const buf = Buffer.from(data);
+    if (buf.length > MAX_BLOB_SIZE) throw new Error(`Blob too large (${buf.length} bytes)`);
+    // Enforce total blob size cap (same logic as REST endpoint)
+    let totalSize = 0;
+    for (const [, meta] of blobMeta) totalSize += meta.size;
+    if (totalSize + buf.length > MAX_TOTAL_BLOBS) {
+      const sorted = [...blobMeta.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+      while (totalSize + buf.length > MAX_TOTAL_BLOBS && sorted.length > 0) {
+        const entry = sorted.shift();
+        if (!entry) break;
+        const [oldKey, oldMeta] = entry;
+        blobStore.delete(oldKey);
+        blobMeta.delete(oldKey);
+        totalSize -= oldMeta.size;
+      }
+    }
+    blobStore.set(key, buf);
+    blobMeta.set(key, { size: buf.length, createdAt: Date.now(), roomId: room.id });
+    return key;
+  };
+  ctx.getBlob = (key: string): ArrayBuffer | undefined => {
+    const buf = blobStore.get(key);
+    return buf ? buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer : undefined;
+  };
+
+  // Execute handler
+  const output = await tool.handler(ctx, validatedInput);
+
+  // Create event
+  const callerRole = callingParticipant?.role;
+  const event: ToolEvent = {
+    id: `${Date.now()}-${actorId}-${Math.random().toString(36).slice(2, 6)}`,
+    ts: Date.now(),
+    actorId,
+    owner: ctx.owner,
+    role: callerRole,
+    tool: toolName,
+    input: validatedInput,
+    output,
+  };
+
+  // Compute observation (falls back to defaultObserve when experience has none)
+  let observation: Record<string, unknown> | undefined;
+  const toolObserve = exp.module.observe ?? defaultObserve;
+  try {
+    observation = toolObserve(room.sharedState, event, actorId);
+  } catch (e: unknown) {
+    console.error(`[observe] Error in ${exp.module.manifest.id}:`, toErrorMessage(e));
+  }
+  if (observation) {
+    event.observation = observation;
+  }
+
+  // Append event
+  room.appendEvent(event);
+
+  // Broadcast state update (delta-compressed)
+  room.broadcastStateUpdate({
+    event,
+    changedBy: actorId,
+    tool: toolName,
+    observation,
+  });
+
+  // Emit for long-poll listeners
+  roomEvents.emit(`room:${room.id}`);
+
+  // Notify tick engine if behavior tools were modified (handle scoped tools like "scope:_behavior.set")
+  const baseTool = toolName.includes(':') ? toolName.split(':').pop()! : toolName;
+  if (baseTool.startsWith("_behavior.")) {
+    const engine = tickEngines.get(room.id);
+    if (engine) engine.markDirty();
+  }
+
+  return { tool: toolName, output, observation };
+}
+
+// ── Single tool HTTP endpoint ───────────────────────────────
+
+async function handleTool(room: Room, req: express.Request, res: express.Response): Promise<void> {
+  const exp = getExperienceForRoom(room);
+  if (!exp) { res.status(500).json({ error: experienceNotLoadedError(room.experienceId) }); return; }
+
+  const toolName = req.params.toolName;
+  const { actorId, input: rawInput = {}, owner } = req.body;
+  // Ensure input is a plain object (not array or primitive)
+  const input = rawInput !== null && typeof rawInput === "object" && !Array.isArray(rawInput) ? rawInput : {};
+
+  // Reject requests without actorId (prevents bypassing participant/allowedTools checks)
+  if (!actorId) {
+    res.status(400).json({ error: "actorId is required" });
+    return;
+  }
+
+  // Verify the caller is a participant in this room
+  if (!room.participants.has(actorId)) {
+    res.status(403).json({ error: `Actor '${actorId}' is not a participant in room '${room.id}'. Call /join first.` });
+    return;
+  }
+
+  // Idempotency: return cached result if same key seen recently (room-scoped)
+  // Placed AFTER participant check to prevent kicked/non-participant actors from replaying cached results
+  const rawIdempotencyKey = req.headers["x-idempotency-key"] as string | undefined;
+  // Skip idempotency for excessively long keys (memory amplification prevention)
+  const idempotencyKey = (rawIdempotencyKey && rawIdempotencyKey.length <= 128) ? `${room.id}:${rawIdempotencyKey}` : undefined;
+  if (idempotencyKey) {
+    const cached = idempotencyCache.get(idempotencyKey);
+    if (cached && Date.now() - cached.ts < IDEMPOTENCY_TTL) {
+      res.json({ output: cached.output, cached: true });
+      return;
+    }
+  }
+
+  try {
+    // Serialize tool execution through per-room queue to prevent state interleaving
+    // Wrap in timeout to prevent a hung handler from permanently blocking the room queue
+    // expiredFlag prevents timed-out handlers from mutating state after the queue moves on
+    const expiredFlag = { value: false };
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const result = await room.enqueueExecution(() =>
+      Promise.race([
+        executeTool(room, toolName, actorId, input, owner, expiredFlag),
+        new Promise<never>((_, reject) => {
+          timeoutHandle = setTimeout(() => {
+            expiredFlag.value = true;
+            reject(new Error(`Tool '${toolName}' timed out after ${TOOL_HTTP_TIMEOUT_MS}ms`));
+          }, TOOL_HTTP_TIMEOUT_MS);
+        }),
+      ])
+    );
+    if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+
+    // Cache for idempotency
+    if (idempotencyKey) {
+      idempotencyCache.set(idempotencyKey, { output: result.output, ts: Date.now() });
+    }
+
+    res.json({ output: result.output, observation: result.observation });
+  } catch (err: unknown) {
+    // Determine HTTP status code based on error type
+    let statusCode = 400;
+    if (err instanceof ToolNotFoundError) statusCode = 404;
+    else if (err instanceof ToolForbiddenError) statusCode = 403;
+
+    // Look up tool for better error formatting (may be undefined if tool not found)
+    const expForError = getExperienceForRoom(room);
+    const toolForError = expForError?.module?.tools?.find((t: ToolDef) => t.name === toolName);
+
+    const errorMsg = err instanceof ZodError
+      ? formatZodError(err, toolName, toolForError)
+      : (err instanceof Error ? formatHandlerError(err, toolName, toolForError, input) : String(err));
+    const resolvedOwner = owner || room.participants.get(actorId)?.owner;
+    const event: ToolEvent = {
+      id: `${Date.now()}-${actorId}-${Math.random().toString(36).slice(2, 6)}`,
+      ts: Date.now(),
+      actorId,
+      ...(resolvedOwner ? { owner: resolvedOwner } : {}),
+      tool: toolName,
+      input,
+      error: errorMsg,
+    };
+    room.appendEvent(event);
+    roomEvents.emit(`room:${room.id}`);
+    res.status(statusCode).json({ error: errorMsg });
+  }
+}
+
+app.post("/tools/:toolName", (req, res) => handleTool(getDefaultRoom(), req, res));
+
+// ── Batch tool endpoint ─────────────────────────────────────
+// Execute multiple tools sequentially in a single HTTP request.
+// Each tool sees the state left by the previous call, so order matters.
+// On error, previously successful calls are NOT rolled back.
+// Returns results for all calls, including errors.
+
+app.post("/tools-batch", (req, res) => handleBatch(getDefaultRoom(), req, res));
+
+async function handleBatch(room: Room, req: express.Request, res: express.Response): Promise<void> {
+  const exp = getExperienceForRoom(room);
+  if (!exp) { res.status(500).json({ error: experienceNotLoadedError(room.experienceId) }); return; }
+
+  const { actorId, owner, calls } = req.body;
+
+  if (!actorId) {
+    res.status(400).json({ error: "actorId is required" });
+    return;
+  }
+
+  // Verify the caller is a participant in this room
+  if (actorId && !room.participants.has(actorId)) {
+    res.status(403).json({ error: `Actor '${actorId}' is not a participant in room '${room.id}'. Call /join first.` });
+    return;
+  }
+
+  if (!Array.isArray(calls) || calls.length === 0) {
+    res.status(400).json({ error: "Missing or empty 'calls' array. Expected: [{ tool, input? }, ...]" });
+    return;
+  }
+
+  if (calls.length > MAX_BATCH_CALLS) {
+    res.status(400).json({ error: `Too many calls in batch (${calls.length}). Maximum is ${MAX_BATCH_CALLS}.` });
+    return;
+  }
+
+  // Serialize entire batch through per-room queue so all calls in the batch
+  // are atomic with respect to other concurrent tool calls.
+  // Per-call timeout prevents a hung handler from permanently blocking the room queue.
+  // Aggregate batch timeout prevents total queue hold > 60s.
+  const BATCH_TOTAL_TIMEOUT_MS = 60_000;
+  const batchStart = Date.now();
+  const { results, lastObservation, hasError } = await room.enqueueExecution(async () => {
+    const results: ToolCallResult[] = [];
+    let lastObservation: Record<string, unknown> | undefined;
+    let hasError = false;
+
+    for (const call of calls) {
+      // Check aggregate batch timeout
+      if (Date.now() - batchStart > BATCH_TOTAL_TIMEOUT_MS) {
+        results.push({ tool: call.tool || "?", error: `Batch total timeout exceeded (${BATCH_TOTAL_TIMEOUT_MS}ms)` });
+        hasError = true;
+        continue;
+      }
+      if (!call.tool) {
+        results.push({ tool: "?", error: "Missing 'tool' field in call" });
+        hasError = true;
+        continue;
+      }
+
+      try {
+        const batchExpiredFlag = { value: false };
+        let batchTimeoutHandle: ReturnType<typeof setTimeout> | undefined;
+        const result = await Promise.race([
+          executeTool(room, call.tool, actorId, (call.input !== null && typeof call.input === 'object' && !Array.isArray(call.input)) ? call.input : {}, owner, batchExpiredFlag),
+          new Promise<never>((_, reject) => {
+            batchTimeoutHandle = setTimeout(() => {
+              batchExpiredFlag.value = true;
+              reject(new Error(`Tool '${call.tool}' timed out after ${TOOL_HTTP_TIMEOUT_MS}ms`));
+            }, TOOL_HTTP_TIMEOUT_MS);
+          }),
+        ]);
+        if (batchTimeoutHandle !== undefined) clearTimeout(batchTimeoutHandle);
+        results.push(result);
+        if (result.observation) lastObservation = result.observation;
+      } catch (err: unknown) {
+        const errorMsg = err instanceof ZodError
+          ? formatZodError(err, call.tool)
+          : (err instanceof Error ? err.message : String(err));
+
+        // Log error event
+        const resolvedBatchOwner = owner || room.participants.get(actorId)?.owner;
+        const event: ToolEvent = {
+          id: `${Date.now()}-${actorId}-${Math.random().toString(36).slice(2, 6)}`,
+          ts: Date.now(),
+          actorId,
+          ...(resolvedBatchOwner ? { owner: resolvedBatchOwner } : {}),
+          tool: call.tool,
+          input: call.input || {},
+          error: errorMsg,
+        };
+        room.appendEvent(event);
+        roomEvents.emit(`room:${room.id}`);
+
+        results.push({ tool: call.tool, error: errorMsg });
+        hasError = true;
+      }
+    }
+    return { results, lastObservation, hasError };
+  });
+
+  // Return 207 (Multi-Status) if there were mixed results, 200 if all succeeded
+  const statusCode = hasError ? 207 : 200;
+  res.status(statusCode).json({ results, observation: lastObservation });
+}
+
+// ── Get events (supports long-poll via ?timeout=N) ──────────
+
+function handleEvents(room: Room, req: express.Request, res: express.Response): void {
+  const since = queryInt(req.query.since);
+  const timeout = Math.min(queryInt(req.query.timeout), LONG_POLL_MAX_TIMEOUT_MS);
+  const requestingActorId = queryString(req.query.actorId);
+
+  // Helper: compute observation for current state
+  const computeObservation = (events: ToolEvent[]): Record<string, unknown> | undefined => {
+    const exp = getExperienceForRoom(room);
+    if (!requestingActorId) return undefined;
+    const agentObserve = exp?.module?.observe ?? defaultObserve;
+    try {
+      const lastEvent = events.length > 0 ? events[events.length - 1] : null;
+      return agentObserve(room.sharedState, lastEvent, requestingActorId);
+    } catch (e: unknown) {
+      console.error(`[observe] Error in ${exp?.module?.manifest?.id}:`, toErrorMessage(e));
+      return undefined;
+    }
+  };
+
+  const getNewEvents = () => room.events.filter((e) => e.ts > since && e.actorId !== requestingActorId);
+
+  let newEvents = getNewEvents();
+  if (newEvents.length > 0 || timeout === 0) {
+    const observation = computeObservation(newEvents);
+    res.json({
+      events: newEvents,
+      sharedState: room.sharedState,
+      participants: room.participantList(),
+      observation,
+    });
+    return;
+  }
+
+  // Long-poll: wait for event emission or timeout
+  let responded = false;
+
+  let batchTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const respond = () => {
+    if (responded) return;
+    responded = true;
+    clearTimeout(timer);
+    if (batchTimer) { clearTimeout(batchTimer); batchTimer = null; }
+    roomEvents.removeListener(`room:${room.id}`, onEvent);
+    newEvents = getNewEvents();
+    const observation = computeObservation(newEvents);
+    res.json({
+      events: newEvents,
+      sharedState: room.sharedState,
+      participants: room.participantList(),
+      observation,
+    });
+  };
+
+  const timer = setTimeout(respond, timeout);
+
+  const onEvent = () => {
+    if (responded) return;
+    if (batchTimer) return; // Deduplicate rapid events
+    // Small delay to batch rapid events
+    batchTimer = setTimeout(() => {
+      batchTimer = null;
+      if (responded) return;
+      // Only respond if there are actual new tool events.
+      // Streams modify state and emit roomEvents but don't create
+      // event log entries — ignore those wake-ups so the long-poll
+      // keeps waiting for real tool events (like _chat.send).
+      const pending = getNewEvents();
+      if (pending.length > 0) {
+        respond();
+      }
+    }, EVENT_BATCH_DEBOUNCE_MS);
+  };
+
+  roomEvents.on(`room:${room.id}`, onEvent);
+
+  // Cleanup on client disconnect
+  req.on("close", () => {
+    responded = true;
+    clearTimeout(timer);
+    if (batchTimer) clearTimeout(batchTimer);
+    roomEvents.removeListener(`room:${room.id}`, onEvent);
+  });
+}
+
+app.get("/events", (req, res) => handleEvents(getDefaultRoom(), req, res));
+
+// ── Cross-room events (watch all rooms) ────────────────────
+
+app.get("/events/all", (req, res) => {
+  const since = queryInt(req.query.since);
+  const timeout = Math.min(queryInt(req.query.timeout), LONG_POLL_MAX_TIMEOUT_MS);
+  const requestingActorId = queryString(req.query.actorId);
+
+  const getAllEvents = () => {
+    const allEvents: Array<ToolEvent & { roomId: string }> = [];
+    for (const room of rooms.values()) {
+      for (const e of room.events) {
+        if (e.ts > since) {
+          // Self-filter: skip own events (consistent with /events and /agent-context)
+          if (requestingActorId && e.actorId === requestingActorId) continue;
+          allEvents.push({ ...e, roomId: room.id });
+        }
+      }
+    }
+    allEvents.sort((a, b) => a.ts - b.ts);
+    return allEvents;
+  };
+
+  const getRoomSummaries = () =>
+    Array.from(rooms.values()).map((room) => ({
+      roomId: room.id,
+      experienceId: room.experienceId,
+      participants: room.participantList(),
+      eventCount: room.events.length,
+    }));
+
+  let newEvents = getAllEvents();
+  if (newEvents.length > 0 || timeout === 0) {
+    res.json({ events: newEvents, rooms: getRoomSummaries() });
+    return;
+  }
+
+  // Long-poll: wait for any room event
+  let responded = false;
+
+  let batchTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const respond = () => {
+    if (responded) return;
+    responded = true;
+    clearTimeout(timer);
+    if (batchTimer) { clearTimeout(batchTimer); batchTimer = null; }
+    clearInterval(newRoomCheck);
+    for (const rid of subscribedRoomIds) {
+      roomEvents.removeListener(`room:${rid}`, onEvent);
+    }
+    res.json({ events: getAllEvents(), rooms: getRoomSummaries() });
+  };
+
+  const timer = setTimeout(respond, timeout);
+
+  const onEvent = () => {
+    if (responded) return;
+    if (batchTimer) return;
+    batchTimer = setTimeout(() => {
+      batchTimer = null;
+      if (responded) return;
+      // Only respond if there are actual new tool events — ignore
+      // stream-only wake-ups (streams don't create event log entries).
+      const pending = getAllEvents();
+      if (pending.length > 0) respond();
+    }, EVENT_BATCH_DEBOUNCE_MS);
+  };
+
+  // Listen on all existing rooms + track subscribed IDs for cleanup
+  const subscribedRoomIds = new Set<string>();
+  for (const room of rooms.values()) {
+    roomEvents.on(`room:${room.id}`, onEvent);
+    subscribedRoomIds.add(room.id);
+  }
+
+  // Also check periodically for newly spawned rooms during long-poll
+  const newRoomCheck = setInterval(() => {
+    if (responded) { clearInterval(newRoomCheck); return; }
+    for (const room of rooms.values()) {
+      if (!subscribedRoomIds.has(room.id)) {
+        roomEvents.on(`room:${room.id}`, onEvent);
+        subscribedRoomIds.add(room.id);
+      }
+    }
+  }, 2000);
+
+  req.on("close", () => {
+    responded = true;
+    clearTimeout(timer);
+    if (batchTimer) clearTimeout(batchTimer);
+    clearInterval(newRoomCheck);
+    for (const rid of subscribedRoomIds) {
+      roomEvents.removeListener(`room:${rid}`, onEvent);
+    }
+  });
+});
+
+// ── Browser error capture ──────────────────────────────────────
+// The viewer POSTs browser errors here so the agent can see them
+// via /agent-context and fix them automatically.
+
+const roomBrowserErrors: Map<string, { message: string; ts: number }[]> = new Map();
+const MAX_BROWSER_ERRORS = 20;
+
+const lastBrowserErrorAt: Map<string, number> = new Map(); // Rate limit per room
+const BROWSER_ERROR_COOLDOWN_MS = 200; // Min interval between error-triggered wake-ups
+const MAX_BROWSER_ERROR_MSG_LEN = 500; // Truncate overlong error messages
+
+app.post("/browser-error", (req, res) => {
+  const { message, roomId: errorRoomId } = req.body || {};
+  if (typeof message === "string" && message.trim()) {
+    // Truncate message to prevent memory bloat
+    const trimmed = message.trim().slice(0, MAX_BROWSER_ERROR_MSG_LEN);
+    const now = Date.now();
+
+    // Scope errors to the room they came from
+    const targetRoom = (typeof errorRoomId === "string" && rooms.has(errorRoomId))
+      ? errorRoomId
+      : getDefaultRoom().id;
+
+    let errors = roomBrowserErrors.get(targetRoom);
+    if (!errors) {
+      errors = [];
+      roomBrowserErrors.set(targetRoom, errors);
+    }
+    errors.push({ message: trimmed, ts: now });
+    if (errors.length > MAX_BROWSER_ERRORS) {
+      errors.splice(0, errors.length - MAX_BROWSER_ERRORS);
+    }
+
+    // Rate-limit wake-ups per room
+    const lastErrorAt = lastBrowserErrorAt.get(targetRoom) || 0;
+    if (now - lastErrorAt >= BROWSER_ERROR_COOLDOWN_MS) {
+      lastBrowserErrorAt.set(targetRoom, now);
+      roomEvents.emit(`room:${targetRoom}`);
+    }
+  }
+  res.json({ ok: true });
+});
+
+// ── Agent context (combined events + observe for Stop hook) ──
+
+app.get("/agent-context", (req, res) => {
+  const rawSince = queryInt(req.query.since);
+  const timeout = Math.min(queryInt(req.query.timeout), AGENT_CONTEXT_MAX_TIMEOUT_MS);
+  const actorId = queryString(req.query.actorId) || "unknown";
+  const requestedRoomId = queryString(req.query.roomId);
+
+  // Find the agent's actual room:
+  // 1. Explicit roomId query param (preferred)
+  // 2. Search all rooms for the actorId
+  // 3. Fall back to default room
+  let agentRoom: Room = getDefaultRoom();
+  if (requestedRoomId) {
+    const r = getRoom(requestedRoomId);
+    if (r) agentRoom = r;
+  } else {
+    for (const room of rooms.values()) {
+      if (room.participants.has(actorId)) {
+        agentRoom = room;
+        break;
+      }
+    }
+  }
+
+  // Resolve owner: explicit query param > participant record from agent's room
+  // Never fall back to actorId.split — that caused multi-agent collisions
+  // where two agents both resolved to the same prefix and filtered each other out
+  const participantEntry = agentRoom.participants.get(actorId);
+  const requestingOwner = queryString(req.query.owner) || participantEntry?.owner;
+
+  // Use server-tracked cursor when client sends since=0 (e.g. stop hook runs
+  // as a fresh process each time and can't persist cursors between invocations).
+  // This makes the server the true source of truth for cursor state.
+  const since = (rawSince === 0 && participantEntry?.eventCursor)
+    ? participantEntry.eventCursor
+    : rawSince;
+
+  // Update lastPollAt for AI heartbeat tracking
+  if (participantEntry) {
+    participantEntry.lastPollAt = Date.now();
+  }
+
+  // Gather events from ALL rooms (not just default) so the agent sees sub-room activity
+  const getAllNewEvents = () => {
+    const allEvents: (ToolEvent & { roomId: string })[] = [];
+    for (const room of rooms.values()) {
+      for (const e of room.events) {
+        // Self-filter: skip events from the same owner
+        // If either side has no owner, don't filter (safe default: show the event)
+        if (requestingOwner && e.owner === requestingOwner) continue;
+        // Skip tick engine events — agents react to observations, not individual ticks
+        if (e.actorId === "_tick-engine" || e.owner === "_system") continue;
+        if (e.ts > since) {
+          allEvents.push({ ...e, roomId: room.id });
+        }
+      }
+    }
+    return allEvents.sort((a, b) => a.ts - b.ts);
+  };
+
+  // Collect all participants and available tools across rooms
+  const getAllParticipants = () => {
+    const all = new Set<string>();
+    for (const room of rooms.values()) {
+      for (const p of room.participantList()) all.add(p);
+    }
+    return [...all];
+  };
+
+  // Resolve the requesting agent's allowed tools from their participant record in their actual room
+  const requestingParticipant = agentRoom.participants.get(actorId);
+  const agentAllowedTools = requestingParticipant?.allowedTools;
+
+  const getAllRoomInfo = () => {
+    const info: Record<string, { experience: string; tools: string[]; participants: string[] }> = {};
+    for (const room of rooms.values()) {
+      const exp = getExperienceForRoom(room);
+      let toolNames = exp?.module?.tools?.map((t: ToolDef) => t.name) || [];
+      if (agentAllowedTools) toolNames = toolNames.filter((n: string) => agentAllowedTools.includes(n));
+      info[room.id] = {
+        experience: exp?.module?.manifest?.id || room.experienceId || "unknown",
+        tools: toolNames,
+        participants: room.participantList(),
+      };
+    }
+    return info;
+  };
+
+  const buildResponse = () => {
+    // Check if agentRoom was deleted during long-poll
+    if (!rooms.has(agentRoom.id)) {
+      return {
+        events: [],
+        observation: { done: true, reason: "room_deleted" },
+        participants: getAllParticipants(),
+        rooms: getAllRoomInfo(),
+      };
+    }
+
+    const events = getAllNewEvents();
+
+    // Check if this agent was kicked — return done:true so the stop hook archives the state file
+    if (agentRoom.kickedActors.has(actorId)) {
+      agentRoom.kickedActors.delete(actorId); // One-shot: clear after notifying
+      return {
+        events: [],
+        observation: { done: true, reason: "kicked" },
+        participants: getAllParticipants(),
+        rooms: getAllRoomInfo(),
+      };
+    }
+
+    // Compute observation from the agent's actual room (not always default)
+    const observeExp = getExperienceForRoom(agentRoom);
+    let observation: Record<string, unknown> | undefined;
+    let observeError: string | undefined;
+    if (observeExp?.module?.observe) {
+      try {
+        const lastEvent = events.length > 0 ? events[events.length - 1] : null;
+        observation = observeExp.module.observe(agentRoom.sharedState, lastEvent, actorId);
+      } catch (e: unknown) {
+        console.error(`[observe] Error in ${observeExp.module.manifest?.id}:`, toErrorMessage(e));
+        observeError = toErrorMessage(e);
+      }
+    }
+
+    // Find the agent's most recent error (own events are filtered from `events`,
+    // so scan raw room events for this actor's errors since the last poll)
+    let lastError: { tool: string; error: string } | undefined;
+    for (const room of rooms.values()) {
+      for (const e of room.events) {
+        if (e.ts > since && e.error && e.actorId === actorId) {
+          lastError = { tool: e.tool, error: e.error };
+        }
+      }
+    }
+
+    // Collect tick engine status across all rooms
+    const tickStatus: Record<string, { enabled: boolean; tickCount: number }> = {};
+    for (const [roomId, engine] of tickEngines) {
+      const status = engine.getStatus();
+      tickStatus[roomId] = {
+        enabled: status.enabled,
+        tickCount: status.tickCount,
+      };
+    }
+
+    // Collect browser errors for this agent's room since last poll
+    const roomErrors = roomBrowserErrors.get(agentRoom.id) || [];
+    const recentBrowserErrors = roomErrors.filter(e => e.ts > since);
+    // Clear reported errors for this room so they don't repeat
+    if (recentBrowserErrors.length > 0) {
+      roomBrowserErrors.set(agentRoom.id, roomErrors.filter(e => e.ts <= since));
+    }
+
+    // Track eventCursor server-side so agents don't need local state files
+    let eventCursor: number | undefined;
+    if (events.length > 0 && participantEntry) {
+      eventCursor = Math.max(
+        participantEntry.eventCursor || 0,
+        ...events.map(e => e.ts)
+      );
+      participantEntry.eventCursor = eventCursor;
+    } else if (participantEntry?.eventCursor) {
+      eventCursor = participantEntry.eventCursor;
+    }
+
+    return {
+      events,
+      observation: observation || {},
+      observeError,
+      lastError,
+      browserErrors: recentBrowserErrors.length > 0 ? recentBrowserErrors : undefined,
+      participants: getAllParticipants(),
+      rooms: getAllRoomInfo(),
+      tickEngines: Object.keys(tickStatus).length > 0 ? tickStatus : undefined,
+      eventCursor,
+    };
+  };
+
+  // If events, browser errors, or kicked status are already available, respond immediately
+  let newEvents = getAllNewEvents();
+  const pendingBrowserErrors = (roomBrowserErrors.get(agentRoom.id) || []).filter(e => e.ts > since);
+  const isKicked = agentRoom.kickedActors.has(actorId);
+  if (newEvents.length > 0 || pendingBrowserErrors.length > 0 || isKicked || timeout === 0) {
+    res.json(buildResponse());
+    return;
+  }
+
+  // Long-poll: wait for events or timeout
+  let responded = false;
+
+  let batchTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const respond = () => {
+    if (responded) return;
+    responded = true;
+    clearTimeout(timer);
+    if (batchTimer) { clearTimeout(batchTimer); batchTimer = null; }
+    clearInterval(newRoomCheck);
+    // Remove listeners from all subscribed rooms (tracked set handles deleted rooms)
+    for (const rid of subscribedRoomIds) {
+      roomEvents.removeListener(`room:${rid}`, onEvent);
+    }
+    res.json(buildResponse());
+  };
+
+  const timer = setTimeout(respond, timeout);
+
+  const onEvent = () => {
+    if (responded) return;
+    if (batchTimer) return;
+    batchTimer = setTimeout(() => {
+      batchTimer = null;
+      if (responded) return;
+      const pending = getAllNewEvents();
+      if (pending.length > 0 || agentRoom.kickedActors.has(actorId)) respond();
+    }, EVENT_BATCH_DEBOUNCE_MS);
+  };
+
+  // Listen on ALL rooms + track subscribed IDs for cleanup
+  const subscribedRoomIds = new Set<string>();
+  for (const room of rooms.values()) {
+    roomEvents.on(`room:${room.id}`, onEvent);
+    subscribedRoomIds.add(room.id);
+  }
+
+  // Check periodically for newly spawned rooms during long-poll
+  const newRoomCheck = setInterval(() => {
+    if (responded) { clearInterval(newRoomCheck); return; }
+    for (const room of rooms.values()) {
+      if (!subscribedRoomIds.has(room.id)) {
+        roomEvents.on(`room:${room.id}`, onEvent);
+        subscribedRoomIds.add(room.id);
+      }
+    }
+  }, 2000);
+
+  req.on("close", () => {
+    responded = true;
+    clearTimeout(timer);
+    if (batchTimer) clearTimeout(batchTimer);
+    clearInterval(newRoomCheck);
+    for (const rid of subscribedRoomIds) {
+      roomEvents.removeListener(`room:${rid}`, onEvent);
+    }
+  });
+});
+
+// ── Serve client bundle ────────────────────────────────────
+
+app.get("/bundle", async (_req, res) => {
+  // Wait for any in-progress hot-reload to complete before serving
+  if (rebuildingPromise) await rebuildingPromise;
+  const host = experienceCache.get(hostExperienceId);
+  res.setHeader("Content-Type", "text/javascript");
+  setNoCacheHeaders(res);
+  res.send(host?.clientBundle || "");
+});
+
+// ── Memory endpoints ───────────────────────────────────────
+
+app.get("/memory", (req, res) => {
+  const key = queryString(req.query.key);
+  if (!key) { res.json({}); return; }
+  res.json(agentMemory.get(key) || {});
+});
+
+app.post("/memory", (req, res) => {
+  const { key, updates } = req.body;
+  if (!key) { res.status(400).json({ error: "key required" }); return; }
+  if (!updates || typeof updates !== "object" || Array.isArray(updates)) { res.status(400).json({ error: "updates must be a plain object" }); return; }
+  const current = agentMemory.get(key) || {};
+  const merged = deepMerge(current, updates);
+  // Cap per-key object to 100 keys (same limit as tool-path setMemory)
+  const keys = Object.keys(merged);
+  if (keys.length > 100) {
+    res.status(400).json({ error: `Memory key limit exceeded (${keys.length}/100)` });
+    return;
+  }
+  agentMemory.set(key, merged);
+  res.json({ saved: true });
+});
+
+// ── Blob store endpoints ──────────────────────────────────
+app.get("/blobs/:key", (req, res) => {
+  const blob = blobStore.get(req.params.key);
+  if (!blob) { res.status(404).json({ error: "Blob not found" }); return; }
+  res.setHeader("Content-Type", "application/octet-stream");
+  res.setHeader("Content-Length", String(blob.length));
+  res.setHeader("Cache-Control", `public, max-age=${BLOB_CACHE_MAX_AGE_SECONDS}`);
+  res.send(blob);
+});
+
+app.post("/blobs/:key", express.raw({ limit: "10mb", type: "*/*" }), (req, res) => {
+  const key = req.params.key;
+  const { roomId, actorId } = req.query as { roomId?: string; actorId?: string };
+
+  // Validate blob key: safe characters only, no prototype-pollution keys
+  if (!/^[a-zA-Z0-9._\-]+$/.test(key) || key.length > 256) {
+    res.status(400).json({ error: "Invalid blob key format" });
+    return;
+  }
+  if (key === "__proto__" || key === "constructor" || key === "prototype") {
+    res.status(400).json({ error: "Reserved blob key name" });
+    return;
+  }
+
+  if (!Buffer.isBuffer(req.body) || req.body.length === 0) {
+    res.status(400).json({ error: "Empty or invalid blob data" });
+    return;
+  }
+
+  if (req.body.length > MAX_BLOB_SIZE) {
+    res.status(413).json({ error: `Blob too large (${req.body.length} bytes, max ${MAX_BLOB_SIZE})` });
+    return;
+  }
+
+  // Check total size
+  let totalSize = 0;
+  for (const [, meta] of blobMeta) totalSize += meta.size;
+  if (totalSize + req.body.length > MAX_TOTAL_BLOBS) {
+    // Garbage collect: remove oldest blobs until we have space
+    const sorted = [...blobMeta.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+    while (totalSize + req.body.length > MAX_TOTAL_BLOBS && sorted.length > 0) {
+      const [oldKey, oldMeta] = sorted.shift()!;
+      blobStore.delete(oldKey);
+      blobMeta.delete(oldKey);
+      totalSize -= oldMeta.size;
+    }
+  }
+
+  blobStore.set(key, req.body);
+  blobMeta.set(key, { size: req.body.length, createdAt: Date.now(), roomId: roomId || "local" });
+
+  res.json({ key, size: req.body.length });
+});
+
+app.delete("/blobs/:key", (req, res) => {
+  const key = req.params.key;
+  // Validate key format (same safe-char check as POST)
+  if (!/^[a-zA-Z0-9_\-.:]+$/.test(key) || key.length > 200) {
+    res.status(400).json({ error: "Invalid blob key" });
+    return;
+  }
+  if (!blobStore.has(key)) {
+    res.status(404).json({ error: "Blob not found" });
+    return;
+  }
+  blobStore.delete(key);
+  blobMeta.delete(key);
+  res.json({ deleted: true });
+});
+
+app.get("/blobs", (_req, res) => {
+  const list = [...blobMeta.entries()].map(([key, meta]) => ({ key, ...meta }));
+  res.json(list);
+});
+
+// ── Screenshot capture ────────────────────────────────────
+
+const pendingScreenshots = new Map<string, {
+  resolve: (data: Buffer) => void;
+  reject: (err: Error) => void;
+  timer: NodeJS.Timeout;
+  viewerWs: WebSocket;
+}>();
+
+app.get("/screenshot", (req, res) => {
+  // Find an open viewer WebSocket connection (check default room first, then all rooms)
+  let viewerWs: WebSocket | null = null;
+  for (const room of rooms.values()) {
+    for (const [ws] of room.wsConnections) {
+      if (ws.readyState === WebSocket.OPEN) {
+        viewerWs = ws;
+        break;
+      }
+    }
+    if (viewerWs) break;
+  }
+
+  if (!viewerWs) {
+    res.status(503).json({ error: `No browser viewer connected. Open ${getBaseUrl()} first.` });
+    return;
+  }
+
+  const requestId = `ss-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+  const timeoutMs = Math.min(queryInt(req.query.timeout) || SCREENSHOT_DEFAULT_TIMEOUT_MS, SCREENSHOT_MAX_TIMEOUT_MS);
+
+  const promise = new Promise<Buffer>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingScreenshots.delete(requestId);
+      reject(new Error("Screenshot timeout"));
+    }, timeoutMs);
+
+    pendingScreenshots.set(requestId, { resolve, reject, timer, viewerWs: viewerWs! });
+  });
+
+  // Clean up if HTTP client disconnects before screenshot arrives
+  req.on("close", () => {
+    const p = pendingScreenshots.get(requestId);
+    if (p) {
+      clearTimeout(p.timer);
+      pendingScreenshots.delete(requestId);
+      p.reject(new Error("Client disconnected"));
+    }
+  });
+
+  // Ask the viewer to capture
+  try {
+    viewerWs.send(JSON.stringify({ type: "screenshot_request", id: requestId }));
+  } catch (err) {
+    const p = pendingScreenshots.get(requestId);
+    if (p) {
+      clearTimeout(p.timer);
+      pendingScreenshots.delete(requestId);
+      p.reject(new Error("WebSocket send failed"));
+    }
+  }
+
+  promise
+    .then((pngBuffer) => {
+      res.setHeader("Content-Type", "image/png");
+      res.setHeader("Content-Length", String(pngBuffer.length));
+      res.send(pngBuffer);
+    })
+    .catch((err) => {
+      res.status(500).json({ error: toErrorMessage(err) });
+    });
+});
+
+// ── Sync (re-bundle) ──────────────────────────────────────
+
+app.post("/sync", async (_req, res) => {
+  try {
+    // Stop tick engines for host rooms before reloading (prevents ghost tick loops)
+    for (const room of rooms.values()) {
+      if (room.experienceId === hostExperienceId) {
+        stopTickEngine(room.id);
+      }
+    }
+    await loadHost();
+    const hostLoaded = experienceCache.get(hostExperienceId);
+    // Broadcast and restart tick engines for rooms running the host experience
+    for (const room of rooms.values()) {
+      if (room.experienceId === hostExperienceId) {
+        room.broadcastToAll({ type: "experience_updated" });
+        if (hostLoaded) maybeStartTickEngine(room, hostLoaded);
+      }
+    }
+    const host = getHostExperience();
+    res.json({ synced: true, title: host?.manifest?.title });
+  } catch (err: unknown) {
+    res.status(500).json({ error: toErrorMessage(err) });
+  }
+});
+
+// ── Room management routes ─────────────────────────────────
+
+app.get("/rooms", (_req, res) => {
+  const roomList = Array.from(rooms.values()).map((room) => {
+    const exp = experienceCache.get(room.experienceId);
+    const st = room.sharedState as Record<string, unknown>;
+    const flags: Record<string, unknown> = {};
+    if (st._recruitment) flags._recruitment = st._recruitment;
+    if (st._announcement) flags._announcement = st._announcement;
+    return {
+      roomId: room.id,
+      experienceId: room.experienceId,
+      experienceTitle: exp?.module?.manifest?.title || room.experienceId,
+      participants: room.participantDetails(),
+      participantCount: room.participants.size,
+      eventCount: room.events.length,
+      parentRoomId: room.parentRoomId,
+      childRoomIds: room.childRoomIds,
+      config: room.config,
+      flags,
+    };
+  });
+  res.json(roomList);
+});
+
+app.post("/rooms/spawn", async (req, res) => {
+  try {
+    const { experienceId, name, initialState, linkBack, sourceRoomId, config } = req.body;
+    const source = sourceRoomId || DEFAULT_ROOM_ID;
+    // Validate sourceRoomId exists (prevents rate limit bypass via crafted sourceRoomId)
+    if (sourceRoomId && !rooms.has(source)) {
+      res.status(400).json({ error: `Source room '${source}' not found` });
+      return;
+    }
+    // Only the actual library room bypasses rate limiting
+    const skipRateLimit = source === "library" && rooms.has("library");
+    const result = await spawnRoom(source, {
+      experienceId: experienceId || hostExperienceId,
+      name,
+      initialState,
+      linkBack,
+      config,
+      skipRateLimit,
+    });
+    res.json(result);
+  } catch (err: unknown) {
+    res.status(400).json({ error: toErrorMessage(err) });
+  }
+});
+
+// ── Room config schema endpoint ────────────────────────────
+app.get("/rooms/config-schema", async (req, res) => {
+  try {
+    const loaded = await getLoadedExperience();
+    const roomConfigDef = loaded.module?.roomConfig;
+
+    if (!roomConfigDef) {
+      res.json({ hasConfig: false, experienceId: hostExperienceId });
+      return;
+    }
+    const schema = roomConfigDef.schema
+      ? zodToJsonSchema(roomConfigDef.schema)
+      : {};
+    res.json({
+      hasConfig: true,
+      experienceId: hostExperienceId,
+      schema,
+      defaults: roomConfigDef.defaults || {},
+      presets: Object.keys(roomConfigDef.presets || {}),
+      description: roomConfigDef.description || "",
+    });
+  } catch (err: unknown) {
+    res.status(400).json({ error: toErrorMessage(err) });
+  }
+});
+
+// ── Tick status endpoint ───────────────────────────────────
+
+app.get("/rooms/:roomId/tick-status", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  const engine = tickEngines.get(room.id);
+  if (!engine) {
+    res.json({ enabled: false, tickRateMs: 0, tickCount: 0, behaviorsTotal: 0, behaviorsEnabled: 0, lastTick: null });
+    return;
+  }
+  res.json(engine.getStatus());
+});
+
+// ── Experiences endpoint (discovery for agents) ────────────
+
+app.get("/experiences", async (_req, res) => {
+  try {
+    const loaded = await getLoadedExperience();
+    res.json([{
+      id: loaded.module.manifest.id,
+      title: loaded.module.manifest.title,
+      description: loaded.module.manifest.description,
+      version: loaded.module.manifest.version,
+      loaded: true,
+      hasRoomConfig: !!loaded.module.roomConfig,
+      category: loaded.module.manifest.category,
+      tags: loaded.module.manifest.tags,
+    }]);
+  } catch (err: unknown) {
+    res.json([]);
+  }
+});
+
+app.get("/rooms/:roomId", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  const exp = getExperienceForRoom(room);
+  let observation: Record<string, unknown> | undefined;
+  const roomObserve = exp?.module?.observe ?? defaultObserve;
+  const observeActorId = typeof req.query.actorId === "string" ? req.query.actorId : "viewer";
+  try { observation = roomObserve(room.sharedState, null, observeActorId); } catch (err: unknown) { console.warn(`[observe] Error: ${toErrorMessage(err)}`); }
+  res.json({
+    roomId: room.id,
+    experienceId: room.experienceId,
+    sharedState: room.sharedState,
+    stateVersion: room.stateVersion,
+    participants: room.participantList(),
+    events: room.events.slice(-ROOM_STATE_EVENT_HISTORY),
+    parentRoomId: room.parentRoomId,
+    childRoomIds: room.childRoomIds,
+    config: room.config,
+    observation,
+  });
+});
+
+app.get("/rooms/:roomId/links", (req, res) => {
+  const roomId = req.params.roomId;
+  const links = roomLinks.filter(
+    (l) => l.parentRoomId === roomId || l.childRoomId === roomId,
+  );
+  res.json(links);
+});
+
+// ── Slots (query participant slot definitions + occupancy) ────
+app.get("/rooms/:roomId/slots", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  const exp = getExperienceForRoom(room);
+  const slots = exp?.module?.manifest?.participantSlots || exp?.module?.participants || [];
+  res.json({
+    slots,
+    participantDetails: room.participantDetails(),
+  });
+});
+
+app.post("/rooms/:roomId/join", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  handleJoin(room, req, res);
+});
+
+app.post("/rooms/:roomId/leave", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  handleLeave(room, req, res);
+});
+
+app.post("/rooms/:roomId/kick", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  const result = handleKick(room, req.body.kickerActorId, req.body.targetActorId);
+  res.status(result.error ? 400 : 200).json(result);
+});
+
+// ── Reset room to initial state ──────────────────────────────
+app.post("/rooms/:roomId/reset", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  const loaded = getExperienceForRoom(room);
+  if (!loaded) {
+    res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+    return;
+  }
+  const config = resolveRoomConfig(loaded.module, room.config);
+  const initialState = resolveInitialState(loaded.module, config);
+  room.sharedState = initialState;
+  room.events.length = 0;
+  // Reset all participant event cursors so agents see the reset event
+  for (const [, p] of room.participants) {
+    p.eventCursor = 0;
+  }
+
+  // Append a reset event so stop hooks see it
+  const resetEvent: ToolEvent = {
+    id: `${Date.now()}-system-${Math.random().toString(36).slice(2, 6)}`,
+    ts: Date.now(),
+    actorId: "system",
+    tool: "_reset",
+    input: {},
+    output: { reset: true },
+  };
+  room.appendEvent(resetEvent);
+  roomEvents.emit(`room:${room.id}`);
+
+  // Reset sends full state (not delta) since the entire state changed
+  room.resetDeltaTracking();
+  room.broadcastStateUpdate({
+    changedBy: "system",
+    tool: "_reset",
+  }, true);
+  res.json({ ok: true });
+});
+
+// ── Delete room (cleanup spawned rooms) ─────────────────────
+app.delete("/rooms/:roomId", (req, res) => {
+  const roomId = req.params.roomId;
+  if (roomId === DEFAULT_ROOM_ID) {
+    res.status(400).json({ error: "Cannot delete the default room." });
+    return;
+  }
+  const room = getRoom(roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(roomId) });
+    return;
+  }
+
+  // Stop tick engine
+  stopTickEngine(roomId);
+
+  cleanupRoomLinks(roomId, room);
+
+  // Clean up agent memory entries before clearing participants
+  const expForDelete = getExperienceForRoom(room);
+  const expIdForDelete = expForDelete?.module?.manifest?.id || room.experienceId;
+  for (const [actorId] of room.participants) {
+    agentMemory.delete(`${expIdForDelete}:${actorId}`);
+  }
+
+  // Close all WebSocket connections for this room
+  for (const [ws] of room.wsConnections) {
+    try { ws.close(1001, "Room deleted"); } catch {}
+  }
+  room.wsConnections.clear();
+  room.participants.clear();
+
+  // Clean up blobs associated with this room
+  for (const [key, meta] of blobMeta) {
+    if (meta.roomId === roomId) {
+      blobStore.delete(key);
+      blobMeta.delete(key);
+    }
+  }
+
+  // Wake up any long-poll listeners waiting on this room
+  roomEvents.emit(`room:${roomId}`);
+
+  // Clean up event listeners, GC tracking, and room data
+  roomEvents.removeAllListeners(`room:${roomId}`);
+  rooms.delete(roomId);
+  roomBrowserErrors.delete(roomId);
+  lastBrowserErrorAt.delete(roomId);
+  spawnCounts.delete(roomId);
+  roomEmptySince.delete(roomId);
+
+  res.json({ deleted: true, roomId });
+});
+
+app.post("/rooms/:roomId/tools/:toolName", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  handleTool(room, req, res);
+});
+
+app.post("/rooms/:roomId/tools-batch", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  handleBatch(room, req, res);
+});
+
+// ── Stream endpoints (REST API for MCP agents) ──────────────
+
+function handleStreamRequest(room: Room, streamName: string, req: express.Request, res: express.Response): void {
+  const exp = getExperienceForRoom(room);
+  if (!exp?.module?.streams) {
+    res.status(404).json({ error: "No streams defined" });
+    return;
+  }
+
+  const streamDef = exp.module.streams.find((s: StreamDef) => s.name === streamName);
+  if (!streamDef) {
+    res.status(404).json({ error: `Stream '${streamName}' not found` });
+    return;
+  }
+
+  const { actorId, input } = req.body;
+
+  // Require actorId — anonymous stream writes are not allowed
+  if (!actorId) {
+    res.status(400).json({ error: "actorId is required for stream updates" });
+    return;
+  }
+
+  // Verify the caller is a participant
+  if (!room.participants.has(actorId)) {
+    res.status(403).json({ error: `Actor '${actorId}' is not a participant in room '${room.id}'. Call /join first.` });
+    return;
+  }
+
+  // Rate limiting
+  const rateLimitKey = `${room.id}:${actorId}:${streamName}`;
+  const now = Date.now();
+  const rateLimit = streamDef.rateLimit || DEFAULT_STREAM_RATE_LIMIT;
+  const windowMs = STREAM_RATE_WINDOW_MS;
+  if (!streamRateLimits.has(rateLimitKey)) {
+    streamRateLimits.set(rateLimitKey, { count: 0, windowStart: now });
+  }
+  const rl = streamRateLimits.get(rateLimitKey)!;
+  if (now - rl.windowStart > windowMs) {
+    rl.count = 0;
+    rl.windowStart = now;
+  }
+  if (rl.count >= rateLimit) {
+    res.status(429).json({ error: `Rate limited: max ${rateLimit} updates/sec for stream '${streamName}'. Try again shortly.` });
+    return;
+  }
+  rl.count++;
+
+  // Validate input
+  let validatedInput = input;
+  if (streamDef.input_schema?.parse) {
+    try {
+      validatedInput = streamDef.input_schema.parse(input);
+    } catch (err: unknown) {
+      res.status(400).json({ error: toErrorMessage(err) });
+      return;
+    }
+  }
+
+  // Execute merge
+  try {
+    room.sharedState = streamDef.merge(room.sharedState, validatedInput, actorId);
+  } catch (err: unknown) {
+    res.status(400).json({ error: toErrorMessage(err) });
+    return;
+  }
+
+  // Broadcast state update (no event log entry for streams, delta-compressed)
+  room.broadcastStateUpdate({
+    changedBy: actorId,
+    stream: streamName,
+  });
+  roomEvents.emit(`room:${room.id}`);
+
+  res.json({ ok: true });
+}
+
+app.post("/streams/:streamName", (req, res) => {
+  handleStreamRequest(getDefaultRoom(), req.params.streamName, req, res);
+});
+
+app.post("/rooms/:roomId/streams/:streamName", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  handleStreamRequest(room, req.params.streamName, req, res);
+});
+
+app.get("/rooms/:roomId/events", (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  handleEvents(room, req, res);
+});
+
+// ── Room-specific bundle (serves the correct experience's client bundle) ──
+app.get("/rooms/:roomId/bundle", async (req, res) => {
+  // Wait for any in-progress hot-reload to complete before serving
+  if (rebuildingPromise) await rebuildingPromise;
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  const loaded = getExperienceForRoom(room);
+  if (!loaded) {
+    res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+    return;
+  }
+  res.setHeader("Content-Type", "text/javascript");
+  setNoCacheHeaders(res);
+  res.send(loaded.clientBundle);
+});
+
+// ── Protocol experience HTML canvas ───────────────────────
+
+app.get("/rooms/:roomId/canvas", async (req, res) => {
+  const room = getRoom(req.params.roomId);
+  if (!room) {
+    res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    return;
+  }
+  const loaded = getExperienceForRoom(room);
+  if (!loaded) {
+    res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+    return;
+  }
+  const canvasPath = (loaded.module as any)?._canvasPath;
+  if (!canvasPath) {
+    res.status(404).json({ error: "This experience has no HTML canvas" });
+    return;
+  }
+  res.setHeader("Content-Type", "text/html");
+  setNoCacheHeaders(res);
+  res.sendFile(canvasPath);
+});
+
+// ── MCP config (for remote joiners) ───────────────────────
+
+app.get("/mcp-config", (_req, res) => {
+  const serverUrl = getBaseUrl();
+  res.json({
+    mcpServers: {
+      "vibevibes-remote": {
+        command: "npx",
+        args: ["-y", "@vibevibes/mcp@latest"],
+        env: {
+          VIBEVIBES_SERVER_URL: serverUrl,
+        },
+      },
+    },
+    instructions: [
+      `Add the above to your .mcp.json to join this room.`,
+      `Or run: npx @vibevibes/mcp@latest ${serverUrl}`,
+    ],
+  });
+});
+
+// ── Catch-all: serve viewer for path-based room routing (e.g. /room/room-abc123) ──
+// Must be AFTER all API routes so it doesn't shadow them.
+app.get("*", (req, res, next) => {
+  // Skip API-like paths and static assets
+  if (req.path.startsWith("/rooms/") || req.path.startsWith("/tools/") ||
+      req.path.startsWith("/viewer/") || req.path.startsWith("/blobs/") ||
+      req.path.startsWith("/streams/") || req.path.endsWith(".js") ||
+      req.path.endsWith(".css") || req.path.endsWith(".map")) {
+    next();
+    return;
+  }
+  // Serve the viewer — client-side JS will extract room ID from the path
+  setNoCacheHeaders(res);
+  res.sendFile(path.join(__runtimeDir, "viewer", "index.html"));
+});
+
+// ── Client bundle smoke test ──────────────────────────────────
+// Fetches the client bundle from the running server and tries to parse it.
+// Catches SyntaxErrors (like duplicate declarations) before the user sees them.
+
+async function smokeTestClientBundle(port: number): Promise<void> {
+  try {
+    const res = await fetch(`http://localhost:${port}/bundle`);
+    const bundleCode = await res.text();
+    if (bundleCode) {
+      const error = validateClientBundle(bundleCode);
+      if (error) {
+        console.error(`\n  ⚠ SMOKE TEST FAILED — client bundle has errors:`);
+        console.error(`    ${error}`);
+        console.error(`    The viewer will fail to load. Fix the source and save to hot-reload.\n`);
+      } else {
+        console.log(`  Smoke test: client bundle OK`);
+      }
+    }
+  } catch (err: unknown) {
+    console.error(`\n  ⚠ SMOKE TEST FAILED — client bundle has errors:`);
+    console.error(`    ${toErrorMessage(err)}`);
+    console.error(`    The viewer will fail to load. Fix the source and save to hot-reload.\n`);
+  }
+}
+
+// ── Start server ───────────────────────────────────────────
+
+export async function startServer(config?: ServerConfig): Promise<import("http").Server> {
+  // Apply config
+  if (config?.projectRoot) {
+    PROJECT_ROOT = config.projectRoot;
+  }
+  if (config?.port) {
+    PORT = config.port;
+  }
+  if (!PROJECT_ROOT) {
+    throw new Error("@vibevibes/runtime: projectRoot is required. Pass it via ServerConfig.");
+  }
+  await loadHost();
+
+  // Create default room (with default config + initial state from experience)
+  const hostExp = getHostExperience()!;
+  const defaultConfig = resolveRoomConfig(hostExp, undefined);
+  const hostInitialState = resolveInitialState(hostExp, defaultConfig);
+  const defaultRoom = new Room(DEFAULT_ROOM_ID, hostExperienceId, hostInitialState, defaultConfig);
+  rooms.set(DEFAULT_ROOM_ID, defaultRoom);
+
+
+  // Start tick engine for default room if host experience uses tick netcode
+  const hostLoaded = experienceCache.get(hostExperienceId);
+  if (hostLoaded) {
+    maybeStartTickEngine(defaultRoom, hostLoaded);
+  }
+
+  console.log(`  Experience: ${hostExperienceId}`);
+
+  const server = http.createServer(app);
+  const wss = new WebSocketServer({ server, maxPayload: WS_MAX_PAYLOAD_BYTES });
+  wss.on("error", (err) => { console.error("[WSS] server error:", err.message); });
+
+  // Grace period timers for WS close → participant deletion (allows page-refresh reconnects)
+  const wsCloseTimers = new Map<string, NodeJS.Timeout>();
+
+  wss.on("connection", (ws) => {
+    // Heartbeat: mark alive on connection and on pong
+    const hbWs = ws as HeartbeatWebSocket;
+    hbWs.isAlive = true;
+    ws.on("pong", () => { hbWs.isAlive = true; });
+    ws.on("error", (err) => { console.error("[WS] connection error:", (err as Error).message); });
+
+    ws.on("message", (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+
+        if (msg.type === "join") {
+          const username = (msg.username || "viewer").slice(0, 100);
+          const wsOwner: string = msg.owner || username;
+          const roomId = msg.roomId || DEFAULT_ROOM_ID;
+          const room = getRoom(roomId);
+          if (!room) {
+            ws.send(JSON.stringify({ type: "error", error: roomNotFoundError(roomId) }));
+            return;
+          }
+
+          // Reuse actorId if the viewer sends one back (e.g. on refresh)
+          let actorId: string;
+          if (msg.actorId) {
+            // Check kick status BEFORE evicting stale WS or reusing actorId
+            if (room.kickedActors.has(msg.actorId)) {
+              ws.send(JSON.stringify({ type: "error", error: "You have been kicked from this room." }));
+              return;
+            }
+            if (room.kickedOwners.has(wsOwner)) {
+              ws.send(JSON.stringify({ type: "error", error: "You have been kicked from this room." }));
+              return;
+            }
+
+            // Check if the old actorId is held by a stale WS (refresh scenario)
+            let staleWs: WebSocket | null = null;
+            for (const [existingWs, existingId] of room.wsConnections.entries()) {
+              if (existingId === msg.actorId && existingWs !== ws) {
+                staleWs = existingWs;
+                break;
+              }
+            }
+            if (staleWs) {
+              // Evict the stale connection
+              room.wsConnections.delete(staleWs);
+              try { staleWs.close(); } catch {}
+            }
+            // Cancel any pending close grace timer for this actorId
+            const closeTimer = wsCloseTimers.get(msg.actorId);
+            if (closeTimer) { clearTimeout(closeTimer); wsCloseTimers.delete(msg.actorId); }
+            // Re-add participant if it was deleted during grace window
+            if (!room.participants.has(msg.actorId)) {
+              room.participants.set(msg.actorId, { type: "human", joinedAt: Date.now(), owner: wsOwner });
+            }
+            // Reuse the old actorId
+            actorId = msg.actorId;
+          } else {
+            // Block kicked owners before burning an actorId counter slot
+            if (room.kickedOwners.has(wsOwner)) {
+              ws.send(JSON.stringify({ type: "error", error: "You have been kicked from this room." }));
+              return;
+            }
+
+            // Dedup by owner: reuse existing participant if same owner already joined (matches HTTP join logic)
+            let existingActorId: string | undefined;
+            for (const [aid, p] of room.participants) {
+              if (p.owner === wsOwner) { existingActorId = aid; break; }
+            }
+            if (existingActorId) {
+              actorId = existingActorId;
+              // Evict any stale WS for this actorId
+              for (const [existingWs, existingId] of room.wsConnections.entries()) {
+                if (existingId === existingActorId && existingWs !== ws) {
+                  room.wsConnections.delete(existingWs);
+                  try { existingWs.close(); } catch {}
+                  break;
+                }
+              }
+            } else {
+            // Match human join against participant slots (if defined)
+            const exp = getExperienceForRoom(room);
+            const pSlots: ParticipantSlot[] | undefined = exp?.module?.manifest?.participantSlots || exp?.module?.participants;
+            let wsSlotRole: string | undefined;
+
+            if (pSlots?.length) {
+              const roleOccupancy = new Map<string, number>();
+              for (const [, p] of room.participants) {
+                if (p.role) roleOccupancy.set(p.role, (roleOccupancy.get(p.role) || 0) + 1);
+              }
+              const hasCapacity = (slot: ParticipantSlot) => {
+                const max = slot.maxInstances ?? 1;
+                const current = roleOccupancy.get(slot.role) || 0;
+                return current < max;
+              };
+              // Match: requested role → type-specific → any
+              let matched: ParticipantSlot | undefined;
+              if (msg.role) {
+                matched = pSlots.find((s) =>
+                  s.role === msg.role && (!s.type || s.type === "human" || s.type === "any") && hasCapacity(s)
+                );
+              }
+              if (!matched) {
+                matched = pSlots.find((s) =>
+                  s.type === "human" && hasCapacity(s)
+                );
+              }
+              if (!matched) {
+                matched = pSlots.find((s) =>
+                  (!s.type || s.type === "any") && hasCapacity(s)
+                );
+              }
+              // Fallback: if all human-compatible slots are full, use first compatible
+              if (!matched) {
+                matched = pSlots.find((s) => !s.type || s.type === "human" || s.type === "any");
+              }
+              if (matched) {
+                wsSlotRole = matched.role;
+                const base = matched.role.toLowerCase().replace(/\s+/g, "-");
+                actorId = assignActorId(username, "human", base);
+              } else {
+                actorId = assignActorId(username, "human");
+              }
+            } else {
+              actorId = assignActorId(username, "human");
+            }
+            const wsRole = wsSlotRole || msg.role || undefined;
+            room.participants.set(actorId, { type: "human", joinedAt: Date.now(), owner: wsOwner, role: wsRole });
+            } // end: new actorId assignment block
+          }
+          // For reconnect case: if msg.actorId no longer has a participant entry
+          // (e.g., after room reset), reject the stale reconnect. Viewer must do a fresh join.
+          if (msg.actorId && !room.participants.has(msg.actorId)) {
+            ws.send(JSON.stringify({ type: "error", error: "Session expired. Please rejoin the room." }));
+            return;
+          }
+
+          // Track this WS → actorId in the room
+          room.wsConnections.set(ws, actorId);
+
+          // Resolve role from participant entry
+          const resolvedWsRole = room.participants.get(actorId)?.role;
+
+          // Send initial state (includes stateVersion for delta tracking)
+          ws.send(JSON.stringify({
+            type: "joined",
+            roomId: room.id,
+            actorId,
+            role: resolvedWsRole,
+            sharedState: room.sharedState,
+            stateVersion: room.stateVersion,
+            participants: room.participantList(),
+            participantDetails: room.participantDetails(),
+            events: room.events.slice(-JOIN_EVENT_HISTORY),
+            config: room.config,
+          }));
+
+          // Broadcast presence update to others in this room
+          broadcastPresenceUpdate(room);
+        }
+
+        if (msg.type === "ephemeral") {
+          // Relay ephemeral data to all OTHER clients in the same room.
+          // No validation, no persistence — this is the fast path for cursors,
+          // typing indicators, follow mode, and other high-frequency cosmetic data.
+          // Size guard: reject oversized payloads to prevent DoS amplification
+          const ephPayload = JSON.stringify(msg.data);
+          if (ephPayload.length > WS_EPHEMERAL_MAX_BYTES) {
+            ws.send(JSON.stringify({ type: "error", error: "Ephemeral payload too large (max 64KB)" }));
+            return;
+          }
+          for (const room of rooms.values()) {
+            const senderActorId = room.wsConnections.get(ws);
+            if (senderActorId) {
+              const payload = JSON.stringify({
+                type: "ephemeral",
+                actorId: senderActorId,
+                data: msg.data,
+              });
+              for (const [otherWs, otherId] of room.wsConnections.entries()) {
+                if (otherWs !== ws && otherWs.readyState === WebSocket.OPEN) {
+                  otherWs.send(payload);
+                }
+              }
+              break;
+            }
+          }
+        }
+
+        if (msg.type === "stream") {
+          // Validate stream name
+          if (typeof msg.name !== "string" || !msg.name) {
+            ws.send(JSON.stringify({ type: "stream_error", error: "stream.name must be a non-empty string" }));
+            return;
+          }
+          // High-frequency continuous state channel
+          // Find which room this WS belongs to
+          for (const room of rooms.values()) {
+            const senderActorId = room.wsConnections.get(ws);
+            if (!senderActorId) continue;
+
+            const exp = getExperienceForRoom(room);
+            if (!exp?.module?.streams) break;
+
+            const streamDef = exp.module.streams.find((s: StreamDef) => s.name === msg.name);
+            if (!streamDef) {
+              ws.send(JSON.stringify({ type: "stream_error", error: `Stream '${msg.name}' not found` }));
+              break;
+            }
+
+            // Rate limiting
+            const rateLimitKey = `${room.id}:${senderActorId}:${msg.name}`;
+            const now = Date.now();
+            const rateLimit = streamDef.rateLimit || DEFAULT_STREAM_RATE_LIMIT;
+            const windowMs = STREAM_RATE_WINDOW_MS;
+            if (!streamRateLimits.has(rateLimitKey)) {
+              streamRateLimits.set(rateLimitKey, { count: 0, windowStart: now });
+            }
+            const rl = streamRateLimits.get(rateLimitKey)!;
+            if (now - rl.windowStart > windowMs) {
+              rl.count = 0;
+              rl.windowStart = now;
+            }
+            if (rl.count >= rateLimit) {
+              ws.send(JSON.stringify({ type: "stream_error", error: `Rate limited: max ${rateLimit}/sec for '${msg.name}'` }));
+              break;
+            }
+            rl.count++;
+
+            // Validate input
+            let validatedInput = msg.input;
+            if (streamDef.input_schema?.parse) {
+              try {
+                validatedInput = streamDef.input_schema.parse(msg.input);
+              } catch (err: unknown) {
+                ws.send(JSON.stringify({ type: "stream_error", error: `Invalid input for stream '${msg.name}': ${toErrorMessage(err)}` }));
+                break;
+              }
+            }
+
+            // Execute merge
+            try {
+              room.sharedState = streamDef.merge(room.sharedState, validatedInput, senderActorId);
+            } catch (err: unknown) {
+              ws.send(JSON.stringify({ type: "stream_error", error: `Stream '${msg.name}' merge failed: ${toErrorMessage(err)}` }));
+              break;
+            }
+
+            // Broadcast state update (no event log entry for streams, delta-compressed)
+            room.broadcastStateUpdate({
+              changedBy: senderActorId,
+              stream: msg.name,
+            });
+            roomEvents.emit(`room:${room.id}`);
+
+            break;
+          }
+        }
+
+        if (msg.type === "kick") {
+          let found = false;
+          for (const room of rooms.values()) {
+            const kickerActorId = room.wsConnections.get(ws);
+            if (!kickerActorId) continue;
+            found = true;
+            const result = handleKick(room, kickerActorId, msg.targetActorId);
+            if (result.error) {
+              console.warn(`[kick] ${kickerActorId} failed to kick ${msg.targetActorId}: ${result.error}`);
+              ws.send(JSON.stringify({ type: "kick_error", error: result.error }));
+            } else {
+              ws.send(JSON.stringify({ type: "kick_success", actorId: msg.targetActorId }));
+            }
+            break;
+          }
+          if (!found) {
+            ws.send(JSON.stringify({ type: "kick_error", error: "You are not in any room" }));
+          }
+        }
+
+        if (msg.type === "screenshot_response") {
+          const pending = pendingScreenshots.get(msg.id);
+          if (pending && pending.viewerWs === ws) {
+            clearTimeout(pending.timer);
+            pendingScreenshots.delete(msg.id);
+
+            if (msg.error) {
+              pending.reject(new Error(msg.error));
+            } else if (msg.dataUrl) {
+              // Validate data URL format before decoding
+              if (typeof msg.dataUrl !== "string" || !msg.dataUrl.startsWith("data:image/png;base64,")) {
+                pending.reject(new Error("Invalid screenshot data URL format"));
+              } else {
+                const base64Data = msg.dataUrl.slice("data:image/png;base64,".length);
+                const buffer = Buffer.from(base64Data, "base64");
+                pending.resolve(buffer);
+              }
+            } else {
+              pending.reject(new Error("Empty screenshot response"));
+            }
+          }
+        }
+      } catch (err: unknown) {
+        // Log unexpected errors (not JSON parse failures) for debugging
+        if (!(err instanceof SyntaxError)) {
+          console.error("[WS] Unexpected handler error:", err instanceof Error ? err.message : String(err));
+        }
+      }
+    });
+
+    ws.on("close", () => {
+      // Clean up participant from whichever room this WS belongs to.
+      // Only delete human participants — AI agents join via HTTP and don't rely on WS for presence.
+      for (const room of rooms.values()) {
+        const actorId = room.wsConnections.get(ws);
+        if (actorId) {
+          room.wsConnections.delete(ws);
+          const participant = room.participants.get(actorId);
+          if (!participant || participant.type === "human") {
+            // Grace period: delay participant deletion to allow page refresh reconnects.
+            // If the same actorId reconnects within the grace period, the deletion is cancelled.
+            const timer = setTimeout(() => {
+              wsCloseTimers.delete(actorId);
+              // Only delete if no new WS reconnected for this actorId
+              let reconnected = false;
+              for (const [, wsActorId] of room.wsConnections) {
+                if (wsActorId === actorId) { reconnected = true; break; }
+              }
+              if (!reconnected) {
+                room.participants.delete(actorId);
+                broadcastPresenceUpdate(room);
+              }
+            }, WS_CLOSE_GRACE_MS);
+            // Cancel any previous timer for this actorId and store the new one
+            const prev = wsCloseTimers.get(actorId);
+            if (prev) clearTimeout(prev);
+            wsCloseTimers.set(actorId, timer);
+          }
+          break;
+        }
+      }
+    });
+  });
+
+  // ── WebSocket heartbeat interval ──────────────────────────
+  const heartbeatInterval = setInterval(() => {
+    for (const ws of wss.clients) {
+      if ((ws as HeartbeatWebSocket).isAlive === false) {
+        // Dead connection — clean up from rooms and terminate
+        for (const room of rooms.values()) {
+          const actorId = room.wsConnections.get(ws);
+          if (actorId) {
+            room.participants.delete(actorId);
+            room.wsConnections.delete(ws);
+            broadcastPresenceUpdate(room);
+            break;
+          }
+        }
+        ws.terminate();
+        continue;
+      }
+      (ws as HeartbeatWebSocket).isAlive = false;
+      ws.ping();
+    }
+  }, WS_HEARTBEAT_INTERVAL_MS);
+
+  // ── AI agent heartbeat sweep ──────────────────────────────
+  // Evict AI participants that haven't polled /agent-context within the timeout.
+  // This cleans up zombie agents after crashes, SIGKILLs, etc.
+  // 5 minutes — generous enough for Claude Code's turn model.
+  const AI_HEARTBEAT_TIMEOUT_MS = 300_000;
+  const aiHeartbeatInterval = setInterval(() => {
+    const now = Date.now();
+    for (const room of rooms.values()) {
+      const toEvict: string[] = [];
+      for (const [actorId, p] of room.participants) {
+        if (p.type !== "ai") continue;
+        // "behavior" agents run autonomously via tick engine — they never poll, so skip heartbeat eviction
+        if (p.agentMode === "behavior") continue;
+        const lastSeen = p.lastPollAt || p.joinedAt;
+        if (now - lastSeen > AI_HEARTBEAT_TIMEOUT_MS) toEvict.push(actorId);
+      }
+      for (const actorId of toEvict) {
+        room.participants.delete(actorId);
+        // Clean up memory entries keyed by this actorId
+        const exp = getExperienceForRoom(room);
+        const expId = exp?.module?.manifest?.id || room.experienceId;
+        agentMemory.delete(`${expId}:${actorId}`);
+      }
+      if (toEvict.length > 0) {
+        broadcastPresenceUpdate(room);
+        // Notify long-pollers that participants changed
+        roomEvents.emit(`room:${room.id}`);
+      }
+    }
+  }, WS_HEARTBEAT_INTERVAL_MS);
+
+  // ── Room garbage collection sweep ──────────────────────────
+  // Auto-delete spawned rooms that have been empty (zero participants) for over 5 minutes.
+  // The default "local" room is never deleted. Rooms with active WebSocket connections
+  // or recent participants are kept alive. This prevents zombie rooms from accumulating.
+  const ROOM_EMPTY_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+  const roomGcInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [roomId, room] of rooms) {
+      if (roomId === DEFAULT_ROOM_ID || room.preCreated) continue; // Never GC the default or pre-created rooms
+
+      if (room.participants.size === 0 && room.wsConnections.size === 0) {
+        // Room is empty — track when we first noticed
+        if (!roomEmptySince.has(roomId)) {
+          roomEmptySince.set(roomId, now);
+        }
+        const emptySince = roomEmptySince.get(roomId)!;
+        if (now - emptySince >= ROOM_EMPTY_TTL_MS) {
+          // TTL expired — garbage collect this room
+          console.log(`[GC] Deleting empty room '${roomId}' (empty for ${Math.round((now - emptySince) / 1000)}s)`);
+          stopTickEngine(roomId);
+          cleanupRoomLinks(roomId, room);
+
+          // Clean up memory entries only for actors that were in this room.
+          // Per-actor cleanup already happens during heartbeat eviction (line ~2846).
+          // Don't wildcard-delete all memory for the experience — other rooms
+          // running the same experience would lose their agents' memory.
+          const exp = getExperienceForRoom(room);
+          const expId = exp?.module?.manifest?.id || room.experienceId;
+          for (const [actorId] of room.participants) {
+            agentMemory.delete(`${expId}:${actorId}`);
+          }
+
+          // Clean up blobs associated with this room
+          for (const [key, meta] of blobMeta) {
+            if (meta.roomId === roomId) {
+              blobStore.delete(key);
+              blobMeta.delete(key);
+            }
+          }
+
+          // Wake any long-poll listeners before deletion, then clean up event emitter
+          roomEvents.emit(`room:${roomId}`);
+          roomEvents.removeAllListeners(`room:${roomId}`);
+
+          rooms.delete(roomId);
+          roomEmptySince.delete(roomId);
+          roomBrowserErrors.delete(roomId);
+          lastBrowserErrorAt.delete(roomId);
+          spawnCounts.delete(roomId);
+        }
+      } else {
+        // Room has participants — reset the empty timer
+        roomEmptySince.delete(roomId);
+      }
+    }
+  }, ROOM_GC_INTERVAL_MS);
+
+  // Watch src/ and experiences/ directories for changes (host experience only)
+  // Check both PROJECT_ROOT/experiences/ and PROJECT_ROOT/../experiences/ (top-level monorepo)
+  const watchDirs = [
+    path.join(PROJECT_ROOT, "src"),
+    path.join(PROJECT_ROOT, "experiences"),
+    path.resolve(PROJECT_ROOT, "..", "experiences"),
+  ].filter((d) => fs.existsSync(d));
+  let debounceTimer: NodeJS.Timeout | null = null;
+
+  function onSrcChange(filename?: string): void {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    // Signal that a rebuild is starting (so bundle endpoints can wait)
+    if (!rebuildingPromise) {
+      rebuildingPromise = new Promise<void>((resolve) => { rebuildingResolve = resolve; });
+    }
+    debounceTimer = setTimeout(async () => {
+      console.log(`\nFile changed${filename ? ` (${filename})` : ""}, rebuilding...`);
+
+      // Determine which experiences are affected by this file change
+      // Stop tick engines before reloading
+      for (const room of rooms.values()) {
+        stopTickEngine(room.id);
+      }
+
+      try {
+        // Reload the experience
+        await loadHost();
+        const reloaded = experienceCache.get(hostExperienceId);
+        for (const room of rooms.values()) {
+          room.broadcastToAll({ type: "experience_updated" });
+          if (reloaded) maybeStartTickEngine(room, reloaded);
+        }
+        smokeTestClientBundle(PORT);
+
+        console.log("Hot reload complete.");
+      } catch (err: unknown) {
+        experienceErrors.set(hostExperienceId, toErrorMessage(err));
+        console.error("Hot reload failed:", toErrorMessage(err));
+        // Restart tick engines with last-known-good experience so rooms don't stay frozen
+        const lastGood = experienceCache.get(hostExperienceId);
+        for (const room of rooms.values()) {
+          if (room.experienceId === hostExperienceId) {
+            room.broadcastToAll({ type: "build_error", error: toErrorMessage(err) });
+            if (lastGood) maybeStartTickEngine(room, lastGood);
+          }
+        }
+      } finally {
+        // Always resolve the rebuilding promise so bundle endpoints unblock
+        if (rebuildingResolve) { rebuildingResolve(); rebuildingResolve = null; rebuildingPromise = null; }
+      }
+    }, HOT_RELOAD_DEBOUNCE_MS);
+  }
+
+  for (const watchDir of watchDirs) {
+    try {
+      // recursive: true works on Windows and macOS
+      fs.watch(watchDir, { recursive: true }, (_event, filename) => {
+        if (filename && /\.(tsx?|jsx?|css|json)$/.test(filename)) {
+          // Resolve filename against watchDir (fs.watch gives paths relative to watched dir)
+          onSrcChange(path.join(path.relative(PROJECT_ROOT, watchDir), filename));
+        }
+      });
+    } catch {
+      // Fallback for Linux: watch individual directories
+      function watchDirRecursive(dir: string): void {
+        fs.watch(dir, (_event, filename) => {
+          if (filename && /\.(tsx?|jsx?|css|json)$/.test(filename)) {
+            onSrcChange(path.join(path.relative(PROJECT_ROOT, dir), filename));
+          }
+        });
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory()) watchDirRecursive(path.join(dir, entry.name));
+        }
+      }
+      watchDirRecursive(watchDir);
+    }
+  }
+
+  server.listen(PORT, async () => {
+    console.log(`\n  vibe-vibe local runtime`);
+    console.log(`  ───────────────────────`);
+    console.log(`  Viewer:  http://localhost:${PORT}`);
+
+    // Verify the client bundle can be parsed without errors
+    smokeTestClientBundle(PORT);
+    if (publicUrl) {
+      const shareUrl = getBaseUrl();
+      console.log(``);
+      console.log(`  ┌─────────────────────────────────────────────────┐`);
+      console.log(`  │  SHARE WITH FRIENDS:                            │`);
+      console.log(`  │                                                 │`);
+      console.log(`  │  ${shareUrl.padEnd(47)} │`);
+      console.log(`  │                                                 │`);
+      console.log(`  │  Open in browser to join the room.              │`);
+      console.log(`  │  AI: npx @vibevibes/mcp ${(shareUrl).padEnd(23)} │`);
+      console.log(`  └─────────────────────────────────────────────────┘`);
+    }
+    console.log(`\n  Watching src/ and experiences/ for changes\n`);
+  });
+
+  // Cleanup all intervals on server close
+  server.on("close", () => {
+    clearInterval(heartbeatInterval);
+    clearInterval(aiHeartbeatInterval);
+    clearInterval(roomGcInterval);
+    clearInterval(_streamRateCleanupTimer);
+    clearInterval(_spawnRateCleanupTimer);
+    clearInterval(_idempotencyCleanupTimer);
+  });
+
+  return server;
+}
+
+// Convenience: allow setting PROJECT_ROOT before startServer() is called
+// (e.g., for registry loading during setup).
+export function setProjectRoot(root: string): void {
+  PROJECT_ROOT = root;
+}