@pyric/cli 0.1.0-alpha.30.2 → 0.1.0-alpha.31

package/src/bounded-request.ts

@@ -10,11 +10,13 @@
  * socket in any state. `req.setTimeout()` is no substitute: it does not arm
  * until the `connect` event.
  *
- * Discovery's health probes and the register beacon both go through
- * {@link boundedRequest}. The http modules load on first use, so a runtime
+ * Discovery's health probes and the register beacon go through
+ * {@link boundedRequest}; the CLI's other local probes (snapshot, serve
+ * diagnostics, the sandbox peer wait, the collision probe) go through its
+ * fetch-shaped {@link boundedFetch} (#1167). The http modules load on first use, so a runtime
  * without them loses the request only, never the importing module.
  */
-import type { IncomingMessage, OutgoingHttpHeaders, request as httpRequestFn } from 'node:http';
+import type { IncomingHttpHeaders, IncomingMessage, OutgoingHttpHeaders, request as httpRequestFn } from 'node:http';
 import { createRequire } from 'node:module';
 
 /** The most response body a bounded request reads. Past it, the request gives up. */
@@ -33,10 +35,15 @@ export interface BoundedRequestOptions {
    * deadline still ends it.
    */
   readonly unref?: boolean;
+  /** The most response body to read. Past it, the request gives up. Defaults to {@link MAX_RESPONSE_BYTES}. */
+  readonly maxBytes?: number;
+  /** Ends the request early, as the deadline would. */
+  readonly signal?: AbortSignal;
 }
 
 export interface BoundedResponse {
   readonly status: number;
+  readonly headers: IncomingHttpHeaders;
   readonly body: Buffer;
 }
 
@@ -73,13 +80,18 @@ function readBody(res: IncomingMessage, maxBytes: number): Promise<Buffer | null
 /**
  * Send one request to `url` and read its response, all within
  * `options.deadlineMs` of the call. `null` for a refused or dropped connect,
- * an error, a body past {@link MAX_RESPONSE_BYTES}, a url the http module
- * rejects, or the deadline passing. Never rejects. Redirects are not followed:
+ * an error, a body past `options.maxBytes`, a url the http module rejects, an
+ * aborted `options.signal`, or the deadline passing. Never rejects. Redirects are not followed:
  * a 3xx is returned as its own status. No agent is used, and the socket is
  * destroyed when the result settles, so nothing outlives the call.
  */
 export function boundedRequest(url: string, options: BoundedRequestOptions): Promise<BoundedResponse | null> {
   return new Promise((resolve) => {
+    const signal = options.signal;
+    if (signal?.aborted) {
+      resolve(null);
+      return;
+    }
     let req: ReturnType<RequestFn>;
     try {
       // No agent: a pooled keep-alive socket would outlive the call.
@@ -93,10 +105,13 @@ export function boundedRequest(url: string, options: BoundedRequestOptions): Pro
       if (settled) return;
       settled = true;
       clearTimeout(deadline);
+      signal?.removeEventListener('abort', onAbort);
       req.destroy();
       resolve(result);
     };
     const deadline = setTimeout(() => finish(null), options.deadlineMs);
+    const onAbort = (): void => finish(null);
+    signal?.addEventListener('abort', onAbort, { once: true });
     if (options.unref) {
       deadline.unref();
       req.on('socket', (socket) => socket.unref());
@@ -104,9 +119,9 @@ export function boundedRequest(url: string, options: BoundedRequestOptions): Pro
     req.on('error', () => finish(null));
     req.on('response', (res: IncomingMessage) => {
       res.on('error', () => finish(null));
-      void readBody(res, MAX_RESPONSE_BYTES).then((body) => {
+      void readBody(res, options.maxBytes ?? MAX_RESPONSE_BYTES).then((body) => {
         const hasBody = body !== null;
-        finish(hasBody ? { status: res.statusCode ?? 0, body } : null);
+        finish(hasBody ? { status: res.statusCode ?? 0, headers: res.headers, body } : null);
       });
     });
     req.end(options.body);
@@ -133,3 +148,47 @@ export async function getJsonWithin(url: string, deadlineMs: number): Promise<Js
     return null;
   }
 }
+
+/** Options for {@link boundedFetch}: a bounded request plus fetch's redirect mode. */
+export interface BoundedFetchOptions extends BoundedRequestOptions {
+  /**
+   * Redirects are never followed. `'error'` rejects on a 3xx, as fetch does;
+   * `'manual'`, the default, returns it.
+   */
+  readonly redirect?: 'error' | 'manual';
+}
+
+/** Statuses whose `Response` must have a null body. */
+const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304]);
+
+function headersOf(incoming: IncomingHttpHeaders): Headers {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(incoming)) {
+    const values = Array.isArray(value) ? value : [value];
+    for (const one of values) {
+      const isPresent = one !== undefined;
+      if (isPresent) headers.append(name, one);
+    }
+  }
+  return headers;
+}
+
+/**
+ * {@link boundedRequest} in fetch's shape, for code written against `fetch`
+ * and its injectable `fetchImpl` seams. Resolves a `Response` whose body is
+ * already read, and rejects with a `TypeError` where `boundedRequest` gives
+ * `null`, as `fetch` rejects on a network error or an abort.
+ */
+export async function boundedFetch(input: string | URL, options: BoundedFetchOptions): Promise<Response> {
+  const url = String(input);
+  const response = await boundedRequest(url, options);
+  if (response === null) throw new TypeError(`fetch failed: ${url}`);
+  const { status } = response;
+  const isRedirect = status >= 300 && status < 400;
+  const refusesRedirect = isRedirect && options.redirect === 'error';
+  if (refusesRedirect) throw new TypeError(`fetch failed: ${url} redirected`);
+  const isConstructible = status >= 200 && status <= 599;
+  if (!isConstructible) throw new TypeError(`fetch failed: ${url} answered ${status}`);
+  const body = NULL_BODY_STATUSES.has(status) ? null : new Uint8Array(response.body);
+  return new Response(body, { status, headers: headersOf(response.headers) });
+}

package/src/bridge/client/bridge-url.ts

@@ -1,6 +1,10 @@
 import { DEFAULT_BRIDGE_PORT, DEFAULT_SANDBOX_PATH } from '../protocol.js';
 
-/** Explicit URL, Vite injection, then the sidecar on the page's hostname. */
+/**
+ * Explicit URL, then `window.__PYRIC_BRIDGE_URL__` when the page sets it (no
+ * pyric integration does), then the standalone `pyric bridge` port on the
+ * page's hostname, which refuses a browser page with a reason (#1468).
+ */
 export function resolveBridgeUrl(explicit?: string): string {
   const hasExplicitUrl = explicit !== undefined && explicit.length > 0;
   if (hasExplicitUrl) return explicit;

package/src/bridge/client/bridge.ts

@@ -7,8 +7,13 @@
  *
  * Discovery order for the bridge URL:
  *   1. Explicit `opts.url`.
- *   2. `window.__PYRIC_BRIDGE_URL__` (set by the Vite plugin).
- *   3. `ws://${location.hostname}:5174/sandbox` (sidecar default).
+ *   2. `window.__PYRIC_BRIDGE_URL__`, when the page sets it. No pyric
+ *      integration sets it: the Vite plugin, `withPyric` and the served entry
+ *      mount their own bridge and hand its URL to their own runtime.
+ *   3. `ws://${location.hostname}:5174/sandbox`, the standalone `pyric bridge`
+ *      port. That bridge has no browser socket (#1468): it closes the page
+ *      with NO_BROWSER_PEER_CLOSE_CODE, and this client stops there with a
+ *      reason that names `pyric sandbox --bridge`.
  *
  * Reconnect strategy: simple exponential backoff up to 30s. The
  * connection is best-effort — if the bridge is down the host app
@@ -42,6 +47,7 @@ import {
   isBridgeMessage,
   MAX_BRIDGE_FRAME_BYTES,
   assertJsonSafeRelayValue,
+  NO_BROWSER_PEER_CLOSE_CODE,
   PEER_REPLACED_CLOSE_CODE,
   WORKER_RELAY_CAPABILITY,
 } from '../protocol.js';
@@ -58,7 +64,8 @@ const utf8 = new TextEncoder();
 export interface ConnectBridgeOptions {
   /**
    * Bridge WebSocket URL. Overrides the discovery chain.
-   * Example: `ws://localhost:5174/sandbox`.
+   * Example: `ws://localhost:3473/__pyric/sandbox`, the socket
+   * `pyric sandbox --bridge` serves.
    */
   url?: string;
   /**
@@ -367,6 +374,15 @@ export function connectBridge(
       // and re-issues it after the next hello, so live worker listeners from
       // THIS connection must go now (or the next connection double-delivers).
       teardownRelaySubs();
+      const hasNoBrowserSocket = event.code === NO_BROWSER_PEER_CLOSE_CODE;
+      if (hasNoBrowserSocket) {
+        // The standalone `pyric bridge` takes no browser peer. Reconnecting
+        // can never succeed, so stop and say what to run instead.
+        closed = true;
+        console.error(`[pyric] ${reason}`);
+        setState({ kind: 'disconnected', reason });
+        return;
+      }
       const isReplacedByPeer = event.code === PEER_REPLACED_CLOSE_CODE;
       if (isReplacedByPeer) {
         // Another tab won the peer slot. Re-helloing now would kick it right

package/src/bridge/frame-output.ts

@@ -93,8 +93,53 @@ export function failBridgeResponse(frame: BridgeMessage, error: FrameError): Bri
   }
 }
 
+const RTDB_WRITE_FIELDS = ['value', 'values', 'priority'] as const;
+
+function childPath(path: string, key: string): string {
+  return path.endsWith('/') ? `${path}${key}` : `${path}/${key}`;
+}
+
+/** Where `value` holds something JSON drops or turns into null, and what it is. */
+function findJsonLoss(value: unknown, path: string): { path: string; found: string } | undefined {
+  const isLost = value === undefined || (typeof value === 'number' && !Number.isFinite(value));
+  if (isLost) return { path, found: String(value) };
+  const isLeaf = typeof value !== 'object' || value === null;
+  if (isLeaf) return;
+  for (const [key, child] of Object.entries(value)) {
+    const loss = findJsonLoss(child, childPath(path, key));
+    if (loss !== undefined) return loss;
+  }
+}
+
+/**
+ * Refuse an RTDB write whose value JSON cannot carry. NaN and Infinity encode
+ * as null and an undefined member vanishes, so the host would store a delete
+ * (RP-1, #1362). The served client refuses these first with the SDK's text;
+ * this is the second line.
+ */
+function assertJsonSafeRtdbWrite(frame: BridgeMessage): void {
+  const isOtherFrame = frame.type !== 'worker-message';
+  if (isOtherFrame) return;
+  const message = frame.message;
+  const isRtdbOperation = message.t === 'op' && message.method.startsWith('rtdb.');
+  if (!isRtdbOperation) return;
+  const fields: Record<string, unknown> = { ...message };
+  const path = typeof fields.path === 'string' ? fields.path : '/';
+  for (const field of RTDB_WRITE_FIELDS) {
+    const isAbsent = !Object.hasOwn(fields, field);
+    if (isAbsent) continue;
+    const loss = findJsonLoss(fields[field], path);
+    const isJsonSafe = loss === undefined;
+    if (isJsonSafe) continue;
+    throw new Error(
+      `RTDB ${message.method} ${field} at ${loss.path} holds ${loss.found}, which a JSON frame cannot carry. The write was not sent.`,
+    );
+  }
+}
+
 /** Encode bounded output, retaining correlation when an oversized result can be refused. */
 export function encodeBridgeMessage(frame: BridgeMessage): string | undefined {
+  assertJsonSafeRtdbWrite(frame);
   const payload = JSON.stringify(frame);
   const fitsFrameLimit = utf8.encode(payload).byteLength <= MAX_BRIDGE_FRAME_BYTES;
   if (fitsFrameLimit) return payload;

package/src/bridge/protocol.ts

@@ -84,6 +84,19 @@ export const PEER_REPLACED_CLOSE_CODE = 4001;
 /** Human-readable reason sent with {@link PEER_REPLACED_CLOSE_CODE}. */
 export const PEER_REPLACED_CLOSE_REASON = 'replaced by a newer sandbox peer';
 
+/**
+ * WS close code the standalone `pyric bridge` sends a page that opens its
+ * `/sandbox` socket. That bridge has no browser peer (#1468): the page is
+ * closed before it can register, and `connectBridge` stops instead of
+ * reconnecting. A page that needs a browser bridge runs under
+ * `pyric sandbox --bridge`, which serves the page and guards its socket.
+ */
+export const NO_BROWSER_PEER_CLOSE_CODE = 4010;
+
+/** Reason sent with {@link NO_BROWSER_PEER_CLOSE_CODE}; a close frame carries at most 123 bytes. */
+export const NO_BROWSER_PEER_CLOSE_REASON =
+  'pyric bridge does not accept a browser sandbox. Run pyric sandbox --bridge, which serves the page and its bridge.';
+
 // ── Bridge ↔ browser WebSocket protocol ──────────────────────────────
 //
 // All messages are JSON. Each message has a `type` discriminator.

package/src/bridge/server/in-process.ts

@@ -53,6 +53,14 @@ import {
 import type { BridgeToolEvent } from './bridge.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { claimProjectState } from '../../serve/hosted/project-ownership.js';
+import {
+  firestoreDatabaseWarnings,
+  firestoreDatabases,
+  prepareStorageRulesSource,
+  storageRulesPath,
+} from '../../serve/rules.js';
+import { readFirebaseRcSync, type FirebaseJson } from '../../cli/firebase-json.js';
+import { defaultFirestoreDatabase } from 'pyric/sandbox/internal';
 import { TargetRouter } from './target-router.js';
 import type { discoverServe } from '../../serve/discovery.js';
 import type { callHostedMethod } from '../../cli/hosted-method.js';
@@ -156,17 +164,44 @@ export interface ProjectRulesLoad {
   refused: string | null;
 }
 
+function readProjectFirebaseJson(cwd: string): FirebaseJson | null {
+  const path = join(cwd, 'firebase.json');
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as FirebaseJson;
+  } catch (error) {
+    throw new Error(`pyric: failed to parse firebase.json: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 /**
- * Load `<cwd>/firestore.rules` into the sandbox when present. A file
- * production would not load (it does not parse, or it is past a compile
- * limit) is refused: the rules in force stay, and lint and simulate read the
- * file's source. Null when there is no rules file. Without rules,
- * rules-enforcing (`as:{uid}`) ops fall back to the sandbox's default; admin
- * ops are unaffected.
+ * Load the rules `<cwd>/firebase.json` deploys to the `(default)` Firestore
+ * database, resolved as the dev server resolves them, else
+ * `<cwd>/firestore.rules` when `firebase.json` names none. A file production
+ * would not load (it does not parse, or it is past a compile limit) is
+ * refused: the rules in force stay, and lint and simulate read the file's
+ * source. Null when there is no rules file. Without rules, rules-enforcing
+ * (`as:{uid}`) ops fall back to the sandbox's default; admin ops are
+ * unaffected. `onWarning` receives one line per named database or unresolved
+ * deploy target pyric does not serve yet, and one for a named file that is
+ * missing.
  */
-export function loadProjectRules(sandbox: LocalSandbox, cwd: string): ProjectRulesLoad | null {
-  const path = join(cwd, 'firestore.rules');
-  if (!existsSync(path)) return null;
+export function loadProjectRules(
+  sandbox: LocalSandbox,
+  cwd: string,
+  onWarning: (message: string) => void = () => {},
+): ProjectRulesLoad | null {
+  const config = readProjectFirebaseJson(cwd);
+  const projectId = readFirebaseRcSync(cwd)?.projects?.default;
+  const databases = firestoreDatabases(cwd, config, projectId === undefined ? {} : { projectId });
+  for (const warning of firestoreDatabaseWarnings(cwd, databases)) onWarning(warning);
+  const entry = defaultFirestoreDatabase(databases);
+  const path = entry?.rulesFile;
+  if (entry === undefined || path === undefined) return null;
+  if (!existsSync(path)) {
+    if (entry.configured) onWarning(`${entry.label} points Firestore rules at ${path}, but it does not exist.`);
+    return null;
+  }
   return { path, refused: loadFirestoreRules(sandbox, readFileSync(path, 'utf8')) };
 }
 
@@ -179,23 +214,28 @@ export function loadProjectRules(sandbox: LocalSandbox, cwd: string): ProjectRul
  * a restored session complete. Returns the storage handle, which the sidecar
  * codec reads and writes; storage keeps its own durability and is not in the
  * bundle at all.
+ *
+ * Storage enforces the rules file the project deploys, found and prepared as
+ * the dev server finds and prepares it: the first `firebase.json` `storage`
+ * entry with a `rules` path, else `storage.rules` in `cwd`, with `2+modules`
+ * imports resolved against the file's own directory.
  */
 export function openPersistedServices(sandbox: LocalSandbox, cwd: string): FirebaseStorage {
   getAuth(sandbox);
   getAdminDatabase(sandbox);
   // Storage rules are read only by the call that opens the service, so the
   // project's rules have to be in hand here or not at all.
-  const rulesPath = join(cwd, 'storage.rules');
+  const rulesPath = storageRulesPath(cwd, readProjectFirebaseJson(cwd));
   if (!existsSync(rulesPath)) return getAdminStorageSandbox(sandbox);
   const source = readFileSync(rulesPath, 'utf8');
   try {
-    return getAdminStorageSandbox(sandbox, { rules: source });
+    return getAdminStorageSandbox(sandbox, { rules: prepareStorageRulesSource(source, rulesPath) });
   } catch (error) {
-    // A rules file that does not parse cannot govern the service, but a lint
-    // call must still be able to say what is wrong with it. The service opens
-    // without rules and the source is kept for the lint operation.
+    // A rules file the sandbox cannot install cannot govern the service, but a
+    // lint call must still be able to say what is wrong with it. The service
+    // opens without rules and the source is kept for the lint operation.
     process.stderr.write(
-      `[pyric mcp in-process] storage.rules not loaded: ${error instanceof Error ? error.message : String(error)}\n`,
+      `[pyric mcp in-process] Storage rules not loaded: ${error instanceof Error ? error.message : String(error)}\n`,
     );
     rememberUnloadedStorageRules(sandbox, source);
     return getAdminStorageSandbox(sandbox);
@@ -389,13 +429,13 @@ async function runInProcessSession(
   }
   // After the snapshot: restoring it resets the ruleset to the sandbox default,
   // and the project's rules file is the authority for what the server enforces.
-  const projectRules = loadProjectRules(sandbox, projectDir);
+  const projectRules = loadProjectRules(sandbox, projectDir, log);
   if (projectRules !== null && projectRules.refused === null) {
     log(`rules loaded from ${projectRules.path}`);
   } else if (projectRules !== null) {
     log(`rules not loaded from ${projectRules.path}: ${projectRules.refused} The sandbox keeps the rules in force.`);
   } else {
-    log(`no firestore.rules found in ${projectDir}`);
+    log(`no Firestore rules for (default) found in ${projectDir}`);
   }
   const restoredObjects = await loadStorageSidecar(storage, projectDir);
   const restoredStorage = restoredObjects > 0;

package/src/bridge/server/peer.ts

@@ -449,6 +449,17 @@ export function createConsumerSession(
  *  code lets a route answer 413 instead of treating it as malformed JSON. */
 export const BODY_TOO_LARGE_CODE = 'PYRIC_BODY_TOO_LARGE';
 
+/**
+ * Headers for an answer sent before the request body was read to its end,
+ * as a 413 is. The server is still owed the rest of the upload, so a client
+ * that reuses the socket would have its next request read as that remainder
+ * and answered 400 (#1706). Closing the connection sends the next request on
+ * a fresh one (RFC 9112 §9.6).
+ */
+export function closingHeaders(headers: Record<string, string> = {}): Record<string, string> {
+  return { ...headers, connection: 'close' };
+}
+
 function bodyTooLarge(): Error {
   return Object.assign(new Error('request body too large'), { code: BODY_TOO_LARGE_CODE });
 }

package/src/bridge/server/standalone.ts

@@ -1,10 +1,15 @@
 /**
  * Standalone bridge server. Spins up an HTTP server on a known
- * loopback port that handles three routes:
+ * loopback port that handles two routes:
  *
  *   GET  /health           — diagnostic
  *   POST /mcp              — MCP-over-HTTP (StreamableHTTPServerTransport)
- *   GET  /sandbox (Upgrade) — WebSocket the browser tab connects to
+ *
+ * It serves only the tools that run in the bridge process. It has no browser
+ * socket (#1468): a page that opens `/sandbox` is closed with
+ * NO_BROWSER_PEER_CLOSE_CODE and a reason naming `pyric sandbox --bridge`,
+ * before it can register as the sandbox peer. `connectBridge` stops on that
+ * close and reports the reason.
  *
  * Bound to 127.0.0.1 only. Refuses to start if the port is occupied.
  *
@@ -16,7 +21,7 @@
 
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
-import { WebSocketServer, WebSocket } from 'ws';
+import { WebSocketServer } from 'ws';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createBridge, type Bridge, type BridgeToolEvent } from './bridge.js';
 import { buildMcpServer } from './mcp.js';
@@ -29,16 +34,15 @@ import {
 } from './logger.js';
 import {
   DEFAULT_BRIDGE_PORT,
-  MAX_BRIDGE_FRAME_BYTES,
   DEFAULT_HEALTH_PATH,
   DEFAULT_MCP_PATH,
   DEFAULT_SANDBOX_PATH,
-  type BridgeMessage,
+  NO_BROWSER_PEER_CLOSE_CODE,
+  NO_BROWSER_PEER_CLOSE_REASON,
 } from '../protocol.js';
-import { parseBridgeMessage, requestEnvelopeError, requestProtocolError } from './request-envelope.js';
-import { sendBridgeMessage } from './socket-message.js';
 import { pyricVersion } from '../../serve/standalone-assets.js';
 import { isAllowedLoopbackRequest, isAllowedUpgrade } from '../../serve/server.js';
+import { createAppPorts } from '../../serve/app-ports.js';
 
 const BRIDGE_VERSION = pyricVersion();
 const DEFAULT_SESSION_IDLE_MS = 10 * 60 * 1000; // 10 minutes
@@ -112,7 +116,8 @@ export async function startServer(
     },
   });
 
-  const { forwarded, inProcess } = getBridgeToolSurface({
+  // No browser peer can attach here, so the tools a peer would run are not offered.
+  const { inProcess } = getBridgeToolSurface({
     projectDir: opts.projectDir ?? process.cwd(),
     consumers: bridge.consumers,
     callerIdentity: bridge.callerIdentity,
@@ -165,7 +170,7 @@ export async function startServer(
         logger.verbose(`session ${id.slice(0, 8)}… initialized`);
       },
     });
-    const server = buildMcpServer(bridge, { forwarded, inProcess });
+    const server = buildMcpServer(bridge, { forwarded: [], inProcess });
     const session: Session = {
       transport,
       idleTimer: null,
@@ -185,6 +190,8 @@ export async function startServer(
   }
 
   // ── HTTP server ─────────────────────────────────────────────────
+  // No proxy fronts this bridge, so it learns no port: an MCP request names this port or none.
+  const mcpPorts = createAppPorts('127.0.0.1');
   const http = createServer(async (req, res) => {
     const url = req.url ?? '/';
     const debugEnabled = Boolean(process.env.PYRIC_DEBUG);
@@ -201,7 +208,7 @@ export async function startServer(
     const supportsMcpMethod = req.method === 'POST' || req.method === 'GET' || req.method === 'DELETE';
     const requestsMcp = url === DEFAULT_MCP_PATH && supportsMcpMethod;
     if (requestsMcp) {
-      const refusesOrigin = !isAllowedLoopbackRequest(req, '127.0.0.1', opts.allowedHosts);
+      const refusesOrigin = !isAllowedLoopbackRequest(req, '127.0.0.1', opts.allowedHosts, mcpPorts.forRequest(req));
       if (refusesOrigin) {
         res.writeHead(403, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Forbidden: invalid host or origin' }));
@@ -259,17 +266,20 @@ export async function startServer(
     res.end(JSON.stringify({ error: 'not found', path: url }));
   });
 
-  // ── WebSocket server (mounted on /sandbox) ──────────────────────
-  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_BRIDGE_FRAME_BYTES });
+  // ── /sandbox: refused with a reason ─────────────────────────────
+  // A browser cannot read an HTTP refusal of an upgrade, so the socket is
+  // accepted and closed at once with a reason `connectBridge` reports. No
+  // message from it is read, and it never registers as the sandbox peer.
+  const wss = new WebSocketServer({ noServer: true, maxPayload: 1024 });
   http.on('upgrade', (req, socket, head) => {
     const hasWrongPath = (req.url ?? '') !== DEFAULT_SANDBOX_PATH;
     if (hasWrongPath) {
       socket.destroy();
       return;
     }
-    // DNS-rebinding + cross-origin hijack guard (the request-time isAllowedHost
-    // runs on the `request` event only — `upgrade` bypasses it). The standalone
-    // bridge binds 127.0.0.1 only, so the allowlist is the loopback set.
+    // DNS-rebinding + cross-origin guard: only a loopback page is told why.
+    // The port is not compared here: the page that reaches this socket loads
+    // from the app's own dev server on another port.
     const refusesUpgrade = !isAllowedUpgrade(req.headers, '127.0.0.1', opts.allowedHosts);
     if (refusesUpgrade) {
       logger.error(
@@ -279,7 +289,8 @@ export async function startServer(
       return;
     }
     wss.handleUpgrade(req, socket, head, (ws) => {
-      attachPeer(bridge, ws, logger);
+      logger.info(`refused a browser sandbox on ${DEFAULT_SANDBOX_PATH}: run pyric sandbox --bridge instead`);
+      ws.close(NO_BROWSER_PEER_CLOSE_CODE, NO_BROWSER_PEER_CLOSE_REASON);
     });
   });
 
@@ -305,12 +316,9 @@ export async function startServer(
     url,
     auditLogPath: auditWriter?.path ?? null,
     async stop() {
-      // Stop accepting new WebSocket upgrades…
+      // Stop accepting new WebSocket upgrades, and terminate a refused
+      // socket whose close handshake is still in flight.
       wss.close();
-      // …and forcibly terminate any existing WS clients. Without this,
-      // http.close() below waits for clients to disconnect on their own
-      // (MCP keep-alives sit forever — a Ctrl-C with any open peer
-      // would hang the CLI shutdown indefinitely).
       for (const client of wss.clients) {
         try { client.terminate(); } catch { /* already closed */ }
       }
@@ -332,92 +340,6 @@ export async function startServer(
   };
 }
 
-function attachPeer(bridge: Bridge, ws: WebSocket, logger: BridgeLogger): void {
-  let disconnect: (() => void) | null = null;
-  let helloed = false;
-  let sandboxId: string | null = null;
-  let peerGeneration = 0;
-
-  ws.on('message', (raw) => {
-    const isClosingConnection = ws.readyState !== ws.OPEN;
-    if (isClosingConnection) return;
-    const parsed = parseBridgeMessage(raw.toString());
-    const isInvalidMessage = parsed.kind === 'invalid';
-    if (isInvalidMessage) {
-      ws.close(1002, parsed.reason);
-      return;
-    }
-    const msg = parsed.message;
-    const isHello = msg.type === 'hello';
-    if (isHello) {
-      const protocolError = requestProtocolError(msg);
-      const hasProtocolError = protocolError !== undefined;
-      if (hasProtocolError) {
-        ws.close(1008, protocolError);
-        return;
-      }
-      const envelopeError = requestEnvelopeError(msg);
-      const hasEnvelopeError = envelopeError !== undefined;
-      if (hasEnvelopeError) {
-        ws.close(1002, envelopeError);
-        return;
-      }
-      if (helloed) return; // ignore duplicate hellos
-      helloed = true;
-      sandboxId = msg.sandboxId;
-      logger.info(
-        `peer connected — sandboxId=${sandboxId.slice(0, 12)} tools=${msg.tools.length}`,
-      );
-      disconnect = bridge.registerSandboxPeer(
-        (out: BridgeMessage) => {
-          try {
-            sendBridgeMessage(ws, out, bridge.handleSandboxMessage);
-          } catch {
-            // socket likely closed; the close handler runs disconnect.
-          }
-        },
-        msg.tools,
-        msg.sandboxId,
-      );
-      peerGeneration = bridge.peerGeneration();
-      sendBridgeMessage(ws, {
-        type: 'hello-ack',
-        protocol: 1,
-        bridgeVersion: bridge.version,
-      });
-      return;
-    }
-
-    const isUnregistered = !helloed;
-    if (isUnregistered) return; // ignore messages before hello
-    const envelopeError = requestEnvelopeError(msg);
-    const hasEnvelopeError = envelopeError !== undefined;
-    if (hasEnvelopeError) {
-      ws.close(1002, envelopeError);
-      return;
-    }
-    bridge.handleSandboxMessage(msg, peerGeneration);
-  });
-
-  ws.on('close', () => {
-    const releasePeer = disconnect;
-    const hasPeer = releasePeer !== null;
-    if (hasPeer) {
-      releasePeer();
-      const id = sandboxId;
-      const hasId = id !== null && id.length > 0;
-      let label = 'unknown';
-      if (hasId) label = id.slice(0, 12);
-      logger.info(`peer disconnected — sandboxId=${label}`);
-    }
-    disconnect = null;
-  });
-
-  ws.on('error', () => {
-    // ws will follow up with a 'close' event; cleanup happens there.
-  });
-}
-
 /** Construct a default logger only when the caller did not supply one. */
 function defaultLogger(silent = false): BridgeLogger {
   if (silent) return createSilentLogger();