@reticlehq/server 3.6.0 → 3.7.0

package/dist/telemetry/project-profile.js

@@ -16,6 +16,7 @@ import { ProjectSize, ReticleDir } from '@reticlehq/core';
 import { gitFacts } from './git-facts.js';
 import { detectStack } from './feedback-context.js';
 import { readProjectId } from '../command/cli/ports/resolve/cli-port.js';
+import { DRIVE_RECORD_SUFFIX } from '../memory/project/dir/reticle-dir.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
@@ -134,9 +135,9 @@ const defaultReadDir = (dir) => {
 };
 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) {
+function countIn(reticleRoot, subdir, extension, except) {
     try {
-        const names = readdirSync(join(reticleRoot, subdir));
+        const names = readdirSync(join(reticleRoot, subdir)).filter((n) => except === undefined || !n.endsWith(except));
         return extension === undefined ? names.length : names.filter((n) => extension.test(n)).length;
     }
     catch {
@@ -158,7 +159,8 @@ export function profileProject(cwd, now, install) {
     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$/);
+    // A drive's own record sits beside its run and is not one.
+    const runCount = countIn(reticleRoot, ReticleDir.RUNS_SUBDIR, /\.json$/, DRIVE_RECORD_SUFFIX);
     const capsuleCount = countIn(reticleRoot, ReticleDir.CAPSULES_SUBDIR, /\.json$/);
     const hasContract = exists(join(reticleRoot, ReticleDir.CONTRACT_FILE));
     const hasHistory = exists(join(reticleRoot, ReticleDir.PROJECT_FILE));

package/dist/telemetry/proxy-telemetry.js

@@ -16,6 +16,9 @@ export async function flushProxySessionMetrics(telemetry = getTelemetry(), metri
     if (metrics.empty)
         return;
     await telemetry.emit(TelemetryEventKind.SESSION_PROGRESS, {
-        session: metrics.summarize(true),
+        // A window, not the final roll-up: this rides `session_progress`, which every query sums, and a
+        // final summary would also resolve calls and stamp an end reason for a process that is not the
+        // daemon whose session this is.
+        session: metrics.summarize(false),
     });
 }

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

@@ -15,8 +15,9 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, type AgentNudgeKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
 import type { HudUseData } from '@reticlehq/core';
+import { type HudSignals } from './hud-metrics.js';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -25,8 +26,12 @@ export declare class SessionMetrics {
     #private;
     /** Clock injected — this file must stay testable without a real one, per the repo's clock rule. */
     constructor(now: () => number);
-    /** A person used the HUD. Names only; the wire schema has already narrowed it. */
-    recordHudUse(use: HudUseData): void;
+    /** A person used the HUD on one tab. Names only; the wire schema has already narrowed it. */
+    recordHudUse(use: HudUseData, tab?: string): HudSignals;
+    /** A tab went into the background (true) or came back (false): its HUD time pauses meanwhile. */
+    setHudTabHidden(tab: string, hidden: boolean): void;
+    /** A tab went away: its HUD stops accruing time. */
+    closeHudTab(tab: string): void;
     /**
      * Record a call starting. Returns a function to call when it finishes — that closure is what makes
      * timing correct under CONCURRENCY: several agents can be inside `runTool` at once, so a single
@@ -114,6 +119,8 @@ export declare class SessionMetrics {
      * only lets a reader separate "how many distinct defects" from "how often they were hit", which
      * are different claims and were previously indistinguishable in the data.
      */
+    /** The 1-based occurrence of this finding in the session, or undefined past the cap. */
+    recordBugOccurrence(fingerprint: string): number | undefined;
     recordBug(kind: string): boolean;
     /**
      * One connection ATTEMPT. Call before the attempt; settle it with the outcome.
@@ -137,6 +144,10 @@ export declare class SessionMetrics {
     get currentRun(): number;
     /** Reticle invited the agent to send feedback. The denominator for feedback_submitted. */
     recordFeedbackPrompt(): void;
+    /** An agent was shown a platform or Harness advisory. */
+    recordNudge(kind: AgentNudgeKind): void;
+    /** A Harness drive was refused because the app's coverage is below the gate. */
+    recordHarnessRefused(percent: number): void;
     /** Which tool surface was advertised to agents this session. */
     recordSurface(surface: string): void;
     /**
@@ -166,6 +177,6 @@ export declare const recordSdkFailure: (failure: {
     message: string;
 }) => void;
 /** Narrow-and-record one HUD use. Keeps the session hot path to a single call. */
-export declare const recordHudUse: (use: HudUseData) => void;
+export declare const recordHudUse: (use: HudUseData, tab?: string) => HudSignals;
 /** Tests only — drop the singleton so each case starts from zero. */
 export declare const resetSessionMetrics: () => void;

package/dist/telemetry/session-metrics.js

@@ -15,7 +15,7 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, coverageBucketOf, } from '@reticlehq/core/telemetry';
 import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
@@ -34,6 +34,8 @@ const MAX_REPEAT_TOOLS = 64;
  * not tell which one, and the outcome is identical.
  */
 const NO_SESSION_ERROR = /no browser session connected|no connected session with id|multiple sessions connected/i;
+/** Distinct findings a session numbers occurrences for. A real session finds far fewer. */
+const MAX_BUG_FINGERPRINTS = 500;
 /** Cap distinct MCP clients recorded; more than a handful on one daemon is already the story. */
 const MAX_CLIENTS = 8;
 /** Bounds on the parameter map. Our own schemas are already finite; these are a belt-and-braces cap. */
@@ -64,19 +66,12 @@ export class SessionMetrics {
     #toolErrors = 0;
     #verifications = 0;
     /**
-     * Session-LIFETIME totals for the four numbers the funnel is computed from.
-     *
-     * `reset()` zeroes every window counter on each periodic flush, but `durationMs` is measured from
-     * `#startedAt` and is never reset. Without these, the FINAL summary — the one whose docstring
-     * promises "the whole session in a single event" — reports a long session containing zero tool
-     * calls, because it carries only the residue since the last flush, and anyone computing "did this
-     * session use Reticle" off the event named for the end of the session reads `no`.
-     *
-     * Window semantics are unchanged: `session_progress` still reports its own window, so nothing that
-     * already sums those events double-counts. Only `final: true` swaps in the lifetime numbers.
+     * Session-LIFETIME totals, never reset by a flush. The final summary carries them as
+     * `lifetime*` fields BESIDE its windowed counters, never in place of them: a final event whose
+     * `toolCalls` was the lifetime made every query summing a session's events count each flushed
+     * window twice.
      */
     #lifetimeToolCalls = 0;
-    #lifetimeToolErrors = 0;
     #lifetimeVerifications = 0;
     #lifetimeBugsFound = 0;
     #toolCounts = new Map();
@@ -95,11 +90,10 @@ export class SessionMetrics {
     #peakConcurrent = 0;
     #unknownToolCalls = 0;
     /**
-     * Names the agent guessed at, session-LIFETIME — a guess made early must still be reported at
-     * the end, so this is deliberately not cleared by a flush.
+     * Names the agent guessed at, this window. Reported in the window the guess was made; a lifetime
+     * map here restated every early guess on each later flush, which a sum over windows counts again.
      */
     #unknownTools = new Map();
-    #lifetimeUnknownToolCalls = 0;
     #bugsFound = 0;
     #browserMs = 0;
     #browserCommands = 0;
@@ -113,6 +107,11 @@ export class SessionMetrics {
      * capped: the kind vocabulary is a bounded enum plus oracle names, not user data.
      */
     #seenBugKinds = new Set();
+    /**
+     * Occurrences per finding fingerprint, session-lifetime like `#seenBugKinds`, so two hits of one
+     * defect are never byte-identical rows. Capped; past the cap a new fingerprint gets no index.
+     */
+    #bugOccurrences = new Map();
     /**
      * Tool errors meaning "the agent could not reach an app at all" — counted as a field of its own
      * because the alternative is unpacking `errors[]` in HogQL.
@@ -120,10 +119,8 @@ export class SessionMetrics {
     #noSessionErrors = 0;
     /** Connection-level MCP POST failures the SSE stream cannot see. See SessionSummary. */
     #postSocketFailures = 0;
-    #lifetimePostSocketFailures = 0;
     /** Retries of those POSTs that then delivered. */
     #postRetriesSaved = 0;
-    #lifetimePostRetriesSaved = 0;
     /** Longest back-to-back run per tool — a retry loop, which `toolCounts` cannot distinguish. */
     #repeatRuns = new Map();
     #lastTool;
@@ -143,7 +140,11 @@ export class SessionMetrics {
     #clientLeft = false;
     /** Feedback invitations shown, session-lifetime — the denominator for feedback_submitted. */
     #feedbackPrompted = 0;
-    /** Error buckets by whose defect. Session-lifetime: the mix is a fact about the session. */
+    /** Platform and Harness advisories shown to an agent this window, by kind. */
+    #nudges = new Map();
+    /** Harness drives refused for coverage this window, by coverage bucket. */
+    #harnessRefused = new Map();
+    /** Error buckets by whose defect, this window. */
     #errorClasses = new Map();
     /**
      * The recovery hinge. A call's outcome is only known once the NEXT one starts, so the verdict for
@@ -173,9 +174,20 @@ export class SessionMetrics {
         this.#startedAt = now();
         this.#hud = new HudMetrics(now);
     }
-    /** A person used the HUD. Names only; the wire schema has already narrowed it. */
-    recordHudUse(use) {
-        this.#hud.record(use);
+    /** A person used the HUD on one tab. Names only; the wire schema has already narrowed it. */
+    recordHudUse(use, tab) {
+        return this.#hud.record(use, tab);
+    }
+    /** A tab went into the background (true) or came back (false): its HUD time pauses meanwhile. */
+    setHudTabHidden(tab, hidden) {
+        if (hidden)
+            this.#hud.hide(tab);
+        else
+            this.#hud.show(tab);
+    }
+    /** A tab went away: its HUD stops accruing time. */
+    closeHudTab(tab) {
+        this.#hud.close(tab);
     }
     /**
      * Record a call starting. Returns a function to call when it finishes — that closure is what makes
@@ -224,7 +236,6 @@ export class SessionMetrics {
      */
     recordUnknownTool(name) {
         this.#unknownToolCalls += 1;
-        this.#lifetimeUnknownToolCalls += 1;
         if (name === undefined || 0 === name.length)
             return;
         const key = name.slice(0, 64);
@@ -285,7 +296,6 @@ export class SessionMetrics {
      */
     recordToolError(message, tool) {
         this.#toolErrors += 1;
-        this.#lifetimeToolErrors += 1;
         // Whose defect. Only the `schema` bucket is fixable by writing better descriptions, and it was
         // indistinguishable from the rest inside one `toolErrors` count.
         bump(this.#errorClasses, classifyError(message));
@@ -340,7 +350,6 @@ export class SessionMetrics {
      */
     recordPostSocketFailure() {
         this.#postSocketFailures += 1;
-        this.#lifetimePostSocketFailures += 1;
     }
     /**
      * A bounded retry of an unsent POST then delivered. The pair against `recordPostSocketFailure`:
@@ -348,7 +357,6 @@ export class SessionMetrics {
      */
     recordPostRetrySaved() {
         this.#postRetriesSaved += 1;
-        this.#lifetimePostRetriesSaved += 1;
     }
     /** The agent's recent approach run + the call in flight — context for a crash report. */
     get trail() {
@@ -406,6 +414,15 @@ export class SessionMetrics {
      * only lets a reader separate "how many distinct defects" from "how often they were hit", which
      * are different claims and were previously indistinguishable in the data.
      */
+    /** The 1-based occurrence of this finding in the session, or undefined past the cap. */
+    recordBugOccurrence(fingerprint) {
+        const seen = this.#bugOccurrences.get(fingerprint);
+        if (seen === undefined && this.#bugOccurrences.size >= MAX_BUG_FINGERPRINTS)
+            return undefined;
+        const occurrence = (seen ?? 0) + 1;
+        this.#bugOccurrences.set(fingerprint, occurrence);
+        return occurrence;
+    }
     recordBug(kind) {
         this.#bugsFound += 1;
         this.#lifetimeBugsFound += 1;
@@ -468,6 +485,14 @@ export class SessionMetrics {
     recordFeedbackPrompt() {
         this.#feedbackPrompted += 1;
     }
+    /** An agent was shown a platform or Harness advisory. */
+    recordNudge(kind) {
+        bump(this.#nudges, kind);
+    }
+    /** A Harness drive was refused because the app's coverage is below the gate. */
+    recordHarnessRefused(percent) {
+        bump(this.#harnessRefused, coverageBucketOf(percent));
+    }
     /** Which tool surface was advertised to agents this session. */
     recordSurface(surface) {
         this.#surface = surface.slice(0, 32);
@@ -482,28 +507,18 @@ export class SessionMetrics {
         if (final)
             this.#resolveRecovery();
         const machine = machineSnapshot();
-        // A FINAL summary reports the session; a periodic flush reports its window. `durationMs` was
-        // always session-lifetime, so a windowed count next to it described a 30-minute session that
-        // made no calls. The histograms below stay windowed by design — summing them across a session's
-        // events is correct, and duplicating every map to make them lifetime would double the memory
-        // this class exists to keep small.
-        const scalars = final
-            ? {
-                toolCalls: this.#lifetimeToolCalls,
-                toolErrors: this.#lifetimeToolErrors,
-                verifications: this.#lifetimeVerifications,
-                bugsFound: this.#lifetimeBugsFound,
-                postSocketFailures: this.#lifetimePostSocketFailures,
-                postRetriesSaved: this.#lifetimePostRetriesSaved,
-            }
-            : {
-                toolCalls: this.#toolCalls,
-                toolErrors: this.#toolErrors,
-                verifications: this.#verifications,
-                bugsFound: this.#bugsFound,
-                postSocketFailures: this.#postSocketFailures,
-                postRetriesSaved: this.#postRetriesSaved,
-            };
+        // EVERY event reports its own window, the final one included: summing a session's
+        // `session_progress` + `daemon_stopped` rows is then its total. The final event used to swap in
+        // the lifetime numbers, so every flushed window was counted twice by exactly that sum. The
+        // session totals ride beside them under their own names, on the final event only.
+        const scalars = {
+            toolCalls: this.#toolCalls,
+            toolErrors: this.#toolErrors,
+            verifications: this.#verifications,
+            bugsFound: this.#bugsFound,
+            postSocketFailures: this.#postSocketFailures,
+            postRetriesSaved: this.#postRetriesSaved,
+        };
         return {
             durationMs: Math.max(0, this.#now() - this.#startedAt),
             toolCalls: scalars.toolCalls,
@@ -534,7 +549,7 @@ export class SessionMetrics {
             browserMs: this.#browserMs,
             browserCommands: this.#browserCommands,
             peakConcurrentTools: this.#peakConcurrent,
-            unknownToolCalls: final ? this.#lifetimeUnknownToolCalls : this.#unknownToolCalls,
+            unknownToolCalls: this.#unknownToolCalls,
             ...(this.#unknownTools.size > 0
                 ? { unknownTools: Object.fromEntries(this.#unknownTools) }
                 : {}),
@@ -549,8 +564,19 @@ export class SessionMetrics {
             // verification number in this payload is windowed and a reader who summed the wrong one got a
             // different question's answer. `false` is sent, not omitted: a session that drove an app and
             // never asked whether it worked is the whole finding.
-            ...(final ? { endedWithVerdict: this.#lifetimeVerifications > 0 } : {}),
+            ...(final
+                ? {
+                    endedWithVerdict: this.#lifetimeVerifications > 0,
+                    lifetimeToolCalls: this.#lifetimeToolCalls,
+                    lifetimeVerifications: this.#lifetimeVerifications,
+                    lifetimeBugsFound: this.#lifetimeBugsFound,
+                }
+                : {}),
             ...(this.#feedbackPrompted > 0 ? { feedbackPrompted: this.#feedbackPrompted } : {}),
+            ...(this.#nudges.size > 0 ? { nudgesShown: Object.fromEntries(this.#nudges) } : {}),
+            ...(this.#harnessRefused.size > 0
+                ? { harnessRefusedCoverage: Object.fromEntries(this.#harnessRefused) }
+                : {}),
             ...(this.#errorClasses.size > 0
                 ? { errorClasses: Object.fromEntries(this.#errorClasses) }
                 : {}),
@@ -622,6 +648,8 @@ export class SessionMetrics {
             0 === this.#sdkFailures &&
             0 === this.#postSocketFailures &&
             0 === this.#postRetriesSaved &&
+            0 === this.#nudges.size &&
+            0 === this.#harnessRefused.size &&
             this.#hud.empty);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
@@ -651,6 +679,16 @@ export class SessionMetrics {
         this.#bugsFound = 0;
         this.#bugKinds.clear();
         this.#hud.reset();
+        this.#nudges.clear();
+        this.#harnessRefused.clear();
+        // These five were never cleared, so every flush restated them and a sum over a session's
+        // windows came out larger than its tool calls. Counts are windowed, all of them; only the
+        // facts below (an app ever connected, which clients, which bug kinds seen) outlive a window.
+        this.#errorClasses.clear();
+        this.#errorsRecovered = 0;
+        this.#errorsRepeated = 0;
+        this.#feedbackPrompted = 0;
+        this.#unknownTools.clear();
         // #seenBugKinds is deliberately NOT cleared. It is not a window counter — it is the
         // session-lifetime memory behind `repeat` on bug_found, and zeroing it made the same defect,
         // found again after a flush, report as a newly distinct one. Sessions run to 11.5 hours in the
@@ -676,9 +714,7 @@ export const recordSdkFailure = (failure) => {
     getSessionMetrics().recordSdkFailure(failure.site, failure.message);
 };
 /** Narrow-and-record one HUD use. Keeps the session hot path to a single call. */
-export const recordHudUse = (use) => {
-    getSessionMetrics().recordHudUse(use);
-};
+export const recordHudUse = (use, tab) => getSessionMetrics().recordHudUse(use, tab);
 /** Tests only — drop the singleton so each case starts from zero. */
 export const resetSessionMetrics = () => {
     current = undefined;

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,10 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
+/**
+ * Presence of this file marks the MACHINE as the Reticle team's own: every event carries
+ * `internal: true`. The persistent twin of `RETICLE_INTERNAL=1`, for a dev machine where setting a
+ * variable in every shell would be forgotten once and pollute the numbers for good.
+ */
+export declare const INTERNAL_MARKER_FILE = "telemetry-internal";
 /**
  * PostHog's group type for a licensed customer. Sent as `$groups` so PostHog can aggregate a whole
  * organisation natively: per-company retention, "which orgs went quiet", one row per customer rather
@@ -21,6 +27,7 @@ export declare const POSTHOG_GROUP_ORGANIZATION = "organization";
 export declare const resolveIdentity: (file?: string) => {
     anonymousId: string;
     firstRun: boolean;
+    ephemeral?: true;
 };
 /**
  * One-way project fingerprint: distinct-count of this = "projects Reticle is used in", reveals nothing.
@@ -94,6 +101,17 @@ export interface TelemetryExtra {
     instrumentation?: AppInstrumentation;
     /** `reticle_installed` / `init_completed`: which published route brought this install in. */
     installSource?: InstallSource;
+    /** `hud_viewed` / `hud_signin_prompted`: which HUD page or prompt. */
+    hud?: HudEvent;
+    /** `platform_linked`: how this project got linked. */
+    link?: PlatformLink;
+    /** `harness_run`: one phase of one Harness run. */
+    harness?: HarnessRun;
+    /**
+     * `platform_linked`: the workspace just linked. Overrides the envelope's own reading, which looks
+     * at the daemon's working directory and not at the project the HUD linked.
+     */
+    workspaceId?: string;
 }
 export interface Telemetry {
     /**
@@ -125,7 +143,13 @@ export declare const createTelemetry: (opts: {
     cwd?: string;
     now?: () => number;
     fetchImpl?: typeof fetch;
-    spawnImpl?: (command: string, args: string[]) => void;
+    /** The send a `detach: true` emit hands off; `input` is written to the child's stdin. */
+    spawnImpl?: (command: string, args: string[], input: string) => void;
+    /** The state home (`~/.reticle`). Injected so a test never touches the real one. */
+    reticleDir?: string;
+    /** Where `~/.reticle/session.json` is looked for. Injected by tests only. */
+    home?: string;
 }) => Telemetry;
+export declare const droppedInvalidEvents: () => number;
 export declare const getTelemetry: () => Telemetry;
 export { TelemetryEventKind };