@reticlehq/server 2.2.1 → 2.3.0

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;
+}

package/dist/telemetry/project-profile.d.ts

@@ -0,0 +1,44 @@
+import { ProjectSize, type ProjectProfile } from '@reticlehq/core';
+/**
+ * The feature FAMILIES, and the on-disk evidence that a project has adopted each. Named rather than
+ * counted so the vocabulary stays stable as tools are added, renamed, or merged into action-dispatched
+ * families — a count would silently change meaning the next time the tool surface is reorganized.
+ */
+export declare const FeatureFamily: {
+    readonly DETERMINISTIC_REPLAY: "deterministic_replay";
+    readonly VISUAL_BASELINE: "visual_baseline";
+    readonly TEXT_BASELINE: "text_baseline";
+    readonly CAPABILITY_CONTRACT: "capability_contract";
+    readonly RUN_ARTIFACTS: "run_artifacts";
+    readonly BUG_CAPSULES: "bug_capsules";
+    readonly CROSS_RUN_HISTORY: "cross_run_history";
+};
+export type FeatureFamily = (typeof FeatureFamily)[keyof typeof FeatureFamily];
+/** Count source files, stopping at the cap (the cap itself lands in the largest bucket, correctly). */
+export declare function countSourceFiles(root: string, readDir?: DirReader): number;
+export declare function sizeBucket(sourceFiles: number): ProjectSize;
+/**
+ * Project age in whole WEEKS, from the repo's first commit.
+ *
+ * Weeks rather than a date, deliberately: an exact creation timestamp combined with a framework and a
+ * size bucket starts to narrow toward a specific repository, and the question being asked — "is
+ * Reticle being adopted on greenfield spikes or on mature codebases?" — does not need that precision.
+ *
+ * Read from git's own reflog tail rather than by shelling out, for the same reason the origin lookup
+ * does: this runs on a startup path and must not cost a subprocess or require a `git` binary.
+ */
+export declare function projectAgeWeeks(root: string, now: number, read?: FileReader): number | undefined;
+/** True when package.json declares workspaces — monorepos exercise very different code paths. */
+export declare function isMonorepo(root: string, read?: FileReader): boolean;
+interface DirEntry {
+    name: string;
+    isDirectory: boolean;
+}
+type DirReader = (dir: string) => DirEntry[];
+type FileReader = (path: string) => string;
+/**
+ * Build the full profile. Best-effort throughout: an unreadable project yields a profile of zeroes
+ * rather than an exception, because a telemetry snapshot must never be able to fail a daemon start.
+ */
+export declare function profileProject(cwd: string, now: number): ProjectProfile;
+export {};

package/dist/telemetry/project-profile.js

@@ -0,0 +1,205 @@
+/**
+ * What kind of project is this, and how much of Reticle does it actually use?
+ *
+ * A DAU chart cannot tell apart someone running forty saved flows with visual baselines and a
+ * checked-in contract from someone who called `reticle_snapshot` twice and never came back. Both are
+ * one active user. Only one of them is retained, and only one of them is a company. `featureDepth`
+ * is the number that separates them, and it is the closest thing here to an activation metric.
+ *
+ * Everything is derived from files already on disk in the project, and everything is reduced before
+ * it leaves: sizes become buckets, ages become whole weeks, feature use becomes a fixed vocabulary of
+ * family names we define ourselves. No file names, no paths, no flow names, no dependency inventory.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { ProjectSize, ReticleDir } from '@reticlehq/core';
+import { gitFacts } from './git-facts.js';
+import { detectStack } from './feedback-context.js';
+/**
+ * The feature FAMILIES, and the on-disk evidence that a project has adopted each. Named rather than
+ * counted so the vocabulary stays stable as tools are added, renamed, or merged into action-dispatched
+ * families — a count would silently change meaning the next time the tool surface is reorganized.
+ */
+export const FeatureFamily = {
+    DETERMINISTIC_REPLAY: 'deterministic_replay',
+    VISUAL_BASELINE: 'visual_baseline',
+    TEXT_BASELINE: 'text_baseline',
+    CAPABILITY_CONTRACT: 'capability_contract',
+    RUN_ARTIFACTS: 'run_artifacts',
+    BUG_CAPSULES: 'bug_capsules',
+    CROSS_RUN_HISTORY: 'cross_run_history',
+};
+const ALL_FAMILIES = Object.values(FeatureFamily);
+/** Source-file thresholds for each bucket. A bucket answers "toy or real codebase"; a count fingerprints. */
+const SIZE_THRESHOLDS = [
+    [50, ProjectSize.TINY],
+    [250, ProjectSize.SMALL],
+    [1000, ProjectSize.MEDIUM],
+    [5000, ProjectSize.LARGE],
+];
+const SOURCE_EXTENSIONS = /\.(?:tsx?|jsx?|mjs|cjs|vue|svelte|astro)$/;
+/** Never walked: cost, and nothing in them describes the project the team actually wrote. */
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.turbo', 'coverage']);
+/** Bound the walk — a huge monorepo must not turn a telemetry snapshot into a filesystem crawl. */
+const MAX_FILES_SCANNED = 6000;
+const MAX_WALK_DEPTH = 8;
+const MS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
+/** Count source files, stopping at the cap (the cap itself lands in the largest bucket, correctly). */
+export function countSourceFiles(root, readDir = defaultReadDir) {
+    let count = 0;
+    const walk = (dir, depth) => {
+        if (depth > MAX_WALK_DEPTH || count >= MAX_FILES_SCANNED)
+            return;
+        for (const entry of readDir(dir)) {
+            if (count >= MAX_FILES_SCANNED)
+                return;
+            if (entry.isDirectory) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+                    walk(join(dir, entry.name), depth + 1);
+                }
+            }
+            else if (SOURCE_EXTENSIONS.test(entry.name)) {
+                count += 1;
+            }
+        }
+    };
+    walk(root, 0);
+    return count;
+}
+export function sizeBucket(sourceFiles) {
+    for (const [threshold, bucket] of SIZE_THRESHOLDS) {
+        if (sourceFiles < threshold)
+            return bucket;
+    }
+    return ProjectSize.HUGE;
+}
+/**
+ * Project age in whole WEEKS, from the repo's first commit.
+ *
+ * Weeks rather than a date, deliberately: an exact creation timestamp combined with a framework and a
+ * size bucket starts to narrow toward a specific repository, and the question being asked — "is
+ * Reticle being adopted on greenfield spikes or on mature codebases?" — does not need that precision.
+ *
+ * Read from git's own reflog tail rather than by shelling out, for the same reason the origin lookup
+ * does: this runs on a startup path and must not cost a subprocess or require a `git` binary.
+ */
+export function projectAgeWeeks(root, now, read = defaultRead) {
+    for (const path of [join(root, '.git', 'logs', 'HEAD')]) {
+        try {
+            const first = read(path).split('\n')[0];
+            // reflog line: `<old> <new> <name> <email> <unix-ts> <tz>\t<message>`
+            const seconds = first?.match(/\s(\d{9,11})\s[+-]\d{4}/)?.[1];
+            if (seconds === undefined)
+                continue;
+            const ageMs = now - parseInt(seconds, 10) * 1000;
+            if (ageMs < 0)
+                continue;
+            return Math.floor(ageMs / MS_PER_WEEK);
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/** True when package.json declares workspaces — monorepos exercise very different code paths. */
+export function isMonorepo(root, read = defaultRead) {
+    try {
+        const pkg = JSON.parse(read(join(root, 'package.json')));
+        if (pkg.workspaces !== undefined)
+            return true;
+    }
+    catch {
+        /* no package.json — fall through to the pnpm check */
+    }
+    try {
+        read(join(root, 'pnpm-workspace.yaml'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const defaultReadDir = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true }).map((e) => ({
+            name: e.name,
+            isDirectory: e.isDirectory(),
+        }));
+    }
+    catch {
+        return [];
+    }
+};
+const defaultRead = (path) => readFileSync(path, 'utf8');
+/** How many entries a `.reticle` subdirectory holds, matching an optional extension. 0 when absent. */
+function countIn(reticleRoot, subdir, extension) {
+    try {
+        const names = readdirSync(join(reticleRoot, subdir));
+        return extension === undefined ? names.length : names.filter((n) => extension.test(n)).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function exists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the full profile. Best-effort throughout: an unreadable project yields a profile of zeroes
+ * rather than an exception, because a telemetry snapshot must never be able to fail a daemon start.
+ */
+export function profileProject(cwd, now) {
+    const reticleRoot = join(cwd, ReticleDir.ROOT);
+    const flowCount = countIn(reticleRoot, ReticleDir.FLOWS_SUBDIR, /\.json$/);
+    const baselineCount = countIn(reticleRoot, ReticleDir.BASELINES_SUBDIR);
+    // `.diff.png` files are diff OUTPUT, not baselines — counting them would double every visual user.
+    const visualBaselineCount = countIn(reticleRoot, ReticleDir.VISUAL_SUBDIR, /(?<!\.diff)\.png$/);
+    const runCount = countIn(reticleRoot, ReticleDir.RUNS_SUBDIR, /\.json$/);
+    const capsuleCount = countIn(reticleRoot, ReticleDir.CAPSULES_SUBDIR, /\.json$/);
+    const hasContract = exists(join(reticleRoot, ReticleDir.CONTRACT_FILE));
+    const hasHistory = exists(join(reticleRoot, ReticleDir.PROJECT_FILE));
+    const featuresUsed = [];
+    if (flowCount > 0)
+        featuresUsed.push(FeatureFamily.DETERMINISTIC_REPLAY);
+    if (visualBaselineCount > 0)
+        featuresUsed.push(FeatureFamily.VISUAL_BASELINE);
+    if (baselineCount > 0)
+        featuresUsed.push(FeatureFamily.TEXT_BASELINE);
+    if (hasContract)
+        featuresUsed.push(FeatureFamily.CAPABILITY_CONTRACT);
+    if (runCount > 0)
+        featuresUsed.push(FeatureFamily.RUN_ARTIFACTS);
+    if (capsuleCount > 0)
+        featuresUsed.push(FeatureFamily.BUG_CAPSULES);
+    if (hasHistory)
+        featuresUsed.push(FeatureFamily.CROSS_RUN_HISTORY);
+    const { stack, stackMajor } = detectStack(cwd);
+    const ageWeeks = projectAgeWeeks(cwd, now);
+    const git = gitFacts(cwd);
+    return {
+        git: git.state,
+        ...(git.forge !== undefined ? { forge: git.forge } : {}),
+        ...(stack !== undefined ? { stack } : {}),
+        ...(stackMajor !== undefined ? { stackMajor } : {}),
+        size: sizeBucket(countSourceFiles(cwd)),
+        monorepo: isMonorepo(cwd),
+        ...(ageWeeks !== undefined ? { ageWeeks } : {}),
+        flowCount,
+        baselineCount,
+        visualBaselineCount,
+        runCount,
+        hasContract,
+        capsuleCount,
+        featuresUsed,
+        // Rounded to 2dp: the exact ratio is a function of the counts above, and an unrounded float would
+        // just be a higher-cardinality restatement of them.
+        featureDepth: Math.round((featuresUsed.length / ALL_FAMILIES.length) * 100) / 100,
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Telemetry for the verification RUNNER — the path `reticle verify` and the HTTP verify surface take.
+ *
+ * This path does not go through `runTool`, so for a while it produced nothing at all: no timing, no
+ * `verification_completed`, and — worst — no `bug_found`. Which meant every defect Reticle caught in
+ * CI was invisible to the one number we intend to publish, on precisely the surface most likely to
+ * run at scale and unattended. A metric that is blind to CI is not measuring the product.
+ *
+ * Reported from the assembled run rather than from inside the replay loop: the run artifact is the
+ * finished, already-classified verdict, so this cannot double-count and does not need to understand
+ * how a replay works.
+ */
+import { type ReticleVerificationRun } from '@reticlehq/core';
+/** The tool name reported for this path, so CI runs are distinguishable from agent-driven ones. */
+export declare const VERIFY_SURFACE = "reticle_verify";
+/**
+ * Report one completed verification run: the verdict, and one bug per failing flow.
+ *
+ * Best-effort and wrapped — a verification's exit code must never depend on whether a metric sent.
+ */
+export declare function reportRunTelemetry(run: ReticleVerificationRun): void;