@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/recall/memory-tools.js

@@ -0,0 +1,81 @@
+/**
+ * `reticle_memory` — ask the project what it already knows.
+ *
+ * Shared memory reached three callers before this one: the sync writes it, flow replay consults it
+ * automatically, and `reticle memory` prints it at a terminal. The one who could not ask was the
+ * agent doing the work — mid-drive, holding a question, with a whole tool surface and nothing on it
+ * for "what has this team already established about checkout?".
+ *
+ * That matters twice over. An agent that can read the corpus stops re-deriving what a colleague
+ * proved last week; and because the read is attributed, the coverage map's fetch counts finally
+ * measure something rather than staying at zero because consulting the corpus was a separate act.
+ */
+import { z } from 'zod';
+import { ReticleTool } from '@reticlehq/core';
+import { countSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { asNumber, asString } from '@reticlehq/core';
+import { sessionRoot } from '../project/session-root.js';
+import { MemoryUnavailable, readProjectMemory } from './project-memory.js';
+import { homedir } from 'node:os';
+/**
+ * Enough to orient on, not enough to flood a context.
+ *
+ * A busy subject on a real project runs to dozens of statements; an agent asking a question wants
+ * the ones that settle it. `total` always rides along, so the cap is never silent.
+ */
+const DEFAULT_LIMIT = 10;
+/** What to do next, per reason. A refusal that does not say how to fix it is a dead end. */
+const ADVICE = {
+    [MemoryUnavailable.NOT_LINKED]: 'this project is not linked to a Reticle workspace, so there is no shared memory to read. Run `npx @reticlehq/server login` in the project to link it.',
+    [MemoryUnavailable.DISABLED]: 'this project is linked but memory sync is turned off in .reticle/cloud.json, so nothing is being shared. Enable `sync.memory` to use it.',
+    [MemoryUnavailable.UNREACHABLE]: 'the workspace could not be reached, or refused the key. Nothing is wrong with this project — try again, or check the link with `reticle status`.',
+};
+export const MEMORY_TOOLS = [
+    {
+        name: ReticleTool.MEMORY,
+        description: 'Ask what THIS PROJECT already knows — the shared memory its team has built up, written by every engineer who verified something and readable by every agent since. Use it BEFORE re-deriving how a feature is supposed to behave: a colleague may already have proved it, and a statement marked `proved` was established by a real verdict rather than written down. With { subject } it narrows to one area (a flow name, or a route like "checkout"); without, it returns across the project. Each entry carries the flow and the source file it is about, so a claim can be checked. The read is recorded as an agent consultation, which is what the dashboard\'s per-flow fetch counts are built from. Returns { subject, known, total } or { error, reason, advice } when this project is not linked to a workspace.',
+        inputSchema: {
+            subject: z
+                .string()
+                .optional()
+                .describe('Narrow to one area — a flow name ("checkout-pay") or a route segment ("issues"). Omit to read across the whole project. Subjects come from the coverage map; an unknown one returns nothing rather than erroring.'),
+            limit: countSchema
+                .optional()
+                .describe(`Most relevant N statements. Defaults to ${String(DEFAULT_LIMIT)}. Proved statements rank first, so a small limit still returns the settled ones. \`total\` always reports the true count.`),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            subject: z.string().nullable().optional(),
+            known: z.array(z.unknown()).optional(),
+            total: z.number().optional(),
+            error: z.string().optional(),
+            reason: z.string().optional(),
+            advice: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            /*
+             * The APP's root, not the daemon's.
+             *
+             * `deps.reticleRoot` is wherever the daemon was launched, which for a user-scoped MCP
+             * registration is almost never the project being driven — so the link file it reads is the
+             * wrong one or absent, and every project silently reads as "not attached". The same defect
+             * has now been fixed three times in this codebase; routing through sessionRoot is what stops
+             * a fourth.
+             */
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const subject = asString(args['subject']);
+            const result = await readProjectMemory(deps.fs, root, homedir(), process.env, {
+                subject,
+                limit: asNumber(args['limit']) ?? DEFAULT_LIMIT,
+            });
+            if (!result.ok)
+                return {
+                    error: 'no shared memory available for this project',
+                    reason: result.reason,
+                    advice: ADVICE[result.reason],
+                };
+            return { subject: result.subject, known: result.known, total: result.total };
+        },
+    },
+];

package/dist/memory/recall/prior/connection-memory.d.ts

@@ -0,0 +1,65 @@
+/**
+ * One durable bit: has an app ever connected to Reticle on this port, for this project?
+ *
+ * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
+ * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
+ * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
+ * install has never worked, and sends them looking for a missing config file that was always there.
+ * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
+ * as evidence about the install, not as a fact about a process that booted four seconds ago.
+ *
+ * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
+ * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
+ * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
+ * no diagnostic at all.
+ */
+/**
+ * Record that a session connected. Best-effort — a daemon must never fail to serve a session
+ * because it could not write a hint about it.
+ */
+export declare function rememberConnected(stateDir: string, port: number, projectId: string | undefined): void;
+/**
+ * Whether an app has connected on this port before, for this project.
+ *
+ * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
+ * that is the honest reading when the caller cannot name a project: the alternative is to answer
+ * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
+ * exists to remove.
+ */
+/**
+ * Has ANY app connected on this port — not necessarily the one in front of you.
+ *
+ * The name says "any app" because the old one did not, and the ambiguity cost a shipped lie.
+ * With a project id this answers the narrow question; WITHOUT one it falls back to "has this
+ * daemon ever served anything", which is deliberate and is what the lease diagnosis and the
+ * dev-server branch of `status` both want.
+ *
+ * It is also, read carelessly, a boolean called `previouslyConnected` that is true in a
+ * directory with no app in it. `reticle status` took that fallback and printed "This project
+ * has connected before, so the wiring is correct" in an empty directory. Two files already
+ * explained the distinction in prose, including this one, and the prose did not stop it — so
+ * the distinction is in the name now, where a caller has to type it.
+ *
+ * Want "has THIS project connected": `hasProjectConnectedBefore`, immediately below.
+ */
+export declare function hasAnyAppConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;
+/**
+ * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
+ *
+ * Separate from `hasAnyAppConnectedBefore`, which asks "has this daemon ever served an app" and so
+ * tolerates the untagged fallback. An absent projectId answers `false` here: a project with no
+ * Reticle identity has nothing recorded under another project's name that could be evidence about
+ * it, and deciding this narrower claim from the port suppressed the guidance on any machine where
+ * the default port had served anything at all.
+ *
+ * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
+ * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
+ * without writing that file. So a project wired by hand with the plugin and no `init` records a real
+ * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
+ * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
+ * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
+ * alternative — answering from the port — is the leak this function exists to close, which is the
+ * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
+ * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
+ */
+export declare function hasProjectConnectedBefore(stateDir: string, port: number, projectId: string | undefined): boolean;

package/dist/memory/recall/prior/connection-memory.js

@@ -0,0 +1,114 @@
+/**
+ * One durable bit: has an app ever connected to Reticle on this port, for this project?
+ *
+ * `SessionManager.everConnected()` answers a narrower question than every reader of it assumed — it
+ * is scoped to the CURRENT PROCESS. Daemons are short-lived by design (they idle out and respawn),
+ * so a diagnosis built on that boolean tells a user whose app connected a minute ago that this
+ * install has never worked, and sends them looking for a missing config file that was always there.
+ * Reported repeatedly, and the confident phrasing is what made it expensive: "never seen one" reads
+ * as evidence about the install, not as a fact about a process that booted four seconds ago.
+ *
+ * Deliberately tiny: one JSON file per port under the daemon's state home, holding the set of
+ * projectIds that have connected. It is a HINT, so every failure mode here degrades to "we do not
+ * know" rather than throwing — a diagnostic that can crash the tool it is diagnosing is worse than
+ * no diagnostic at all.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Sessions from an SDK old enough not to stamp a projectId still count, under this key. */
+const UNTAGGED = '(untagged)';
+/**
+ * Cap on remembered projects per port.
+ *
+ * A shared 4400 on a busy machine sees many projects over a week and this file is never garbage
+ * collected, so the set is bounded and oldest-out. The bit it answers is only ever used to soften a
+ * diagnosis, so losing the tail costs nothing.
+ */
+const MAX_REMEMBERED_PROJECTS = 32;
+function memoryPath(stateDir, port) {
+    return join(stateDir, `connected-${String(port)}.json`);
+}
+/** The remembered project ids for a port. Empty on absent, unreadable, or malformed state. */
+function read(stateDir, port) {
+    try {
+        const parsed = JSON.parse(readFileSync(memoryPath(stateDir, port), 'utf8'));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => 'string' === typeof entry);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Record that a session connected. Best-effort — a daemon must never fail to serve a session
+ * because it could not write a hint about it.
+ */
+export function rememberConnected(stateDir, port, projectId) {
+    const key = projectId ?? UNTAGGED;
+    const known = read(stateDir, port);
+    if (known.includes(key))
+        return;
+    const next = [...known, key].slice(-MAX_REMEMBERED_PROJECTS);
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(memoryPath(stateDir, port), JSON.stringify(next), 'utf8');
+    }
+    catch {
+        // An unwritable state home is already reported elsewhere; it must not break the session path.
+    }
+}
+/**
+ * Whether an app has connected on this port before, for this project.
+ *
+ * An absent `projectId` asks the weaker question — "has ANY app connected on this port" — because
+ * that is the honest reading when the caller cannot name a project: the alternative is to answer
+ * "no" for a daemon that plainly has served apps, which is the same over-confident claim this file
+ * exists to remove.
+ */
+/**
+ * Has ANY app connected on this port — not necessarily the one in front of you.
+ *
+ * The name says "any app" because the old one did not, and the ambiguity cost a shipped lie.
+ * With a project id this answers the narrow question; WITHOUT one it falls back to "has this
+ * daemon ever served anything", which is deliberate and is what the lease diagnosis and the
+ * dev-server branch of `status` both want.
+ *
+ * It is also, read carelessly, a boolean called `previouslyConnected` that is true in a
+ * directory with no app in it. `reticle status` took that fallback and printed "This project
+ * has connected before, so the wiring is correct" in an empty directory. Two files already
+ * explained the distinction in prose, including this one, and the prose did not stop it — so
+ * the distinction is in the name now, where a caller has to type it.
+ *
+ * Want "has THIS project connected": `hasProjectConnectedBefore`, immediately below.
+ */
+export function hasAnyAppConnectedBefore(stateDir, port, projectId) {
+    const known = read(stateDir, port);
+    if (projectId === undefined)
+        return known.length > 0;
+    return known.includes(projectId);
+}
+/**
+ * Has an app connected before FOR THIS PROJECT — the question the first-move instructions ask.
+ *
+ * Separate from `hasAnyAppConnectedBefore`, which asks "has this daemon ever served an app" and so
+ * tolerates the untagged fallback. An absent projectId answers `false` here: a project with no
+ * Reticle identity has nothing recorded under another project's name that could be evidence about
+ * it, and deciding this narrower claim from the port suppressed the guidance on any machine where
+ * the default port had served anything at all.
+ *
+ * KNOWN LIMIT, and the reason it is accepted rather than worked around. The WRITE side records the
+ * id the SDK supplied, while the read side asks `.reticle.json` — and the Vite plugin derives an id
+ * without writing that file. So a project wired by hand with the plugin and no `init` records a real
+ * id on every connect and reads `undefined` here forever, and is told at each handshake that nothing
+ * has connected. Two things make that tolerable: the block's own advice is to run `init`, which
+ * writes the file and heals the detection, so it is actionable rather than merely wrong; and the
+ * alternative — answering from the port — is the leak this function exists to close, which is the
+ * larger error by a wide margin. `no-session-watch` had already made exactly this call for its own
+ * diagnosis, which is why it now shares this function instead of keeping a second copy of the rule.
+ */
+export function hasProjectConnectedBefore(stateDir, port, projectId) {
+    if (projectId === undefined)
+        return false;
+    return hasAnyAppConnectedBefore(stateDir, port, projectId);
+}

package/dist/memory/recall/project-memory.d.ts

@@ -0,0 +1,33 @@
+import type { FileSystemPort } from '../project/fs/fs-port.js';
+/** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
+export declare const MemoryUnavailable: {
+    /** No `.reticle/cloud.json` — this project has never been linked to a workspace. */
+    readonly NOT_LINKED: "not-linked";
+    /** Linked, but the link says not to sync memory. A setting, not a failure. */
+    readonly DISABLED: "memory-sync-disabled";
+    /** The server was reached and said no, or could not be reached at all. */
+    readonly UNREACHABLE: "unreachable";
+};
+export type MemoryUnavailable = (typeof MemoryUnavailable)[keyof typeof MemoryUnavailable];
+export interface KnownThing {
+    statement: string;
+    status: string;
+    flowName: string | null;
+    sourceFile: string | null;
+    subject: string;
+}
+type ProjectMemoryResult = {
+    ok: true;
+    subject: string | null;
+    known: KnownThing[];
+    total: number;
+} | {
+    ok: false;
+    reason: MemoryUnavailable;
+};
+export declare const rankKnown: (things: readonly KnownThing[]) => KnownThing[];
+export declare function readProjectMemory(fs: FileSystemPort, root: string, home: string, env: NodeJS.ProcessEnv, opts: {
+    subject?: string | undefined;
+    limit: number;
+}): Promise<ProjectMemoryResult>;
+export {};

package/dist/portal/bridge/auth-failure-reason.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Why the bridge refused a HELLO — the specific reason when there is one.
+ *
+ * A daemon left running by one project answers the next project's app and rejects it on token, and
+ * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
+ * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ *
+ * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
+ * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
+ * would report "different project" on every auth failure — the same confidently-wrong diagnostic
+ * this exists to replace. What the daemon knows for certain is which projects it has ALREADY
+ * accepted a session from; if it has served X and a HELLO arrives for Y, it demonstrably belongs to
+ * someone else.
+ *
+ * A HELLO with no token at all is a third case, and a reload cannot fix it: the CDN snippet and a
+ * Next config evaluated before any token existed froze an empty credential into the page. Naming
+ * that is what stops the close reason from prescribing a recovery that cannot work.
+ *
+ * With no evidence — a fresh daemon, or a HELLO naming no project — nothing is inferred and the
+ * plain reason stands, unless the page sent no token.
+ */
+/**
+ * Whether a recorded close is a pairing-token refusal.
+ *
+ * The bridge records the specific sentence it sent on the socket, not one fixed string, so a
+ * comparison with a single constant misses a wrong token, a missing token, and a daemon that
+ * belongs to another project. All three are refusals. A later good session is a separate question
+ * the caller answers with `connectedSinceLastClosure`.
+ */
+export declare function isAuthRefusalReason(reason: string | undefined): boolean;
+export declare function authFailureReason(servedProjects: ReadonlySet<string>, helloProject: string | undefined, helloToken?: string): string;

package/dist/portal/bridge/auth-failure-reason.js

@@ -0,0 +1,68 @@
+/**
+ * Why the bridge refused a HELLO — the specific reason when there is one.
+ *
+ * A daemon left running by one project answers the next project's app and rejects it on token, and
+ * the SDK printed `bridge refused the connection: authentication failed`. That sends someone to
+ * check a token which is perfectly correct — it is simply a DIFFERENT project's token. The two cases
+ * need opposite fixes: "your token is wrong" versus "that daemon is not yours, stop it".
+ *
+ * The discriminator is EVIDENCE, not derivation. The daemon and the SDK derive project ids by
+ * different schemes (the SDK from its Vite root, the daemon from its own cwd), so comparing those
+ * would report "different project" on every auth failure — the same confidently-wrong diagnostic
+ * this exists to replace. What the daemon knows for certain is which projects it has ALREADY
+ * accepted a session from; if it has served X and a HELLO arrives for Y, it demonstrably belongs to
+ * someone else.
+ *
+ * A HELLO with no token at all is a third case, and a reload cannot fix it: the CDN snippet and a
+ * Next config evaluated before any token existed froze an empty credential into the page. Naming
+ * that is what stops the close reason from prescribing a recovery that cannot work.
+ *
+ * With no evidence — a fresh daemon, or a HELLO naming no project — nothing is inferred and the
+ * plain reason stands, unless the page sent no token.
+ */
+const PLAIN = 'authentication failed';
+/**
+ * A token WAS presented and did not match. That is not "check your credentials" — the page holds a
+ * real token from a state directory this daemon does not own, which in the field means a dev server
+ * that does not share a filesystem with the daemon (container, devcontainer, WSL), or a page served
+ * before `~/.reticle` was replaced. Both need the same first move: ask `status`, which can say which.
+ */
+const WRONG_TOKEN = 'authentication failed: wrong pairing token — run `reticle status` for the cause';
+/** A paste-in snippet or a Next config that never saw a token. Reload cannot mint one. */
+const NO_TOKEN = 'authentication failed: no pairing token on the page';
+/** WebSocket close reasons are capped at 123 bytes; a longer one throws and closes with nothing. */
+const MAX_REASON_BYTES = 123;
+const DIFFERENT_PROJECT_PREFIX = 'this daemon serves a different project';
+/**
+ * Whether a recorded close is a pairing-token refusal.
+ *
+ * The bridge records the specific sentence it sent on the socket, not one fixed string, so a
+ * comparison with a single constant misses a wrong token, a missing token, and a daemon that
+ * belongs to another project. All three are refusals. A later good session is a separate question
+ * the caller answers with `connectedSinceLastClosure`.
+ */
+export function isAuthRefusalReason(reason) {
+    if (reason === undefined)
+        return false;
+    return reason.startsWith('authentication failed') || reason.startsWith(DIFFERENT_PROJECT_PREFIX);
+}
+export function authFailureReason(servedProjects, helloProject, helloToken) {
+    // ONE served project, not merely some. A daemon that has accepted sessions from SEVERAL projects
+    // is demonstrably not owned by any one of them, so "that daemon is not yours, stop it" is the
+    // wrong story — and its advice is actively harmful there, because stopping it breaks the projects
+    // that are working. This is the normal shape for a globally-registered daemon, which several
+    // editors start from the user's home directory and point at everything.
+    //
+    // With one served project the inference holds and is worth making: the daemon belongs to that
+    // project and this HELLO is somebody else's. With several, the token is the suspect, and the plain
+    // reason says so without prescribing a recovery that costs other people their sessions.
+    if (helloProject !== undefined &&
+        1 === servedProjects.size &&
+        !servedProjects.has(helloProject)) {
+        const reason = `${DIFFERENT_PROJECT_PREFIX} — run \`reticle stop\` and retry`;
+        return Buffer.byteLength(reason, 'utf8') <= MAX_REASON_BYTES ? reason : PLAIN;
+    }
+    if (helloToken === undefined || 0 === helloToken.length)
+        return NO_TOKEN;
+    return Buffer.byteLength(WRONG_TOKEN, 'utf8') <= MAX_REASON_BYTES ? WRONG_TOKEN : PLAIN;
+}

package/dist/portal/bridge/bridge-security.d.ts

@@ -0,0 +1,30 @@
+import type { StartOptions } from '../../start-options.js';
+import { pairingTokenSource } from './pairing-token.js';
+/** The security contract the bridge/daemon enforce: bind host, pairing token, and WS origin allow-list. */
+interface BridgeSecurity {
+    host?: string;
+    token?: string;
+    allowedOrigins?: string[];
+    /**
+     * Which source supplied `token`, decided HERE because this is the only place that knows.
+     * By the time the Bridge sees it, an auto-provisioned token and one passed by a caller are the
+     * same field — so computing it downstream would report `explicit` for every daemon and describe
+     * nothing. See pairingTokenSource for why a refusal needs this at all.
+     */
+    tokenSource?: ReturnType<typeof pairingTokenSource>;
+}
+/**
+ * Resolve the bridge's security options from explicit options first, then the environment. Shared by
+ * both `start` and `startDaemon` so the token/host/origin contract is enforced identically on
+ * every entrypoint — a past divergence let daemon mode silently run with auth disabled.
+ */
+export declare function resolveBridgeSecurity(options: StartOptions): BridgeSecurity;
+/**
+ * Same as `resolveBridgeSecurity`, but when no explicit/env token is set it auto-provisions one from
+ * ~/.reticle/pairing-token so the bridge always requires a secret by default — this is what closes the
+ * "any loopback origin is trusted" gap (a rogue localhost app can't read the file to present it). The
+ * build plugins read the same file and inject it, so plugin-served apps stay zero-config. Best-effort:
+ * if provisioning fails, the daemon degrades to the prior tokenless behavior rather than failing to start.
+ */
+export declare function resolveBridgeSecurityWithAutoToken(options: StartOptions): Promise<BridgeSecurity>;
+export {};

package/dist/portal/bridge/bridge-security.js

@@ -0,0 +1,53 @@
+import { ReticleEnv } from '@reticlehq/core';
+import { defaultPairingTokenDir, nodePairingTokenDeps, readOrCreatePairingToken, pairingTokenSource, } from './pairing-token.js';
+import { log } from '../../log.js';
+/**
+ * Resolve the bridge's security options from explicit options first, then the environment. Shared by
+ * both `start` and `startDaemon` so the token/host/origin contract is enforced identically on
+ * every entrypoint — a past divergence let daemon mode silently run with auth disabled.
+ */
+export function resolveBridgeSecurity(options) {
+    const tokenSource = pairingTokenSource({
+        explicit: options.token !== undefined && 0 < options.token.length,
+        env: process.env,
+    });
+    const envToken = process.env[ReticleEnv.TOKEN];
+    const envOrigins = process.env[ReticleEnv.ALLOWED_ORIGINS];
+    const host = options.host ?? process.env[ReticleEnv.HOST];
+    const token = options.token ?? (envToken !== undefined && envToken.length > 0 ? envToken : undefined);
+    const allowedOrigins = options.allowedOrigins ??
+        envOrigins
+            ?.split(',')
+            .map((origin) => origin.trim())
+            .filter((origin) => origin.length > 0);
+    return {
+        ...(host === undefined ? {} : { host }),
+        ...(token === undefined ? {} : { token }),
+        ...(allowedOrigins === undefined ? {} : { allowedOrigins }),
+        tokenSource,
+    };
+}
+/**
+ * Same as `resolveBridgeSecurity`, but when no explicit/env token is set it auto-provisions one from
+ * ~/.reticle/pairing-token so the bridge always requires a secret by default — this is what closes the
+ * "any loopback origin is trusted" gap (a rogue localhost app can't read the file to present it). The
+ * build plugins read the same file and inject it, so plugin-served apps stay zero-config. Best-effort:
+ * if provisioning fails, the daemon degrades to the prior tokenless behavior rather than failing to start.
+ */
+export async function resolveBridgeSecurityWithAutoToken(options) {
+    const security = resolveBridgeSecurity(options);
+    if (security.token !== undefined)
+        return security;
+    const dir = options.pairingTokenDir ?? defaultPairingTokenDir();
+    const token = await readOrCreatePairingToken(dir, nodePairingTokenDeps());
+    if (token === undefined) {
+        // Fail-open is deliberate (never block a dev daemon on an unwritable $HOME), but it must be LOUD:
+        // the bridge is now trusting every loopback origin. Say so plainly, not just as a silent event.
+        log('pairing_token_provision_failed', {
+            dir,
+            warning: 'SECURITY: could not provision a pairing token — the bridge is running WITHOUT auth and will trust any localhost origin. Any local process/page can drive your browser sessions. Fix write access to this dir, or set RETICLE_TOKEN.',
+        });
+        return security;
+    }
+    return { ...security, token };
+}

package/dist/portal/bridge/bridge.d.ts

@@ -0,0 +1,109 @@
+import * as http from 'node:http';
+import { Session } from '../session/session.js';
+import { SessionManager } from '../session/session-manager.js';
+import { pairingTokenSource } from './pairing-token.js';
+/** A human clicked ▶ on a saved flow in the panel — replay it with no agent. Wired by the daemon. */
+type ReplayRequestHandler = (sessionId: string, flowName: string) => void;
+/** Called once a browser session connects, so the daemon can push it the replayable-flow list. */
+type SessionReadyHandler = (session: Session) => void;
+/**
+ * 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 declare 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.
+     */
+    readonly PROTOCOL_MISMATCH: "protocol version mismatch — @reticlehq/browser and server disagree";
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly HANDSHAKE_POOL_FULL: string;
+};
+interface BridgeOptions {
+    port: number;
+    host?: string;
+    token?: string;
+    /** Which source supplied `token`. Set by resolveBridgeSecurity; logged on a refusal, never sent. */
+    tokenSource?: ReturnType<typeof pairingTokenSource>;
+    allowedOrigins?: string[];
+    maxMessagesPerSecond?: number;
+    maxSessions?: number;
+    maxPendingConnections?: number;
+    helloTimeoutMs?: number;
+    clock?: () => number;
+    /**
+     * When set, the WebSocket server attaches to this HTTP server instead of binding standalone.
+     * Used in daemon mode where a single HTTP server handles both WS and SSE MCP traffic.
+     * `port` and `host` are ignored for binding when this is provided.
+     */
+    server?: http.Server;
+    /**
+     * The SDK-upgrade sentence to attach when a HELLO is skewed. Injected so the daemon can name
+     * this project's packages and package manager; tests that omit it get the no-project fallback.
+     */
+    sdkFix?: () => string;
+}
+/**
+ * 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 declare class Bridge {
+    #private;
+    readonly sessions: SessionManager;
+    /** Resolves with the actually-bound port once the server is listening. */
+    readonly ready: Promise<number>;
+    constructor(options: BridgeOptions);
+    /** Register the daemon's handler for a panel ▶ replay (it owns the flow store). */
+    attachReplay(handler: ReplayRequestHandler): void;
+    /**
+     * 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: SessionReadyHandler): void;
+    /** 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: (session: Session) => Promise<void>): void;
+    /**
+     * 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: () => void): void;
+    /**
+     * 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: (enabled: boolean) => void): void;
+    /** Register a handler to run when a session connects. Additive — every handler runs. */
+    attachSessionCreate(handler: (session: Session) => void): void;
+    close(): Promise<void>;
+}
+export {};