@reticlehq/server 3.6.0 → 3.7.0

package/dist/telemetry/hud-metrics.d.ts

@@ -1,19 +1,23 @@
-import { HudPanel, HudView, type HudUseData } from '@reticlehq/core';
+import { HudPanel, HudView, type HudPromptSurface, type HudUseData } from '@reticlehq/core';
 /**
  * How people use the in-page HUD, rolled into the session summary.
  *
  * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
  * last one, so a dashboard sums across a session's events. Names only — every key is a control id
  * the wire schema already checked against core's closed list.
+ *
+ * Time is kept PER TAB and only while the tab is visible. Two tabs used to share one open view, so
+ * one tab's change closed the other's clock, and a hidden or closed tab kept accruing for as long as
+ * the daemon lived.
  */
 /** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
 export declare const HUD_JOURNEY_MAX = 60;
 export interface HudSummary {
     /** Presses per control; a toggle counts under `id:on` / `id:off` so a switch reads both ways. */
     hudControls?: Record<string, number>;
-    /** Milliseconds the HUD spent in each view during the window. */
+    /** Milliseconds the HUD spent in each view during the window, summed over visible tabs. */
     hudViewMs?: Partial<Record<HudView, number>>;
-    /** Milliseconds each panel was showing during the window. */
+    /** Milliseconds each panel was showing during the window, summed over visible tabs. */
     hudPanelMs?: Partial<Record<HudPanel, number>>;
     /** The window's presses and view changes, in order, cut at HUD_JOURNEY_MAX. */
     hudJourney?: string[];
@@ -22,13 +26,30 @@ export interface HudSummary {
     /** Times each rail slide became the visible one. Slide ids are Reticle's own, never page text. */
     hudSlides?: Record<string, number>;
 }
+/** The same page opened again on the same tab within this long is one view, not two. */
+export declare const HUD_VIEW_DEDUPE_MS = 30000;
+/** What one HUD use means for the per-event signals, beside what it adds to the summary. */
+export interface HudSignals {
+    /** A page this tab had not opened within the dedupe window. */
+    viewed?: HudPanel;
+    /** A sign-in prompt this tab had not shown before. */
+    prompted?: HudPromptSurface;
+    /** Tabs with a HUD right now. */
+    tabs: number;
+}
 export declare class HudMetrics {
     #private;
     constructor(now: () => number);
-    record(use: HudUseData): void;
+    record(use: HudUseData, tabId?: string): HudSignals;
+    /** The tab went into the background: its HUD stops accruing time until it is shown again. */
+    hide(tabId: string): void;
+    /** The tab is in front again: its HUD's view and panel accrue from now. */
+    show(tabId: string): void;
+    /** The tab went away: whatever it had open is counted up to now and stops. */
+    close(tabId: string): void;
     get empty(): boolean;
-    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    /** The window so far. Open views and panels are counted up to now, and keep running after. */
     summarize(): HudSummary;
-    /** Start the next window. The current view and panel carry over, timed from now. */
+    /** Start the next window. Each visible tab's view and panel carry over, timed from now. */
     reset(): void;
 }

package/dist/telemetry/hud-metrics.js

@@ -6,12 +6,20 @@ import { HudPanel, HudView } from '@reticlehq/core';
  * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
  * last one, so a dashboard sums across a session's events. Names only — every key is a control id
  * the wire schema already checked against core's closed list.
+ *
+ * Time is kept PER TAB and only while the tab is visible. Two tabs used to share one open view, so
+ * one tab's change closed the other's clock, and a hidden or closed tab kept accruing for as long as
+ * the daemon lived.
  */
 /** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
 export const HUD_JOURNEY_MAX = 60;
 /** Distinct slide ids counted per window; past this a broken notices file is not a dashboard. */
 const MAX_SLIDE_IDS = 20;
 const SLIDE_ID = /^[a-z0-9-]{1,56}$/;
+/** The same page opened again on the same tab within this long is one view, not two. */
+export const HUD_VIEW_DEDUPE_MS = 30_000;
+/** A tab whose page reported HUD use without saying which tab: an older caller, or a test. */
+const UNNAMED_TAB = '';
 export class HudMetrics {
     #now;
     #controls = new Map();
@@ -19,39 +27,103 @@ export class HudMetrics {
     #panelMs = new Map();
     #journey = [];
     #slides = new Map();
+    #tabs = new Map();
     #cut = false;
     /** Did anything happen this window. A HUD merely sitting open is not worth a flush of its own. */
     #changed = false;
-    #view;
-    #panel;
     constructor(now) {
         this.#now = now;
     }
-    record(use) {
+    record(use, tabId = UNNAMED_TAB) {
+        const tab = this.#tab(tabId);
+        const signals = { tabs: this.#tabs.size };
+        if (use.prompt !== undefined && !tab.prompted.has(use.prompt)) {
+            tab.prompted.add(use.prompt);
+            signals.prompted = use.prompt;
+        }
         // A control the HUD never rendered is dropped here, the one place HUD use is counted, so free
         // text cannot ride in on the id.
         const control = use.control !== undefined && isHudControl(use.control) ? use.control : undefined;
         if (use.slide !== undefined)
             this.#countSlide(use.slide);
         if (control === undefined && use.view === undefined && use.panel === undefined)
-            return;
+            return signals;
         this.#changed = true;
         if (control !== undefined) {
             const key = use.toggle === undefined ? control : `${control}:${use.toggle}`;
             this.#controls.set(key, (this.#controls.get(key) ?? 0) + 1);
             this.#step(key);
         }
-        if (use.view !== undefined && use.view !== this.#view?.value) {
-            this.#close(this.#view, this.#viewMs);
-            this.#view = { value: use.view, since: this.#now() };
+        const at = this.#now();
+        const since = tab.hidden ? undefined : at;
+        if (use.view !== undefined && use.view !== tab.view?.value) {
+            this.#close(tab.view, this.#viewMs);
+            tab.view = { value: use.view, since };
             this.#step(`view:${use.view}`);
         }
-        if (use.panel !== undefined && use.panel !== this.#panel?.value) {
-            this.#close(this.#panel, this.#panelMs);
-            this.#panel = { value: use.panel, since: this.#now() };
-            if (use.panel !== HudPanel.NONE)
+        if (use.panel !== undefined && use.panel !== tab.panel?.value) {
+            this.#close(tab.panel, this.#panelMs);
+            tab.panel = { value: use.panel, since };
+            if (use.panel !== HudPanel.NONE) {
                 this.#step(`panel:${use.panel}`);
+                const last = tab.viewedAt.get(use.panel);
+                if (last === undefined || at - last >= HUD_VIEW_DEDUPE_MS) {
+                    tab.viewedAt.set(use.panel, at);
+                    signals.viewed = use.panel;
+                }
+            }
         }
+        return signals;
+    }
+    /** The tab went into the background: its HUD stops accruing time until it is shown again. */
+    hide(tabId) {
+        const tab = this.#tabs.get(tabId);
+        if (tab === undefined || tab.hidden)
+            return;
+        tab.hidden = true;
+        this.#pause(tab);
+    }
+    /** The tab is in front again: its HUD's view and panel accrue from now. */
+    show(tabId) {
+        const tab = this.#tabs.get(tabId);
+        if (tab === undefined || !tab.hidden)
+            return;
+        tab.hidden = false;
+        const at = this.#now();
+        if (tab.view !== undefined)
+            tab.view = { ...tab.view, since: at };
+        if (tab.panel !== undefined)
+            tab.panel = { ...tab.panel, since: at };
+    }
+    /** The tab went away: whatever it had open is counted up to now and stops. */
+    close(tabId) {
+        const tab = this.#tabs.get(tabId);
+        if (tab === undefined)
+            return;
+        this.#pause(tab);
+        this.#tabs.delete(tabId);
+    }
+    #tab(tabId) {
+        const known = this.#tabs.get(tabId);
+        if (known !== undefined)
+            return known;
+        const tab = {
+            view: undefined,
+            panel: undefined,
+            hidden: false,
+            viewedAt: new Map(),
+            prompted: new Set(),
+        };
+        this.#tabs.set(tabId, tab);
+        return tab;
+    }
+    #pause(tab) {
+        this.#close(tab.view, this.#viewMs);
+        this.#close(tab.panel, this.#panelMs);
+        if (tab.view !== undefined)
+            tab.view = { ...tab.view, since: undefined };
+        if (tab.panel !== undefined)
+            tab.panel = { ...tab.panel, since: undefined };
     }
     #countSlide(slide) {
         // A slide id is Reticle's own (`notice-<id>` for the remote ones): lowercase words and dashes.
@@ -65,10 +137,14 @@ export class HudMetrics {
     get empty() {
         return !this.#changed;
     }
-    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    /** The window so far. Open views and panels are counted up to now, and keep running after. */
     summarize() {
-        const viewMs = this.#withOpen(this.#view, this.#viewMs);
-        const panelMs = this.#withOpen(this.#panel, this.#panelMs);
+        const viewMs = new Map(this.#viewMs);
+        const panelMs = new Map(this.#panelMs);
+        for (const tab of this.#tabs.values()) {
+            this.#close(tab.view, viewMs);
+            this.#close(tab.panel, panelMs);
+        }
         return {
             ...(this.#controls.size > 0 ? { hudControls: Object.fromEntries(this.#controls) } : {}),
             ...(viewMs.size > 0 ? { hudViewMs: Object.fromEntries(viewMs) } : {}),
@@ -78,7 +154,7 @@ export class HudMetrics {
             ...(this.#slides.size > 0 ? { hudSlides: Object.fromEntries(this.#slides) } : {}),
         };
     }
-    /** Start the next window. The current view and panel carry over, timed from now. */
+    /** Start the next window. Each visible tab's view and panel carry over, timed from now. */
     reset() {
         const at = this.#now();
         this.#controls.clear();
@@ -88,10 +164,12 @@ export class HudMetrics {
         this.#journey.length = 0;
         this.#cut = false;
         this.#changed = false;
-        if (this.#view !== undefined)
-            this.#view = { ...this.#view, since: at };
-        if (this.#panel !== undefined)
-            this.#panel = { ...this.#panel, since: at };
+        for (const tab of this.#tabs.values()) {
+            if (tab.view?.since !== undefined)
+                tab.view = { ...tab.view, since: at };
+            if (tab.panel?.since !== undefined)
+                tab.panel = { ...tab.panel, since: at };
+        }
     }
     #step(entry) {
         if (this.#journey.length < HUD_JOURNEY_MAX)
@@ -99,14 +177,10 @@ export class HudMetrics {
         else
             this.#cut = true;
     }
+    /** Add an open view's time since it last started accruing; nothing while it is paused. */
     #close(open, into) {
-        if (open === undefined)
+        if (open?.since === undefined)
             return;
         into.set(open.value, (into.get(open.value) ?? 0) + Math.max(0, this.#now() - open.since));
     }
-    #withOpen(open, closed) {
-        const out = new Map(closed);
-        this.#close(open, out);
-        return out;
-    }
 }

package/dist/telemetry/init-telemetry.js

@@ -12,7 +12,7 @@
  */
 import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
-import { resolveInstallSource } from './install-source.js';
+import { INSTALL_STATE_DIR, resolveInstallSource } from './install-source.js';
 // The failure vocabulary lives in `@reticlehq/init`, which is what classifies a failed run.
 // Re-exported so every consumer here is unchanged.
 export { InitFailure } from '@reticlehq/init';
@@ -25,7 +25,7 @@ export function reportInitOutcome(init) {
             // The other half of attribution: `reticle_installed` says a machine arrived, this says the
             // setup on it finished, and only together do they say which route converts. Same self-declared
             // marker, same refusal to infer — see install-source.ts.
-            installSource: resolveInstallSource(),
+            installSource: resolveInstallSource(process.env, INSTALL_STATE_DIR),
         });
     }
     catch {

package/dist/telemetry/install-source.d.ts

@@ -1,27 +1,3 @@
-/**
- * Which published route brought an install in.
- *
- * Four install routes ship at once and none of them could be told apart, so every question about
- * where distribution effort is working had no data behind it at all.
- *
- * ONE mechanism: an environment variable a channel sets on itself. Everything else that looked like
- * a signal turned out not to be one — see `InstallSource` in core for why `npm_config_user_agent`,
- * a `.claude-plugin/` directory and an installed skill folder all fail to separate these routes.
- *
- * WHICH CHANNELS ARE GENUINELY DETECTABLE TODAY, so nobody later reads a small `unknown` as success:
- *  - `plugin` — real. The Claude Code plugin registers the MCP server itself and can set the marker
- *    in that server's `env`, so it is carried by the process without anybody typing anything.
- *  - `skill_file` / `npx_skill` / `docs_site` / `readme` — real ONLY where that channel's own copy
- *    of the install command carries the marker. Each is a separately published artifact, so a copy
- *    that has not been updated is indistinguishable from no channel at all.
- *  - `cli_direct` — NOT detectable. Nobody types a marker to say they typed a command. It exists so
- *    a wrapper can declare it, and until something does, a direct install reports `unknown`.
- *
- * `unknown` is therefore expected to be the largest bucket for as long as the marker is spreading,
- * and shrinking it is a distribution job, never a classifier job. A guessed attribution is worse
- * than none: it is the number distribution decisions get steered on, and a guess and a measurement
- * are indistinguishable once they are in the same column.
- */
 import { InstallSource } from '@reticlehq/core/telemetry';
 /** The one marker. Set by a channel on the process that runs the install. */
 export declare const INSTALL_SOURCE_ENV = "RETICLE_INSTALL_SOURCE";
@@ -33,7 +9,19 @@ export declare const INSTALL_SOURCE_ENV = "RETICLE_INSTALL_SOURCE";
  * whole contract is built on. Trimmed and lowercased first, because the marker travels through
  * shell snippets and copy-paste, and `Skill_File` is the same channel as `skill_file`.
  */
-export declare function resolveInstallSource(env?: NodeJS.ProcessEnv): InstallSource;
+export declare function resolveInstallSource(env?: NodeJS.ProcessEnv, 
+/** Where the machine's remembered channel lives. Omitted, only the environment is read. */
+stateDir?: string): InstallSource;
+export declare const INSTALL_STATE_DIR: string;
+/**
+ * Remember a declared channel for the commands that follow, which declare nothing.
+ *
+ * The one-line installer declares itself on `reticle setup install`, and the next thing that runs
+ * is an agent spawning `reticle mcp` with no marker at all, so without this the declaration lived
+ * for one process. Write-once (exclusive create): the first channel is the one that brought this
+ * machine in, and a later command through a different route must not take that credit.
+ */
+export declare function rememberInstallSource(env?: NodeJS.ProcessEnv, stateDir?: string): void;
 /**
  * The install source declared by the environment, or undefined when nothing declared one.
  *

package/dist/telemetry/install-source.js

@@ -22,6 +22,9 @@
  * than none: it is the number distribution decisions get steered on, and a guess and a measurement
  * are indistinguishable once they are in the same column.
  */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { InstallSource } from '@reticlehq/core/telemetry';
 import { findProjectConfig } from '../command/cli/ports/resolve/cli-port.js';
 /** The one marker. Set by a channel on the process that runs the install. */
@@ -35,9 +38,47 @@ const KNOWN = new Set(Object.values(InstallSource));
  * whole contract is built on. Trimmed and lowercased first, because the marker travels through
  * shell snippets and copy-paste, and `Skill_File` is the same channel as `skill_file`.
  */
-export function resolveInstallSource(env = process.env) {
+export function resolveInstallSource(env = process.env, 
+/** Where the machine's remembered channel lives. Omitted, only the environment is read. */
+stateDir) {
     const declared = (env[INSTALL_SOURCE_ENV] ?? '').trim().toLowerCase();
-    return KNOWN.has(declared) ? declared : InstallSource.UNKNOWN;
+    if (KNOWN.has(declared))
+        return declared;
+    return ((stateDir === undefined ? undefined : machineInstallSource(stateDir)) ?? InstallSource.UNKNOWN);
+}
+/** `~/.reticle/install-source`: the channel that installed the CLI on this machine, written once. */
+const MACHINE_FILE = 'install-source';
+export const INSTALL_STATE_DIR = join(homedir(), '.reticle');
+function machineInstallSource(stateDir) {
+    try {
+        const recorded = readFileSync(join(stateDir, MACHINE_FILE), 'utf8').trim().toLowerCase();
+        return KNOWN.has(recorded) && InstallSource.UNKNOWN !== recorded
+            ? recorded
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Remember a declared channel for the commands that follow, which declare nothing.
+ *
+ * The one-line installer declares itself on `reticle setup install`, and the next thing that runs
+ * is an agent spawning `reticle mcp` with no marker at all, so without this the declaration lived
+ * for one process. Write-once (exclusive create): the first channel is the one that brought this
+ * machine in, and a later command through a different route must not take that credit.
+ */
+export function rememberInstallSource(env = process.env, stateDir = INSTALL_STATE_DIR) {
+    const declared = declaredInstallSource(env);
+    if (declared === undefined)
+        return;
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(join(stateDir, MACHINE_FILE), declared, { encoding: 'utf8', flag: 'wx' });
+    }
+    catch {
+        /* already remembered, or an unwritable home: attribution is never worth a failure */
+    }
 }
 /**
  * The install source declared by the environment, or undefined when nothing declared one.
@@ -70,7 +111,7 @@ export function projectInstallSource(cwd, env = process.env) {
         if (KNOWN.has(narrowed))
             return narrowed;
     }
-    return resolveInstallSource(env);
+    return resolveInstallSource(env, INSTALL_STATE_DIR);
 }
 /**
  * `configWithInstallSource` lives in `@reticlehq/init` — `init` is the only thing that writes

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

@@ -1,18 +1,4 @@
 export declare function markDaemonStart(now: number): void;
-/**
- * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
- * connects.
- *
- * The name is required in practice, and that is the fix rather than a restriction. `connection.client`
- * was defined and documented and never once populated: the only caller reported from
- * `transport.connect().then(...)`, which resolves when the SSE stream opens — before the client has
- * said who it is. `clientInfo` first exists at `oninitialized`, so the event carried every fact about
- * the connection except the one that makes "which agent client converts best" answerable at all.
- *
- * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
- * not a client attaching, and counting it was what put an unattributable row exactly where the name
- * belonged.
- */
 export declare function reportMcpConnected(client?: string, now?: () => number): void;
 /** Tests only. */
 export declare function resetMcpConnections(): void;

package/dist/telemetry/mcp-connection.js

@@ -33,6 +33,8 @@ export function markDaemonStart(now) {
  * not a client attaching, and counting it was what put an unattributable row exactly where the name
  * belonged.
  */
+/** `connection.client`'s wire cap. */
+const MAX_CLIENT_NAME = 64;
 export function reportMcpConnected(client, now = () => Date.now()) {
     if (client === undefined)
         return;
@@ -45,7 +47,9 @@ export function reportMcpConnected(client, now = () => Date.now()) {
                 // 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,
+                // Capped at the wire limit: the client names itself, and an over-long name would fail the
+                // schema and drop the whole event.
+                client: client.slice(0, MAX_CLIENT_NAME),
                 // WHAT THE AGENT HAD TO LOOK AT. Most clients that attach never call a tool, and that cohort
                 // emits nothing at all — an agent that reads the instructions, learns nothing is wired and
                 // stops has refused nothing, so `tool_refused` cannot see it either. Read off the same flag

package/dist/telemetry/onboarding-firsts.d.ts

@@ -1,3 +1,6 @@
+import { type OnboardingStep } from '@reticlehq/core';
+/** Report `step` once per process, and only if this machine + project has never reported it. */
+export declare function reportFirstStep(step: OnboardingStep): void;
 /** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export declare function noteOnboardingFirst(toolName: string): void;
 /**
@@ -36,5 +39,34 @@ export declare function noteFirstVerdict(): void;
  * chokepoint — a drive that is refused before its first action drove nothing and says nothing.
  */
 export declare function noteDriven(): void;
+/**
+ * The FIRST_RUN rung "a verdict was produced". Once per machine + project, with how long the call
+ * took: it fired on every verdict, so a busy session put hundreds of first-run steps in the funnel.
+ */
+export declare function noteVerdictProduced(elapsedMs: number): void;
 /** Arm again for the next daemon run — the tests' seam, mirroring resetAppInstrumented. */
 export declare function resetOnboardingFirsts(): void;
+/**
+ * Has this machine + project EVER crossed this onboarding step?
+ *
+ * The in-memory flags in `onboarding-firsts.ts` and `app-instrumented.ts` answer "this daemon
+ * process", and a daemon restarts many times a day, so every "first" step re-fired on every start.
+ * The answer is kept on disk instead, as one empty marker file per step under the state home:
+ * `~/.reticle/firsts/<projectId>/<step>`. The exclusive create (`wx`) IS the claim, so two daemons
+ * racing for the same first cannot both win, and nothing is ever rewritten in place.
+ *
+ * Only while telemetry is ENABLED: a disabled emitter has nothing to report and must leave nothing
+ * behind on disk.
+ */
+export declare const FirstEver: {
+    /** This call claimed it: the true first on this machine + project. */
+    readonly FIRST: "first";
+    /** Claimed before, by this process or an earlier one. Report nothing. */
+    readonly SEEN: "seen";
+    /** The state home cannot be written. Report per process, and never claim a first. */
+    readonly UNKNOWN: "unknown";
+};
+export type FirstEver = (typeof FirstEver)[keyof typeof FirstEver];
+/** Tests only: a state home and project of the test's own. `undefined` restores the default. */
+export declare function setFirstEverDir(dir: string | undefined, projectId?: string): void;
+export declare function claimFirstEver(step: string, projectId?: string): FirstEver;

package/dist/telemetry/onboarding-firsts.js

@@ -1,5 +1,9 @@
-import { ActionType, OnboardingPhase, OnboardingStepStatus, ReticleTool } from '@reticlehq/core';
+import { ActionType, OnboardingPhase, OnboardingStepStatus, ReticleTool, } from '@reticlehq/core';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { reportOnboardingStep } from './onboarding-funnel.js';
+import { getTelemetry, projectFingerprint } from './telemetry.js';
 /**
  * The onboarding steps only the DAEMON can answer, reported once each per run.
  *
@@ -13,13 +17,25 @@ import { reportOnboardingStep } from './onboarding-funnel.js';
  *
  * The flags are module state rather than per-session, because a person who tours in one tab and
  * drives in another has still only crossed each of these once.
+ *
+ * And once per MACHINE + PROJECT on top of that: the flags only know this process, and a daemon
+ * restarts many times a day, so each first re-fired on every start. `claimFirstEver` answers from
+ * disk; the true first carries `firstEver: true`, and a home that cannot be written falls back to
+ * once per process without the flag.
  */
-const seen = { look: false, act: false, verdict: false, driven: false };
+const seen = { look: false, act: false, verdict: false, driven: false, verdictProduced: false };
+/** Report `step` once per process, and only if this machine + project has never reported it. */
+export function reportFirstStep(step) {
+    const ever = claimFirstEver(step.step);
+    if (FirstEver.SEEN === ever)
+        return;
+    void reportOnboardingStep({ ...step, ...(FirstEver.FIRST === ever ? { firstEver: true } : {}) });
+}
 /** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
 export function noteOnboardingFirst(toolName) {
     if (!seen.look && LOOK_TOOLS.has(toolName)) {
         seen.look = true;
-        void reportOnboardingStep({
+        reportFirstStep({
             phase: OnboardingPhase.ONBOARD,
             step: 'first_look',
             status: OnboardingStepStatus.COMPLETED,
@@ -49,7 +65,7 @@ export function noteActed(args) {
     if (seen.act)
         return;
     seen.act = true;
-    void reportOnboardingStep({
+    reportFirstStep({
         phase: OnboardingPhase.ONBOARD,
         step: 'first_act',
         status: OnboardingStepStatus.COMPLETED,
@@ -65,7 +81,7 @@ export function noteFirstVerdict() {
     if (seen.verdict)
         return;
     seen.verdict = true;
-    void reportOnboardingStep({
+    reportFirstStep({
         phase: OnboardingPhase.ONBOARD,
         step: 'first_verdict',
         status: OnboardingStepStatus.COMPLETED,
@@ -87,12 +103,27 @@ export function noteDriven() {
     if (seen.driven)
         return;
     seen.driven = true;
-    void reportOnboardingStep({
+    reportFirstStep({
         phase: OnboardingPhase.FIRST_RUN,
         step: 'driven',
         status: OnboardingStepStatus.COMPLETED,
     });
 }
+/**
+ * The FIRST_RUN rung "a verdict was produced". Once per machine + project, with how long the call
+ * took: it fired on every verdict, so a busy session put hundreds of first-run steps in the funnel.
+ */
+export function noteVerdictProduced(elapsedMs) {
+    if (seen.verdictProduced)
+        return;
+    seen.verdictProduced = true;
+    reportFirstStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: 'verdict_produced',
+        status: OnboardingStepStatus.COMPLETED,
+        elapsedMs: Math.max(0, Math.round(elapsedMs)),
+    });
+}
 /** Looking: the tools that read the page without changing it. */
 const LOOK_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
@@ -106,4 +137,48 @@ export function resetOnboardingFirsts() {
     seen.act = false;
     seen.verdict = false;
     seen.driven = false;
+    seen.verdictProduced = false;
+}
+/**
+ * Has this machine + project EVER crossed this onboarding step?
+ *
+ * The in-memory flags in `onboarding-firsts.ts` and `app-instrumented.ts` answer "this daemon
+ * process", and a daemon restarts many times a day, so every "first" step re-fired on every start.
+ * The answer is kept on disk instead, as one empty marker file per step under the state home:
+ * `~/.reticle/firsts/<projectId>/<step>`. The exclusive create (`wx`) IS the claim, so two daemons
+ * racing for the same first cannot both win, and nothing is ever rewritten in place.
+ *
+ * Only while telemetry is ENABLED: a disabled emitter has nothing to report and must leave nothing
+ * behind on disk.
+ */
+export const FirstEver = {
+    /** This call claimed it: the true first on this machine + project. */
+    FIRST: 'first',
+    /** Claimed before, by this process or an earlier one. Report nothing. */
+    SEEN: 'seen',
+    /** The state home cannot be written. Report per process, and never claim a first. */
+    UNKNOWN: 'unknown',
+};
+const DEFAULT_DIR = join(homedir(), '.reticle', 'firsts');
+const EEXIST = 'EEXIST';
+let override;
+let cachedProjectId;
+/** Tests only: a state home and project of the test's own. `undefined` restores the default. */
+export function setFirstEverDir(dir, projectId = 'test-project') {
+    override = dir === undefined ? undefined : { dir, projectId };
+}
+const currentProjectId = () => (cachedProjectId ??= projectFingerprint(process.cwd()).projectId);
+export function claimFirstEver(step, projectId) {
+    if (override === undefined && !getTelemetry().enabled)
+        return FirstEver.UNKNOWN;
+    try {
+        const dir = join(override?.dir ?? DEFAULT_DIR, projectId ?? override?.projectId ?? currentProjectId());
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, step), '', { flag: 'wx' });
+        return FirstEver.FIRST;
+    }
+    catch (error) {
+        const code = 'object' === typeof error && null !== error ? error.code : undefined;
+        return EEXIST === code ? FirstEver.SEEN : FirstEver.UNKNOWN;
+    }
 }

package/dist/telemetry/platform-linked.d.ts

@@ -0,0 +1,5 @@
+import { type PlatformLinked } from '../command/cli/cloud-link.js';
+import { type Telemetry } from './telemetry.js';
+export declare function reportPlatformLinked(link: PlatformLinked, telemetry?: Pick<Telemetry, 'emit'>): void;
+/** Report every link this process makes. Installed once, by the entry point. */
+export declare function installPlatformLinkTelemetry(): void;

package/dist/telemetry/platform-linked.js

@@ -0,0 +1,32 @@
+/**
+ * `platform_linked`: a project on this machine was bound to a workspace.
+ *
+ * The join between OSS usage and the platform. The platform holds who is in each workspace; this
+ * event, and every event after it from a linked project, carries only the workspace's pseudonymous
+ * id. So a person is never named on this side, and the two sides still meet on `workspaceId`.
+ *
+ * Once per NEW binding: re-running `link` against the project a repo already reports to (rotating a
+ * key, an agent retrying) is not a link being created.
+ */
+import { PlatformLinkVia, TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { onPlatformLinked } from '../command/cli/cloud-link.js';
+import { getTelemetry } from './telemetry.js';
+export function reportPlatformLinked(link, telemetry = getTelemetry()) {
+    if (link.priorProjectId === link.projectId)
+        return;
+    try {
+        void telemetry.emit(TelemetryEventKind.PLATFORM_LINKED, {
+            link: { via: link.via },
+            ...(link.workspaceId === undefined ? {} : { workspaceId: link.workspaceId }),
+            // A CLI command exits straight after; the daemon (a HUD link) sends in-process.
+            detach: PlatformLinkVia.HUD !== link.via,
+        });
+    }
+    catch {
+        /* a metric never fails a link */
+    }
+}
+/** Report every link this process makes. Installed once, by the entry point. */
+export function installPlatformLinkTelemetry() {
+    onPlatformLinked((link) => reportPlatformLinked(link));
+}