@reticlehq/server 2.12.0 → 2.13.0

package/dist/bridge/bridge.js

@@ -9,6 +9,7 @@ import { log } from '../log.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { describeSkew, sdkFix, SkewPair } from '../version/version-skew.js';
 import { noteVersionSkew } from '../version/version-nudge.js';
+import { protocolSkewReason } from './protocol-skew.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 /**
  * Take the mutable half of a session's identity from a repeat HELLO.
@@ -37,8 +38,19 @@ function refreshIdentity(session, hello) {
  * surfacing them is strictly better than the generic answer.
  */
 export const WS_CLOSE_REASON = {
-    PROTOCOL_MISMATCH: 'protocol version mismatch — upgrade @reticlehq/browser',
+    /**
+     * 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 — reload the page to pick up the current 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
@@ -78,13 +90,13 @@ const WS_CLOSE = {
     HELLO_TIMEOUT: [1008, 'hello timeout'],
     INVALID_MESSAGE: [1008, 'invalid message'],
     HELLO_DUPLICATE: [1008, 'hello already received'],
-    // Names the recovery, because the SDK prints this reason and then stops retrying — so it is the
-    // last thing the developer sees. The common cause is a page served before the daemon existed,
-    // which carries no token; a reload re-fetches the connect module and picks the current one up.
-    // Kept under the 123-byte WebSocket close-reason limit.
+    // 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) {
@@ -175,6 +187,7 @@ export class Bridge {
     #maxSessions;
     #maxPendingConnections;
     #helloTimeoutMs;
+    #sdkFix;
     #pendingConnections = 0;
     #onReplay;
     /**
@@ -188,7 +201,15 @@ export class Bridge {
      * is the only thing that could have found it.
      */
     #onSessionReady = [];
-    #onSessionCreate;
+    /*
+     * 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;
     constructor(options) {
@@ -202,9 +223,24 @@ export class Bridge {
         this.#clock = options.clock ?? (() => Date.now());
         this.#token =
             options.token !== undefined && options.token.length > 0 ? options.token : undefined;
-        this.#allowedOrigins = new Set((options.allowedOrigins ?? [])
-            .map(normalizeOrigin)
-            .filter((origin) => origin !== null));
+        // 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.
@@ -224,6 +260,7 @@ export class Bridge {
         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({
@@ -323,176 +360,221 @@ export class Bridge {
             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) => {
-            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 });
-                    // 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(WS_CLOSE_REASON.PROTOCOL_MISMATCH, this.#clock());
-                    socket.close(...WS_CLOSE.PROTOCOL_MISMATCH);
-                    return;
+            try {
+                const now = this.#clock();
+                if (now - messageWindowStartedAt >= 1000) {
+                    messageWindowStartedAt = now;
+                    messagesInWindow = 0;
+                    highValueInWindow = 0;
                 }
-                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);
+                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;
                 }
-            }
-            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);
+                // 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;
                     }
-                    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);
-                    log('authentication_failed', {
-                        served: [...this.#servedProjects],
-                        ...(parsed.projectId === undefined ? {} : { helloProject: parsed.projectId }),
-                    });
-                    this.sessions.noteClosure(WS_CLOSE_REASON.AUTH_FAILED, this.#clock());
-                    socket.close(WS_CLOSE.AUTH_FAILED[0], reason);
+                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);
+                        log('authentication_failed', {
+                            served: [...this.#servedProjects],
+                            ...(parsed.projectId === undefined ? {} : { helloProject: parsed.projectId }),
+                            presented: parsed.token !== undefined && 0 < parsed.token.length,
+                        });
+                        this.sessions.noteClosure(WS_CLOSE_REASON.AUTH_FAILED, 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);
+                    if (replaced !== undefined) {
+                        // Name the newcomer. A field report had a live session vanish during `reticle_lease` and the
+                        // only evidence was "session replaced by a newer connection" in the page console — which
+                        // says a replacement happened but not BY WHAT, so the cause had 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(`session replaced by a newer connection claiming the same id (${session.id}) from ${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,
+                        fix: this.#sdkFix(),
+                    }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
+                    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;
                 }
-                const existing = this.sessions.get(parsed.sessionId);
-                if (existing === undefined && this.sessions.count() >= this.#maxSessions) {
-                    socket.close(...WS_CLOSE.SESSION_LIMIT);
+                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);
+                    if (replay !== undefined)
+                        this.#onReplay?.(session.id, replay);
+                    // 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'));
                 }
-                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);
-                this.#onSessionCreate?.(session); // attach the durable journal before any events stream in
-                // 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);
-                    recordImpact({ sessions: 1 });
-                }
-                session.pushImpact(impactSnapshot, true);
-                const replaced = this.sessions.add(session);
-                if (replaced !== undefined) {
-                    // Name the newcomer. A field report had a live session vanish during `reticle_lease` and the
-                    // only evidence was "session replaced by a newer connection" in the page console — which
-                    // says a replacement happened but not BY WHAT, so the cause had 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(`session replaced by a newer connection claiming the same id (${session.id}) from ${session.url}`);
+                else if (parsed.kind === MessageKind.COMMAND_RESULT) {
+                    session.handleResult(parsed);
                 }
-                // 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,
-                    fix: sdkFix(SERVER_VERSION),
-                }, { version: SERVER_VERSION, contract: CONTRACT_FINGERPRINT });
-                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.
+            }
+            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 {
-                    getSessionMetrics().recordAppConnected();
+                    socket.close(...WS_CLOSE.HANDLER_FAILED);
                 }
                 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 */
-                    }
+                    socket.terminate();
                 }
-                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);
-                if (replay !== undefined)
-                    this.#onReplay?.(session.id, replay);
-                // 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);
             }
         });
         socket.on('close', () => {
@@ -593,8 +675,9 @@ export class Bridge {
     attachSessionEnd(handler) {
         this.#onSessionEnd = handler;
     }
+    /** Register a handler to run when a session connects. Additive — every handler runs. */
     attachSessionCreate(handler) {
-        this.#onSessionCreate = handler;
+        this.#onSessionCreate.push(handler);
     }
     close() {
         return new Promise((resolve) => {

package/dist/bridge/pairing-token.d.ts

@@ -25,3 +25,8 @@ export declare function nodePairingTokenDeps(): PairingTokenDeps;
  * fails, so the caller degrades to the prior tokenless behavior rather than bricking the daemon.
  */
 export declare function readOrCreatePairingToken(dir: string, deps: PairingTokenDeps): Promise<string | undefined>;
+/**
+ * Sync twin of `readOrCreatePairingToken`. `reticle init` and Next's `withReticle` are both
+ * synchronous, and a snippet printed with no token is a page that can never authenticate.
+ */
+export declare function readOrCreatePairingTokenSync(dir: string): string | undefined;

package/dist/bridge/pairing-token.js

@@ -1,4 +1,5 @@
 import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -59,3 +60,30 @@ export async function readOrCreatePairingToken(dir, deps) {
         return undefined;
     }
 }
+/**
+ * Sync twin of `readOrCreatePairingToken`. `reticle init` and Next's `withReticle` are both
+ * synchronous, and a snippet printed with no token is a page that can never authenticate.
+ */
+export function readOrCreatePairingTokenSync(dir) {
+    const path = pairingTokenPath(dir);
+    try {
+        const existing = readFileSync(path, 'utf8').trim();
+        if (existing.length > 0)
+            return existing;
+    }
+    catch {
+        /* missing or unreadable — fall through and create one */
+    }
+    try {
+        const token = randomBytes(TOKEN_BYTES).toString('hex');
+        if (0 === token.length)
+            return undefined;
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(path, token, { encoding: 'utf8', mode: 0o600 });
+        chmodSync(path, 0o600);
+        return token;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/bridge/protocol-skew.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Which side of a protocol mismatch is the stale one, and therefore what to tell the user to do.
+ *
+ * The close reason was a single fixed string — "upgrade @reticlehq/browser" — sent whichever way the
+ * versions disagreed. That is correct only when the page is BEHIND the daemon, and the common real
+ * skew runs the other way: the app's package.json pulls a current `@reticlehq/browser` while the
+ * daemon is an older `@reticlehq/server` that npx resolved from cache. Observed in this repo's own
+ * logs as `got: 2, expected: 1` — a browser two steps ahead, told to upgrade itself.
+ *
+ * Advice that names the wrong component is worse than none: the user upgrades the thing that was
+ * already current, sees no change, and concludes the tool is broken.
+ *
+ * Kept short on purpose — a WebSocket close reason is capped at 123 BYTES, and a reason that
+ * overflows is dropped by the socket layer, which would take the diagnosis with it.
+ *
+ * NOT a duplicate of `version/version-skew.ts`, and the two should not be merged. That module
+ * describes peers which connected SUCCESSFULLY and then disagree about behaviour, so it has both
+ * versions and a wire-contract fingerprint to reason from and a whole sentence to say it in. This
+ * one runs where the hello was rejected outright: the connection never forms, a single integer is
+ * all that is known, and the answer has to fit in a close frame. The remedies are worded to match
+ * that module's, because a user who hits both should not be told two different things.
+ */
+/** The page is older than the daemon: its SDK cannot speak the protocol the daemon expects. */
+export declare const BROWSER_IS_OLDER = "protocol mismatch \u2014 upgrade @reticlehq/browser in this app";
+/** The daemon is older than the page. Usually an npx cache serving a stale @reticlehq/server. */
+export declare const DAEMON_IS_OLDER = "protocol mismatch \u2014 the daemon is older; run `reticle stop`, then retry";
+/** The versions disagree but not in a direction we can read. */
+export declare const SKEW_UNKNOWN = "protocol version mismatch \u2014 @reticlehq/browser and server disagree";
+/** The cap a WebSocket close reason must fit inside, in bytes. */
+export declare const CLOSE_REASON_MAX_BYTES = 123;
+/**
+ * Name the stale component, given what the page announced and what this daemon speaks.
+ *
+ * `got` is the page's protocol version, `expected` is the daemon's. A `got` we could not read at
+ * all falls back to naming both, which is vague but never actively misleading.
+ */
+export declare const protocolSkewReason: (got: number | null, expected: number) => string;

package/dist/bridge/protocol-skew.js

@@ -0,0 +1,45 @@
+/**
+ * Which side of a protocol mismatch is the stale one, and therefore what to tell the user to do.
+ *
+ * The close reason was a single fixed string — "upgrade @reticlehq/browser" — sent whichever way the
+ * versions disagreed. That is correct only when the page is BEHIND the daemon, and the common real
+ * skew runs the other way: the app's package.json pulls a current `@reticlehq/browser` while the
+ * daemon is an older `@reticlehq/server` that npx resolved from cache. Observed in this repo's own
+ * logs as `got: 2, expected: 1` — a browser two steps ahead, told to upgrade itself.
+ *
+ * Advice that names the wrong component is worse than none: the user upgrades the thing that was
+ * already current, sees no change, and concludes the tool is broken.
+ *
+ * Kept short on purpose — a WebSocket close reason is capped at 123 BYTES, and a reason that
+ * overflows is dropped by the socket layer, which would take the diagnosis with it.
+ *
+ * NOT a duplicate of `version/version-skew.ts`, and the two should not be merged. That module
+ * describes peers which connected SUCCESSFULLY and then disagree about behaviour, so it has both
+ * versions and a wire-contract fingerprint to reason from and a whole sentence to say it in. This
+ * one runs where the hello was rejected outright: the connection never forms, a single integer is
+ * all that is known, and the answer has to fit in a close frame. The remedies are worded to match
+ * that module's, because a user who hits both should not be told two different things.
+ */
+/** The page is older than the daemon: its SDK cannot speak the protocol the daemon expects. */
+export const BROWSER_IS_OLDER = 'protocol mismatch — upgrade @reticlehq/browser in this app';
+/** The daemon is older than the page. Usually an npx cache serving a stale @reticlehq/server. */
+export const DAEMON_IS_OLDER = 'protocol mismatch — the daemon is older; run `reticle stop`, then retry';
+/** The versions disagree but not in a direction we can read. */
+export const SKEW_UNKNOWN = 'protocol version mismatch — @reticlehq/browser and server disagree';
+/** The cap a WebSocket close reason must fit inside, in bytes. */
+export const CLOSE_REASON_MAX_BYTES = 123;
+/**
+ * Name the stale component, given what the page announced and what this daemon speaks.
+ *
+ * `got` is the page's protocol version, `expected` is the daemon's. A `got` we could not read at
+ * all falls back to naming both, which is vague but never actively misleading.
+ */
+export const protocolSkewReason = (got, expected) => {
+    if (null === got || !Number.isFinite(got))
+        return SKEW_UNKNOWN;
+    if (got < expected)
+        return BROWSER_IS_OLDER;
+    if (got > expected)
+        return DAEMON_IS_OLDER;
+    return SKEW_UNKNOWN;
+};