@reticlehq/server 2.2.0 → 2.3.0

package/dist/telemetry/feedback.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The feedback channel — the one place in Reticle that sends words someone wrote.
+ *
+ * Reticle is built for agents, and until now nothing closed the loop: when a tool misbehaved, or a
+ * verification came back undecidable, or an observer simply could not see the thing that mattered,
+ * that knowledge died in the agent's context window. This module is the return path. An agent files a
+ * report through `reticle_feedback` when a tool fails it; a human files one through `reticle
+ * feedback` with a rating and their own words.
+ *
+ * Three properties are non-negotiable here, because free text is a different privacy class from the
+ * event counters the rest of telemetry sends:
+ *
+ *   1. NEVER PASSIVE. There is no code path that emits feedback on its own. Every event is the direct
+ *      result of an explicit call someone made carrying content they authored. Nothing is scraped
+ *      from the app, the DOM, the network log, or the repo.
+ *   2. REDACTED BEFORE THE WIRE. `redactFeedbackText` strips the credential/PII shapes that leak into
+ *      a pasted trace even when the author meant no harm. It runs client-side, so the redaction is
+ *      auditable in this repo rather than promised in a policy.
+ *   3. INDEPENDENTLY DISABLE-ABLE. `RETICLE_FEEDBACK=0` kills the channel while leaving anonymous
+ *      adoption metrics on — the setting an org wants when counters are fine but prose is not. Every
+ *      existing switch (`RETICLE_TELEMETRY=0`, `DO_NOT_TRACK`, `reticle telemetry disable`) still
+ *      disables it too, since it rides the same emitter.
+ */
+import { type Feedback } from '@reticlehq/core';
+import { type SessionFacts } from './feedback-context.js';
+/** Kills the feedback channel ONLY — adoption counters keep flowing. */
+export declare const FEEDBACK_ENV = "RETICLE_FEEDBACK";
+/** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
+export declare const REDACTED = "[redacted]";
+export interface Redaction {
+    text: string;
+    /** Which rules fired, deduped. Surfaced back to the author so a redaction is never silent. */
+    removed: string[];
+}
+/** Strip credential/PII shapes and cap the length. Pure — the tests read like a spec of what leaks. */
+export declare function redactFeedbackText(input: string, max: number): Redaction;
+/** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
+export declare function feedbackDisabled(env?: NodeJS.ProcessEnv): boolean;
+/** What the author supplies; the environment context is detected, never asked for. */
+export type FeedbackInput = Pick<Feedback, 'source' | 'kind' | 'text' | 'trace' | 'rating' | 'need' | 'impact' | 'currentApproach' | 'model'>;
+export interface FeedbackReceipt {
+    /** False when a kill switch is on — the report was DROPPED, and the caller is told so plainly. */
+    sent: boolean;
+    reason?: string;
+    /** Which redaction rules fired. Empty when nothing needed removing. */
+    redacted: string[];
+    /** The exact context that went with it, echoed back so the send is never a black box. */
+    context: Partial<Feedback>;
+}
+/**
+ * Redact, validate, and emit one feedback report. Returns a receipt rather than throwing: a feedback
+ * send that fails must never take down the tool call that reported the failure — that would punish
+ * the exact behaviour we are trying to encourage.
+ */
+export declare function submitFeedback(input: FeedbackInput, opts?: {
+    cwd?: string;
+    session?: SessionFacts;
+    env?: NodeJS.ProcessEnv;
+}): Promise<FeedbackReceipt>;
+/**
+ * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the
+ * reticle version, the OS, and whether this is CI. They are the single most-asked question of any bug
+ * report ("what version?"), so they are echoed here rather than left as an invisible claim: what the
+ * CLI prints is then genuinely everything that goes.
+ */
+export declare function describeFeedbackPayload(context: Partial<Feedback>): Record<string, unknown>;

package/dist/telemetry/feedback.js

@@ -0,0 +1,175 @@
+/**
+ * The feedback channel — the one place in Reticle that sends words someone wrote.
+ *
+ * Reticle is built for agents, and until now nothing closed the loop: when a tool misbehaved, or a
+ * verification came back undecidable, or an observer simply could not see the thing that mattered,
+ * that knowledge died in the agent's context window. This module is the return path. An agent files a
+ * report through `reticle_feedback` when a tool fails it; a human files one through `reticle
+ * feedback` with a rating and their own words.
+ *
+ * Three properties are non-negotiable here, because free text is a different privacy class from the
+ * event counters the rest of telemetry sends:
+ *
+ *   1. NEVER PASSIVE. There is no code path that emits feedback on its own. Every event is the direct
+ *      result of an explicit call someone made carrying content they authored. Nothing is scraped
+ *      from the app, the DOM, the network log, or the repo.
+ *   2. REDACTED BEFORE THE WIRE. `redactFeedbackText` strips the credential/PII shapes that leak into
+ *      a pasted trace even when the author meant no harm. It runs client-side, so the redaction is
+ *      auditable in this repo rather than promised in a policy.
+ *   3. INDEPENDENTLY DISABLE-ABLE. `RETICLE_FEEDBACK=0` kills the channel while leaving anonymous
+ *      adoption metrics on — the setting an org wants when counters are fine but prose is not. Every
+ *      existing switch (`RETICLE_TELEMETRY=0`, `DO_NOT_TRACK`, `reticle telemetry disable`) still
+ *      disables it too, since it rides the same emitter.
+ */
+import { FeedbackSchema, FEEDBACK_TEXT_MAX, FEEDBACK_TRACE_MAX, FEEDBACK_FIELD_MAX, TelemetryEventKind, } from '@reticlehq/core';
+import { platform } from 'node:os';
+import { getTelemetry } from './telemetry.js';
+import { SERVER_VERSION } from '../server-version.js';
+import { feedbackContext } from './feedback-context.js';
+/** Kills the feedback channel ONLY — adoption counters keep flowing. */
+export const FEEDBACK_ENV = 'RETICLE_FEEDBACK';
+/** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
+export const REDACTED = '[redacted]';
+/**
+ * The shapes that leak. Ordered most-specific first — a URL carrying inline credentials must be
+ * caught as a URL before the bare-token rule chews the middle out of it.
+ *
+ * This is a net, not a proof. It cannot catch a secret that looks like an ordinary word, which is
+ * exactly why the tool description tells the agent not to paste app source or user data in the first
+ * place. Defense in depth: instruct first, redact second, cap third.
+ */
+const REDACTIONS = [
+    // scheme://user:pass@host — the credential is in the authority section.
+    { pattern: /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+:[^\s/@]+@/gi, label: 'url-credentials' },
+    { pattern: /\b[\w.%+-]+@[\w.-]+\.[a-z]{2,}\b/gi, label: 'email' },
+    // Credential assignments: the KEY stays (it is the useful part), the VALUE goes. The auth SCHEME
+    // (`Bearer`, `Basic`, `Token`) is consumed as part of the value, not left as the value — matching
+    // only `\S+` after the separator ate the word "Bearer" and published the secret right behind it.
+    {
+        pattern: /\b(authorization|api[-_]?key|secret|token|password|passwd|pwd)\b(?:\s*[:=]\s*|\s+)(?:(?:bearer|basic|token|digest)\s+)?\S+/gi,
+        label: 'credential-assignment',
+    },
+    // Vendor key formats that are self-identifying (sk-…, ghp_…, AKIA…, xoxb-…, eyJ… JWTs).
+    { pattern: /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/g, label: 'vendor-key' },
+    { pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, label: 'github-token' },
+    { pattern: /\bAKIA[0-9A-Z]{16}\b/g, label: 'aws-key' },
+    { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, label: 'slack-token' },
+    { pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, label: 'jwt' },
+    // Home directories carry the account name, and a trace is full of them.
+    { pattern: /(?:\/Users\/|\/home\/|[A-Z]:\\Users\\)[^\s/\\:"']+/g, label: 'home-path' },
+];
+/** Strip credential/PII shapes and cap the length. Pure — the tests read like a spec of what leaks. */
+export function redactFeedbackText(input, max) {
+    const removed = new Set();
+    let text = input;
+    for (const { pattern, label } of REDACTIONS) {
+        text = text.replace(pattern, (_match, ...groups) => {
+            removed.add(label);
+            // A rule with a leading capture keeps it (the scheme, the `api_key=` key) so the reader still
+            // sees WHAT was removed, not just that something was.
+            const prefix = typeof groups[0] === 'string' ? groups[0] : '';
+            return `${prefix}${REDACTED}`;
+        });
+    }
+    return { text: text.slice(0, max), removed: [...removed] };
+}
+/** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
+export function feedbackDisabled(env = process.env) {
+    const value = (env[FEEDBACK_ENV] ?? '').toLowerCase();
+    return value === '0' || value === 'false' || value === 'off' || value === 'no';
+}
+/**
+ * The fields an author writes, and therefore the fields that must be redacted. ONE list, used both to
+ * redact and to assemble — so a new field cannot be added to one and missed by the other.
+ *
+ * `model` is deliberately included: it is agent-supplied text like the rest, and while a model name
+ * is not sensitive, exempting it would re-introduce the "which fields are safe?" judgement call that
+ * caused the original gap.
+ */
+const AUTHOR_WRITTEN_FIELDS = new Set([
+    'text',
+    'trace',
+    'need',
+    'impact',
+    'currentApproach',
+    'model',
+]);
+/** Per-field caps; anything unlisted uses the standard field cap. */
+const FIELD_CAPS = {
+    text: FEEDBACK_TEXT_MAX,
+    trace: FEEDBACK_TRACE_MAX,
+    model: 64,
+};
+/**
+ * Redact, validate, and emit one feedback report. Returns a receipt rather than throwing: a feedback
+ * send that fails must never take down the tool call that reported the failure — that would punish
+ * the exact behaviour we are trying to encourage.
+ */
+export async function submitFeedback(input, opts = {}) {
+    const env = opts.env ?? process.env;
+    const context = feedbackContext(opts.cwd ?? process.cwd(), opts.session);
+    // Redact EVERY author-written field, derived from the input rather than listed.
+    //
+    // The first version named `text` and `trace` explicitly. When `need`, `impact` and
+    // `currentApproach` were added later they silently bypassed redaction entirely — three new
+    // free-text fields going to the wire raw, and a `currentApproach` reading "hardcoding the token
+    // sk-…" would have shipped the token. Enumerating the fields to protect is the same class of
+    // mistake as hand-copying an enum: correct on the day it is written, quietly wrong at the next
+    // addition. Deriving the set means a sixth field is covered the moment it exists.
+    const redactions = new Map();
+    for (const [key, value] of Object.entries(input)) {
+        if (typeof value !== 'string' || value === '')
+            continue;
+        if (!AUTHOR_WRITTEN_FIELDS.has(key))
+            continue;
+        redactions.set(key, redactFeedbackText(value, FIELD_CAPS[key] ?? FEEDBACK_FIELD_MAX));
+    }
+    const body = redactions.get('text') ?? { text: '', removed: [] };
+    const redacted = [...new Set([...redactions.values()].flatMap((r) => r.removed))];
+    if (feedbackDisabled(env)) {
+        return { sent: false, reason: `feedback is disabled by ${FEEDBACK_ENV}`, redacted, context };
+    }
+    const telemetry = getTelemetry();
+    if (!telemetry.enabled) {
+        return {
+            sent: false,
+            reason: 'telemetry is disabled on this machine, so feedback has nowhere to go',
+            redacted,
+            context,
+        };
+    }
+    const parsed = FeedbackSchema.safeParse({
+        source: input.source,
+        kind: input.kind,
+        // Every author-written field, redacted. Built from the map so nothing can be forgotten here
+        // either — the field list exists in exactly one place.
+        ...Object.fromEntries([...redactions].filter(([, r]) => r.text !== '').map(([key, r]) => [key, r.text])),
+        text: body.text,
+        ...(input.rating !== undefined ? { rating: input.rating } : {}),
+        ...context,
+    });
+    if (!parsed.success) {
+        return {
+            sent: false,
+            reason: parsed.error.issues[0]?.message ?? 'invalid feedback',
+            redacted,
+            context,
+        };
+    }
+    await telemetry.emit(TelemetryEventKind.FEEDBACK_SUBMITTED, { feedback: parsed.data });
+    return { sent: true, redacted, context };
+}
+/**
+ * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the
+ * reticle version, the OS, and whether this is CI. They are the single most-asked question of any bug
+ * report ("what version?"), so they are echoed here rather than left as an invisible claim: what the
+ * CLI prints is then genuinely everything that goes.
+ */
+export function describeFeedbackPayload(context) {
+    return {
+        ...context,
+        version: SERVER_VERSION,
+        os: platform(),
+        ci: process.env['CI'] !== undefined,
+    };
+}

package/dist/telemetry/git-facts.d.ts

@@ -0,0 +1,21 @@
+import { GitState, RepoForge } from '@reticlehq/core';
+export interface GitFacts {
+    /** none | local_only (init'd, never pushed) | remote (has an origin). */
+    state: GitState;
+    /** The NORMALIZED origin — hashed by the caller, never sent raw. Absent unless state is `remote`. */
+    origin?: string;
+    /** Which forge hosts it, bucketed. Absent unless state is `remote`. */
+    forge?: RepoForge;
+}
+/** `git@github.com:Acme/Web.git` / `https://u:p@github.com/Acme/Web` → `github.com/acme/web`. */
+export declare const normalizeGitOrigin: (url: string) => string;
+/** Bucket a normalized origin by its host. Unknown hosts are `self_hosted` — never the host itself. */
+export declare function forgeOf(normalizedOrigin: string): RepoForge;
+type FileReader = (path: string) => string;
+type PathExists = (path: string) => boolean;
+/**
+ * Walk up from `cwd` looking for a `.git`, and report what is there. Never throws: an unreadable or
+ * malformed config reports the state we could confirm rather than failing a startup path.
+ */
+export declare function gitFacts(cwd: string, read?: FileReader, exists?: PathExists): GitFacts;
+export {};

package/dist/telemetry/git-facts.js

@@ -0,0 +1,109 @@
+/**
+ * What we can honestly know about a project's git setup, read from `.git/` on disk.
+ *
+ * This exists to make three counting questions answerable and, just as importantly, to make it
+ * visible when they are NOT answerable:
+ *
+ *   - how many users does one project have?  (distinct anonymousId per projectId)
+ *   - how many projects does one user have?  (distinct projectId per anonymousId)
+ *   - how many people work alone vs on a shared repo?
+ *
+ * All three depend on `projectId` meaning the same thing on two different machines, which is only
+ * true when it was derived from a git ORIGIN. Outside a repo, or in a repo nobody has pushed, the
+ * fingerprint falls back to a hash of the directory path — and two teammates on the same unpushed
+ * project then look like two unrelated projects. That is not a bug we can fix (there is nothing
+ * shared to hash), so instead every event reports WHICH source it used, and the analytics can filter
+ * to the rows where "users per project" is a real number instead of quietly averaging in the ones
+ * where it is always 1.
+ *
+ * Read from `.git/config` directly rather than by shelling out to `git`: this runs on the CLI's
+ * startup path, where a ~30ms subprocess spawn would tax every single `reticle` command, and it must
+ * work on a machine with no `git` binary installed at all.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { GitState, RepoForge } from '@reticlehq/core';
+/** How far up the tree to look for a `.git` before giving up. Deep monorepos are still well inside. */
+const MAX_PARENT_WALK = 20;
+/**
+ * The public forges we name. Everything else reports `self_hosted` WITHOUT its hostname — an internal
+ * git host is often `git.<company>.com`, which would identify the company outright and is exactly the
+ * covert identification the telemetry policy promises not to do. The bucket alone is the useful
+ * signal anyway: self-hosted git is a strong enterprise tell, which is the question actually being
+ * asked.
+ */
+const PUBLIC_FORGES = [
+    ['github.com', RepoForge.GITHUB],
+    ['gitlab.com', RepoForge.GITLAB],
+    ['bitbucket.org', RepoForge.BITBUCKET],
+    ['dev.azure.com', RepoForge.AZURE],
+    ['git.sr.ht', RepoForge.SOURCEHUT],
+    ['codeberg.org', RepoForge.CODEBERG],
+];
+/** `git@github.com:Acme/Web.git` / `https://u:p@github.com/Acme/Web` → `github.com/acme/web`. */
+export const normalizeGitOrigin = (url) => url
+    .trim()
+    .replace(/^[a-z][a-z0-9+.-]*:\/\/[^@/]*@/i, '') // strip scheme + any inline credentials
+    .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '') // strip a bare scheme
+    .replace(/^[^@/]+@/, '') // strip `git@` from the scp-style form
+    .replace(/:/g, '/') // scp-style `host:path` → `host/path`
+    // Trailing slashes BEFORE the `.git` suffix: a url written `…/web.git/` would otherwise keep its
+    // `.git` and count as a different project from the same repo cloned without the slash.
+    .replace(/\/+$/, '')
+    .replace(/\.git$/i, '')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+/** Bucket a normalized origin by its host. Unknown hosts are `self_hosted` — never the host itself. */
+export function forgeOf(normalizedOrigin) {
+    const host = normalizedOrigin.split('/')[0] ?? '';
+    for (const [domain, forge] of PUBLIC_FORGES) {
+        // `ssh.dev.azure.com` and `www.github.com` are the same forge; match on suffix, not equality.
+        if (host === domain || host.endsWith(`.${domain}`))
+            return forge;
+    }
+    return RepoForge.SELF_HOSTED;
+}
+const defaultRead = (path) => readFileSync(path, 'utf8');
+const defaultExists = (path) => {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Walk up from `cwd` looking for a `.git`, and report what is there. Never throws: an unreadable or
+ * malformed config reports the state we could confirm rather than failing a startup path.
+ */
+export function gitFacts(cwd, read = defaultRead, exists = defaultExists) {
+    let dir = cwd;
+    for (let depth = 0; depth < MAX_PARENT_WALK; depth += 1) {
+        const gitDir = join(dir, '.git');
+        if (exists(gitDir)) {
+            let config = '';
+            try {
+                config = read(join(gitDir, 'config'));
+            }
+            catch {
+                // A `.git` with no readable config is still a repo — report it as one rather than as absent.
+                return { state: GitState.LOCAL_ONLY };
+            }
+            // The url line inside the [remote "origin"] section — the first url after that header wins.
+            const section = config.split(/\[remote\s+"origin"\]/)[1];
+            const url = section?.match(/^\s*url\s*=\s*(.+)$/m)?.[1];
+            if (url === undefined)
+                return { state: GitState.LOCAL_ONLY };
+            const origin = normalizeGitOrigin(url);
+            if (origin === '')
+                return { state: GitState.LOCAL_ONLY };
+            return { state: GitState.REMOTE, origin, forge: forgeOf(origin) };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // hit the filesystem root
+        dir = parent;
+    }
+    return { state: GitState.NONE };
+}

package/dist/telemetry/identify.d.ts

@@ -0,0 +1,22 @@
+import { UsageContextKind, type Identity } from '@reticlehq/core';
+/** Re-exported so the CLI has one import for the whole feature; the shape itself lives in core. */
+export { UsageContextKind };
+export type { Identity };
+export declare function readIdentity(file?: string): Identity | undefined;
+export declare function saveIdentity(identity: Identity, file?: string): void;
+export declare function clearIdentity(file?: string): void;
+/**
+ * What identifying yourself actually does, in plain words, shown BEFORE anything is sent.
+ *
+ * The second sentence is the one that matters and the one a consent notice usually omits: the
+ * identity is keyed to the same anonymous id the previous events carried, so opting in links the
+ * usage history that was already collected. That is exactly what makes it useful to us, which is
+ * exactly why the user has to be told before they choose, not after.
+ */
+export declare const IDENTIFY_NOTICE: string;
+/**
+ * Report an identity. Emitted as its own event so it is trivially separable from the anonymous
+ * stream — a distinct name is what lets the analytics side hold it under a different retention rule,
+ * or drop it entirely, without touching the adoption metrics.
+ */
+export declare function submitIdentity(identity: Identity): Promise<boolean>;

package/dist/telemetry/identify.js

@@ -0,0 +1,73 @@
+/**
+ * `reticle identify` — the ONLY way Reticle ever learns who you are, and it is a thing you type.
+ *
+ * The product question behind this is real: which of these anonymous ids are companies who would pay
+ * for support, an enterprise licence, or a design-partner slot? The tempting answer is to infer it —
+ * match a git remote against a company domain, sniff an email out of `git config`, resolve an npm org.
+ * Reticle does none of that, and the refusal is deliberate rather than squeamish:
+ *
+ *   - it would contradict a promise made in four places (README, usage, enterprise FAQ, telemetry
+ *     policy) that project names, git remotes and account identifiers are never sent;
+ *   - covert identification of a data subject is not "anonymous usage metrics", so it would also
+ *     break the legal basis the policy states — legitimate interest, minimized to the listed fields;
+ *   - and it is worse at the actual job. A scraped lead is a cold email from a tool the recipient
+ *     trusted, which is the fastest way to turn an advocate into someone who runs
+ *     `reticle telemetry disable` and tells their team to do the same. A self-identified one already
+ *     wants to talk to you.
+ *
+ * So this is opt-in, explicit, reversible, and it tells the user exactly what it links before it
+ * sends anything.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { TelemetryEventKind, UsageContextKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+const RETICLE_DIR = join(homedir(), '.reticle');
+/** Persisted so the identity survives shells and is attached to later sessions — and so it can be shown back. */
+const IDENTITY_FILE = join(RETICLE_DIR, 'identity.json');
+/** Re-exported so the CLI has one import for the whole feature; the shape itself lives in core. */
+export { UsageContextKind };
+export function readIdentity(file = IDENTITY_FILE) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveIdentity(identity, file = IDENTITY_FILE) {
+    mkdirSync(RETICLE_DIR, { recursive: true });
+    writeFileSync(file, JSON.stringify(identity, null, 2), 'utf8');
+}
+export function clearIdentity(file = IDENTITY_FILE) {
+    rmSync(file, { force: true });
+}
+/**
+ * What identifying yourself actually does, in plain words, shown BEFORE anything is sent.
+ *
+ * The second sentence is the one that matters and the one a consent notice usually omits: the
+ * identity is keyed to the same anonymous id the previous events carried, so opting in links the
+ * usage history that was already collected. That is exactly what makes it useful to us, which is
+ * exactly why the user has to be told before they choose, not after.
+ */
+export const IDENTIFY_NOTICE = [
+    'This sends the details you type here to the Reticle maintainers, so we can contact you and',
+    "understand how teams use Reticle. It is linked to this machine's anonymous id, which means it",
+    'also connects the anonymous usage already recorded from this machine to what you enter now.',
+    'Nothing about your app, your code, or your repository is included, and nothing else changes.',
+    'Undo it any time with `reticle identify --forget` (that stops future sends and deletes the local file;',
+    'email support@reticlehq.com to have what was already sent removed).',
+].join('\n');
+/**
+ * Report an identity. Emitted as its own event so it is trivially separable from the anonymous
+ * stream — a distinct name is what lets the analytics side hold it under a different retention rule,
+ * or drop it entirely, without touching the adoption metrics.
+ */
+export async function submitIdentity(identity) {
+    const telemetry = getTelemetry();
+    if (!telemetry.enabled)
+        return false;
+    await telemetry.emit(TelemetryEventKind.IDENTIFIED, { identity });
+    return true;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * How `reticle init` went.
+ *
+ * The onboarding funnel had no instrumentation at all, which meant the two most different failure
+ * modes were indistinguishable: someone whose setup died on a missing dependency looked exactly like
+ * someone who installed the package and never ran the command. One is a bug we can fix; the other is
+ * a marketing problem. Both showed up as silence.
+ *
+ * `reticle init` runs as a one-shot CLI command that exits immediately, so the send is DETACHED — the
+ * same treatment `cli_command_run` gets, for the same reason: an in-process fetch would keep the
+ * event loop alive and tax the command by most of a second.
+ */
+import { type InitOutcome } from '@reticlehq/core';
+/** Classified init failures — our own vocabulary, never a raw error or a path. */
+export declare const InitFailure: {
+    /** Run outside a project root. The single most common first-run mistake. */
+    readonly NO_PACKAGE_JSON: "no_package_json";
+    /** The package manager failed: offline, a locked registry, a broken install. */
+    readonly DEPENDENCY_INSTALL: "dependency_install";
+    /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */
+    readonly MCP_REGISTRATION: "mcp_registration";
+    readonly OTHER: "other";
+};
+export type InitFailure = (typeof InitFailure)[keyof typeof InitFailure];
+/** Report one init outcome. Best-effort; setup must never fail because a metric did. */
+export declare function reportInitOutcome(init: InitOutcome): void;

package/dist/telemetry/init-telemetry.js

@@ -0,0 +1,33 @@
+/**
+ * How `reticle init` went.
+ *
+ * The onboarding funnel had no instrumentation at all, which meant the two most different failure
+ * modes were indistinguishable: someone whose setup died on a missing dependency looked exactly like
+ * someone who installed the package and never ran the command. One is a bug we can fix; the other is
+ * a marketing problem. Both showed up as silence.
+ *
+ * `reticle init` runs as a one-shot CLI command that exits immediately, so the send is DETACHED — the
+ * same treatment `cli_command_run` gets, for the same reason: an in-process fetch would keep the
+ * event loop alive and tax the command by most of a second.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+/** Classified init failures — our own vocabulary, never a raw error or a path. */
+export const InitFailure = {
+    /** Run outside a project root. The single most common first-run mistake. */
+    NO_PACKAGE_JSON: 'no_package_json',
+    /** The package manager failed: offline, a locked registry, a broken install. */
+    DEPENDENCY_INSTALL: 'dependency_install',
+    /** The `claude mcp add` step failed — the CLI is missing or refused. Reticle installs but is unreachable. */
+    MCP_REGISTRATION: 'mcp_registration',
+    OTHER: 'other',
+};
+/** Report one init outcome. Best-effort; setup must never fail because a metric did. */
+export function reportInitOutcome(init) {
+    try {
+        void getTelemetry().emit(TelemetryEventKind.INIT_COMPLETED, { init, detach: true });
+    }
+    catch {
+        /* a metric must never break `reticle init` */
+    }
+}

package/dist/telemetry/machine-snapshot.d.ts

@@ -0,0 +1,6 @@
+import type { MachineSnapshot } from '@reticlehq/core';
+/**
+ * Sample the machine. Never throws — this is called from a crash handler, where the one unacceptable
+ * outcome is making the crash worse.
+ */
+export declare function machineSnapshot(): MachineSnapshot | undefined;

package/dist/telemetry/machine-snapshot.js

@@ -0,0 +1,39 @@
+/**
+ * What the machine looked like at a moment worth remembering.
+ *
+ * "Out of memory" and "our bug" produce identical-looking stack traces and are completely different
+ * problems — one is a docs/limits issue on the user's side, the other is ours to fix. Without this,
+ * every crash report arrived with that ambiguity baked in and no way to resolve it after the fact.
+ *
+ * Sampled at MOMENTS — a crash, the end of a session — never per tool call. `os.loadavg()` and
+ * `process.memoryUsage()` are cheap but not free, and taking them two hundred times a session to
+ * answer a question only ever asked about the bad moments would be a continuous cost for an
+ * occasional need.
+ *
+ * Nothing here describes the person: it is our own process's footprint plus coarse machine capacity.
+ * No hostname, no username, no disk paths, no process list.
+ */
+import { cpus, freemem, loadavg, totalmem } from 'node:os';
+const MB = 1024 * 1024;
+/**
+ * Sample the machine. Never throws — this is called from a crash handler, where the one unacceptable
+ * outcome is making the crash worse.
+ */
+export function machineSnapshot() {
+    try {
+        const memory = process.memoryUsage();
+        return {
+            rssMb: Math.round(memory.rss / MB),
+            heapUsedMb: Math.round(memory.heapUsed / MB),
+            freeMemMb: Math.round(freemem() / MB),
+            totalMemMb: Math.round(totalmem() / MB),
+            // ×100 so it stays an integer property rather than a float. Windows always reports 0 here,
+            // which is a platform fact rather than an idle machine — read it alongside `os`.
+            load1x100: Math.max(0, Math.round((loadavg()[0] ?? 0) * 100)),
+            cpuCount: cpus().length,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/telemetry/mcp-connection.d.ts

@@ -0,0 +1,5 @@
+export declare function markDaemonStart(now: number): void;
+/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+export declare function reportMcpConnected(client?: string, now?: () => number): void;
+/** Tests only. */
+export declare function resetMcpConnections(): void;

package/dist/telemetry/mcp-connection.js

@@ -0,0 +1,44 @@
+/**
+ * When an MCP client actually attaches.
+ *
+ * This is the signal that separates "Reticle is installed and the daemon is running" from "a person
+ * is using it". A daemon can sit up for days with no agent ever attaching — which looks like healthy
+ * adoption in `daemon_started` and is in fact an onboarding failure nobody would think to report.
+ *
+ * It also exposes reconnect CHURN. A client whose transport keeps dropping reattaches every few
+ * minutes, and in every other metric that is indistinguishable from enthusiastic use: more sessions,
+ * more connects, more activity. The `reconnect` flag is what tells those two stories apart.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+let connectsSeen = 0;
+/** Set when the daemon starts, so the FIRST connect can report how long Reticle sat unused. */
+let daemonStartedAt;
+export function markDaemonStart(now) {
+    daemonStartedAt = now;
+    connectsSeen = 0;
+}
+/** Report one client attaching. Best-effort; a metric must never affect whether a client connects. */
+export function reportMcpConnected(client, now = () => Date.now()) {
+    try {
+        const reconnect = connectsSeen > 0;
+        connectsSeen += 1;
+        void getTelemetry().emit(TelemetryEventKind.MCP_CLIENT_CONNECTED, {
+            connection: {
+                reconnect,
+                // A large value on the FIRST connect is the interesting case: Reticle was started and then
+                // sat there. On a reconnect it is just how long the daemon has been up.
+                daemonAgeMs: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
+                ...(client !== undefined ? { client } : {}),
+            },
+        });
+    }
+    catch {
+        /* never let a metric interfere with a client attaching */
+    }
+}
+/** Tests only. */
+export function resetMcpConnections() {
+    connectsSeen = 0;
+    daemonStartedAt = undefined;
+}