sliccy 4.23.0 → 4.24.0

package/dist/node-server/bridge-security.d.ts

@@ -31,8 +31,33 @@ export declare const BRIDGE_SUBPROTOCOL_PREFIX = "slicc.bridge.v1.";
 export declare const BRIDGE_TOKEN_QUERY_PARAM = "bridgeToken";
 /** Query-param name the launch URL uses to forward the local /cdp WebSocket URL. */
 export declare const BRIDGE_WS_QUERY_PARAM = "bridge";
+/**
+ * Request header carrying the per-process bridge token on cross-origin
+ * /api/* calls from a remote allowlisted leader (e.g. sliccy.ai). The
+ * webapp's `proxied-fetch.ts` attaches it whenever a local API base
+ * origin is set; the thin-bridge CORS middleware validates it. Header
+ * is included in `CORS_BASE_ALLOW_HEADERS` so browsers don't strip it
+ * on the preflight.
+ */
+export declare const BRIDGE_TOKEN_HEADER = "X-Bridge-Token";
 /** True iff `origin` is in the bridge allowlist. Case-sensitive (origins are normalized lowercase). */
 export declare function isAllowedBridgeOrigin(origin: string | undefined | null): boolean;
+/**
+ * True iff `origin` is a loopback host (localhost / 127.0.0.1 / ::1).
+ * Loopback allowlisted origins (e.g. the locally-served OAuth callback
+ * page at `http://localhost:5710/auth/callback` posting to
+ * `/api/oauth-result`) are exempt from the bridge-token requirement —
+ * the token's threat model is "remote allowlisted origin (sliccy.ai)
+ * with a hostile script", not "local server talking to itself".
+ */
+export declare function isLoopbackBridgeOrigin(origin: string | undefined | null): boolean;
+/**
+ * Constant-time compare for the bridge token. `presented` may be missing
+ * or shaped wrong (Express delivers headers as `string | string[] |
+ * undefined`). Returns `false` for any non-string, length mismatch, or
+ * empty expected — never throws.
+ */
+export declare function validateBridgeToken(presented: string | string[] | undefined, expected: string | null): boolean;
 /**
  * Mint a per-process bridge token. Embedded in the leader launch URL and
  * required as the WebSocket subprotocol on /cdp. Use `crypto.randomUUID()`
@@ -77,6 +102,18 @@ export declare function validateBridgeUpgrade(input: {
     subprotocolHeader: string | string[] | undefined;
     expectedToken: string;
 }): BridgeUpgradeGateResult;
+/**
+ * Resolve the `Access-Control-Allow-Headers` value for a request. Starts
+ * from `CORS_BASE_ALLOW_HEADERS` (the static set covering the documented
+ * /api endpoints + the `/api/fetch-proxy` transport headers) and unions
+ * in any header names from the request's `Access-Control-Request-Headers`
+ * that aren't already listed. This is the reflect-headers pattern: the
+ * agent's `bash curl -H X-Custom: …` can route through `/api/fetch-proxy`
+ * cross-origin without us having to enumerate every possible upstream
+ * header in advance. Comparison is case-insensitive; the static set's
+ * canonical casing wins on duplicates.
+ */
+export declare function resolveCorsAllowHeaders(requestHeadersHeader: string | undefined | null): string;
 /**
  * CORS headers for an allowlisted `Origin`. Returns `null` when the origin
  * is not in the allowlist (caller should NOT set CORS headers).
@@ -84,8 +121,12 @@ export declare function validateBridgeUpgrade(input: {
  * `Access-Control-Allow-Credentials: true` is included so the hosted leader
  * can carry cookies to /api/* (e.g. auth) when that's added later. Today
  * the bridge token is the auth factor, not cookies.
+ *
+ * `requestHeadersHeader` should be the request's `Access-Control-Request-Headers`
+ * value (preflight only); on a non-preflight request pass `null` and the
+ * caller can omit it.
  */
-export declare function buildCorsHeaders(origin: string | undefined | null): Record<string, string> | null;
+export declare function buildCorsHeaders(origin: string | undefined | null, requestHeadersHeader?: string | string[] | null): Record<string, string> | null;
 /**
  * PNA preflight extras. Added on OPTIONS responses for allowlisted origins
  * when the request carries `Access-Control-Request-Private-Network: true`

package/dist/node-server/bridge-security.js

@@ -18,7 +18,7 @@
  * Pure module (no node-only imports) so the WS gate is trivially unit
  * testable from `tests/bridge-security.test.ts`.
  */
-import { randomUUID } from 'node:crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
 /**
  * Origin allowlist. Production + staging worker plus the dev-mode loopback
  * origins (parallel to chrome-extension's `BRIDGE_DEV_ORIGINS`). Add a new
@@ -37,8 +37,42 @@ export const BRIDGE_SUBPROTOCOL_PREFIX = 'slicc.bridge.v1.';
 export const BRIDGE_TOKEN_QUERY_PARAM = 'bridgeToken';
 /** Query-param name the launch URL uses to forward the local /cdp WebSocket URL. */
 export const BRIDGE_WS_QUERY_PARAM = 'bridge';
-/** Headers we allow on cross-origin /api requests from the hosted leader. */
-const CORS_ALLOW_HEADERS = 'Content-Type, X-Slicc-Raw-Body, X-Session-Id, X-Bridge-Token, Authorization';
+/**
+ * Request header carrying the per-process bridge token on cross-origin
+ * /api/* calls from a remote allowlisted leader (e.g. sliccy.ai). The
+ * webapp's `proxied-fetch.ts` attaches it whenever a local API base
+ * origin is set; the thin-bridge CORS middleware validates it. Header
+ * is included in `CORS_BASE_ALLOW_HEADERS` so browsers don't strip it
+ * on the preflight.
+ */
+export const BRIDGE_TOKEN_HEADER = 'X-Bridge-Token';
+/**
+ * Headers we allow on cross-origin /api requests from the hosted leader.
+ * Includes the `/api/fetch-proxy` transport headers (`X-Target-URL`, the
+ * forbidden-header `X-Proxy-*` bridges, `X-Slicc-Raw-Body`) so the
+ * webapp's `createProxiedFetch` can route through the local node-server
+ * cross-origin in thin-bridge mode. Custom upstream headers (any header
+ * the agent's `curl -H …` would pass through) are reflected via
+ * `Access-Control-Request-Headers` in `buildCorsHeaders` below.
+ */
+const CORS_BASE_ALLOW_HEADERS = [
+    'Content-Type',
+    'X-Slicc-Raw-Body',
+    'X-Session-Id',
+    'X-Bridge-Token',
+    'Authorization',
+    'X-Target-URL',
+    'X-Proxy-Cookie',
+    'X-Proxy-Origin',
+    'X-Proxy-Referer',
+];
+/**
+ * Response headers the browser is allowed to read after a cross-origin
+ * /api call — must include the proxy's infrastructure-error marker
+ * (`isProxyError` reads `X-Proxy-Error`) and the forbidden-response
+ * bridge (`decodeForbiddenResponseHeaders` reads `X-Proxy-Set-Cookie`).
+ */
+const CORS_EXPOSE_HEADERS = 'Link, X-Proxy-Error, X-Proxy-Set-Cookie';
 /** Methods exposed to the hosted leader. */
 const CORS_ALLOW_METHODS = 'GET, POST, PUT, DELETE, OPTIONS';
 /** True iff `origin` is in the bridge allowlist. Case-sensitive (origins are normalized lowercase). */
@@ -47,6 +81,48 @@ export function isAllowedBridgeOrigin(origin) {
         return false;
     return BRIDGE_ALLOWED_ORIGINS.includes(origin);
 }
+/**
+ * True iff `origin` is a loopback host (localhost / 127.0.0.1 / ::1).
+ * Loopback allowlisted origins (e.g. the locally-served OAuth callback
+ * page at `http://localhost:5710/auth/callback` posting to
+ * `/api/oauth-result`) are exempt from the bridge-token requirement —
+ * the token's threat model is "remote allowlisted origin (sliccy.ai)
+ * with a hostile script", not "local server talking to itself".
+ */
+export function isLoopbackBridgeOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const url = new URL(origin);
+        // Node's WHATWG URL parser keeps the brackets on IPv6 hostnames
+        // (`http://[::1]:5710` → `[::1]`); accept both bracketed and bare.
+        return (url.hostname === 'localhost' ||
+            url.hostname === '127.0.0.1' ||
+            url.hostname === '::1' ||
+            url.hostname === '[::1]');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Constant-time compare for the bridge token. `presented` may be missing
+ * or shaped wrong (Express delivers headers as `string | string[] |
+ * undefined`). Returns `false` for any non-string, length mismatch, or
+ * empty expected — never throws.
+ */
+export function validateBridgeToken(presented, expected) {
+    if (!expected)
+        return false;
+    const value = Array.isArray(presented) ? presented[0] : presented;
+    if (typeof value !== 'string' || value.length === 0)
+        return false;
+    const a = Buffer.from(value);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
 /**
  * Mint a per-process bridge token. Embedded in the leader launch URL and
  * required as the WebSocket subprotocol on /cdp. Use `crypto.randomUUID()`
@@ -102,6 +178,36 @@ export function validateBridgeUpgrade(input) {
     }
     return { ok: true, acceptedSubprotocol: accepted };
 }
+/**
+ * Resolve the `Access-Control-Allow-Headers` value for a request. Starts
+ * from `CORS_BASE_ALLOW_HEADERS` (the static set covering the documented
+ * /api endpoints + the `/api/fetch-proxy` transport headers) and unions
+ * in any header names from the request's `Access-Control-Request-Headers`
+ * that aren't already listed. This is the reflect-headers pattern: the
+ * agent's `bash curl -H X-Custom: …` can route through `/api/fetch-proxy`
+ * cross-origin without us having to enumerate every possible upstream
+ * header in advance. Comparison is case-insensitive; the static set's
+ * canonical casing wins on duplicates.
+ */
+export function resolveCorsAllowHeaders(requestHeadersHeader) {
+    if (!requestHeadersHeader)
+        return CORS_BASE_ALLOW_HEADERS.join(', ');
+    const seen = new Set(CORS_BASE_ALLOW_HEADERS.map((h) => h.toLowerCase()));
+    const extras = [];
+    for (const raw of requestHeadersHeader.split(',')) {
+        const name = raw.trim();
+        if (!name)
+            continue;
+        const lower = name.toLowerCase();
+        if (seen.has(lower))
+            continue;
+        seen.add(lower);
+        extras.push(name);
+    }
+    if (extras.length === 0)
+        return CORS_BASE_ALLOW_HEADERS.join(', ');
+    return [...CORS_BASE_ALLOW_HEADERS, ...extras].join(', ');
+}
 /**
  * CORS headers for an allowlisted `Origin`. Returns `null` when the origin
  * is not in the allowlist (caller should NOT set CORS headers).
@@ -109,17 +215,24 @@ export function validateBridgeUpgrade(input) {
  * `Access-Control-Allow-Credentials: true` is included so the hosted leader
  * can carry cookies to /api/* (e.g. auth) when that's added later. Today
  * the bridge token is the auth factor, not cookies.
+ *
+ * `requestHeadersHeader` should be the request's `Access-Control-Request-Headers`
+ * value (preflight only); on a non-preflight request pass `null` and the
+ * caller can omit it.
  */
-export function buildCorsHeaders(origin) {
+export function buildCorsHeaders(origin, requestHeadersHeader) {
     if (!isAllowedBridgeOrigin(origin))
         return null;
+    const reqHeaders = Array.isArray(requestHeadersHeader)
+        ? requestHeadersHeader.join(', ')
+        : (requestHeadersHeader ?? null);
     return {
         'Access-Control-Allow-Origin': origin,
         'Access-Control-Allow-Credentials': 'true',
         'Access-Control-Allow-Methods': CORS_ALLOW_METHODS,
-        'Access-Control-Allow-Headers': CORS_ALLOW_HEADERS,
-        'Access-Control-Expose-Headers': 'Link',
-        Vary: 'Origin',
+        'Access-Control-Allow-Headers': resolveCorsAllowHeaders(reqHeaders),
+        'Access-Control-Expose-Headers': CORS_EXPOSE_HEADERS,
+        Vary: 'Origin, Access-Control-Request-Headers',
     };
 }
 /**

package/dist/node-server/index.js

@@ -10,7 +10,7 @@ import { homedir } from 'os';
 import { basename, dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { WebSocket, WebSocketServer } from 'ws';
-import { buildCorsHeaders, buildPnaPreflightHeaders, mintBridgeToken, selectBridgeSubprotocol, validateBridgeUpgrade, } from './bridge-security.js';
+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';
@@ -813,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.
@@ -843,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);
@@ -911,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);
@@ -950,37 +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', () => {
-        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,
+/**
+ * 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 if (!THIN_BRIDGE_MODE) {
-            // Thin-bridge mode has no local UI page to forward console output from.
-            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
@@ -1014,10 +1063,25 @@ async function bootstrapSecrets() {
  * 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() {
+function createThinBridgeCorsMiddleware(bridgeToken) {
     return (req, res, next) => {
-        const cors = buildCorsHeaders(req.headers.origin);
+        // 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);
@@ -1029,6 +1093,17 @@ function createThinBridgeCorsMiddleware() {
             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();
     };
 }
@@ -1052,13 +1127,18 @@ function createCdpWebSocketServer(bridgeToken) {
     });
 }
 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();
@@ -1066,7 +1146,7 @@ async function main() {
     // Append SLICC's standard RFC 8288 Link header set on every /api/* response.
     app.use(sliccLinksMiddleware());
     if (THIN_BRIDGE_MODE) {
-        app.use(createThinBridgeCorsMiddleware());
+        app.use(createThinBridgeCorsMiddleware(state.bridgeToken));
     }
     // ---------------------------------------------------------------------------
     // Lick system — WebSocket bridge for webhooks/crontasks (all logic in browser)
@@ -1094,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
@@ -1167,7 +1251,6 @@ async function main() {
         fileLogger,
         wss,
         server,
-        cdpPort: CDP_PORT,
     });
     process.on('SIGINT', () => {
         gracefulShutdown();
@@ -1187,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,
     });
 }
 // ---------------------------------------------------------------------------