@reticlehq/server 2.2.1 → 2.3.0

package/dist/telemetry/argument-shape.js

@@ -0,0 +1,87 @@
+/**
+ * Which flags and parameters people actually use — WITHOUT ever sending what they set them to.
+ *
+ * This is the most dangerous data in the product to collect, and the split that makes it safe is
+ * NAMES versus VALUES:
+ *
+ *   - A flag or parameter NAME comes from a closed vocabulary we wrote ourselves. `--headed`,
+ *     `--port`, `ref`, `timeout_ms` — there are a few dozen, none of them describe the user, and
+ *     knowing which ones get used is the whole product question ("is anyone passing `fullPage`?
+ *     does anybody use `--storage-state`?").
+ *   - A VALUE is the user's. `--http-token` holds a secret. `--drive` holds a URL. `reticle_act`'s
+ *     `args` holds the text being typed into the app, which on a login form is a password. A rule
+ *     like "send short values, they're probably enums" would leak all three.
+ *
+ * So values are never sent, with one narrow exception: a handful of parameters whose values ARE our
+ * own enums, listed explicitly below. `action: "click"` is our vocabulary, not the user's, and it
+ * answers a real question. Membership in that list is opt-in per parameter and each entry names the
+ * exact values allowed — anything outside the list is reported as `other`, so a schema change can
+ * never quietly start forwarding free text.
+ */
+import { ActionType, FeedbackKind, QueryBy, SnapshotMode } from '@reticlehq/core';
+/**
+ * Parameters whose values are enums WE define, and the exact values allowed on the wire. An
+ * unrecognized value reports `other` rather than itself; that fallback is what makes this safe
+ * against a future where one of these params starts accepting free text.
+ */
+const SAFE_ENUM_PARAMS = new Map([
+    // Every entry DERIVED from the enum core already owns, never hand-listed. The first version listed
+    // them literally and was wrong on the day it shipped, not merely at risk: `action` was missing
+    // `fill`, `dblclick`, `submit`, `scrollIntoView`, `drag` and `webmcp` — so `fill`, one of the most
+    // common actions there is, silently reported as `other` — while carrying a `scroll` that
+    // `ActionType` does not define. `mode` mixed SnapshotMode with unrelated session-lifecycle values.
+    // Deriving is not tidiness here; it is the difference between the data being right and being wrong.
+    ['action', new Set(Object.values(ActionType))],
+    ['by', new Set(Object.values(QueryBy))],
+    ['mode', new Set(Object.values(SnapshotMode))],
+    ['kind', new Set(Object.values(FeedbackKind))],
+    // `level` has no core enum — console levels come from the DOM console API, not from us. Listed
+    // literally BECAUSE there is nothing to derive from, which is a different situation from the four
+    // above and the reason it is called out rather than left looking like an oversight.
+    ['level', new Set(['error', 'warn', 'info', 'log', 'debug'])],
+]);
+export const OTHER_VALUE = 'other';
+/** True for anything we are willing to report a value for. */
+export function isSafeEnumParam(name) {
+    return SAFE_ENUM_PARAMS.has(name);
+}
+/**
+ * The reportable form of one parameter: `name` on its own, or `name:value` when the parameter is a
+ * known enum. Never the raw value of anything else.
+ */
+export function describeParam(name, value) {
+    const allowed = SAFE_ENUM_PARAMS.get(name);
+    if (allowed === undefined)
+        return name;
+    if (typeof value !== 'string')
+        return name;
+    return `${name}:${allowed.has(value) ? value : OTHER_VALUE}`;
+}
+/** Every parameter an agent actually passed to one tool call, reduced to names (+ safe enums). */
+export function describeToolParams(args) {
+    return Object.keys(args)
+        .filter((key) => args[key] !== undefined)
+        .map((key) => describeParam(key, args[key]))
+        .sort();
+}
+/**
+ * The flags PRESENT on a CLI invocation, by name only.
+ *
+ * Values are dropped without exception here — no enum allowlist — because the CLI's flag values are
+ * uniformly the user's: a port, a URL, a file path, a pairing token. `--http-token` alone is reason
+ * enough to make this rule absolute rather than case-by-case.
+ *
+ * Anything not starting with `--` is an argument, not a flag, and is dropped entirely: that is where
+ * the URL, the file list, and the feedback message live.
+ */
+export function describeCliFlags(argv) {
+    const flags = new Set();
+    for (const arg of argv) {
+        if (!arg.startsWith('--'))
+            continue;
+        // `--port=9000` — split so the NAME is reported and the value is discarded with everything else.
+        const name = arg.split('=')[0] ?? arg;
+        flags.add(name);
+    }
+    return [...flags].sort();
+}

package/dist/telemetry/bug-found.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Counting the defects Reticle actually finds.
+ *
+ * Every other metric in this product measures whether Reticle is USED. This one measures whether it
+ * WORKS — and it is the only number that can honestly be put in front of an investor or published,
+ * because it counts outcomes for users rather than activity by them.
+ *
+ * It is read off tool RESULTS at the single chokepoint every tool already crosses, rather than
+ * emitted from the four places that produce findings. That is deliberate: the detectors are pure
+ * functions and should stay that way, and reading results means a fifth source of findings is covered
+ * the day it starts returning one of these shapes, instead of the day someone remembers to instrument
+ * it.
+ *
+ * What is sent is the KIND from Reticle's own findings vocabulary — `signal-contradicted`,
+ * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
+ * anyone's app: that a class of defect was found, never what it was found in.
+ */
+import { type BugFound } from '@reticlehq/core';
+/**
+ * A defect as the CLASSIFIER sees it — everything except `repeat`.
+ *
+ * Whether a kind is new belongs to the session, and these detectors are pure functions that know
+ * nothing about sessions and should stay that way. The emission site owns the dedup flag.
+ */
+export type BugCandidate = Omit<BugFound, 'repeat'>;
+/**
+ * The defects in one tool result.
+ *
+ * Ordering matters for the false-green flag: a contradiction found alongside a PASSING assertion is
+ * the case the product exists for — the screen looked right, the write failed, and every other tool
+ * on the market would have called it green. That pairing is what `falseGreen` marks.
+ */
+export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];

package/dist/telemetry/bug-found.js

@@ -0,0 +1,95 @@
+/**
+ * Counting the defects Reticle actually finds.
+ *
+ * Every other metric in this product measures whether Reticle is USED. This one measures whether it
+ * WORKS — and it is the only number that can honestly be put in front of an investor or published,
+ * because it counts outcomes for users rather than activity by them.
+ *
+ * It is read off tool RESULTS at the single chokepoint every tool already crosses, rather than
+ * emitted from the four places that produce findings. That is deliberate: the detectors are pure
+ * functions and should stay that way, and reading results means a fifth source of findings is covered
+ * the day it starts returning one of these shapes, instead of the day someone remembers to instrument
+ * it.
+ *
+ * What is sent is the KIND from Reticle's own findings vocabulary — `signal-contradicted`,
+ * `console-error`, `duplicate-request`. Never a selector, a URL, an element, or a description of
+ * anyone's app: that a class of defect was found, never what it was found in.
+ */
+import { BugSource, ContradictionKind } from '@reticlehq/core';
+/** Cap per tool call — a pathological crawl must not turn one call into a thousand events. */
+const MAX_BUGS_PER_CALL = 25;
+function kindsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        const kind = entry?.kind;
+        return typeof kind === 'string' ? kind : undefined;
+    })
+        .filter((kind) => kind !== undefined);
+}
+/**
+ * The defects in one tool result.
+ *
+ * Ordering matters for the false-green flag: a contradiction found alongside a PASSING assertion is
+ * the case the product exists for — the screen looked right, the write failed, and every other tool
+ * on the market would have called it green. That pairing is what `falseGreen` marks.
+ */
+export function bugsInResult(toolName, result) {
+    const bugs = [];
+    const passed = result['pass'] === true;
+    // 1. Contradictions — channels disagreeing. Invisible to a human watching the screen.
+    for (const kind of kindsOf(result['contradictions'])) {
+        bugs.push({ source: BugSource.CONTRADICTION, kind, falseGreen: passed, tool: toolName });
+    }
+    // 2. Crawl anomalies — found autonomously, with nobody writing a test. Crawl reports its own
+    //    contradictions inside `anomalies` too, so classify by kind rather than by which array it sat in.
+    for (const kind of kindsOf(result['anomalies'])) {
+        bugs.push({
+            source: BugSource.CRAWL,
+            kind,
+            // A crawl contradiction presents as success too — the click looked fine and its write did not
+            // — even though no assertion was made. See the definition on `falseGreen`.
+            falseGreen: CONTRADICTION_KINDS.has(kind),
+            tool: toolName,
+        });
+    }
+    // 3. A failed assertion — the agent declared a consequence and it did not hold.
+    //    Only when nothing above already explained it, or one defect would be counted twice.
+    if (result['pass'] === false && bugs.length === 0) {
+        const reason = result['assertion'];
+        bugs.push({
+            source: BugSource.ASSERTION,
+            kind: typeof reason === 'string' && reason.length > 0 ? reason.slice(0, 64) : 'assertion-failed',
+            falseGreen: false,
+            tool: toolName,
+        });
+    }
+    // 4. Replay failures — a saved flow that used to pass no longer does. That is a regression caught,
+    //    which is a different and stronger claim than "a check failed".
+    if (result['status'] === 'fail' && Array.isArray(result['failures'])) {
+        for (const _failure of result['failures'].slice(0, MAX_BUGS_PER_CALL)) {
+            bugs.push({
+                source: BugSource.REPLAY,
+                kind: 'flow-regression',
+                falseGreen: false,
+                tool: toolName,
+            });
+        }
+    }
+    return bugs.slice(0, MAX_BUGS_PER_CALL);
+}
+/**
+ * Crawl anomaly kinds that are CONTRADICTIONS rather than single-channel faults.
+ *
+ * `reticle_crawl` returns both classes in one `anomalies` array — a console error is one channel
+ * complaining, while a UI that advanced over a failed write is two channels disagreeing. Only the
+ * second presents as success, and collapsing them would inflate the one claim that has to be exact.
+ *
+ * DERIVED from core's `ContradictionKind`, never hand-listed. The first version copied the twelve
+ * strings into a literal here, which matched on the day it was written and would have silently
+ * misclassified the thirteenth: a new contradiction kind would have been counted as an ordinary
+ * fault, quietly deflating the exact number we intend to publish. A copied enum is a drift hazard
+ * wherever it appears; it is a correctness hazard when the thing that drifts is a public claim.
+ */
+const CONTRADICTION_KINDS = new Set(Object.values(ContradictionKind));

package/dist/telemetry/cli-telemetry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Report that a person ran a `reticle` subcommand.
+ *
+ * `_daemon` is EXCLUDED, and that exclusion is the whole point of this function. `reticle mcp` and
+ * `reticle serve` start the daemon by re-running this very binary, so the child re-entered the CLI
+ * entry point and emitted a second event for what a person experienced as ONE action. The old
+ * `invoke` metric was therefore inflated ~2x — and inflated worst on the agent-driven sessions that
+ * matter most, while one-shot commands like `version` counted once. That skewed the RATIO between
+ * commands, not merely the scale, which is the kind of error you cannot correct for after the fact.
+ * The daemon\'s own lifecycle is already reported by `daemon_started` / `daemon_stopped`; a spawned
+ * daemon is not a CLI run.
+ */
+export declare function reportCliRun(argv: readonly string[]): void;

package/dist/telemetry/cli-telemetry.js

@@ -0,0 +1,43 @@
+/**
+ * The one telemetry event a human directly causes: they typed a `reticle` command.
+ *
+ * Lives in its own module so `cli.ts` stays a dispatcher, and so the `_daemon` exclusion below sits
+ * next to the explanation of why it exists rather than buried in a startup function.
+ */
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { DAEMON_INNER_COMMAND, knownCommand } from '../cli-parse.js';
+import { getTelemetry } from './telemetry.js';
+import { describeCliFlags } from './argument-shape.js';
+/**
+ * Report that a person ran a `reticle` subcommand.
+ *
+ * `_daemon` is EXCLUDED, and that exclusion is the whole point of this function. `reticle mcp` and
+ * `reticle serve` start the daemon by re-running this very binary, so the child re-entered the CLI
+ * entry point and emitted a second event for what a person experienced as ONE action. The old
+ * `invoke` metric was therefore inflated ~2x — and inflated worst on the agent-driven sessions that
+ * matter most, while one-shot commands like `version` counted once. That skewed the RATIO between
+ * commands, not merely the scale, which is the kind of error you cannot correct for after the fact.
+ * The daemon\'s own lifecycle is already reported by `daemon_started` / `daemon_stopped`; a spawned
+ * daemon is not a CLI run.
+ */
+export function reportCliRun(argv) {
+    const firstArg = argv[0];
+    if (firstArg === DAEMON_INNER_COMMAND)
+        return;
+    const telemetry = getTelemetry();
+    // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
+    if (telemetry.firstRun)
+        void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, { detach: true });
+    void telemetry.emit(TelemetryEventKind.CLI_COMMAND_RUN, {
+        detach: true,
+        actor: TelemetryActor.HUMAN,
+        // A fixed, low-cardinality vocabulary WE define, so it is safe to send whole and it is the closest
+        // honest read we have on intent: `verify` and `gate` mean something very different from `status`.
+        // An unrecognized first arg reports as `unknown` rather than being echoed — an echo would put
+        // whatever someone mistyped, including a path or a URL, straight onto the wire.
+        command: knownCommand(firstArg),
+        // Which flags were PRESENT, by name only — never their values. `--http-token` alone makes that
+        // rule absolute rather than case-by-case; `--drive` and `--storage-state` carry a URL and a path.
+        flags: describeCliFlags(argv),
+    });
+}

package/dist/telemetry/connect-failure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Classifying WHY a browser connection failed, into causes that each have a different fix.
+ *
+ * A raw error message cannot be sent — it carries CDP URLs, executable paths, and home directories —
+ * and would be useless if it could, because the same cause arrives worded five different ways from
+ * Playwright, Node and the OS. What we need is the small set of THINGS THAT ACTUALLY GO WRONG:
+ * a missing browser binary is a docs problem, a refused CDP endpoint is a configuration problem, a
+ * pool timeout is a capacity problem. Three very different responses from us.
+ *
+ * `OTHER` is the bucket to watch. A large `OTHER` count means the classifier has a blind spot and
+ * this list needs another entry — which is a signal in itself, and the reason it is never merged
+ * into one of the known causes.
+ */
+import { ConnectFailure } from '@reticlehq/core';
+/** The cause behind a connection error, or `OTHER` when we do not recognize it. */
+export declare function classifyConnectFailure(error: unknown): ConnectFailure;

package/dist/telemetry/connect-failure.js

@@ -0,0 +1,44 @@
+/**
+ * Classifying WHY a browser connection failed, into causes that each have a different fix.
+ *
+ * A raw error message cannot be sent — it carries CDP URLs, executable paths, and home directories —
+ * and would be useless if it could, because the same cause arrives worded five different ways from
+ * Playwright, Node and the OS. What we need is the small set of THINGS THAT ACTUALLY GO WRONG:
+ * a missing browser binary is a docs problem, a refused CDP endpoint is a configuration problem, a
+ * pool timeout is a capacity problem. Three very different responses from us.
+ *
+ * `OTHER` is the bucket to watch. A large `OTHER` count means the classifier has a blind spot and
+ * this list needs another entry — which is a signal in itself, and the reason it is never merged
+ * into one of the known causes.
+ */
+import { ConnectFailure } from '@reticlehq/core';
+/** Ordered most-specific first; the first match wins. Patterns track messages we have actually seen. */
+const RULES = [
+    // Playwright's own wording when the browser was never downloaded.
+    {
+        match: /executable doesn.?t exist|playwright install|browsertype\.launch/i,
+        cause: ConnectFailure.CHROMIUM_MISSING,
+    },
+    {
+        match: /cannot find module ['"]?playwright|playwright is not installed/i,
+        cause: ConnectFailure.PLAYWRIGHT_MISSING,
+    },
+    {
+        match: /econnrefused|connect over cdp|websocket error|failed to connect|enotfound|etimedout/i,
+        cause: ConnectFailure.CDP_UNREACHABLE,
+    },
+    {
+        match: /target (?:page|closed)|browser has been closed|browser has disconnected|crashed/i,
+        cause: ConnectFailure.BROWSER_CRASHED,
+    },
+    { match: /pool|lease.*timed out|timed out waiting/i, cause: ConnectFailure.POOL_TIMEOUT },
+];
+/** The cause behind a connection error, or `OTHER` when we do not recognize it. */
+export function classifyConnectFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    for (const rule of RULES) {
+        if (rule.match.test(message))
+            return rule.cause;
+    }
+    return ConnectFailure.OTHER;
+}

package/dist/telemetry/daemon-telemetry.d.ts

@@ -0,0 +1,19 @@
+/** Stops the timers this installed. Called from the daemon's shutdown path. */
+export interface DaemonTelemetry {
+    /**
+     * Emit the final, rich session summary and stop flushing. Safe to call more than once.
+     *
+     * AWAITABLE, and the daemon must await it. Every other send in the product is fire-and-forget
+     * because losing one counter never matters — but this one carries the whole session, and the
+     * process calls `process.exit(0)` immediately afterwards, which kills an in-flight POST. Verified
+     * against a local capture server: fire-and-forget lost the event every single time. A send that
+     * fails or hangs still cannot block the exit, because `emit` swallows its own errors and is bounded
+     * by its own request timeout.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Report the daemon as started, profile the project once, and keep the session counters flushing.
+ * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
+ */
+export declare function installDaemonTelemetry(cwd: string, now?: () => number): DaemonTelemetry;

package/dist/telemetry/daemon-telemetry.js

@@ -0,0 +1,76 @@
+/**
+ * The daemon's telemetry lifecycle, in one place: start, the periodic flush that survives a kill, the
+ * one-shot project profile, and the rich summary on shutdown.
+ *
+ * Extracted from `cli.ts` because it is a cohesive unit with its own timers and its own failure rule
+ * (nothing here may ever be able to fail a daemon start), and because `cli.ts` is a dispatcher — the
+ * more of this that lives there, the harder it is to see what a command actually does.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+import { getSessionMetrics } from './session-metrics.js';
+import { profileProject } from './project-profile.js';
+import { startUpdateCheck } from '../update/update-nudge.js';
+import { markDaemonStart } from './mcp-connection.js';
+/** Let the daemon finish coming up before walking the source tree for a profile. */
+const PROJECT_PROFILE_DELAY_MS = 5_000;
+/**
+ * How often a long-lived daemon flushes its counters.
+ *
+ * ponytail: coarse on purpose. A daemon that is SIGKILLed — OOM, a closed laptop, `kill -9` — never
+ * reaches its shutdown handler, so without this the whole session's counters die with it. Thirty
+ * minutes bounds that loss to one window while keeping the event volume near zero for the common case
+ * (most daemons stop cleanly and send exactly one summary). If the lost windows ever show up as a
+ * real gap, the upgrade is a small on-disk journal replayed at the next start, not a shorter timer.
+ */
+const SESSION_FLUSH_MS = 30 * 60 * 1000;
+/**
+ * Report the daemon as started, profile the project once, and keep the session counters flushing.
+ * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
+ */
+export function installDaemonTelemetry(cwd, now = () => Date.now()) {
+    const metrics = getSessionMetrics(now);
+    void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED);
+    // Ask npm whether a newer Reticle exists, so the agent can tell the human. Nothing checked before
+    // this, so a published fix was invisible until someone manually ran `reticle update`.
+    startUpdateCheck(now);
+    markDaemonStart(now());
+    // One profile per daemon start: what kind of project this is and how deeply Reticle is used in it.
+    // Deferred off the boot path — it walks the source tree, and nothing about a daemon coming up
+    // should wait on a filesystem scan.
+    setTimeout(() => {
+        try {
+            void getTelemetry().emit(TelemetryEventKind.PROJECT_PROFILED, {
+                project: profileProject(cwd, now()),
+            });
+        }
+        catch {
+            /* a profile is a nice-to-have; it must never touch the daemon */
+        }
+    }, PROJECT_PROFILE_DELAY_MS).unref();
+    const flush = setInterval(() => {
+        if (metrics.empty)
+            return; // an idle window is not worth an event
+        void getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
+            session: metrics.summarize(false),
+        });
+        metrics.reset();
+    }, SESSION_FLUSH_MS);
+    flush.unref();
+    let stopped;
+    return {
+        shutdown() {
+            // Both SIGTERM and the idle-shutdown path can call this; the second caller awaits the first
+            // send rather than emitting a duplicate summary.
+            stopped ??= (async () => {
+                clearInterval(flush);
+                // The rich one: the whole session in a single event — duration, the tool histogram, error
+                // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
+                await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
+                    session: metrics.summarize(true),
+                });
+            })();
+            return stopped;
+        },
+    };
+}

package/dist/telemetry/dev-repo.d.ts

@@ -0,0 +1,10 @@
+/** Walk up from `cwd` to the filesystem root, looking for a package.json that names this monorepo. */
+export declare function isReticleSourceCheckout(cwd: string): boolean;
+/**
+ * Load `<dir>/.env` into `env`. Best-effort and deliberately minimal — no expansion, no multiline.
+ *
+ * A variable already present in the environment ALWAYS wins. A .env that overrode an explicit
+ * `RETICLE_PORT` from the caller's shell would bind the daemon somewhere the caller never asked for,
+ * which is a worse surprise than the convenience is worth.
+ */
+export declare function loadDotEnv(dir: string, env?: NodeJS.ProcessEnv): void;

package/dist/telemetry/dev-repo.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+/**
+ * Two guards that keep Reticle's own development off its telemetry.
+ *
+ * `.env` is the convenient one and is useful to every user: put `RETICLE_TELEMETRY=0` in a project's
+ * `.env` and the daemon honours it. But `.env` is gitignored, so it exists only on the machine that
+ * created it — a fresh clone of this repo would phone home on the first `reticle serve` a
+ * contributor runs. `isReticleSourceCheckout` closes that: the marker is the committed root
+ * package.json, so the guarantee travels with the repository instead of with one developer's
+ * untracked file.
+ */
+/** The monorepo's root package name — the one committed marker that says "this IS Reticle". */
+const MONOREPO_NAME = 'reticle-monorepo';
+/** Walk up from `cwd` to the filesystem root, looking for a package.json that names this monorepo. */
+export function isReticleSourceCheckout(cwd) {
+    let dir = cwd;
+    const { root } = parse(cwd);
+    for (;;) {
+        const pkg = join(dir, 'package.json');
+        if (existsSync(pkg)) {
+            try {
+                const parsed = JSON.parse(readFileSync(pkg, 'utf8'));
+                const name = typeof parsed === 'object' && parsed !== null
+                    ? parsed.name
+                    : undefined;
+                if (name === MONOREPO_NAME)
+                    return true;
+            }
+            catch {
+                /* an unreadable/!JSON package.json simply is not the marker */
+            }
+        }
+        if (dir === root)
+            return false;
+        const next = dirname(dir);
+        if (next === dir)
+            return false;
+        dir = next;
+    }
+}
+/** Strip one layer of matching quotes from a .env value. */
+function unquote(value) {
+    const first = value[0];
+    if ((first === '"' || first === "'") && value.endsWith(first) && value.length >= 2) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Load `<dir>/.env` into `env`. Best-effort and deliberately minimal — no expansion, no multiline.
+ *
+ * A variable already present in the environment ALWAYS wins. A .env that overrode an explicit
+ * `RETICLE_PORT` from the caller's shell would bind the daemon somewhere the caller never asked for,
+ * which is a worse surprise than the convenience is worth.
+ */
+export function loadDotEnv(dir, env = process.env) {
+    const file = join(dir, '.env');
+    let text;
+    try {
+        if (!existsSync(file))
+            return;
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue; // not a KEY=value pair — skip rather than fail the whole file
+        const key = line.slice(0, eq).trim();
+        if (key.length === 0 || env[key] !== undefined)
+            continue;
+        env[key] = unquote(line.slice(eq + 1).trim());
+    }
+}

package/dist/telemetry/error-fingerprint.d.ts

@@ -0,0 +1,24 @@
+/** The skeleton of a message: variable parts blanked, whitespace collapsed, length bounded. */
+export declare function errorSkeleton(message: string): string;
+/** A stable, opaque group key for an error message. Same defect ⇒ same key, on every machine. */
+export declare function fingerprintError(message: string): string;
+/**
+ * Frames from a stack trace that belong to RETICLE, reduced to `basename:line`.
+ *
+ * A crash stack is mostly the user's own application and node internals; neither is ours to collect,
+ * and the user's frames are the ones that would carry their directory layout and module names. Only
+ * frames inside a `@reticlehq/*` package or a `reticle` dist path survive, and even those keep just
+ * the file basename — enough to point a maintainer at the right file, never enough to describe
+ * anyone's machine.
+ */
+export declare function reticleFrames(stack: string): string[];
+/** How many of our own frames to carry. The innermost few are where the defect is. */
+export declare const MAX_REPORTED_FRAMES = 12;
+/**
+ * A crash fingerprint from the error's type and its Reticle-owned frames. Falls back to the message
+ * skeleton when a stack has no Reticle frames at all (a crash from deep inside a dependency), so a
+ * crash is never dropped for lack of a clean attribution.
+ */
+export declare function fingerprintCrash(errorType: string, stack: string, message: string): string;
+/** The error's constructor name (`TypeError`), or `Unknown` for a thrown non-Error. */
+export declare function errorTypeOf(error: unknown): string;

package/dist/telemetry/error-fingerprint.js

@@ -0,0 +1,88 @@
+/**
+ * Turning errors into something we can COUNT without carrying anything anyone wrote.
+ *
+ * An error message is the most tempting thing to send and the most dangerous: it is where a selector,
+ * a URL, a customer id, a file path, or a snippet of someone's app ends up. But "which error is
+ * hurting people most" is genuinely the highest-value product question we can ask, and it needs
+ * grouping — a thousand machines hitting the same defect have to collapse into one row before anyone
+ * can rank it.
+ *
+ * A fingerprint gives us the grouping without the content: strip every variable part, keep the
+ * skeleton, hash it. `no baseline named 'checkout-v3'` and `no baseline named 'login'` both become
+ * the same fingerprint, and neither flow name leaves the machine. The output is a short hex string,
+ * so even the skeleton is not readable on our side — it is an opaque group key, and its only power is
+ * that identical failures share it.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * The variable parts, replaced before hashing. Order matters: quoted strings go first, because a
+ * quoted value often contains the very numbers and paths the later rules would only partly catch.
+ */
+const VARIABLE_PARTS = [
+    /"[^"]*"|'[^']*'|`[^`]*`/g, // quoted values — names, selectors, snippets
+    /\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, // URLs
+    /(?:\/[\w.-]+){2,}\/?/g, // POSIX-ish paths
+    /[A-Za-z]:\\[^\s]*/g, // Windows paths
+    /\b[0-9a-f]{8,}\b/gi, // hex ids, hashes, uuids-without-dashes
+    /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, // uuids
+    /\d+/g, // any remaining number — ports, counts, timeouts
+];
+/** The skeleton of a message: variable parts blanked, whitespace collapsed, length bounded. */
+export function errorSkeleton(message) {
+    let skeleton = message;
+    for (const pattern of VARIABLE_PARTS)
+        skeleton = skeleton.replace(pattern, '*');
+    return skeleton.replace(/\s+/g, ' ').trim().slice(0, 200);
+}
+/** A stable, opaque group key for an error message. Same defect ⇒ same key, on every machine. */
+export function fingerprintError(message) {
+    return createHash('sha256').update(errorSkeleton(message)).digest('hex').slice(0, 12);
+}
+/**
+ * Frames from a stack trace that belong to RETICLE, reduced to `basename:line`.
+ *
+ * A crash stack is mostly the user's own application and node internals; neither is ours to collect,
+ * and the user's frames are the ones that would carry their directory layout and module names. Only
+ * frames inside a `@reticlehq/*` package or a `reticle` dist path survive, and even those keep just
+ * the file basename — enough to point a maintainer at the right file, never enough to describe
+ * anyone's machine.
+ */
+export function reticleFrames(stack) {
+    const frames = [];
+    for (const line of stack.split('\n')) {
+        if (!/@reticlehq[/\\]|[/\\]reticle[/\\]dist[/\\]/.test(line))
+            continue;
+        const location = line.match(/([\w.-]+\.(?:js|mjs|cjs|ts)):(\d+)/);
+        if (location === null)
+            continue;
+        // `at Object.runTool (/path/to/invoke-tool.js:88:3)` → `runTool`. The function name is half the
+        // value of a frame in an RCA — "it died in act-tools.js" narrows to a file, "it died in
+        // resolveAnchor" names the thing that broke. Anonymous frames just report the location.
+        const fn = line.match(/at\s+(?:async\s+)?(?:new\s+)?([\w.$<>[\]]+)\s+\(/)?.[1];
+        const where = `${location[1] ?? ''}:${location[2] ?? ''}`;
+        // `Object.` / `Module.` prefixes are V8 noise that make the same function look like two.
+        const name = fn?.replace(/^(?:Object|Module|Function)\./, '');
+        frames.push(name === undefined || name === '' ? where : `${name}@${where}`);
+    }
+    return frames;
+}
+/** How many of our own frames to carry. The innermost few are where the defect is. */
+export const MAX_REPORTED_FRAMES = 12;
+/**
+ * A crash fingerprint from the error's type and its Reticle-owned frames. Falls back to the message
+ * skeleton when a stack has no Reticle frames at all (a crash from deep inside a dependency), so a
+ * crash is never dropped for lack of a clean attribution.
+ */
+export function fingerprintCrash(errorType, stack, message) {
+    const frames = reticleFrames(stack);
+    const basis = frames.length > 0
+        ? `${errorType}|${frames.join('|')}`
+        : `${errorType}|${errorSkeleton(message)}`;
+    return createHash('sha256').update(basis).digest('hex').slice(0, 12);
+}
+/** The error's constructor name (`TypeError`), or `Unknown` for a thrown non-Error. */
+export function errorTypeOf(error) {
+    if (error instanceof Error)
+        return error.constructor.name.slice(0, 64);
+    return 'Unknown';
+}