@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/bridge/bridge.js

@@ -0,0 +1,808 @@
+import * as http from 'node:http';
+import { authFailureReason } from './auth-failure-reason.js';
+import { impactSnapshot, recordImpact } from '../../memory/impact/impact-recorder.js';
+import { WebSocketServer } from 'ws';
+import { HookEvent } from '@reticlehq/core/hooks';
+import { emitSessionHook } from '../../hooks/hook-emit.js';
+import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, ReticleEnv, RETICLE_PROTOCOL_VERSION, TRANSPORT_LIMITS, isLocalPage, isLoopbackHostname, isOpaqueOrigin, OPAQUE_ORIGIN, isHighValueEvent, RATE_CAP_HIGH_VALUE_RESERVE_RATIO, CONTRACT_FINGERPRINT, CONTRACT_PARTS, } from '@reticlehq/core';
+import { Session } from '../session/session.js';
+import { SessionManager } from '../session/session-manager.js';
+import { tokensMatch } from './token-auth.js';
+import { pairingTokenSource } from './pairing-token.js';
+import { log } from '../../log.js';
+import { getSessionMetrics } from '../../telemetry/session-metrics.js';
+import { sessionReplacedReason } from '../session/facts/session-replaced.js';
+import { describeSkew, sdkFix, SkewPair } from '../../command/version/version-skew.js';
+import { noteVersionSkew } from '../../command/version/version-nudge.js';
+import { protocolSkewReason } from './protocol-skew.js';
+import { SERVER_VERSION } from '../../command/version/identity/server-version.js';
+/**
+ * Take the mutable half of a session's identity from a repeat HELLO.
+ *
+ * Lives here rather than on Session because this is where the protocol decision is made — the caller
+ * has already established that the hello belongs to this same session — and because these fields are
+ * the session's public surface, read by the tools on every listing.
+ *
+ * `hasCapabilities` is the one that matters: it is announced in the hello, which the SDK sends at
+ * connect(), while capabilities are registered AFTER connect by design (registerStore needs a live
+ * SDK to subscribe through). Without this refresh, an app that declared its entire testable surface
+ * reported `hasCapabilities: false` forever.
+ */
+function refreshIdentity(session, hello) {
+    session.url = hello.url;
+    session.title = hello.title;
+    session.adapters = hello.adapters;
+    session.hasCapabilities = hello.hasCapabilities ?? false;
+}
+/**
+ * The close reasons worth telling an AGENT about, not just the SDK.
+ *
+ * The SDK prints these and stops retrying. The agent then calls a tool and is told "no browser
+ * session connected" — which is indistinguishable from an app nobody started. An outdated SDK and a
+ * stale pairing token were both invisible for that reason; these two carry their own remedy, so
+ * surfacing them is strictly better than the generic answer.
+ */
+export const WS_CLOSE_REASON = {
+    /**
+     * The generic form. The live path picks a DIRECTION-aware reason instead (see protocol-skew.ts);
+     * this stays as the close-code table's label and as the fallback when the skew cannot be read.
+     */
+    PROTOCOL_MISMATCH: 'protocol version mismatch — @reticlehq/browser and server disagree',
+    AUTH_FAILED: 'authentication failed — restart the dev server; a reload keeps the old pairing token',
+    /**
+     * The daemon threw while handling a message. Closing is deliberate: an exception leaves the
+     * session in a state neither side can describe, and a socket left OPEN and unresponsive is the
+     * worst of the outcomes — the agent's next tool call reports "no browser session connected",
+     * which reads as an app nobody started. Closing at least makes the SDK reconnect and say so.
+     */
+    HANDLER_FAILED: 'the Reticle daemon failed handling a message — reload the page to reconnect',
+    /**
+     * The pool of half-open handshakes was full, so this dial was turned away before it could say
+     * anything. Every other refusal here records why and this one did not — it closed the socket and
+     * returned — so an app that was running, instrumented and actively dialling looked exactly like an
+     * app nobody had started, and the diagnosis went hunting a stopped dev server.
+     *
+     * Names the cause and the fact that it is transient, because the remedy differs from every other
+     * refusal on this path: nothing about the app is wrong and retrying is the correct response.
+     */
+    HANDSHAKE_POOL_FULL: 'refused at the handshake pool — too many connections were mid-handshake on this daemon, so ' +
+        'this dial never got to identify itself. Nothing is wrong with the app; the pool drains on its ' +
+        'own and reloading the page reconnects. If it persists, something else on this machine is ' +
+        'opening sockets to this port.',
+};
+/**
+ * A dial turned away at the ORIGIN gate, in words the reader can act on.
+ *
+ * This is the refusal that used to leave no trace anywhere. It happens before any HELLO, so it
+ * produced no `noteClosure`, no `session_disconnected`, nothing but an `origin_rejected` log line —
+ * and the daemon log is the file nobody opens until they have already lost the afternoon. Reported
+ * from a multi-tenant app resolving its tenant from the `Host` header: on a hosts-file alias every
+ * dial was refused here, `doctor` reported every check green, and the lease hint blamed the port.
+ *
+ * The origin is IN the message because it is the fix: it is either the alias to allow-list, or the
+ * proof that the page is not being served from where the developer thinks it is.
+ */
+function originRejectedReason(origin) {
+    const named = origin === undefined || 0 === origin.length ? 'a page sending no Origin' : origin;
+    return (`a browser dialled this daemon and was REFUSED at the origin gate: ${named} is not allowed. ` +
+        'Off localhost the SDK needs BOTH `allowNonLocalhost: true` AND a pairing token, and the ' +
+        'daemon needs that origin allow-listed (RETICLE_ALLOWED_ORIGINS). The app is running and ' +
+        'instrumented — it was turned away, so do not go looking for a stopped dev server.');
+}
+/** WS close codes + reasons the bridge sends to the SDK (1008 = policy violation, 1013 = try again later). */
+const WS_CLOSE = {
+    TOO_MANY_HANDSHAKES: [1013, 'too many pending handshakes'],
+    HELLO_TIMEOUT: [1008, 'hello timeout'],
+    INVALID_MESSAGE: [1008, 'invalid message'],
+    HELLO_DUPLICATE: [1008, 'hello already received'],
+    // AUTH_FAILED's code is 1008; the reason string is chosen at close time by authFailureReason
+    // (no token vs wrong token vs different project). A reload cannot mint a credential into a CDN
+    // snippet or a Next env frozen at config eval. Kept under the 123-byte close-reason limit.
+    AUTH_FAILED: [1008, WS_CLOSE_REASON.AUTH_FAILED],
+    SESSION_LIMIT: [1013, 'session limit reached'],
+    PROTOCOL_MISMATCH: [1008, WS_CLOSE_REASON.PROTOCOL_MISMATCH],
+    HANDLER_FAILED: [1011, WS_CLOSE_REASON.HANDLER_FAILED],
+};
+/** Parse a positive integer env override; anything else (unset, zero, junk) falls through to the default. */
+function positiveIntFromEnv(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+/** The flow name if this event is a panel ▶ replay request, else undefined. Pure boundary narrowing. */
+function replayRequest(event) {
+    if (event.type !== EventType.HUMAN_CONTROL)
+        return undefined;
+    if (event.data['kind'] !== HumanControlKind.REPLAY)
+        return undefined;
+    const name = event.data['text'];
+    return 'string' === typeof name && name.length > 0 ? name : undefined;
+}
+/**
+ * The desired harness state if this event is the panel's switch, else undefined.
+ *
+ * Carries `on`/`off` rather than meaning "toggle": a double-click on a flaky connection sends two,
+ * and two toggles land back where they started while two `on`s are the same as one.
+ */
+function harnessRequest(event) {
+    if (event.type !== EventType.HUMAN_CONTROL)
+        return undefined;
+    if (event.data['kind'] !== HumanControlKind.HARNESS)
+        return undefined;
+    const want = event.data['text'];
+    if ('on' === want)
+        return true;
+    if ('off' === want)
+        return false;
+    return undefined;
+}
+/** True when this event is the panel's "sync now" button. Pure boundary narrowing, like the above. */
+function isSyncRequest(event) {
+    return event.type === EventType.HUMAN_CONTROL && event.data['kind'] === HumanControlKind.SYNC;
+}
+/**
+ * Canonical comparable form of a WS `Origin`. Web origins collapse to scheme://host[:port]. An
+ * OPAQUE origin — a desktop webview (`tauri://localhost`, `app://.`) or `file://`, whose `URL.origin`
+ * is the string "null" — is kept VERBATIM instead, so it survives into the allow-list and can be
+ * compared. Collapsing those to "null" would both merge every desktop scheme into one bucket and
+ * feed an unparseable string to `new URL`. Returns null only for a header that is not an origin.
+ */
+function normalizeOrigin(origin) {
+    if (origin === OPAQUE_ORIGIN)
+        return OPAQUE_ORIGIN;
+    try {
+        const web = new URL(origin).origin;
+        return web === OPAQUE_ORIGIN ? origin : web;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * When a message fails the strict schema, detect the specific case of a HELLO whose protocolVersion
+ * differs from ours — so we can tell the operator "upgrade @reticlehq/browser" instead of dropping the
+ * connection into the generic NO_SESSION_CONNECTED path, which misdiagnoses it as a port mismatch.
+ * Returns the mismatched version, or null when it isn't a version-mismatched HELLO.
+ */
+function helloProtocolMismatch(text) {
+    try {
+        const json = JSON.parse(text);
+        if (json.kind === MessageKind.HELLO &&
+            'number' === typeof json.protocolVersion &&
+            json.protocolVersion !== RETICLE_PROTOCOL_VERSION) {
+            return json.protocolVersion;
+        }
+    }
+    catch {
+        /* not JSON — fall through to the generic invalid-message path */
+    }
+    return null;
+}
+/** Normalize ws RawData (string | Buffer | Buffer[] | ArrayBuffer) into a UTF-8 string. */
+function rawToString(raw) {
+    if ('string' === typeof raw)
+        return raw;
+    if (Array.isArray(raw))
+        return Buffer.concat(raw).toString('utf8');
+    if (raw instanceof ArrayBuffer)
+        return Buffer.from(raw).toString('utf8');
+    return raw.toString('utf8');
+}
+/**
+ * The browser-facing half of the relay: a localhost WebSocket server. Each connection
+ * announces itself with HELLO (registering a Session), then streams EVENTs and replies to
+ * COMMANDs.
+ */
+export class Bridge {
+    sessions = new SessionManager();
+    /** Resolves with the actually-bound port once the server is listening. */
+    ready;
+    #wss;
+    #clock;
+    #token;
+    /** Which source supplied #token — logged on a refusal so a mismatch names its own cause. */
+    #tokenSource;
+    /**
+     * Projects this daemon has ACCEPTED a session from. Evidence, not derivation: it is what lets a
+     * leaked daemon say "I belong to another project" instead of "authentication failed". See
+     * authFailureReason.
+     */
+    #servedProjects = new Set();
+    /** Session ids already counted in the impact record - a reconnect is not a new session. */
+    #countedSessions = new Set();
+    #allowedOrigins;
+    #maxMessagesPerSecond;
+    #maxSessions;
+    #maxPendingConnections;
+    #helloTimeoutMs;
+    #sdkFix;
+    #pendingConnections = 0;
+    #onReplay;
+    /**
+     * EVERY session-ready handler, not the most recent one.
+     *
+     * This was a single slot, and a second `attachSessionReady` silently replaced the first. Nothing
+     * threw and nothing went red — the earlier handler simply never ran again. It cost the
+     * `app_instrumented` metric on its first day: the call was wired correctly, registered before the
+     * flow-chip handler, and overwritten by it, so the event that measures whether an app was ever
+     * instrumented was permanently absent. Found by connecting a real session to a real daemon, which
+     * is the only thing that could have found it.
+     */
+    #onSessionReady = [];
+    /*
+     * A LIST, not a single slot.
+     *
+     * It held one handler, so a second `attachSessionCreate` silently replaced the first — and the
+     * first is what stamps a session's artifactRoot, without which every verdict is recorded against
+     * wherever the daemon was started. A registration API whose failure mode is "the previous caller
+     * stops working, quietly" is a trap; anything that needs to run on a new session now simply runs.
+     */
+    #onSessionCreate = [];
+    /** Fired when a session is removed — flushes its journal tail + persists what it learned. */
+    #onSessionEnd;
+    /** Wired by the daemon: push to the dashboard now, because somebody asked in the panel. */
+    #onSyncRequest;
+    #onHarnessRequest;
+    constructor(options) {
+        const host = options.host ?? LOOPBACK_HOST;
+        if ((options.token?.length ?? 0) > TRANSPORT_LIMITS.MAX_TOKEN_LENGTH) {
+            throw new Error(`Reticle pairing token exceeds ${String(TRANSPORT_LIMITS.MAX_TOKEN_LENGTH)} characters`);
+        }
+        if (!isLoopbackHostname(host) && (options.token === undefined || 0 === options.token.length)) {
+            throw new Error('a pairing token is required when the Reticle bridge binds beyond localhost');
+        }
+        this.#clock = options.clock ?? (() => Date.now());
+        this.#token =
+            options.token !== undefined && options.token.length > 0 ? options.token : undefined;
+        // Supplied by resolveBridgeSecurity, which is the only place that can tell an auto-provisioned
+        // token from one a caller passed — both arrive here as options.token. Defaulted rather than
+        // required so a directly-constructed Bridge (tests, embedders) still logs something true.
+        this.#tokenSource =
+            options.tokenSource ??
+                pairingTokenSource({
+                    explicit: options.token !== undefined && 0 < options.token.length,
+                    env: process.env,
+                });
+        // An entry that fails to normalize — typically a scheme-less `myapp.test` — used to be
+        // filtered out with no trace: the allow-list LOOKED configured, every dial from that origin
+        // was refused at the gate, and the refusal read as a scheme mismatch in the page rather than
+        // as a config value that was silently discarded. Warn at construction, naming the entry and
+        // the accepted form, so the config error surfaces at startup instead of as a mystery 403.
+        this.#allowedOrigins = new Set();
+        for (const entry of options.allowedOrigins ?? []) {
+            const normalized = normalizeOrigin(entry);
+            if (null === normalized) {
+                log('allowed_origin_ignored', {
+                    entry,
+                    warning: `${ReticleEnv.ALLOWED_ORIGINS} entry "${entry}" is not a valid origin and was ` +
+                        `IGNORED — an origin needs a scheme, e.g. "http://${entry}" (scheme://host[:port]).`,
+                });
+                continue;
+            }
+            this.#allowedOrigins.add(normalized);
+        }
+        // Binding beyond localhost means the browser dials in from a non-loopback Origin. With no
+        // allow-list, #originAllowed rejects every such Origin at the WS handshake, so the bridge comes
+        // up but accepts nothing — a silent, fail-closed footgun. Refuse to start with a clear message.
+        if (!isLoopbackHostname(host) && 0 === this.#allowedOrigins.size) {
+            throw new Error(`${ReticleEnv.ALLOWED_ORIGINS} must list the app origin(s) when the Reticle bridge binds ` +
+                'beyond localhost — otherwise every non-loopback browser is rejected at the WebSocket ' +
+                'origin check and no connection can be established.');
+        }
+        // Explicit option wins; then the env override, so a genuinely busy app can raise the ceiling
+        // instead of accepting sampled coverage. Free and local — the daemon runs on the same machine,
+        // so a higher cap costs nobody anything, which is also why this is not a paid knob.
+        this.#maxMessagesPerSecond =
+            options.maxMessagesPerSecond ??
+                positiveIntFromEnv(process.env[ReticleEnv.MAX_MESSAGES_PER_SECOND]) ??
+                TRANSPORT_LIMITS.MAX_MESSAGES_PER_SECOND;
+        this.#maxSessions = options.maxSessions ?? TRANSPORT_LIMITS.MAX_SESSIONS;
+        this.#maxPendingConnections =
+            options.maxPendingConnections ?? TRANSPORT_LIMITS.MAX_PENDING_CONNECTIONS;
+        this.#helloTimeoutMs = options.helloTimeoutMs ?? TRANSPORT_LIMITS.HELLO_TIMEOUT_MS;
+        this.#sdkFix = options.sdkFix ?? (() => sdkFix(SERVER_VERSION));
+        if (options.server !== undefined) {
+            const srv = options.server;
+            this.#wss = new WebSocketServer({
+                server: srv,
+                path: RETICLE_WS_PATH,
+                maxPayload: TRANSPORT_LIMITS.MAX_MESSAGE_BYTES,
+                verifyClient: ({ origin }, done) => {
+                    const allowed = this.#originAllowed(origin);
+                    if (!allowed)
+                        this.#noteOriginRejected(origin);
+                    done(allowed, 403, 'Forbidden');
+                },
+            });
+            // In shared-server mode the daemon owns listen; but a WebSocketServer bound to a server that
+            // fails to listen (EADDRINUSE) surfaces the error on the WS instance too. Without a listener
+            // that is an unhandled 'error' that can crash/hang the process — so absorb it here and reject
+            // `ready`, mirroring the standalone branch. The daemon's own listen handler reports the failure.
+            this.ready = new Promise((resolve, reject) => {
+                this.#wss.once('error', reject);
+                if (srv.listening) {
+                    this.#wss.removeListener('error', reject);
+                    resolve(srv.address().port);
+                }
+                else {
+                    srv.once('listening', () => {
+                        this.#wss.removeListener('error', reject);
+                        resolve(srv.address().port);
+                    });
+                }
+            });
+        }
+        else {
+            this.#wss = new WebSocketServer({
+                port: options.port,
+                host,
+                path: RETICLE_WS_PATH,
+                maxPayload: TRANSPORT_LIMITS.MAX_MESSAGE_BYTES,
+                verifyClient: ({ origin }, done) => {
+                    const allowed = this.#originAllowed(origin);
+                    if (!allowed)
+                        this.#noteOriginRejected(origin);
+                    done(allowed, 403, 'Forbidden');
+                },
+            });
+            // Reject on 'error' as well as resolve on 'listening'. A port collision (EADDRINUSE) emits
+            // 'error'; with no listener that becomes an unhandled 'error' (process crash) AND leaves
+            // `ready` pending forever. Surfacing it lets the CLI print "port already in use" cleanly.
+            this.ready = new Promise((resolve, reject) => {
+                this.#wss.once('error', reject);
+                this.#wss.on('listening', () => {
+                    this.#wss.removeListener('error', reject);
+                    resolve(this.#wss.address().port);
+                });
+            });
+        }
+        // A PERMANENT 'error' listener, on top of the one `ready` installs and then removes.
+        //
+        // `ws` re-emits every 'error' from the server it is attached to, and both `ready` branches above
+        // drop their listener the moment the port is bound. From then on the emitter is bare, and an
+        // EventEmitter that emits 'error' with no listener THROWS — which in the daemon is an
+        // uncaughtException, which is an exit, which takes every agent and every session on this port
+        // with it. Logging one is all it takes; the transport itself needs no other reaction.
+        this.#wss.on('error', (err) => {
+            log('bridge_ws_error', { error: err.message });
+        });
+        this.#wss.on('connection', (socket) => {
+            this.#onConnection(socket);
+        });
+    }
+    #onConnection(socket) {
+        if (this.#pendingConnections >= this.#maxPendingConnections) {
+            // On the channel the no-session diagnosis reads, not only into the log. This refusal happens
+            // before any HELLO, so without it the dial leaves no trace at all — the same hole the origin
+            // gate had, and the same fix.
+            this.sessions.noteClosure(WS_CLOSE_REASON.HANDSHAKE_POOL_FULL, this.#clock());
+            log('bridge_handshake_pool_full', { pending: this.#pendingConnections });
+            socket.close(...WS_CLOSE.TOO_MANY_HANDSHAKES);
+            return;
+        }
+        this.#pendingConnections += 1;
+        let awaitingHello = true;
+        let session;
+        let messageWindowStartedAt = this.#clock();
+        let messagesInWindow = 0;
+        let highValueInWindow = 0;
+        const highValueReserve = Math.ceil(this.#maxMessagesPerSecond * RATE_CAP_HIGH_VALUE_RESERVE_RATIO);
+        const releasePending = () => {
+            if (!awaitingHello)
+                return;
+            awaitingHello = false;
+            this.#pendingConnections -= 1;
+        };
+        const helloTimer = setTimeout(() => {
+            if (!awaitingHello)
+                return;
+            releasePending();
+            socket.close(...WS_CLOSE.HELLO_TIMEOUT);
+        }, this.#helloTimeoutMs);
+        let droppedByRate = 0;
+        /*
+         * Everything below runs inside a guard, because a throw here used to leave the socket OPEN and
+         * unresponsive. Every other refusal in this file is careful to say WHY it closed, precisely so a
+         * failure is not mistaken for an app nobody started — and an unhandled exception silently
+         * produced that exact indistinguishable state. Measured: one undefined import turned into a test
+         * that timed out waiting for a close, with no error surfacing anywhere.
+         */
+        socket.on('message', (raw) => {
+            try {
+                const now = this.#clock();
+                if (now - messageWindowStartedAt >= 1000) {
+                    messageWindowStartedAt = now;
+                    messagesInWindow = 0;
+                    highValueInWindow = 0;
+                }
+                messagesInWindow += 1;
+                const overRate = messagesInWindow > this.#maxMessagesPerSecond;
+                const text = rawToString(raw);
+                const parsed = this.#parse(text);
+                if (null === parsed) {
+                    const got = helloProtocolMismatch(text);
+                    if (got !== null) {
+                        log('protocol_version_mismatch', { got, expected: RETICLE_PROTOCOL_VERSION });
+                        /*
+                         * Name the component that is actually stale.
+                         *
+                         * This used to send one fixed "upgrade @reticlehq/browser" whichever way the versions
+                         * disagreed, and the skew seen in practice runs the other way — a current SDK in the app
+                         * dialling a daemon npx served from cache. Advice naming the wrong component is worse than
+                         * none: the user upgrades what was already current, sees no change, and blames the tool.
+                         */
+                        const reason = protocolSkewReason(got, RETICLE_PROTOCOL_VERSION);
+                        // Told to the AGENT too, not only to the SDK that is about to stop retrying. Without this
+                        // the next tool call answers "no browser session connected", which reads as "no app is
+                        // running" — so an SDK too old to connect is invisible.
+                        this.sessions.noteClosure(reason, this.#clock());
+                        socket.close(WS_CLOSE.PROTOCOL_MISMATCH[0], reason);
+                        return;
+                    }
+                    socket.close(...WS_CLOSE.INVALID_MESSAGE);
+                    return;
+                }
+                // Over the cap we SAMPLE — we never disconnect. Going blind is the one thing an observability
+                // layer must not do when it sees too much, and the close was a policy code the SDK correctly
+                // never retries: the app kept running and Reticle was blind from that instant, on exactly the
+                // busiest apps. Measured: each request emits two messages (pending + settled), so the cap binds
+                // at ~500 requests/second — a dashboard burst reaches it, a streaming app lives above it.
+                //
+                // Only EVENTS are dropped. A dropped hello would strand the session and a dropped
+                // command_result would hang the agent's in-flight call, so control traffic is always processed
+                // however fast it arrives — the cap exists to bound observation, not to break the protocol.
+                // Over the cap we drop by VALUE, not by arrival order. Volume is inversely correlated with
+                // value — a render-commit storm is thousands/second while the network call an assertion turns
+                // on is one — so first-come-first-dropped spends the budget on churn and loses the signal.
+                // High-value kinds get a bounded reserve on top of the cap; see event-priority.ts.
+                if (overRate && parsed.kind === MessageKind.EVENT) {
+                    const withinReserve = isHighValueEvent(parsed.event.type) && highValueInWindow < highValueReserve;
+                    if (withinReserve) {
+                        highValueInWindow += 1;
+                    }
+                    else {
+                        droppedByRate += 1;
+                        if (session !== undefined)
+                            session.noteRateLimited(droppedByRate);
+                        return;
+                    }
+                }
+                if (parsed.kind === MessageKind.HELLO) {
+                    if (session !== undefined) {
+                        // A repeat hello on the SAME socket for the SAME session is an identity refresh, not a
+                        // violation: the SDK re-announces when the app registers capabilities, which happens after
+                        // connect by design. Closing the socket on it made `hasCapabilities` permanently false for
+                        // every app that declared anything. A hello bearing a DIFFERENT session id is still a
+                        // protocol violation — that is the case this guard exists for.
+                        if (parsed.sessionId !== session.id) {
+                            socket.close(...WS_CLOSE.HELLO_DUPLICATE);
+                            return;
+                        }
+                        refreshIdentity(session, parsed);
+                        return;
+                    }
+                    if (this.#token !== undefined && !tokensMatch(this.#token, parsed.token)) {
+                        // A daemon left running by ANOTHER project answers this app and rejects it on token. The
+                        // token is not wrong, it is somebody else's — and "authentication failed" sends the user to
+                        // check the one thing that is fine. See auth-failure-reason.
+                        const reason = authFailureReason(this.#servedProjects, parsed.projectId, parsed.token);
+                        // The token SOURCE, never the token. A refusal here has no other witness: the value is
+                        // machine-level on both sides, so the daemon's cwd cannot explain a mismatch (#685) and
+                        // the only thing that can is the environment the two processes were started in — which
+                        // differs exactly when an IDE spawns the MCP server globally instead of from the shell
+                        // that launched the dev server.
+                        log('authentication_failed', {
+                            served: [...this.#servedProjects],
+                            ...(parsed.projectId === undefined ? {} : { helloProject: parsed.projectId }),
+                            presented: parsed.token !== undefined && 0 < parsed.token.length,
+                            tokenSource: this.#tokenSource,
+                        });
+                        this.sessions.noteClosure(reason, this.#clock());
+                        socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
+                        return;
+                    }
+                    const existing = this.sessions.get(parsed.sessionId);
+                    if (existing === undefined && this.sessions.count() >= this.#maxSessions) {
+                        socket.close(...WS_CLOSE.SESSION_LIMIT);
+                        return;
+                    }
+                    clearTimeout(helloTimer);
+                    releasePending();
+                    session = new Session(parsed, socket, this.#clock);
+                    // Recorded on ACCEPTANCE, so it is evidence of what this daemon really serves.
+                    if (parsed.projectId !== undefined)
+                        this.#servedProjects.add(parsed.projectId);
+                    // Attach the durable journal (and anything else registered) before any events stream in.
+                    // One throwing handler must not stop the others, or the order of registration would decide
+                    // which features survive a bad frame.
+                    for (const handler of this.#onSessionCreate) {
+                        try {
+                            handler(session);
+                        }
+                        catch {
+                            /* a handler that failed is not a reason to drop the session */
+                        }
+                    }
+                    // A tab that has just connected has no impact record yet, so the report would read "nothing
+                    // recorded" over a file with a month of history in it. Push what is already on disk as soon
+                    // as there is somewhere to push it to; a session is also a thing that HAPPENED, so it counts.
+                    // A reconnecting tab keeps its id, so counting every connect made a page reload look like
+                    // a fresh session - the number climbed while nothing new happened.
+                    if (!this.#countedSessions.has(session.id)) {
+                        this.#countedSessions.add(session.id);
+                        // Against this session's OWN project. Counted here rather than at the chokepoint because
+                        // a connect is not a tool call, and a session that connects and is never driven is still
+                        // that project's session — not the daemon's.
+                        recordImpact({ sessions: 1 }, {}, session.artifactRoot);
+                    }
+                    // ...and the tab is shown its own project's numbers. Captured into a const so the closure
+                    // cannot be read as capturing a reassignable binding that TS believes may be undefined.
+                    const attached = session;
+                    attached.pushImpact(() => impactSnapshot(attached.artifactRoot), true);
+                    const replaced = this.sessions.add(session);
+                    // Said out loud once the session is actually in the registry, never before: a hook that
+                    // fires on a session a consumer cannot then look up describes a moment that did not happen.
+                    emitSessionHook(HookEvent.SESSION_STARTED, {
+                        id: attached.id,
+                        url: attached.url,
+                        runtime: attached.runtime,
+                    });
+                    if (replaced !== undefined) {
+                        // Name the newcomer. "session replaced by a newer connection" says a replacement
+                        // happened but not BY WHAT, so the cause has to be inferred. A session is only ever
+                        // replaced by one carrying the SAME id, and knowing which URL claimed it is the
+                        // difference between a diagnosis and a guess.
+                        log('session_replaced', {
+                            sessionId: session.id,
+                            byUrl: session.url,
+                            previousUrl: replaced.url,
+                        });
+                        // Hand the displaced session its replacement BEFORE ending it, so a tool call still holding
+                        // the old handle can finish against the live connection instead of returning an error whose
+                        // only answer is to go and rediscover an id that has not changed. See Session.succeededBy.
+                        replaced.succeededBy(session);
+                        replaced.disconnect(sessionReplacedReason(session.id, session.url), true);
+                    }
+                    // The daemon is the single judge of skew, and HELLO is where the page announces itself.
+                    // Reported on the session (reticle_sessions) AND queued for the next tool result, because an
+                    // agent driving a flow never calls reticle_sessions and would never learn.
+                    const skew = describeSkew({
+                        what: 'the page',
+                        version: parsed.sdkVersion,
+                        contract: parsed.contract,
+                        // What the page SPEAKS, when it is new enough to say. Forwarded so `describeSkew` can
+                        // compare names instead of hashes — the branch that was written for this and had no
+                        // producer until the SDK started sending it.
+                        ...(parsed.contractParts === undefined
+                            ? {}
+                            : { contractParts: parsed.contractParts }),
+                        fix: this.#sdkFix(),
+                    }, {
+                        version: SERVER_VERSION,
+                        contract: CONTRACT_FINGERPRINT,
+                        contractParts: CONTRACT_PARTS,
+                    });
+                    // Kept so a remedy can check whether it applies to THIS page — see body-capture-remedy.
+                    session.sdkVersion = parsed.sdkVersion;
+                    session.captureBodies = parsed.captureBodies;
+                    // What this page says it is watching. Read at assert time to refuse a claim that needs
+                    // a channel nobody declared, rather than answering it with an empty result that reads
+                    // exactly like the value not being there.
+                    session.channels = parsed.channels;
+                    // What it will answer, read at dispatch time so a command the page does not serve is
+                    // refused instead of waited out.
+                    //
+                    // `parsed.platform` is deliberately NOT kept. It is a protocol field and it is correct
+                    // on the wire, but this daemon already learns the runtime from the health event and has
+                    // no decision that needs the answer sooner. Storing it would be a handshake fact nobody
+                    // reads, which is the shape this codebase has now produced twice in one week -- see
+                    // handshake-facts-are-read.test.ts, which exists because of it.
+                    session.commands = parsed.commands;
+                    if (skew !== undefined) {
+                        log('version_skew', {
+                            sessionId: session.id,
+                            sdk: parsed.sdkVersion,
+                            daemon: SERVER_VERSION,
+                        });
+                        session.versionSkew = skew;
+                        noteVersionSkew(SkewPair.SDK, skew);
+                    }
+                    log('session_connected', { sessionId: session.id, url: session.url });
+                    // The one fact that separates a broken install from an unused one. Best-effort and wrapped:
+                    // a metric must never affect whether an app can connect. See SessionSummary.appConnects.
+                    try {
+                        getSessionMetrics().recordAppConnected();
+                    }
+                    catch {
+                        /* never let a counter interfere with an app connecting */
+                    }
+                    // Each handler is independent, so one throwing must not cost the others their turn.
+                    for (const onReady of this.#onSessionReady) {
+                        try {
+                            onReady(session);
+                        }
+                        catch {
+                            /* a session-ready observer must never break the session it observes */
+                        }
+                    }
+                    return;
+                }
+                if (session === undefined)
+                    return;
+                session.touch();
+                if (parsed.kind === MessageKind.EVENT) {
+                    // A panel ▶ replay needs the daemon's flow store, which the Session can't reach — route it to
+                    // the daemon-wired handler instead of the in-session control path. Everything else is normal.
+                    const replay = replayRequest(parsed.event);
+                    // Narrowed before the chain, not inside it: the result is needed by the branch AND by the
+                    // test that decides whether this is a panel control at all, and calling it twice would
+                    // invite the two calls to disagree.
+                    const harness = harnessRequest(parsed.event);
+                    if (replay !== undefined)
+                        this.#onReplay?.(session.id, replay);
+                    // Same shape as ▶ replay, and routed the same way: what to push lives in the daemon's
+                    // cloud wiring, which a Session cannot reach. Nothing is awaited — the panel is telling
+                    // us to hurry, not asking for a result.
+                    else if (isSyncRequest(parsed.event))
+                        this.#onSyncRequest?.();
+                    // The switch is written through to the platform by the daemon, for the same reason: the
+                    // Session has no cloud credential and should not grow one.
+                    else if (harness !== undefined)
+                        this.#onHarnessRequest?.(harness);
+                    // Pass the raw frame's byte length so the buffer doesn't re-serialize every event for accounting.
+                    else
+                        session.pushEvent(parsed.event, Buffer.byteLength(text, 'utf8'));
+                }
+                else if (parsed.kind === MessageKind.COMMAND_RESULT) {
+                    session.handleResult(parsed);
+                }
+            }
+            catch (err) {
+                log('message_handler_failed', { error: err instanceof Error ? err.message : String(err) });
+                // Never let the close path throw too — that would restore the hang this guard removes.
+                try {
+                    socket.close(...WS_CLOSE.HANDLER_FAILED);
+                }
+                catch {
+                    socket.terminate();
+                }
+            }
+        });
+        socket.on('close', () => {
+            clearTimeout(helloTimer);
+            releasePending();
+            if (session !== undefined) {
+                const ended = session;
+                if (this.sessions.remove(ended)) {
+                    log('session_disconnected', { sessionId: ended.id });
+                    // Best-effort teardown: flush the journal tail + persist ambient learning. Never awaited here
+                    // (the socket is already closing) and never allowed to reject into the close handler.
+                    void this.#onSessionEnd?.(ended).catch(() => undefined);
+                    // AFTER teardown is started, and deliberately not awaited on it. The payload says a
+                    // session ended, which is already true here; making it wait for the journal flush would
+                    // put a hook in the path of a socket close for no gain to the consumer.
+                    emitSessionHook(HookEvent.SESSION_ENDED, {
+                        id: ended.id,
+                        url: ended.url,
+                        runtime: ended.runtime,
+                    });
+                }
+            }
+        });
+        socket.on('error', (err) => {
+            log('socket_error', { error: err.message });
+        });
+    }
+    /**
+     * Record a refused dial where something OTHER than the daemon log can read it.
+     *
+     * The log line stays — it is the forensic record — but a line in `~/.reticle/daemon-<port>.log` is
+     * invisible to the agent that is, at that exact moment, being told "no browser session connected"
+     * with no reason attached. `noteClosure` is the channel the no-session diagnosis already reads, so
+     * the refusal now travels the same route as an auth failure and a protocol mismatch, and the loop
+     * (the reason is only in the page console; the console needs a session; the refusal prevents one)
+     * is broken from the daemon side.
+     */
+    #noteOriginRejected(origin) {
+        log('origin_rejected', { origin: origin ?? 'missing' });
+        this.sessions.noteClosure(originRejectedReason(origin), this.#clock());
+    }
+    #originAllowed(origin) {
+        // A real browser SDK connection always carries an Origin. A missing Origin means a non-browser
+        // local process (another app, a malicious npm postinstall, an extension's native host) — untrusted
+        // unless a pairing token is required, in which case the HELLO token check is the real gate.
+        if (origin === undefined)
+            return this.#token !== undefined;
+        const normalized = normalizeOrigin(origin);
+        if (null === normalized)
+            return false;
+        if (this.#allowedOrigins.has(normalized))
+            return true;
+        // A desktop webview (Electron, Tauri) or a file:// document sends an opaque Origin: no host to
+        // check, so it is exactly as attributable as a missing Origin — defer to the token, as above.
+        // Without this branch `new URL` throws INSIDE the WS upgrade handler, crashing the process.
+        if (isOpaqueOrigin(normalized))
+            return this.#token !== undefined;
+        // `isLocalPage`, not `isLoopbackHostname` — the SAME rule the SDK applies on the page side.
+        //
+        // They had drifted, and the drift made a whole platform unreachable. Tauri v2 uses an opaque
+        // `tauri://localhost` on macOS/Linux, but on WINDOWS the webview needs a real http origin and
+        // Tauri serves `http://tauri.localhost`. `isLocalPage` was taught that hostname; this check was
+        // not. So a Windows Tauri app passed its own gate, dialed the bridge, and every handshake came
+        // back 403 — Reticle could not connect to a Tauri app on Windows at all, which is precisely the
+        // platform the release notes admitted had never been executed.
+        //
+        // No weaker than before: `.localhost` is reserved for loopback by RFC 6761, so the name cannot
+        // resolve to a remote host, and this is the argument core already made when it accepted the same
+        // hostname for the page.
+        const url = new URL(normalized);
+        return isLocalPage(url.protocol, url.hostname);
+    }
+    #parse(text) {
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        const result = ReticleMessageSchema.safeParse(json);
+        if (!result.success) {
+            log('bad_message', { issues: result.error.issues.length });
+            return null;
+        }
+        return result.data;
+    }
+    /** Register the daemon's handler for a panel ▶ replay (it owns the flow store). */
+    attachReplay(handler) {
+        this.#onReplay = handler;
+    }
+    /**
+     * Register a callback fired when a browser session connects.
+     *
+     * ADDITIVE: every registered handler runs. Assigning to one slot meant the last caller silently
+     * won and every earlier one stopped firing — see the field declaration.
+     */
+    attachSessionReady(handler) {
+        this.#onSessionReady.push(handler);
+    }
+    /** Register a callback fired the instant a session is created — used to attach the durable journal. */
+    /**
+     * Teardown handler fired when a session is removed (tab closed/disconnected). Without it the journal's
+     * batched tail (< one flush batch) never reaches disk and the learned ambient map is discarded.
+     */
+    attachSessionEnd(handler) {
+        this.#onSessionEnd = handler;
+    }
+    /**
+     * Register what to do when the panel's sync button is pressed.
+     *
+     * Optional, like every other panel-routed handler here: a bridge built without one simply ignores
+     * the request rather than refusing it, which is the right behaviour for a button whose whole job
+     * is to make something happen sooner than it already would.
+     */
+    attachSyncRequest(handler) {
+        this.#onSyncRequest = handler;
+    }
+    /**
+     * Register a handler for the panel's harness switch. Optional for the same reason as the above: a
+     * bridge built without one ignores the request rather than refusing it.
+     */
+    attachHarnessRequest(handler) {
+        this.#onHarnessRequest = handler;
+    }
+    /** Register a handler to run when a session connects. Additive — every handler runs. */
+    attachSessionCreate(handler) {
+        this.#onSessionCreate.push(handler);
+    }
+    close() {
+        return new Promise((resolve) => {
+            for (const client of this.#wss.clients)
+                client.terminate();
+            this.#wss.close(() => {
+                resolve();
+            });
+        });
+    }
+}