@reticlehq/server 2.2.1 → 2.4.0

package/README.md

@@ -12,7 +12,7 @@ Point your agent at it (e.g. Claude Code `.mcp.json`):
 { "mcpServers": { "reticle": { "command": "npx", "args": ["@reticlehq/server", "mcp"] } } }
 ```
 
-Tools: `reticle_snapshot`, `reticle_query`, `reticle_inspect`, `reticle_act`, `reticle_act_sequence`, `reticle_observe`, `reticle_wait_for`, `reticle_assert`, `reticle_network`, `reticle_console`, `reticle_animations`, `reticle_baseline_save`/`_list`, `reticle_diff`, `reticle_record_start`/`_stop`, `reticle_explore`, `reticle_sessions`.
+Tools: `reticle_snapshot`, `reticle_query`, `reticle_inspect`, `reticle_act`, `reticle_act_sequence`, `reticle_act_and_wait`, `reticle_observe`, `reticle_wait_for`, `reticle_assert`, `reticle_network`, `reticle_console`, `reticle_animations`, `reticle_baseline`, `reticle_visual_diff`, `reticle_record`, `reticle_flow`, `reticle_explore`, `reticle_sessions`.
 
 See the [main README](https://github.com/reticlehq/reticle).
 

package/dist/bridge-security.d.ts

@@ -20,4 +20,3 @@ export declare function resolveBridgeSecurity(options: StartOptions): BridgeSecu
  */
 export declare function resolveBridgeSecurityWithAutoToken(options: StartOptions): Promise<BridgeSecurity>;
 export {};
-//# sourceMappingURL=bridge-security.d.ts.map

package/dist/bridge-security.js

@@ -46,4 +46,3 @@ export async function resolveBridgeSecurityWithAutoToken(options) {
     }
     return { ...security, token };
 }
-//# sourceMappingURL=bridge-security.js.map

package/dist/bridge.d.ts

@@ -46,4 +46,3 @@ export declare class Bridge {
     close(): Promise<void>;
 }
 export {};
-//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -1,20 +1,44 @@
 import * as http from 'node:http';
 import { WebSocketServer } from 'ws';
-import { EventType, HumanControlKind, RETICLE_WS_PATH, ReticleMessageSchema, LOOPBACK_HOST, MessageKind, ReticleEnv, RETICLE_PROTOCOL_VERSION, TRANSPORT_LIMITS, isLoopbackHostname, } from '@reticlehq/core';
+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, } from '@reticlehq/core';
 import { Session, SessionManager } from './session/session.js';
 import { tokensMatch } from './token-auth.js';
 import { log } from './log.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;
+}
 /** 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'],
-    RATE_EXCEEDED: [1008, 'message rate exceeded'],
     INVALID_MESSAGE: [1008, 'invalid message'],
     HELLO_DUPLICATE: [1008, 'hello already received'],
     AUTH_FAILED: [1008, 'authentication failed'],
     SESSION_LIMIT: [1013, 'session limit reached'],
     PROTOCOL_MISMATCH: [1008, 'protocol version mismatch — upgrade @reticlehq/browser'],
 };
+/** 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)
@@ -24,9 +48,19 @@ function replayRequest(event) {
     const name = event.data['text'];
     return typeof name === 'string' && name.length > 0 ? name : undefined;
 }
+/**
+ * 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 {
-        return new URL(origin).origin;
+        const web = new URL(origin).origin;
+        return web === OPAQUE_ORIGIN ? origin : web;
     }
     catch {
         return null;
@@ -107,8 +141,13 @@ export class Bridge {
                 '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 ?? TRANSPORT_LIMITS.MAX_MESSAGES_PER_SECOND;
+            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;
@@ -182,6 +221,8 @@ export class Bridge {
         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;
@@ -194,18 +235,16 @@ export class Bridge {
             releasePending();
             socket.close(...WS_CLOSE.HELLO_TIMEOUT);
         }, this.#helloTimeoutMs);
+        let droppedByRate = 0;
         socket.on('message', (raw) => {
             const now = this.#clock();
             if (now - messageWindowStartedAt >= 1000) {
                 messageWindowStartedAt = now;
                 messagesInWindow = 0;
+                highValueInWindow = 0;
             }
             messagesInWindow += 1;
-            if (messagesInWindow > this.#maxMessagesPerSecond) {
-                log('message_rate_exceeded', {});
-                socket.close(...WS_CLOSE.RATE_EXCEEDED);
-                return;
-            }
+            const overRate = messagesInWindow > this.#maxMessagesPerSecond;
             const text = rawToString(raw);
             const parsed = this.#parse(text);
             if (parsed === null) {
@@ -218,9 +257,43 @@ export class Bridge {
                 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) {
-                    socket.close(...WS_CLOSE.HELLO_DUPLICATE);
+                    // 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)) {
@@ -288,7 +361,25 @@ export class Bridge {
             return false;
         if (this.#allowedOrigins.has(normalized))
             return true;
-        return isLoopbackHostname(new URL(normalized).hostname);
+        // 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;
@@ -334,4 +425,3 @@ export class Bridge {
         });
     }
 }
-//# sourceMappingURL=bridge.js.map

package/dist/bridge.test-harness.d.ts

@@ -37,6 +37,11 @@ export declare class FakeBrowser {
     }[];
     constructor(port: number, sessionId: string, hasCapabilities?: boolean);
     open(): Promise<void>;
+    /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */
+    reannounce(overrides?: {
+        sessionId?: string;
+        hasCapabilities?: boolean;
+    }): void;
     emit(type: string, data: Record<string, unknown>, ref?: string): void;
     close(): void;
 }
@@ -44,4 +49,3 @@ export declare function waitUntil(cond: () => boolean, timeoutMs?: number): Prom
 export declare const callTool: (deps: ToolDeps, name: string, args?: Record<string, unknown>) => Promise<unknown>;
 /** Builds the ToolDeps wired to a running bridge, with a frozen clock for deterministic tests. */
 export declare function makeDeps(bridge: Bridge): ToolDeps;
-//# sourceMappingURL=bridge.test-harness.d.ts.map

package/dist/bridge.test-harness.js

@@ -59,6 +59,18 @@ export class FakeBrowser {
             });
         });
     }
+    /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */
+    reannounce(overrides = {}) {
+        this.#send({
+            kind: MessageKind.HELLO,
+            protocolVersion: 1,
+            sessionId: overrides.sessionId ?? this.sessionId,
+            url: 'http://localhost:3000/checkout',
+            title: 'Checkout',
+            adapters: [],
+            hasCapabilities: overrides.hasCapabilities ?? this.hasCapabilities,
+        });
+    }
     emit(type, data, ref) {
         this.#send({
             kind: MessageKind.EVENT,
@@ -193,4 +205,3 @@ export function makeDeps(bridge) {
         now: () => 0,
     };
 }
-//# sourceMappingURL=bridge.test-harness.js.map

package/dist/capsule/capsule-store.d.ts

@@ -25,19 +25,19 @@ export declare const CapsuleSchema: z.ZodObject<{
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
 }, "strip", z.ZodTypeAny, {
+    origin: string;
     version: 1;
     id: string;
     expected: string;
-    origin: string;
     steps: FlowStep[];
     observed: string;
     createdAt: number;
     flow?: string | undefined;
 }, {
+    origin: string;
     version: 1;
     id: string;
     expected: string;
-    origin: string;
     steps: FlowStep[];
     observed: string;
     createdAt: number;
@@ -63,4 +63,3 @@ export declare class CapsuleStore {
 export declare function capsuleId(now: number, label: string): string;
 /** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
 export declare function minimalSteps(steps: readonly FlowStep[], failedIndex: number): FlowStep[];
-//# sourceMappingURL=capsule-store.d.ts.map

package/dist/capsule/capsule-store.js

@@ -107,4 +107,3 @@ export function minimalSteps(steps, failedIndex) {
         return [...steps];
     return steps.slice(0, failedIndex + 1);
 }
-//# sourceMappingURL=capsule-store.js.map

package/dist/capsule/capsule.d.ts

@@ -16,4 +16,3 @@ export interface DivergenceCapsule {
 }
 /** Compose the full capsule from the declared chain and the observed (attributed) event window. */
 export declare function buildDivergenceCapsule(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[]): DivergenceCapsule;
-//# sourceMappingURL=capsule.d.ts.map

package/dist/capsule/capsule.js

@@ -33,4 +33,3 @@ export function buildDivergenceCapsule(expected, observed) {
         blastRadius: blastRadius(expected, observed),
     };
 }
-//# sourceMappingURL=capsule.js.map

package/dist/capsule/causal-summary.d.ts

@@ -8,6 +8,17 @@ export interface StateDiff {
     path: string;
     from: unknown;
     to: unknown;
+    /**
+     * WHEN this path moved, in the session's elapsed ms.
+     *
+     * The whole reason a transient was invisible. A store that ends internally consistent can have been
+     * inconsistent on the way there, and a from→to pair cannot express that — measured on a real
+     * merchant dashboard, an account switch moved `accountId` immediately and `payments` 160 ms later,
+     * so for 160 ms the header named one tenant while the rows belonged to another. Both diffs were
+     * reported; nothing said they were 160 ms apart, and waiting for the page to settle is by
+     * construction waiting for the evidence to disappear. The timestamp was on the event all along.
+     */
+    atMs: number;
 }
 export interface StorageDiff {
     key: string;
@@ -25,6 +36,16 @@ export interface CausalSummary {
     storageKeysChanged: string[];
     /** Before→after for each changed store path — the diffs, not just the names. Values capped. */
     stateDiffs: StateDiff[];
+    /**
+     * How long the store took to stop moving: last state change − first, in ms. Present only when more
+     * than one path changed, because with a single change there is no interval to describe.
+     *
+     * A FACT, not a verdict. Many apps update progressively and that is fine; calling every stagger a
+     * defect would make this a noise generator. But a non-zero value is the exact window in which the
+     * UI showed a MIXTURE of old and new, and that window is where the tenant-mismatch class of bug
+     * lives — so it is stated once, cheaply, and the agent decides.
+     */
+    stateSettleMs?: number;
     /** Before→after for each changed storage key. Values capped. */
     storageDiffs: StorageDiff[];
     route?: string;
@@ -33,4 +54,3 @@ export interface CausalSummary {
     longTasks: number;
 }
 export declare function causalSummary(events: readonly ReticleEvent[]): CausalSummary;
-//# sourceMappingURL=causal-summary.d.ts.map

package/dist/capsule/causal-summary.js

@@ -24,6 +24,19 @@ function capValue(value) {
         return '[unserializable]';
     }
 }
+/**
+ * The span over which the store was still moving — and therefore possibly self-inconsistent.
+ *
+ * Omitted for 0 or 1 diffs (no interval) and for a spread of 0 (everything landed in one tick), so a
+ * store that updates atomically pays nothing and the field's PRESENCE is what carries the meaning.
+ */
+function stateSettle(diffs) {
+    if (diffs.length < 2)
+        return {};
+    const times = diffs.map((d) => d.atMs);
+    const spread = Math.max(...times) - Math.min(...times);
+    return spread > 0 ? { stateSettleMs: spread } : {};
+}
 export function causalSummary(events) {
     let netTotal = 0;
     let netErrors = 0;
@@ -64,7 +77,12 @@ export function causalSummary(events) {
                 const hasAfter = 'value' in data || 'new' in data;
                 if (typeof path === 'string' && path.length > 0 && ('old' in data || hasAfter)) {
                     const after = 'value' in data ? data['value'] : data['new'];
-                    stateDiffs.push({ path, from: capValue(data['old']), to: capValue(after) });
+                    stateDiffs.push({
+                        path,
+                        from: capValue(data['old']),
+                        to: capValue(after),
+                        atMs: event.t,
+                    });
                 }
                 break;
             }
@@ -101,6 +119,7 @@ export function causalSummary(events) {
         statePathsChanged,
         storageKeysChanged,
         stateDiffs,
+        ...stateSettle(stateDiffs),
         storageDiffs,
         ...(route === undefined ? {} : { route }),
         signals,
@@ -108,4 +127,3 @@ export function causalSummary(events) {
         longTasks,
     };
 }
-//# sourceMappingURL=causal-summary.js.map

package/dist/capsule/divergence.d.ts

@@ -28,4 +28,3 @@ export interface Divergence {
  * side-by-side of what happened instead), or null when the whole chain held.
  */
 export declare function firstDivergence(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[]): Divergence | null;
-//# sourceMappingURL=divergence.d.ts.map

package/dist/capsule/divergence.js

@@ -38,4 +38,3 @@ export function firstDivergence(expected, observed) {
     }
     return null;
 }
-//# sourceMappingURL=divergence.js.map

package/dist/capsule/minimize.d.ts

@@ -10,4 +10,3 @@
  * `stillFails` holds. Never trims below one step. Deterministic given a deterministic predicate.
  */
 export declare function prefixTrim<T>(steps: readonly T[], stillFails: (candidate: readonly T[]) => Promise<boolean>): Promise<T[]>;
-//# sourceMappingURL=minimize.d.ts.map

package/dist/capsule/minimize.js

@@ -20,4 +20,3 @@ export async function prefixTrim(steps, stillFails) {
     }
     return kept;
 }
-//# sourceMappingURL=minimize.js.map

package/dist/capsule/predicate-to-links.d.ts

@@ -6,4 +6,3 @@ import type { ExpectedLink } from './divergence.js';
  * dataflow sense. allOf/anyOf flatten in order; other kinds are skipped. Pure; feeds the capsule on red.
  */
 export declare function predicateToExpectedLinks(predicate: Predicate): ExpectedLink[];
-//# sourceMappingURL=predicate-to-links.d.ts.map

package/dist/capsule/predicate-to-links.js

@@ -28,4 +28,3 @@ export function predicateToExpectedLinks(predicate) {
             return [];
     }
 }
-//# sourceMappingURL=predicate-to-links.js.map

package/dist/cli-doctor.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
+ * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
+ * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
+ */
+export declare function handleDoctor(port: number): Promise<void>;

package/dist/cli-doctor.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPid, isAlive } from './daemon.js';
+import { diagnoseDesktop, isDesktopProject } from './init/desktop-doctor.js';
+/**
+ * `reticle doctor` — collapse the ~6 independent first-run failure modes into one command. Checks the
+ * Chromium install (the #1 silent failure), whether a daemon is up on the resolved bridge port, and
+ * reminds the user which port the app must dial. Human-readable to stdout (not the JSON log).
+ */
+export async function handleDoctor(port) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    line('reticle doctor');
+    line(`  node         ${process.version}`);
+    try {
+        const { chromium } = await import('playwright');
+        const path = chromium.executablePath();
+        line(existsSync(path)
+            ? '  chromium     ✓ installed'
+            : '  chromium     ✗ missing — run: npx playwright install chromium');
+    }
+    catch {
+        line('  chromium     ✗ missing — run: npx playwright install chromium');
+    }
+    const pid = readPid(port);
+    if (pid !== null && isAlive(pid)) {
+        line(`  daemon       ✓ running on :${port} (pid ${pid})`);
+    }
+    else {
+        line(`  daemon       ✗ not running on :${port} — your agent runs \`reticle mcp\` (or \`reticle serve\`)`);
+    }
+    line(`  bridge port  ${port}  (your app must dial THIS port — not your dev-server port)`);
+    // Desktop setup RCA. Every one of these fails SILENTLY — a Tauri app with the default CSP runs
+    // perfectly and never connects; an Electron app without the preload line reports zero network
+    // activity forever, which reads as "makes no backend calls" rather than "you are blind to them".
+    const readProjectFile = (relative) => {
+        try {
+            return readFileSync(join(process.cwd(), relative), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const desktop = diagnoseDesktop(readProjectFile, port);
+    if (desktop.length > 0) {
+        line('');
+        line(`  desktop      ✗ ${String(desktop.length)} issue(s) — the app will look fine and not work:`);
+        for (const finding of desktop) {
+            line(`                 ${finding.file}`);
+            line(`                   ${finding.problem}`);
+            line(`                   fix: ${finding.fix}`);
+        }
+    }
+    else if (isDesktopProject(readProjectFile)) {
+        // Say so explicitly. Silence would read as "not checked", which is the same ambiguity the
+        // findings above exist to remove.
+        line('  desktop      ✓ desktop wiring looks right');
+    }
+}

package/dist/cli-flow-commands.d.ts

@@ -28,4 +28,3 @@ export declare function handleCapsules(): Promise<void>;
  * that makes verification unavoidable. Never throws; a fault fails closed (exit 1).
  */
 export declare function handleGate(files: string[], since: string | undefined): Promise<void>;
-//# sourceMappingURL=cli-flow-commands.d.ts.map

package/dist/cli-flow-commands.js

@@ -204,4 +204,3 @@ export async function handleGate(files, since) {
         process.exitCode = 1;
     }
 }
-//# sourceMappingURL=cli-flow-commands.js.map

package/dist/cli-launch.d.ts

@@ -50,4 +50,3 @@ export declare function openCommand(url: string, platform: NodeJS.Platform): {
 /** Launch the default browser at `url` (detached). The spawn is injected so tests stay hermetic. */
 export declare function openInBrowser(url: string, platform?: NodeJS.Platform, run?: (cmd: string, args: string[]) => void): void;
 export {};
-//# sourceMappingURL=cli-launch.d.ts.map

package/dist/cli-launch.js

@@ -1,6 +1,6 @@
 import * as http from 'node:http';
 import { spawn } from 'node:child_process';
-import { LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
+import { isOpaqueOrigin, LOOPBACK_HOST, STATUS_PATH } from '@reticlehq/core';
 /**
  * Reduce the daemon's /status JSON to the compact view `reticle status` prints. Pure: narrows the
  * untrusted wire payload (never `any`) and tolerates a missing/partial body so a malformed response
@@ -58,7 +58,12 @@ export function fetchStatus(port) {
 }
 function sameOrigin(a, b) {
     try {
-        return new URL(a).origin === new URL(b).origin;
+        const origin = new URL(a).origin;
+        // Two opaque origins (desktop webviews, file:// docs) BOTH stringify to "null", so comparing them
+        // would call every desktop app the same app and reuse the wrong session. Never match on opaque.
+        if (isOpaqueOrigin(origin))
+            return false;
+        return origin === new URL(b).origin;
     }
     catch {
         return false;
@@ -105,4 +110,3 @@ function defaultRun(cmd, args) {
     const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
     child.unref();
 }
-//# sourceMappingURL=cli-launch.js.map

package/dist/cli-parse.d.ts

@@ -4,7 +4,14 @@
  * file-size cap and keep the parser pure + unit-testable. Re-exported from cli.ts so existing
  * imports are unchanged.
  */
-export declare const CLI_USAGE = "usage:\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)\n  reticle serve [--port N] [--drive <url>] [--headed] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]\n  reticle status [--port N]\n  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port \u2014 one command)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headed]                       (foreground mode \u2014 for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headed]  (MCP stdio proxy \u2014 auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics \u2014 status shows what's sent + the policy)\n\nCloud (link this project to Reticle Cloud \u2014 runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)";
+export declare const CLI_USAGE = "usage:\n  reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install]  (wire Reticle into the project in this directory)\n  reticle serve [--port N] [--drive <url>] [--headless] [--http] [--http-port N] [--http-token T]\n  reticle stop  [--port N] [--quiet]\n  reticle status [--port N]\n  reticle doctor [--port N]                            (diagnose setup: Chromium, daemon, port \u2014 one command)\n  reticle open  [url] [--port N]                        (show the app: reuse the connected tab, else open one)\n  reticle verify <url> [--headed] [--timeout N] [--storage-state <file>]  (one-shot: drive the URL, verify saved flows, exit 0=pass)\n  reticle affected [--since <ref>] [file...]           (which saved flows must re-verify for the changed files)\n  reticle gate [--since <ref>] [file...]               (exit non-zero unless passing artifacts cover the affected flows)\n  reticle watch [url]                                  (on save, report which saved flows must re-verify)\n  reticle drive <url> [--headless]                     (foreground mode \u2014 for debugging)\n  reticle mcp   [--port N] [--drive <url>] [--headless] (MCP stdio proxy \u2014 auto-starts daemon if needed)\n  reticle update                                       (install the latest server version and restart)\n  reticle rollback                                     (restore the previous server version and restart)\n  reticle license                                      (show enterprise license status: active | eval | missing)\n  reticle telemetry [status|enable|disable]            (anonymous usage metrics \u2014 status shows what's sent + the policy)\n  reticle feedback [--rating 1-5] [--bug] \"message\"    (tell us what worked and what didn't \u2014 prints exactly what it sends)\n  reticle identify --context company|side_project|open_source|learning [--company N] [--email E] [--forget]\n                                                       (OPT-IN: tell us who you are, e.g. for support or an enterprise trial)\n\nCloud (link this project to Reticle Cloud \u2014 runs/flows recorded on the dashboard):\n  reticle login --email <e> [--code <c>] [--org <n>]   (sign in: mails a code, then exchanges it)\n  reticle link  [--project <name|id>]                  (bind this repo: mints a scoped key, writes .reticle/cloud.json)\n  reticle whoami                                        (who am I signed in as, and is this repo attached?)\n  reticle project <ls|create <name>>                   (list or create cloud projects)\n  reticle config [--runs on|off] [--memory on|off] [--flows on|off] [--verify local|server]\n  reticle push                                          (send local run artifacts to the dashboard)\n  reticle runs | regression | share <runId>            (read cloud state; regression exits 3 if any flow broke)\n\n'drive' shows the browser; everything else is hidden (serve/mcp own the pool behind leases, replay\nand the spec runner \u2014 batch work). --headed opts any of them in, --headless hides drive, CI hides it.";
+export declare const COMPANY_FLAG = "--company";
+export declare const EMAIL_FLAG = "--email";
+export declare const CONTEXT_FLAG = "--context";
+export declare const FORGET_FLAG = "--forget";
+/** `reticle feedback --rating 4 "the words"` — the human half of the channel. */
+export declare const RATING_FLAG = "--rating";
+export declare const BUG_FLAG = "--bug";
 /** The `reticle telemetry` sub-actions. Bare `reticle telemetry` means `status`. */
 export declare const TelemetryAction: {
     readonly STATUS: "status";
@@ -13,7 +20,25 @@ export declare const TelemetryAction: {
 };
 export type TelemetryAction = (typeof TelemetryAction)[keyof typeof TelemetryAction];
 export declare const DAEMON_INNER_COMMAND = "_daemon";
+/**
+ * Every subcommand a person can type, as one closed vocabulary. Telemetry reports which one ran, and
+ * this is what keeps that property low-cardinality and non-identifying: an argument we do not
+ * recognize reports as `unknown` rather than being echoed, so a typo — which may be a path, a URL, or
+ * a flow name — can never reach the wire just because someone misspelled `status`.
+ *
+ * Lives here rather than in the telemetry module because this is where the command names are already
+ * defined; a second list somewhere else would drift the first time a command is added.
+ */
+export declare const UNKNOWN_COMMAND = "unknown";
+/** The subcommand name if we recognize it, else `unknown`. Bare `reticle` reports `help`. */
+export declare function knownCommand(arg: string | undefined): string;
 export declare const HEADED_FLAG = "--headed";
+/**
+ * Force a hidden browser. The default is now HEADED: a run nobody can see is a run nobody trusts,
+ * and every "did it actually do anything?" question cost a round-trip. CI passes this (or just sets
+ * CI, which flips the default) because there is no display there to be headed on.
+ */
+export declare const HEADLESS_FLAG = "--headless";
 export declare const PORT_FLAG = "--port";
 export declare const DRIVE_FLAG = "--drive";
 export declare const HTTP_FLAG = "--http";
@@ -45,6 +70,17 @@ export type CliResult = {
 } | {
     kind: 'telemetry';
     action: TelemetryAction;
+} | {
+    kind: 'feedback';
+    text: string;
+    rating?: number;
+    bug: boolean;
+} | {
+    kind: 'identify';
+    context?: string;
+    company?: string;
+    email?: string;
+    forget: boolean;
 } | {
     kind: 'version';
 } | {
@@ -79,6 +115,9 @@ export type CliResult = {
     kind: 'affected';
     files: string[];
     since?: string;
+} | {
+    kind: 'hunt';
+    dir: string;
 } | {
     kind: 'capsules';
 } | {
@@ -104,5 +143,10 @@ export type CliResult = {
     kind: 'error';
     message: string;
 };
-export declare function parseCliArgs(argv: string[], defaultPort: number): CliResult;
-//# sourceMappingURL=cli-parse.d.ts.map
+/**
+ * @param defaultHeadless Whether a browser Reticle launches should be hidden when no flag says
+ *   otherwise. Injected rather than read from the environment here, because this module is pure —
+ *   `cli.ts` decides it from `CI`. The product default is FALSE: showing the run is what makes it
+ *   trustworthy, and asking people to opt into seeing their own app was backwards.
+ */
+export declare function parseCliArgs(argv: string[], defaultPort: number, defaultHeadless?: boolean): CliResult;