@pyric/cli 0.1.0-alpha.14 → 0.1.0-alpha.15

package/src/functions-rtdb/development-runtime.ts

@@ -0,0 +1,299 @@
+import type { ChildProcess } from 'node:child_process';
+import {
+  spawnFunctionsRtdbChild,
+  type FunctionsRtdbChildEvent,
+  type FunctionsRtdbChildHandle,
+  type FunctionsRtdbChildReady,
+  type SpawnFunctionsRtdbChildOptions,
+} from './child.js';
+import { buildChildEnv, createLinePrefixer } from '../cli/dev-runner.js';
+
+const INITIAL_PEER_TIMEOUT_MS = 30_000;
+const RELOAD_PEER_TIMEOUT_MS = 5_000;
+const PEER_POLL_INTERVAL_MS = 250;
+
+export interface FunctionsPeerReadiness {
+  wait(options: { timeoutMs: number; signal: AbortSignal }): Promise<boolean>;
+}
+
+export type FunctionsDevelopmentResult =
+  | { kind: 'ready'; ready: FunctionsRtdbChildReady }
+  | { kind: 'no-peer' }
+  | { kind: 'failed'; error: Error };
+
+export type FunctionsDevelopmentEvent =
+  | { type: 'child-event'; event: FunctionsRtdbChildEvent }
+  | { type: 'output'; stream: 'stdout' | 'stderr'; line: string }
+  | { type: 'unexpected-exit'; code: number };
+
+export interface FunctionsDevelopmentRuntime {
+  start(): Promise<FunctionsDevelopmentResult>;
+  reload(): Promise<FunctionsDevelopmentResult>;
+  close(): Promise<void>;
+}
+
+export interface FunctionsDevelopmentRuntimeOptions {
+  sourceDir: string;
+  entry: string;
+  baseEnv: NodeJS.ProcessEnv;
+  serveUrl: string;
+  registerUrl: string;
+  instance: string;
+  location: string;
+  childModuleUrl?: string | URL;
+  readiness: FunctionsPeerReadiness;
+  onEvent?(event: FunctionsDevelopmentEvent): void;
+  /** Internal test seam; production adapters use the real isolated child. */
+  spawn?(options: SpawnFunctionsRtdbChildOptions): FunctionsRtdbChildHandle;
+  initialPeerTimeoutMs?: number;
+  reloadPeerTimeoutMs?: number;
+}
+
+function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done(): void {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', done);
+      resolve();
+    }
+    signal.addEventListener('abort', done, { once: true });
+  });
+}
+
+function settleBeforeAbort<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      cleanup();
+      reject(signal.reason);
+    };
+    const cleanup = (): void => signal.removeEventListener('abort', onAbort);
+    signal.addEventListener('abort', onAbort, { once: true });
+    operation.then(
+      (value) => { cleanup(); resolve(value); },
+      (error) => { cleanup(); reject(error); },
+    );
+  });
+}
+
+export function createInProcessFunctionsPeerReadiness(
+  connected: () => boolean,
+  options: { intervalMs?: number; now?: () => number; sleep?: typeof abortableDelay } = {},
+): FunctionsPeerReadiness {
+  const intervalMs = options.intervalMs ?? PEER_POLL_INTERVAL_MS;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? abortableDelay;
+  return {
+    async wait({ timeoutMs, signal }) {
+      const deadline = now() + timeoutMs;
+      while (!signal.aborted) {
+        if (connected()) return true;
+        if (now() >= deadline) return false;
+        await sleep(intervalMs, signal);
+      }
+      return false;
+    },
+  };
+}
+
+export function createHttpFunctionsPeerReadiness(
+  serveUrl: string,
+  options: {
+    intervalMs?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    sleep?: typeof abortableDelay;
+  } = {},
+): FunctionsPeerReadiness {
+  const baseUrl = serveUrl.replace(/\/$/, '');
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const intervalMs = options.intervalMs ?? PEER_POLL_INTERVAL_MS;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? abortableDelay;
+  return {
+    async wait({ timeoutMs, signal }) {
+      const deadline = now() + timeoutMs;
+      const deadlineAbort = new AbortController();
+      const deadlineTimer = setTimeout(() => deadlineAbort.abort(), timeoutMs);
+      deadlineTimer.unref();
+      const waitSignal = AbortSignal.any([signal, deadlineAbort.signal]);
+      try {
+        while (!waitSignal.aborted) {
+          try {
+            const response = await settleBeforeAbort(
+              fetchImpl(`${baseUrl}/__pyric/health`, { signal: waitSignal }),
+              waitSignal,
+            );
+            if (response.ok) {
+              const health = await settleBeforeAbort(
+                response.json() as Promise<{ sandboxConnected?: boolean }>,
+                waitSignal,
+              );
+              if (health.sandboxConnected === true) return true;
+            }
+          } catch {
+            if (waitSignal.aborted) return false;
+          }
+          if (now() >= deadline) return false;
+          await sleep(intervalMs, waitSignal);
+        }
+        return false;
+      } finally {
+        clearTimeout(deadlineTimer);
+      }
+    },
+  };
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function attachOutput(
+  child: ChildProcess,
+  emit: (event: FunctionsDevelopmentEvent) => void,
+): void {
+  const attach = (stream: 'stdout' | 'stderr'): void => {
+    const readable = child[stream];
+    if (!readable) return;
+    const lines = createLinePrefixer('[functions] ', (line) => emit({ type: 'output', stream, line }));
+    readable.setEncoding('utf8');
+    readable.on('data', (chunk: string) => lines.push(chunk));
+    readable.once('end', () => lines.flush());
+  };
+  attach('stdout');
+  attach('stderr');
+}
+
+export function createFunctionsDevelopmentRuntime(
+  options: FunctionsDevelopmentRuntimeOptions,
+): FunctionsDevelopmentRuntime {
+  const spawn = options.spawn ?? spawnFunctionsRtdbChild;
+  const emit = (event: FunctionsDevelopmentEvent): void => options.onEvent?.(event);
+  const expectedStops = new WeakSet<FunctionsRtdbChildHandle>();
+  let activeChild: FunctionsRtdbChildHandle | null = null;
+  let activeWait: AbortController | null = null;
+  let closed = false;
+  let startPromise: Promise<FunctionsDevelopmentResult> | null = null;
+  let reloadPromise: Promise<FunctionsDevelopmentResult> | null = null;
+  let reloadQueued = false;
+  let closePromise: Promise<void> | null = null;
+
+  const stopChild = async (child: FunctionsRtdbChildHandle | null): Promise<void> => {
+    if (!child) return;
+    expectedStops.add(child);
+    if (activeChild === child) activeChild = null;
+    await child.stop().catch(() => undefined);
+  };
+
+  const launch = async (mode: 'initial' | 'reload'): Promise<FunctionsDevelopmentResult> => {
+    const controller = new AbortController();
+    activeWait = controller;
+    let connected: boolean;
+    try {
+      connected = await options.readiness.wait({
+        timeoutMs: mode === 'initial'
+          ? options.initialPeerTimeoutMs ?? INITIAL_PEER_TIMEOUT_MS
+          : options.reloadPeerTimeoutMs ?? RELOAD_PEER_TIMEOUT_MS,
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted || closed) return { kind: 'no-peer' };
+      return { kind: 'failed', error: asError(error) };
+    } finally {
+      if (activeWait === controller) activeWait = null;
+    }
+    if (!connected || closed) return { kind: 'no-peer' };
+
+    let handle: FunctionsRtdbChildHandle;
+    try {
+      handle = spawn({
+        cwd: options.sourceDir,
+        entry: options.entry,
+        env: buildChildEnv(options.baseEnv, {
+          serveUrl: options.serveUrl,
+          registerUrl: options.registerUrl,
+        }),
+        instance: options.instance,
+        location: options.location,
+        ...(options.childModuleUrl === undefined ? {} : { childModuleUrl: options.childModuleUrl }),
+        onEvent: (event) => emit({ type: 'child-event', event }),
+      });
+    } catch (error) {
+      return { kind: 'failed', error: asError(error) };
+    }
+
+    activeChild = handle;
+    attachOutput(handle.child, emit);
+    let readyReached = false;
+    let exitBeforeReady: number | null = null;
+    const reportUnexpectedExit = (code: number): void => {
+      if (activeChild === handle && !closed && !expectedStops.has(handle)) {
+        activeChild = null;
+        emit({ type: 'unexpected-exit', code });
+      }
+    };
+    void handle.exited.then((code) => {
+      if (!readyReached) exitBeforeReady = code;
+      else reportUnexpectedExit(code);
+    });
+    try {
+      const ready = await handle.ready;
+      readyReached = true;
+      if (exitBeforeReady !== null) reportUnexpectedExit(exitBeforeReady);
+      if (closed) {
+        await stopChild(handle);
+        return { kind: 'no-peer' };
+      }
+      return { kind: 'ready', ready };
+    } catch (error) {
+      await stopChild(handle);
+      return { kind: 'failed', error: asError(error) };
+    }
+  };
+
+  const runtime: FunctionsDevelopmentRuntime = {
+    start() {
+      startPromise ??= launch('initial');
+      return startPromise;
+    },
+    reload() {
+      if (closed) return Promise.resolve({ kind: 'failed', error: new Error('Functions runtime is closed') });
+      reloadQueued = true;
+      if (!reloadPromise) {
+        reloadPromise = (async (): Promise<FunctionsDevelopmentResult> => {
+          let result: FunctionsDevelopmentResult = { kind: 'no-peer' };
+          if (startPromise) await startPromise;
+          do {
+            reloadQueued = false;
+            await stopChild(activeChild);
+            if (closed) return { kind: 'no-peer' };
+            result = await launch('reload');
+          } while (reloadQueued && !closed);
+          return result;
+        })().finally(() => { reloadPromise = null; });
+      }
+      return reloadPromise as Promise<FunctionsDevelopmentResult>;
+    },
+    close() {
+      if (closePromise) return closePromise;
+      closePromise = (async () => {
+        closed = true;
+        reloadQueued = false;
+        activeWait?.abort();
+        await stopChild(activeChild);
+        await Promise.allSettled([
+          ...(startPromise ? [startPromise] : []),
+          ...(reloadPromise ? [reloadPromise] : []),
+        ]);
+        // A transition that crossed the closed check in the same turn may have
+        // installed a child after the first capture. The stop is idempotent.
+        await stopChild(activeChild);
+      })();
+      return closePromise;
+    },
+  };
+  return runtime;
+}

package/src/serve/bridge-mount.ts

@@ -16,7 +16,10 @@
  *   WS   /__pyric/sandbox   the in-page sandbox peer (server `upgrade`)
  */
 import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import { dirname, join } from 'node:path';
+import type { Duplex } from 'node:stream';
 import { WebSocketServer, type WebSocket } from 'ws';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createBridge, type BridgeToolEvent } from '../bridge/server/bridge.js';
@@ -48,10 +51,14 @@ export interface BridgeMount {
    *  The pointer writer records this so the proxy can verify it reached this
    *  exact server across a cross-family port collision. */
   readonly instanceId: string;
+  /** Canonical project identity used by health, audit, URLs, and discovery. */
+  readonly project: string;
   /** Namespace-handler tier: returns true when the request was handled. */
   handler(req: IncomingMessage, res: ServerResponse, url: URL): Promise<boolean>;
-  /** Attach the WS upgrade listener to the serve server. */
-  attachUpgrade(server: Server): void;
+  /** Attach all bridge-owned host resources and return their explicit owner. */
+  attachHost(options: BridgeHostOptions): BridgeHostAttachment;
+  /** Close every attachment, peer, and MCP session. Idempotent. */
+  close(): Promise<void>;
   /** Whether a sandbox peer (a browser tab / SharedWorker relay) is currently
    *  connected. In-process callers (the Vite plugin's Functions start) poll
    *  this instead of self-fetching `/__pyric/health`, which avoids a loopback
@@ -63,6 +70,29 @@ export interface BridgeMount {
   mcpUrl(origin: { host: string; port: number }): string;
 }
 
+export interface BridgeHostOptions {
+  /** Every server accepting upgrades (static serve may bind both IP families). */
+  servers: Server[];
+  /** Server whose listen/close lifecycle owns discovery publication. */
+  lifecycleServer?: Server;
+  projectDir: string;
+  /** Returns null until a stable, externally reachable origin is known. */
+  origin(): { host: string; port: number } | null;
+  /** Defaults true. A host with a broader ordered shutdown can opt out and
+   *  explicitly close the returned attachment from its own close listener. */
+  closeOnServerClose?: boolean;
+  /** Vite cannot dual-bind, so its adapter enables the cross-family probe. */
+  collision?: {
+    warn(message: string, options?: { timestamp?: boolean }): void;
+    /** Internal deterministic test seam. */
+    fetchImpl?: typeof fetch;
+  };
+}
+
+export interface BridgeHostAttachment {
+  close(): Promise<void>;
+}
+
 export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
   const project = opts.project ?? 'sandbox';
   const auditWriter = opts.disableAuditLog ? null : createAuditWriter(project);
@@ -87,19 +117,30 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
     close: () => Promise<void>;
     idle: ReturnType<typeof setTimeout> | null;
     sessionId: string | null;
+    closing: Promise<void> | null;
   };
   const sessions = new Map<string, Session>();
+  const pendingSessions = new Set<Session>();
+  const attachments = new Set<BridgeHostAttachment>();
+  let closed = false;
+  let closePromise: Promise<void> | null = null;
 
   const bumpIdle = (s: Session): void => {
     if (s.idle) clearTimeout(s.idle);
     s.idle = setTimeout(() => {
       if (s.sessionId) sessions.delete(s.sessionId);
+      pendingSessions.delete(s);
       void s.close();
     }, SESSION_IDLE_MS);
   };
 
   const newSession = async (): Promise<Session> => {
-    if (sessions.size >= MAX_SESSIONS) {
+    if (closed) {
+      const error = new Error('pyric bridge: mount is closed');
+      (error as { statusCode?: number }).statusCode = 503;
+      throw error;
+    }
+    if (sessions.size + pendingSessions.size >= MAX_SESSIONS) {
       const e = new Error(`pyric bridge: at session cap (${MAX_SESSIONS})`);
       (e as { statusCode?: number }).statusCode = 503;
       throw e;
@@ -109,34 +150,77 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
       close: async () => {},
       idle: null,
       sessionId: null,
+      closing: null,
     };
     session.transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),
       onsessioninitialized: (id) => {
+        if (closed) {
+          pendingSessions.delete(session);
+          void session.close();
+          return;
+        }
         session.sessionId = id;
         sessions.set(id, session);
+        pendingSessions.delete(session);
         bumpIdle(session);
       },
     });
     session.transport.onclose = () => {
       if (session.sessionId) sessions.delete(session.sessionId);
+      pendingSessions.delete(session);
     };
     const surface = getDefaultMcpToolSurface();
     const server = buildMcpServer(bridge, {
       forwarded: surface.forwarded,
       inProcess: surface.inProcess,
     });
-    session.close = async () => {
-      if (session.idle) clearTimeout(session.idle);
-      await server.close().catch(() => {});
-      await session.transport.close().catch(() => {});
+    session.close = () => {
+      session.closing ??= (async () => {
+        if (session.idle) clearTimeout(session.idle);
+        session.idle = null;
+        await server.close().catch(() => {});
+        await session.transport.close().catch(() => {});
+      })();
+      return session.closing;
     };
-    await server.connect(session.transport);
+    pendingSessions.add(session);
+    try {
+      await server.connect(session.transport);
+    } catch (error) {
+      pendingSessions.delete(session);
+      await session.close();
+      throw error;
+    }
     return session;
   };
 
-  return {
+  const closeSession = async (session: Session): Promise<void> => {
+    if (session.sessionId) sessions.delete(session.sessionId);
+    pendingSessions.delete(session);
+    await session.close();
+  };
+
+  const removeOwnedPointer = (pointer: string): void => {
+    try {
+      if (!existsSync(pointer)) return;
+      const current = JSON.parse(readFileSync(pointer, 'utf8')) as { instanceId?: string };
+      if (current.instanceId === bridge.instanceId) rmSync(pointer);
+    } catch {
+      // Best effort. A malformed or concurrently replaced pointer is not ours.
+    }
+  };
+
+  const mount: BridgeMount = {
+    project,
+    instanceId: bridge.instanceId,
+
     async handler(req, res, url) {
+      if (closed && (url.pathname === HEALTH_PATH || url.pathname === MCP_PATH)) {
+        res.writeHead(503, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'pyric bridge: mount is closed' }));
+        return true;
+      }
       if (url.pathname === HEALTH_PATH) {
         res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(bridge.health()));
         return true;
@@ -144,20 +228,38 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
       if (url.pathname === MCP_PATH) {
         try {
           const sessionId = (req.headers['mcp-session-id'] ?? req.headers['Mcp-Session-Id']) as string | undefined;
-          let session = sessionId ? sessions.get(sessionId) : undefined;
-          if (session) bumpIdle(session);
-          else session = await newSession();
+          let session: Session;
+          let created = false;
+          if (sessionId) {
+            const existing = sessions.get(sessionId);
+            if (!existing) {
+              res.writeHead(404, { 'content-type': 'application/json' });
+              res.end(JSON.stringify({ error: 'pyric bridge: MCP session not found' }));
+              return true;
+            }
+            session = existing;
+            bumpIdle(session);
+          } else {
+            session = await newSession();
+            created = true;
+          }
 
           if (req.method === 'DELETE' && sessionId) {
-            await session.close();
-            sessions.delete(sessionId);
+            await closeSession(session);
             res.writeHead(204).end();
             return true;
           }
           // The transport reads the raw request stream itself. Do NOT pre-parse
           // the body (the old `collectBody` path); a double read hangs the
           // initialize POST.
-          await session.transport.handleRequest(req, res);
+          try {
+            await session.transport.handleRequest(req, res);
+          } finally {
+            // A request without a session id is allowed to allocate only while
+            // it attempts initialization. Invalid/non-initialize traffic must
+            // not strand an uninitialized transport against the session cap.
+            if (created && session.sessionId === null) await closeSession(session);
+          }
         } catch (err) {
           const statusCode = (err as { statusCode?: number })?.statusCode ?? 500;
           if (!res.headersSent) {
@@ -169,10 +271,25 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
       }
       return false;
     },
-    attachUpgrade(server) {
+    attachHost({
+      servers,
+      lifecycleServer = servers[0],
+      projectDir,
+      origin,
+      collision,
+      closeOnServerClose = true,
+    }) {
+      if (closed) throw new Error('pyric bridge: cannot attach a closed mount');
       const wss = new WebSocketServer({ noServer: true });
       const guard = opts.upgradeGuard;
-      server.on('upgrade', (req, socket, head) => {
+      const pointer = join(projectDir, '.pyric', 'serve.json');
+      const upgradedSockets = new Set<Duplex>();
+      const collisionAbort = new AbortController();
+      let collisionProbe: Promise<void> | null = null;
+      let attachmentClosed = false;
+      let attachmentClosePromise: Promise<void> | null = null;
+
+      const onUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
         if ((req.url ?? '') !== WS_PATH) return;
         // DNS-rebinding + cross-origin hijack guard. The static/dev server runs
         // isAllowedHost on the `request` event only; `upgrade` is a separate
@@ -187,14 +304,131 @@ export function createBridgeMount(opts: BridgeMountOptions = {}): BridgeMount {
             return;
           }
         }
+        upgradedSockets.add(socket);
+        socket.once('close', () => upgradedSockets.delete(socket));
         wss.handleUpgrade(req, socket as never, head, (ws: WebSocket) => {
           attachPeer(bridge, ws);
         });
-      });
+      };
+
+      const publish = (): void => {
+        const currentOrigin = origin();
+        if (!currentOrigin?.port || attachmentClosed) return;
+        try {
+          mkdirSync(dirname(pointer), { recursive: true });
+          writeFileSync(pointer, JSON.stringify({
+            url: `http://${currentOrigin.host}:${currentOrigin.port}`,
+            mcpUrl: mount.mcpUrl(currentOrigin),
+            port: currentOrigin.port,
+            pid: process.pid,
+            instanceId: bridge.instanceId,
+            project,
+          }, null, 2) + '\n');
+        } catch {
+          // Discovery falls back to a port scan.
+        }
+      };
+
+      const probeCollision = async (): Promise<void> => {
+        const currentOrigin = origin();
+        if (!collision || !currentOrigin?.port || attachmentClosed) return;
+        for (const probe of [`http://127.0.0.1:${currentOrigin.port}`, `http://[::1]:${currentOrigin.port}`]) {
+          try {
+            const response = await (collision.fetchImpl ?? fetch)(`${probe}${HEALTH_PATH}`, {
+              signal: AbortSignal.any([collisionAbort.signal, AbortSignal.timeout(1000)]),
+            });
+            if (attachmentClosed) return;
+            if (response.status !== 200) continue;
+            const body = (await response.json()) as { mode?: string; instanceId?: string };
+            if (attachmentClosed) return;
+            if (body.mode === 'sandbox' && body.instanceId && body.instanceId !== bridge.instanceId) {
+              collision.warn(
+                `\n⚠  pyric: another sandbox already serves port ${currentOrigin.port} on a different loopback ` +
+                  `family (${probe}). Two dev servers are colliding across IPv4/IPv6 — your MCP ` +
+                  `agent and browser can land on DIFFERENT sandboxes (writes seem to vanish). ` +
+                  `Stop the other server, or give this app a unique \`server.port\` so the two ` +
+                  `don't share one (pinning server.host to a family the squatter holds would ` +
+                  `just EADDRINUSE).\n`,
+                { timestamp: true },
+              );
+              return;
+            }
+          } catch {
+            if (attachmentClosed) return;
+            // The other loopback family is silent.
+          }
+        }
+      };
+
+      const announce = (): void => {
+        publish();
+        if (!collisionProbe) {
+          const current = probeCollision();
+          collisionProbe = current;
+          void current.finally(() => {
+            if (collisionProbe === current) collisionProbe = null;
+          });
+        }
+      };
+      const attachment: BridgeHostAttachment = {
+        close(): Promise<void> {
+          if (attachmentClosePromise) return attachmentClosePromise;
+          attachmentClosePromise = (async () => {
+            attachmentClosed = true;
+            collisionAbort.abort();
+            for (const server of servers) server.removeListener('upgrade', onUpgrade as never);
+            lifecycleServer?.removeListener('listening', announce);
+            lifecycleServer?.removeListener('close', onClose);
+            await collisionProbe;
+            removeOwnedPointer(pointer);
+            for (const client of wss.clients) client.terminate();
+            for (const socket of upgradedSockets) socket.destroy();
+            upgradedSockets.clear();
+            await new Promise<void>((resolve) => {
+              let settled = false;
+              const done = (): void => {
+                if (settled) return;
+                settled = true;
+                clearTimeout(fallback);
+                resolve();
+              };
+              // `noServer` owns no listener socket. Once upgrades are detached
+              // and clients are terminated, a missing ws `close` callback must
+              // not deadlock the host's ordered shutdown.
+              const fallback = setTimeout(done, 500);
+              fallback.unref();
+              try {
+                wss.close(done);
+              } catch {
+                done();
+              }
+            });
+            attachments.delete(attachment);
+          })();
+          return attachmentClosePromise;
+        },
+      };
+      const onClose = (): void => { void attachment.close(); };
+
+      for (const server of servers) server.on('upgrade', onUpgrade as never);
+      if (closeOnServerClose) lifecycleServer?.once('close', onClose);
+      if ((lifecycleServer as unknown as { listening?: boolean } | undefined)?.listening) announce();
+      else lifecycleServer?.once('listening', announce);
+      attachments.add(attachment);
+      return attachment;
     },
     sandboxConnected: () => bridge.health().sandboxConnected === true,
-    instanceId: bridge.instanceId,
     wsUrl: ({ host, port }) => `ws://${host}:${port}${WS_PATH}`,
     mcpUrl: ({ host, port }) => `http://${host}:${port}${MCP_PATH}`,
+    close(): Promise<void> {
+      if (closePromise) return closePromise;
+      closePromise = (async () => {
+        closed = true;
+        await Promise.all([...attachments].map((attachment) => attachment.close()));
+        await Promise.all([...new Set([...sessions.values(), ...pendingSessions])].map(closeSession));
+      })();
+      return closePromise;
+    },
   };
+  return mount;
 }