sliccy 4.22.1 → 4.24.0

package/dist/node-server/index.js

@@ -10,6 +10,7 @@ import { homedir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { WebSocket, WebSocketServer } from 'ws';
+import { BRIDGE_TOKEN_HEADER, buildCorsHeaders, buildPnaPreflightHeaders, isLoopbackBridgeOrigin, mintBridgeToken, selectBridgeSubprotocol, validateBridgeToken, validateBridgeUpgrade, } from './bridge-security.js';
 import { applyCdpUnmask } from './cdp-proxy/cdp-unmask.js';
 import { createCdpSessionUrlTracker } from './cdp-proxy/session-url-tracker.js';
 import { buildChromeLaunchArgs, clearStaleDevToolsActivePort, ensureQaProfileScaffold, findChromeExecutable, legacyChromeCandidates, migrateLegacyDefaultChromeProfile, planChromeSpawn, resolveChromeLaunchProfile, waitForCdpPort, } from './chrome-launch.js';
@@ -65,6 +66,13 @@ const SERVE_ONLY = RUNTIME_FLAGS.serveOnly;
 const ELECTRON_MODE = RUNTIME_FLAGS.electron;
 const ELECTRON_APP = RUNTIME_FLAGS.electronApp;
 const KILL_EXISTING_ELECTRON_APP = RUNTIME_FLAGS.kill;
+/**
+ * Standalone thin-bridge mode: production CLI with no bundled UI. The
+ * launched Chrome opens a sliccy.ai-hosted leader; node-server is a thin
+ * /cdp bridge + /api surface. Dev / electron / serve-only / hosted all
+ * keep the bundled UI path (a separate path B / hosted task covers those).
+ */
+const THIN_BRIDGE_MODE = !DEV_MODE && !SERVE_ONLY && !ELECTRON_MODE && !RUNTIME_FLAGS.hosted;
 // ---------------------------------------------------------------------------
 // File logger — persistent log file in ~/.slicc/logs/
 // ---------------------------------------------------------------------------
@@ -300,6 +308,7 @@ function createServerState() {
         overlayInjector: null,
         shuttingDown: false,
         discoveredTrayJoinUrl: RUNTIME_FLAGS.joinUrl ?? null,
+        bridgeToken: THIN_BRIDGE_MODE ? mintBridgeToken() : null,
         cdpUrl: null,
         chromeWs: null,
         activeClientWs: null,
@@ -465,15 +474,33 @@ async function launchElectronTarget(state) {
         throw error;
     }
 }
+/**
+ * Resolve the leader origin Chrome should open in thin-bridge mode. Prefers
+ * an explicit `--lead <url>` / `WORKER_BASE_URL` so dev can point at staging;
+ * defaults to production sliccy.ai.
+ */
+function resolveThinLeaderOrigin() {
+    const explicit = RUNTIME_FLAGS.leadWorkerBaseUrl ?? process.env['WORKER_BASE_URL'] ?? null;
+    if (explicit) {
+        return explicit.replace(/\/+$/, '');
+    }
+    return 'https://www.sliccy.ai';
+}
 /** Build the Chrome launch URL, appending hosted-runtime + prompt query params. */
 function buildBrowserLaunchUrl(state) {
+    // Thin-bridge standalone: Chrome opens the hosted leader directly; the
+    // local node-server serves no UI at all. Bridge coordinates ride as
+    // query params so the leader can discover + authenticate /cdp.
+    const serveOriginForLaunch = THIN_BRIDGE_MODE && state.bridgeToken ? resolveThinLeaderOrigin() : state.serveOrigin;
     let url = resolveCliBrowserLaunchUrl({
-        serveOrigin: state.serveOrigin,
+        serveOrigin: serveOriginForLaunch,
         lead: RUNTIME_FLAGS.lead,
         leadWorkerBaseUrl: RUNTIME_FLAGS.leadWorkerBaseUrl,
         envWorkerBaseUrl: process.env['WORKER_BASE_URL'] ?? null,
         join: RUNTIME_FLAGS.join,
         joinUrl: RUNTIME_FLAGS.joinUrl,
+        bridgeWsUrl: THIN_BRIDGE_MODE && state.bridgeToken ? `ws://localhost:${state.servePort}/cdp` : null,
+        bridgeToken: state.bridgeToken,
     });
     if (RUNTIME_FLAGS.hosted) {
         url += `${url.includes('?') ? '&' : '?'}runtime=hosted-leader`;
@@ -487,6 +514,11 @@ function buildBrowserLaunchUrl(state) {
     else if (RUNTIME_FLAGS.lead) {
         console.log(`Lead launch URL: ${url}`);
     }
+    else if (THIN_BRIDGE_MODE) {
+        // Print WITHOUT the bridgeToken — it's a session capability.
+        const sanitized = url.replace(/([?&])bridgeToken=[^&]+/, '$1bridgeToken=<redacted>');
+        console.log(`Thin-bridge launch URL: ${sanitized}`);
+    }
     return url;
 }
 function resolveChromeProfileOrExit(state) {
@@ -602,11 +634,56 @@ function closeWebSocketQuietly(ws) {
         /* ignore */
     }
 }
-/** Route `/cdp` and `/licks-ws` upgrades to their servers; leave others for Vite HMR. */
-function attachCdpUpgradeRouting(server, wss, lickWss) {
+/**
+ * Reject a WebSocket upgrade before `handleUpgrade` runs. Writes a minimal
+ * HTTP/1.1 response and destroys the underlying socket. RFC 6455 allows 401
+ * / 403 here; we use 401 so a caller that retries with the correct
+ * subprotocol/origin doesn't trip permanent CORS-style caches.
+ */
+function rejectUpgradeUnauthorized(socket, reason) {
+    try {
+        socket.write(`HTTP/1.1 401 Unauthorized\r\n` +
+            `Content-Type: text/plain\r\n` +
+            `Connection: close\r\n` +
+            `Content-Length: ${Buffer.byteLength(reason)}\r\n` +
+            `\r\n${reason}`);
+    }
+    catch {
+        /* socket may already be gone */
+    }
+    try {
+        socket.destroy();
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Route `/cdp` and `/licks-ws` upgrades to their servers; leave others for Vite HMR.
+ *
+ * When `bridgeToken !== null` (thin standalone mode) the `/cdp` upgrade is
+ * gated by `validateBridgeUpgrade`: bad origin or missing/wrong
+ * `Sec-WebSocket-Protocol` token = socket destroyed before
+ * `wss.emit('connection', ...)` ever fires. Legacy modes (dev / electron /
+ * serve-only / hosted) pass `null` to keep same-origin behavior unchanged.
+ * `/licks-ws` is loopback-only and stays ungated.
+ */
+function attachCdpUpgradeRouting(server, wss, lickWss, bridgeToken) {
     server.on('upgrade', (request, socket, head) => {
         const { pathname } = new URL(request.url, `http://${request.headers.host}`);
         if (pathname === '/cdp') {
+            if (bridgeToken !== null) {
+                const gate = validateBridgeUpgrade({
+                    origin: request.headers.origin,
+                    subprotocolHeader: request.headers['sec-websocket-protocol'],
+                    expectedToken: bridgeToken,
+                });
+                if (!gate.ok) {
+                    console.warn(`[cdp-proxy] /cdp upgrade rejected: ${gate.reason}`);
+                    rejectUpgradeUnauthorized(socket, gate.reason ?? 'rejected');
+                    return;
+                }
+            }
             wss.handleUpgrade(request, socket, head, (ws) => {
                 wss.emit('connection', ws, request);
             });
@@ -736,6 +813,27 @@ function forwardClientFrame(state, data, ctx) {
         console.log(`[cdp-proxy] Client→Chrome (DROPPED — no connection): ${preview}`);
     }
 }
+/**
+ * Wait for `state.cdpPort` to be populated (i.e. `launchChromeTarget`'s
+ * `waitForCdpPort` has resolved). Used by clients that race ahead of the
+ * browser launch — primarily the thin-bridge case where `server.listen()`
+ * runs BEFORE `launchBrowser` so the hosted leader can connect to /cdp
+ * the moment Chrome opens it, even before Chrome's own CDP port is known.
+ */
+async function waitForServerCdpPort(state, timeoutMs = 30_000) {
+    if (state.cdpPort > 0)
+        return state.cdpPort;
+    const startedAt = Date.now();
+    while (state.cdpPort === 0 && Date.now() - startedAt < timeoutMs) {
+        if (state.shuttingDown)
+            throw new Error('Server shutting down');
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    if (state.cdpPort === 0) {
+        throw new Error('Chrome CDP port did not become available in time');
+    }
+    return state.cdpPort;
+}
 async function handleCdpClient(state, clientWs, ctx, cdpPort) {
     try {
         // Only one client active at a time — close the previous one.
@@ -766,7 +864,8 @@ async function handleCdpClient(state, clientWs, ctx, cdpPort) {
         });
         // NOW do async work — messages arriving during these awaits are buffered.
         if (!state.cdpUrl) {
-            state.cdpUrl = await waitForCDP(cdpPort);
+            const port = cdpPort && cdpPort > 0 ? cdpPort : await waitForServerCdpPort(state);
+            state.cdpUrl = await waitForCDP(port);
             console.log(`[cdp-proxy] CDP available at: ${state.cdpUrl}`);
         }
         await ensureChromeConnection(state, state.cdpUrl, ctx);
@@ -834,13 +933,16 @@ function createGracefulShutdown(state, deps) {
         deps.wss.close();
         // Stop accepting new HTTP connections.
         deps.server.close();
-        await closeLaunchedBrowserGracefully(state, deps.cdpPort);
+        // Read cdpPort from state — populated by `launchChromeTarget`; may be 0
+        // if shutdown fires before the browser ever launched.
+        await closeLaunchedBrowserGracefully(state, state.cdpPort);
         process.exit(0);
     };
 }
 /** Pre-connect to Chrome so the proxy is warm before the first client; hosted mode registers leader-restart once CDP is ready. */
-async function preconnectCdp(state, ctx, app, servePort, cdpPort) {
+async function preconnectCdp(state, ctx, app, servePort) {
     try {
+        const cdpPort = state.cdpPort > 0 ? state.cdpPort : await waitForServerCdpPort(state);
         state.cdpUrl = await waitForCDP(cdpPort);
         console.log(`[cdp-proxy] Pre-connected: CDP available at ${state.cdpUrl}`);
         await ensureChromeConnection(state, state.cdpUrl, ctx);
@@ -873,31 +975,61 @@ async function startOverlayInjector(state, cdpPort, servePort) {
         console.error('[electron-float] Failed to start overlay injector:', message);
     }
 }
-/** Start listening and warm up the CDP proxy, overlay injector, and console forwarder. */
-function startCdpServer(state, deps) {
-    const { app, server, ctx, fileLogger, servePort, serveOrigin, cdpPort } = deps;
-    server.listen(servePort, '127.0.0.1', () => {
-        console.log(`Serving UI at ${serveOrigin}`);
-        console.log(`CDP proxy at ws://localhost:${servePort}/cdp`);
-        fileLogger.log('info', 'CLI server started', {
-            port: servePort,
-            cdpPort,
-            devMode: DEV_MODE,
-            electronMode: ELECTRON_MODE,
+/**
+ * Bind the HTTP server (and the /cdp WS upgrade handler attached to it) so
+ * incoming `ws://localhost/cdp` connections are accepted. Resolves when
+ * `server.listen` fires its 'listening' callback.
+ *
+ * Split out of the old `startCdpServer` so `main()` can `await` listening
+ * BEFORE `launchBrowser(state)` runs — without this ordering the hosted
+ * leader's eager `browser.connect()` (fired the moment Chrome opens
+ * sliccy.ai in thin-bridge mode) can race ahead of the bridge and fail
+ * its one-shot WebSocket handshake.
+ */
+function startListening(deps) {
+    const { server, fileLogger, servePort, serveOrigin, cdpPort } = deps;
+    return new Promise((resolve) => {
+        server.listen(servePort, '127.0.0.1', () => {
+            if (THIN_BRIDGE_MODE) {
+                console.log(`Thin /cdp bridge + /api at ${serveOrigin}`);
+            }
+            else {
+                console.log(`Serving UI at ${serveOrigin}`);
+            }
+            console.log(`CDP proxy at ws://localhost:${servePort}/cdp`);
+            fileLogger.log('info', 'CLI server started', {
+                port: servePort,
+                cdpPort,
+                devMode: DEV_MODE,
+                electronMode: ELECTRON_MODE,
+            });
+            resolve();
         });
-        void preconnectCdp(state, ctx, app, servePort, cdpPort);
-        if (ELECTRON_MODE) {
-            void startOverlayInjector(state, cdpPort, servePort);
-        }
-        else {
-            setTimeout(() => {
-                attachConsoleForwarder(cdpPort, String(servePort)).catch((err) => {
-                    console.error('[page] Console forwarder error:', err);
-                });
-            }, 2500);
-        }
     });
 }
+/**
+ * Post-listen warmup: pre-connects to Chrome's CDP (so the proxy is warm
+ * before the first client), starts the Electron overlay injector, and
+ * attaches the console forwarder. Reads `state.cdpPort` dynamically so
+ * the value populated by `launchChromeTarget` is used regardless of when
+ * this runs relative to the listen callback.
+ */
+function runCdpProxyWarmup(state, deps) {
+    const { app, ctx, servePort } = deps;
+    void preconnectCdp(state, ctx, app, servePort);
+    if (ELECTRON_MODE) {
+        void startOverlayInjector(state, state.cdpPort, servePort);
+    }
+    else if (!THIN_BRIDGE_MODE) {
+        // Thin-bridge mode has no local UI page to forward console output from.
+        const cdpPort = state.cdpPort;
+        setTimeout(() => {
+            attachConsoleForwarder(cdpPort, String(servePort)).catch((err) => {
+                console.error('[page] Console forwarder error:', err);
+            });
+        }, 2500);
+    }
+}
 /**
  * Build the secret stores + masking pipeline shared by the fetch-proxy, the
  * /api/secrets routes, and the S3 sign-and-forward handler. Secret-load
@@ -924,20 +1056,98 @@ async function bootstrapSecrets() {
     }
     return { secretStore, secretProxy, oauthStore };
 }
+/**
+ * Thin-bridge CORS + PNA middleware. The hosted leader at sliccy.ai is a
+ * cross-origin caller, so headers go on every response for allowlisted
+ * origins (so /cdp's pre-WS preflight and every /api/* call succeed);
+ * OPTIONS from an allowlisted origin short-circuits to 204 with the PNA
+ * opt-in. Non-allowlisted origins fall through with no CORS headers, which
+ * preserves same-origin (localhost) behavior unchanged.
+ *
+ * Additionally enforces the per-process bridge token on cross-origin
+ * `/api/*` requests from REMOTE allowlisted origins (sliccy.ai) — the
+ * origin allowlist alone is insufficient because any script on
+ * `https://www.sliccy.ai` could otherwise reach the local node-server's
+ * /api surface (secrets, fetch-proxy, etc.). Loopback allowlisted
+ * origins (e.g. the locally-served OAuth callback at
+ * `http://localhost:5710/auth/callback` POSTing to `/api/oauth-result`)
+ * are exempt — they originate from this same server. OPTIONS preflights
+ * are exempt because browsers strip custom headers from preflights.
+ */
+function createThinBridgeCorsMiddleware(bridgeToken) {
+    return (req, res, next) => {
+        // Reflect the requested headers so the agent's `bash curl -H …` (which
+        // can carry arbitrary upstream headers through /api/fetch-proxy) is not
+        // blocked by a hardcoded allowlist. Cross-origin preflights advertise
+        // those headers via `Access-Control-Request-Headers`.
+        const origin = req.headers.origin;
+        const cors = buildCorsHeaders(origin, req.headers['access-control-request-headers']);
+        if (cors) {
+            for (const [k, v] of Object.entries(cors))
+                res.setHeader(k, v);
+        }
+        if (req.method === 'OPTIONS' && cors) {
+            for (const [k, v] of Object.entries(buildPnaPreflightHeaders()))
+                res.setHeader(k, v);
+            res.setHeader('Access-Control-Max-Age', '600');
+            res.status(204).end();
+            return;
+        }
+        // Token gate on /api/* from remote allowlisted origins. `cors` is only
+        // truthy when the Origin is in the allowlist; loopback callers
+        // (localhost/127.0.0.1) and no-Origin curl-style callers fall through
+        // unchanged.
+        if (cors &&
+            req.path.startsWith('/api/') &&
+            !isLoopbackBridgeOrigin(origin) &&
+            !validateBridgeToken(req.headers[BRIDGE_TOKEN_HEADER.toLowerCase()], bridgeToken)) {
+            res.status(403).json({ error: 'bridge-token-required' });
+            return;
+        }
+        next();
+    };
+}
+/**
+ * Build the `/cdp` `WebSocketServer`. `handleProtocols` echoes the matched
+ * bridge subprotocol back in the 101 response (RFC 6455 §1.9). Returning
+ * `false` makes the server omit the header, which makes the browser fail
+ * the upgrade when a subprotocol was offered. Legacy modes (token=null)
+ * pass the first offered subprotocol through unchanged.
+ */
+function createCdpWebSocketServer(bridgeToken) {
+    return new WebSocketServer({
+        noServer: true,
+        handleProtocols: (protocols) => {
+            if (bridgeToken !== null) {
+                return selectBridgeSubprotocol([...protocols], bridgeToken) ?? false;
+            }
+            const first = protocols.values().next();
+            return first.done ? false : first.value;
+        },
+    });
+}
 async function main() {
-    // Resolve ports, launch the browser, then snapshot the now-final values that
-    // the rest of boot reads. Mutable lifecycle fields stay on `state`.
+    // Resolve ports first; `launchBrowser` is deferred until AFTER
+    // `server.listen()` so the /cdp bridge is accepting connections before
+    // Chrome opens its target URL (the packaged-CLI thin-bridge mode opens
+    // the hosted leader at sliccy.ai, whose eager `browser.connect()`
+    // otherwise races ahead of the bridge listener and fails its one-shot
+    // WebSocket handshake). `state.cdpPort` becomes valid inside
+    // `launchChromeTarget` once Chrome announces its CDP port; consumers
+    // that need it (`handleCdpClient`, `preconnectCdp`, the graceful-
+    // shutdown handler) read it dynamically from `state`.
     const state = createServerState();
     await resolvePorts(state);
-    await launchBrowser(state);
-    const { servePort: SERVE_PORT, cdpPort: CDP_PORT, serveOrigin: SERVE_ORIGIN } = state;
-    const discoveredTrayJoinUrl = state.discoveredTrayJoinUrl;
+    const { servePort: SERVE_PORT, serveOrigin: SERVE_ORIGIN } = state;
     // 3. Set up express app with request logging
     const { secretStore, secretProxy, oauthStore } = await bootstrapSecrets();
     const app = express();
     app.use(requestLogger);
     // Append SLICC's standard RFC 8288 Link header set on every /api/* response.
     app.use(sliccLinksMiddleware());
+    if (THIN_BRIDGE_MODE) {
+        app.use(createThinBridgeCorsMiddleware(state.bridgeToken));
+    }
     // ---------------------------------------------------------------------------
     // Lick system — WebSocket bridge for webhooks/crontasks (all logic in browser)
     // ---------------------------------------------------------------------------
@@ -964,7 +1174,11 @@ async function main() {
                 (DEV_MODE
                     ? 'https://slicc-tray-hub-staging.minivelos.workers.dev'
                     : 'https://www.sliccy.ai'),
-            trayJoinUrl: discoveredTrayJoinUrl ?? null,
+            // Read dynamically from state — populated by `launchElectronTarget`
+            // when an existing leader is discovered. `launchBrowser` now runs
+            // after `server.listen()`, so this endpoint must NOT close over a
+            // pre-launch snapshot or it would always return null.
+            trayJoinUrl: state.discoveredTrayJoinUrl ?? null,
         });
     });
     // Localhost API descriptor — the discoverable surface advertised by the
@@ -1012,17 +1226,21 @@ async function main() {
     registerFetchProxyRoute(app, { secretProxy });
     // Create the HTTP server BEFORE Vite so we can register our upgrade handler first
     const server = createServer(app);
-    await attachUiServing(app, server, {
-        devMode: DEV_MODE,
-        hosted: RUNTIME_FLAGS.hosted,
-        serveOrigin: SERVE_ORIGIN,
-        uiDir: resolve(Dirname, '..', 'ui'),
-    });
+    // Thin-bridge mode: skip UI serving entirely. node-server becomes a
+    // pure /cdp bridge + /api surface; Chrome opens the sliccy.ai-hosted
+    // leader which talks to /cdp + /api cross-origin.
+    if (!THIN_BRIDGE_MODE) {
+        await attachUiServing(app, server, {
+            devMode: DEV_MODE,
+            hosted: RUNTIME_FLAGS.hosted,
+            serveOrigin: SERVE_ORIGIN,
+            uiDir: resolve(Dirname, '..', 'ui'),
+        });
+    }
     // 4. CDP WebSocket proxy at /cdp — noServer mode so Vite's dev middleware
-    //    doesn't intercept the upgrade; the per-message cap stays default (the
-    //    feedback-loop defense is Chrome→proxy only, never client→proxy).
-    const wss = new WebSocketServer({ noServer: true });
-    attachCdpUpgradeRouting(server, wss, lickWss);
+    //    doesn't intercept the upgrade.
+    const wss = createCdpWebSocketServer(state.bridgeToken);
+    attachCdpUpgradeRouting(server, wss, lickWss, state.bridgeToken);
     const cdpCtx = {
         wss,
         secretProxy,
@@ -1033,7 +1251,6 @@ async function main() {
         fileLogger,
         wss,
         server,
-        cdpPort: CDP_PORT,
     });
     process.on('SIGINT', () => {
         gracefulShutdown();
@@ -1053,17 +1270,42 @@ async function main() {
             }
         }
     });
+    await startCdpStack(state, { app, server, wss, cdpCtx, fileLogger });
+}
+/**
+ * Bottom half of `main()`: bind the /cdp WS handler, start listening on
+ * the HTTP server BEFORE launching the browser so the /cdp bridge is
+ * accepting the hosted leader's eager connect the instant Chrome opens
+ * sliccy.ai, then launch the browser (populates `state.cdpPort`), then
+ * run the post-launch warmup (preconnect / overlay / console forwarder).
+ *
+ * Extracted purely to keep `main()` under the lint-enforced function-size
+ * cap; not a meaningful boundary, just a co-locating helper.
+ */
+async function startCdpStack(state, deps) {
+    const { app, server, wss, cdpCtx, fileLogger } = deps;
+    const { servePort: SERVE_PORT, serveOrigin: SERVE_ORIGIN } = state;
+    // Read `state.cdpPort` dynamically — populated by `launchChromeTarget`
+    // AFTER `server.listen()` so we can't capture it here.
     wss.on('connection', (clientWs) => {
-        void handleCdpClient(state, clientWs, cdpCtx, CDP_PORT);
+        void handleCdpClient(state, clientWs, cdpCtx, state.cdpPort);
+    });
+    await startListening({
+        server,
+        fileLogger,
+        servePort: SERVE_PORT,
+        serveOrigin: SERVE_ORIGIN,
+        cdpPort: state.cdpPort,
     });
-    startCdpServer(state, {
+    await launchBrowser(state);
+    runCdpProxyWarmup(state, {
         app,
         server,
         ctx: cdpCtx,
         fileLogger,
         servePort: SERVE_PORT,
         serveOrigin: SERVE_ORIGIN,
-        cdpPort: CDP_PORT,
+        cdpPort: state.cdpPort,
     });
 }
 // ---------------------------------------------------------------------------

package/dist/node-server/launch-url.d.ts

@@ -5,5 +5,12 @@ export interface CliLaunchUrlOptions {
     envWorkerBaseUrl?: string | null;
     join: boolean;
     joinUrl?: string | null;
+    /**
+     * Thin-bridge coordinates appended as query params so the hosted leader can
+     * discover + authenticate the local /cdp WebSocket. Both must be set
+     * together; both unset = no bridge params (legacy / bundled UI path).
+     */
+    bridgeWsUrl?: string | null;
+    bridgeToken?: string | null;
 }
 export declare function resolveCliBrowserLaunchUrl(options: CliLaunchUrlOptions): string;

package/dist/node-server/launch-url.js

@@ -1,4 +1,13 @@
+import { BRIDGE_TOKEN_QUERY_PARAM, BRIDGE_WS_QUERY_PARAM } from './bridge-security.js';
 import { buildCanonicalTrayLaunchUrl, normalizeTrayWorkerBaseUrl, parseTrayJoinUrl, } from './tray-url-shared.js';
+function appendBridgeParams(url, opts) {
+    if (!opts.bridgeWsUrl || !opts.bridgeToken)
+        return url;
+    const params = new URLSearchParams();
+    params.set(BRIDGE_WS_QUERY_PARAM, opts.bridgeWsUrl);
+    params.set(BRIDGE_TOKEN_QUERY_PARAM, opts.bridgeToken);
+    return `${url}${url.includes('?') ? '&' : '?'}${params.toString()}`;
+}
 function buildTrayJoinLaunchUrl(locationHref, joinUrl) {
     const parsedJoinUrl = parseTrayJoinUrl(joinUrl);
     if (!parsedJoinUrl) {
@@ -21,14 +30,14 @@ export function resolveCliBrowserLaunchUrl(options) {
         if (!options.joinUrl) {
             throw new Error('The --join launch flow requires a tray join URL via --join <url> or --join=<url>.');
         }
-        return buildTrayJoinLaunchUrl(options.serveOrigin, options.joinUrl);
+        return appendBridgeParams(buildTrayJoinLaunchUrl(options.serveOrigin, options.joinUrl), options);
     }
     if (!options.lead) {
-        return options.serveOrigin;
+        return appendBridgeParams(options.serveOrigin, options);
     }
     const workerBaseUrl = normalizeTrayWorkerBaseUrl(options.leadWorkerBaseUrl ?? options.envWorkerBaseUrl ?? null);
     if (!workerBaseUrl) {
         throw new Error('The --lead launch flow requires a tray worker base URL via --lead <url>, --lead=<url>, or WORKER_BASE_URL.');
     }
-    return buildTrayLeadLaunchUrl(options.serveOrigin, workerBaseUrl);
+    return appendBridgeParams(buildTrayLeadLaunchUrl(options.serveOrigin, workerBaseUrl), options);
 }