@reticlehq/server 2.8.0 → 2.10.0

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

@@ -7,3 +7,21 @@ import { type BugFound } from '@reticlehq/core';
  */
 export type BugCandidate = Omit<BugFound, 'repeat'>;
 export declare function bugsInResult(toolName: string, result: Record<string, unknown>): BugCandidate[];
+/**
+ * Crawl anomaly kinds that are CONTRADICTIONS rather than single-channel faults.
+ *
+ * `reticle_crawl` returns both classes in one `anomalies` array — a console error is one channel
+ * complaining, while a UI that advanced over a failed write is two channels disagreeing. Only the
+ * second presents as success, and collapsing them would inflate the one claim that has to be exact.
+ *
+ * DERIVED from core's `ContradictionKind`, never hand-listed. The first version copied the twelve
+ * strings into a literal here, which matched on the day it was written and would have silently
+ * misclassified the thirteenth: a new contradiction kind would have been counted as an ordinary
+ * fault, quietly deflating the exact number we intend to publish. A copied enum is a drift hazard
+ * wherever it appears; it is a correctness hazard when the thing that drifts is a public claim.
+ */
+/**
+ * The route the app was on when this result was produced — extracted from the tool result so the
+ * fingerprint can identify the same defect across sessions without sending the route itself.
+ */
+export declare function routeOf(result: Record<string, unknown>): string | undefined;

package/dist/telemetry/bug-found.js

@@ -221,4 +221,18 @@ export function bugsInResult(toolName, result) {
  * fault, quietly deflating the exact number we intend to publish. A copied enum is a drift hazard
  * wherever it appears; it is a correctness hazard when the thing that drifts is a public claim.
  */
+/**
+ * The route the app was on when this result was produced — extracted from the tool result so the
+ * fingerprint can identify the same defect across sessions without sending the route itself.
+ */
+export function routeOf(result) {
+    const status = result['status'];
+    if ('object' === typeof status && status !== null) {
+        const r = status['route'];
+        if ('string' === typeof r && r.length > 0)
+            return r;
+    }
+    const r = result['route'];
+    return 'string' === typeof r && r.length > 0 ? r : undefined;
+}
 const CONTRADICTION_KINDS = new Set(Object.values(ContradictionKind));

package/dist/telemetry/daemon-telemetry.js

@@ -13,6 +13,8 @@ import { profileProject } from './project-profile.js';
 import { startUpdateCheck } from '../update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
 import { markInstrumentationClock } from './app-instrumented.js';
+import { markStallClock, reportInstrumentationStall, STALL_AFTER_MS, } from './instrumentation-stall.js';
+import { readProjectId } from '../cli/cli-port.js';
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
 /**
@@ -57,6 +59,8 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
     // Same clock, different half of the install: one measures how long before an AGENT attached, this
     // one how long before an APP did. The gap between them is the funnel.
     markInstrumentationClock(now());
+    // The other half of the same question: how long before an app arrives, and a report if none does.
+    markStallClock(now());
     // One profile per daemon start: what kind of project this is and how deeply Reticle is used in it.
     // Deferred off the boot path — it walks the source tree, and nothing about a daemon coming up
     // should wait on a filesystem scan.
@@ -71,6 +75,22 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
         }
     }, PROJECT_PROFILE_DELAY_MS).unref();
     const flushWindow = () => {
+        // BEFORE the idle return, and that ordering is the whole point: a stalled install produces an
+        // empty window by definition — no app, so no tool calls, so nothing to roll up. Checking it
+        // after the early return would make the one case this event exists for the one case it never
+        // sees. It is self-limiting (once per run, never after an app connects), so running it on every
+        // tick costs a comparison.
+        const stalled = reportInstrumentationStall({
+            // Same test `app_instrumented` uses for the same field, so the success and failure events
+            // stay directly comparable: a stamped projectId means `init` has run here.
+            initialized: readProjectId(cwd) !== undefined,
+            agentAttached: metrics.agentEverAttached,
+        }, now);
+        if (stalled) {
+            const minutes = Math.round(STALL_AFTER_MS / 60_000);
+            process.stderr.write(`[reticle] no app has connected after ${String(minutes)} minutes — ` +
+                'the install may be incomplete. Restart the dev server if you added the Reticle plugin.\n');
+        }
         if (metrics.empty)
             return; // an idle window is not worth an event
         // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
@@ -93,6 +113,15 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             stopped ??= (async () => {
                 clearInterval(flush);
                 clearTimeout(firstFlush);
+                // Last chance to say that no app ever arrived. The periodic path cannot report an
+                // UNATTENDED stall at all — that daemon idle-exits at five minutes and the periodic
+                // threshold is ten — so without this the event only ever describes daemons with an agent
+                // attached, which is not the population it was built to measure. Self-limiting: if the
+                // interval already reported, this returns false and emits nothing.
+                reportInstrumentationStall({
+                    initialized: readProjectId(cwd) !== undefined,
+                    agentAttached: metrics.agentEverAttached,
+                }, now, { atShutdown: true });
                 // The rich one: the whole session in a single event — duration, the tool histogram, error
                 // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
                 await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {

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

@@ -34,3 +34,23 @@ export declare const INSTALL_SOURCE_ENV = "RETICLE_INSTALL_SOURCE";
  * shell snippets and copy-paste, and `Skill_File` is the same channel as `skill_file`.
  */
 export declare function resolveInstallSource(env?: NodeJS.ProcessEnv): InstallSource;
+/**
+ * The install source declared by the environment, or undefined when nothing declared one.
+ *
+ * Distinct from `resolveInstallSource`, which answers `unknown` so an event always carries a value.
+ * A config file wants the opposite: writing `unknown` into `.reticle.json` is indistinguishable
+ * from a config written before this field existed, and those two are different facts.
+ */
+export declare function declaredInstallSource(env?: NodeJS.ProcessEnv): InstallSource | undefined;
+/**
+ * The install source for a project: what its config recorded, else what the environment declares.
+ *
+ * The config wins because it is the durable answer. The marker is an environment variable set by
+ * whichever channel ran the install, so it exists for exactly one command and is gone by the next
+ * one — which is why this field reached a handful of events and nothing else, and why the question
+ * it exists to answer could not be asked.
+ *
+ * Narrowed against the closed list on the way out, the same as the env path: a config file is user
+ * data, and a hand-edited one must not be able to put an arbitrary string on the wire.
+ */
+export declare function projectInstallSource(cwd: string, env?: NodeJS.ProcessEnv): InstallSource;

package/dist/telemetry/install-source.js

@@ -23,6 +23,7 @@
  * are indistinguishable once they are in the same column.
  */
 import { InstallSource } from '@reticlehq/core';
+import { findProjectConfig } from '../cli/cli-port.js';
 /** The one marker. Set by a channel on the process that runs the install. */
 export const INSTALL_SOURCE_ENV = 'RETICLE_INSTALL_SOURCE';
 const KNOWN = new Set(Object.values(InstallSource));
@@ -38,3 +39,36 @@ export function resolveInstallSource(env = process.env) {
     const declared = (env[INSTALL_SOURCE_ENV] ?? '').trim().toLowerCase();
     return KNOWN.has(declared) ? declared : InstallSource.UNKNOWN;
 }
+/**
+ * The install source declared by the environment, or undefined when nothing declared one.
+ *
+ * Distinct from `resolveInstallSource`, which answers `unknown` so an event always carries a value.
+ * A config file wants the opposite: writing `unknown` into `.reticle.json` is indistinguishable
+ * from a config written before this field existed, and those two are different facts.
+ */
+export function declaredInstallSource(env = process.env) {
+    const declared = (env[INSTALL_SOURCE_ENV] ?? '').trim().toLowerCase();
+    return KNOWN.has(declared) && InstallSource.UNKNOWN !== declared
+        ? declared
+        : undefined;
+}
+/**
+ * The install source for a project: what its config recorded, else what the environment declares.
+ *
+ * The config wins because it is the durable answer. The marker is an environment variable set by
+ * whichever channel ran the install, so it exists for exactly one command and is gone by the next
+ * one — which is why this field reached a handful of events and nothing else, and why the question
+ * it exists to answer could not be asked.
+ *
+ * Narrowed against the closed list on the way out, the same as the env path: a config file is user
+ * data, and a hand-edited one must not be able to put an arbitrary string on the wire.
+ */
+export function projectInstallSource(cwd, env = process.env) {
+    const recorded = findProjectConfig(cwd)?.['installSource'];
+    if ('string' === typeof recorded) {
+        const narrowed = recorded.trim().toLowerCase();
+        if (KNOWN.has(narrowed))
+            return narrowed;
+    }
+    return resolveInstallSource(env);
+}

package/dist/telemetry/instrumentation-stall.d.ts

@@ -0,0 +1,57 @@
+/**
+ * When a daemon has waited long enough that no app is coming.
+ *
+ * `app_instrumented` fires on success and only on success, so the population that matters most —
+ * daemons that never get an app wired at all — exists in the data only as an absence. An absence is
+ * the one thing telemetry cannot interpret: it cannot separate "nothing was ever wired" from "the
+ * process was killed before it could say so" from "we never sent the event". The funnel breaks at
+ * exactly this step and nowhere else, which makes it the one silence worth converting into a signal.
+ *
+ * Once per daemon run, and never after an app has connected. A daemon that takes a while and then
+ * works reports nothing at all: the question is "did this run ever get an app", and a run that did
+ * is not stalled no matter how long it took.
+ *
+ * The threshold is a judgement, not a measurement, and it is deliberately generous. Someone running
+ * `init` and then going to make coffee has not hit a defect, and calling that a stall would drown
+ * the real signal in ordinary human latency.
+ *
+ * Read the result against `agentAttached`, which is what makes it actionable: a stalled daemon with
+ * no agent is somebody who installed and walked away, and is not a defect. A stalled daemon WITH an
+ * agent attached is the failure the product actually has — the tools are loaded, something is asking
+ * for them, and there is nothing on the other end to drive.
+ */
+/**
+ * How long a daemon may sit with no app before it counts as stalled.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and well short of the half-hour idle windows that dominate the field, so a stall is reported while
+ * the session is still alive rather than inferred from its corpse.
+ */
+export declare const STALL_AFTER_MS: number;
+/** Start the clock. Called from the same place the instrumentation clock is marked. */
+export declare function markStallClock(now: number): void;
+export interface StallFacts {
+    /** Whether this project has a projectId stamped — i.e. `init` has run here. */
+    initialized: boolean;
+    /** Whether an MCP client is attached right now. */
+    agentAttached: boolean;
+}
+/**
+ * Report a stalled install, at most once per daemon run.
+ *
+ * Returns whether it emitted, so the caller's test can assert the once-only rule without reaching
+ * into the telemetry client. Best-effort like every other metric here: it must never be the reason
+ * a daemon misbehaves.
+ */
+export declare function reportInstrumentationStall(facts: StallFacts, now?: () => number, opts?: {
+    atShutdown?: boolean;
+}): boolean;
+/**
+ * How long this daemon has waited with no app, or undefined if the question is moot.
+ *
+ * Moot means: the clock was never started, or an app already connected. Callers use this to
+ * surface the stall to user-facing channels without coupling to the telemetry event itself.
+ */
+export declare function stallUptime(now: number): number | undefined;
+/** Tests only. */
+export declare function resetInstrumentationStall(): void;

package/dist/telemetry/instrumentation-stall.js

@@ -0,0 +1,103 @@
+/**
+ * When a daemon has waited long enough that no app is coming.
+ *
+ * `app_instrumented` fires on success and only on success, so the population that matters most —
+ * daemons that never get an app wired at all — exists in the data only as an absence. An absence is
+ * the one thing telemetry cannot interpret: it cannot separate "nothing was ever wired" from "the
+ * process was killed before it could say so" from "we never sent the event". The funnel breaks at
+ * exactly this step and nowhere else, which makes it the one silence worth converting into a signal.
+ *
+ * Once per daemon run, and never after an app has connected. A daemon that takes a while and then
+ * works reports nothing at all: the question is "did this run ever get an app", and a run that did
+ * is not stalled no matter how long it took.
+ *
+ * The threshold is a judgement, not a measurement, and it is deliberately generous. Someone running
+ * `init` and then going to make coffee has not hit a defect, and calling that a stall would drown
+ * the real signal in ordinary human latency.
+ *
+ * Read the result against `agentAttached`, which is what makes it actionable: a stalled daemon with
+ * no agent is somebody who installed and walked away, and is not a defect. A stalled daemon WITH an
+ * agent attached is the failure the product actually has — the tools are loaded, something is asking
+ * for them, and there is nothing on the other end to drive.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+import { appEverConnected } from './app-instrumented.js';
+/**
+ * How long a daemon may sit with no app before it counts as stalled.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and well short of the half-hour idle windows that dominate the field, so a stall is reported while
+ * the session is still alive rather than inferred from its corpse.
+ */
+export const STALL_AFTER_MS = 10 * 60 * 1000;
+let reported = false;
+let daemonStartedAt;
+/** Start the clock. Called from the same place the instrumentation clock is marked. */
+export function markStallClock(now) {
+    daemonStartedAt = now;
+    reported = false;
+}
+/**
+ * Report a stalled install, at most once per daemon run.
+ *
+ * Returns whether it emitted, so the caller's test can assert the once-only rule without reaching
+ * into the telemetry client. Best-effort like every other metric here: it must never be the reason
+ * a daemon misbehaves.
+ */
+export function reportInstrumentationStall(facts, now = () => Date.now(), opts = {}) {
+    if (reported)
+        return false;
+    // An app arrived. Whatever this run was, it was not stalled.
+    if (appEverConnected())
+        return false;
+    if (daemonStartedAt === undefined)
+        return false;
+    const waited = now() - daemonStartedAt;
+    // The threshold is a guard against crying stall seconds after boot. At SHUTDOWN there is nothing
+    // left to wait for: this daemon ran, no app ever connected, and it is now gone. That is a fact
+    // rather than an inference, and it does not become truer at ten minutes than at five.
+    //
+    // Skipping it here is what makes the event able to see anything at all. An UNATTENDED daemon
+    // idle-exits at DAEMON_IDLE_SHUTDOWN_MS (5 min), well short of STALL_AFTER_MS (10) — only an
+    // attached one gets the six-times grace that reaches the threshold. So on the periodic path alone
+    // `agentAttached` was forced to true on every row, and the bucket this event exists for —
+    // installed it, walked away, never wired the app — could not appear in the data at all.
+    //
+    // `msWaited` still carries the duration, so a consumer that wants to exclude short runs can do it
+    // on the data instead of being unable to see them.
+    if (true !== opts.atShutdown && waited < STALL_AFTER_MS)
+        return false;
+    reported = true;
+    try {
+        void getTelemetry().emit(TelemetryEventKind.INSTRUMENTATION_STALLED, {
+            stall: {
+                initialized: facts.initialized,
+                agentAttached: facts.agentAttached,
+                msWaited: Math.max(0, waited),
+            },
+        });
+    }
+    catch {
+        /* never let a metric interfere with a running daemon */
+    }
+    return true;
+}
+/**
+ * How long this daemon has waited with no app, or undefined if the question is moot.
+ *
+ * Moot means: the clock was never started, or an app already connected. Callers use this to
+ * surface the stall to user-facing channels without coupling to the telemetry event itself.
+ */
+export function stallUptime(now) {
+    if (daemonStartedAt === undefined)
+        return undefined;
+    if (appEverConnected())
+        return undefined;
+    return now - daemonStartedAt;
+}
+/** Tests only. */
+export function resetInstrumentationStall() {
+    reported = false;
+    daemonStartedAt = undefined;
+}

package/dist/telemetry/license-activation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Enterprise activation, as the three facts telemetry reports on every event.
+ *
+ * WHY IT IS ON EVERY EVENT, not just an activation one: the questions a licensed customer generates
+ * are "how much is this org using it", "what is breaking for them", "did their key lapse" — and every
+ * one of those is answered by an event that has nothing to do with licensing. A status that rode only
+ * its own event would tell us a key verified once and nothing about the sessions it covered. Same
+ * reasoning that moved `installSource` onto every event.
+ *
+ * WHY STATUS IS SEPARATE FROM IDENTITY: `licenseId` is only present while a key verifies, so on
+ * identity alone a lapsed customer and a departed one are the same silence. `licenseStatus` keeps
+ * reporting through `expired` and `invalid`, which is the difference between seeing a renewal coming
+ * and hearing about it from the customer.
+ *
+ * WHAT IS DELIBERATELY ABSENT: the organisation NAME, and the PLAN. The name is free text somebody
+ * typed at signing time, which rule 3 forbids outright. The plan is merely redundant, which is a
+ * quieter reason to leave something out and an easy one to lose sight of: it is keyed by this same
+ * `lid` in the issuance ledger, so sending it on every event from every machine forever pays a
+ * per-event cost to carry what one local file already holds, and the join that turns a `lid` into a
+ * company turns it into a plan at the same moment. `reticle license` still reports it locally, where
+ * it costs nothing and answers a question the operator is actually asking.
+ *
+ * More on the name: It is free text somebody typed at signing time,
+ * and rule 3 of the telemetry contract is names-never-values. `licenseId` is an opaque uuid that
+ * resolves to a company only against the issuance ledger held locally, so the analytics backend never
+ * holds a customer list.
+ */
+import { LicenseActivation } from '@reticlehq/core';
+/** The activation facts that ride the wire. All absent on a build with no issuer key baked. */
+export interface LicenseFacts {
+    licenseId?: string;
+    licenseStatus?: LicenseActivation;
+}
+/**
+ * Resolve activation for one event. The clock is passed in (rule 7) and is the EVENT's clock, not a
+ * value captured at startup: sessions here run to eleven hours, so a key that expires mid-session must
+ * start reporting `expired` from the event it expired on rather than the whole run inheriting the
+ * status it had at boot.
+ *
+ * `eval` reports NOTHING. It means no issuer key is baked at all, which is every OSS install and every
+ * source checkout, so emitting it would add three properties to the dominant population to say "not a
+ * licensed build" — which absence already says, more cheaply. A mis-built production release resolves
+ * to `invalid` rather than `eval` and IS reported, because that one we need to hear about.
+ *
+ * Never throws. A telemetry property may not change behaviour (rule 5), and this one sits in front of
+ * key parsing, which is the part most likely to be handed something malformed.
+ */
+export declare function licenseFacts(now: number, env?: NodeJS.ProcessEnv): LicenseFacts;

package/dist/telemetry/license-activation.js

@@ -0,0 +1,57 @@
+/**
+ * Enterprise activation, as the three facts telemetry reports on every event.
+ *
+ * WHY IT IS ON EVERY EVENT, not just an activation one: the questions a licensed customer generates
+ * are "how much is this org using it", "what is breaking for them", "did their key lapse" — and every
+ * one of those is answered by an event that has nothing to do with licensing. A status that rode only
+ * its own event would tell us a key verified once and nothing about the sessions it covered. Same
+ * reasoning that moved `installSource` onto every event.
+ *
+ * WHY STATUS IS SEPARATE FROM IDENTITY: `licenseId` is only present while a key verifies, so on
+ * identity alone a lapsed customer and a departed one are the same silence. `licenseStatus` keeps
+ * reporting through `expired` and `invalid`, which is the difference between seeing a renewal coming
+ * and hearing about it from the customer.
+ *
+ * WHAT IS DELIBERATELY ABSENT: the organisation NAME, and the PLAN. The name is free text somebody
+ * typed at signing time, which rule 3 forbids outright. The plan is merely redundant, which is a
+ * quieter reason to leave something out and an easy one to lose sight of: it is keyed by this same
+ * `lid` in the issuance ledger, so sending it on every event from every machine forever pays a
+ * per-event cost to carry what one local file already holds, and the join that turns a `lid` into a
+ * company turns it into a plan at the same moment. `reticle license` still reports it locally, where
+ * it costs nothing and answers a question the operator is actually asking.
+ *
+ * More on the name: It is free text somebody typed at signing time,
+ * and rule 3 of the telemetry contract is names-never-values. `licenseId` is an opaque uuid that
+ * resolves to a company only against the issuance ledger held locally, so the analytics backend never
+ * holds a customer list.
+ */
+import { LicenseActivation } from '@reticlehq/core';
+import { describeLicense } from '../license/license.js';
+/**
+ * Resolve activation for one event. The clock is passed in (rule 7) and is the EVENT's clock, not a
+ * value captured at startup: sessions here run to eleven hours, so a key that expires mid-session must
+ * start reporting `expired` from the event it expired on rather than the whole run inheriting the
+ * status it had at boot.
+ *
+ * `eval` reports NOTHING. It means no issuer key is baked at all, which is every OSS install and every
+ * source checkout, so emitting it would add three properties to the dominant population to say "not a
+ * licensed build" — which absence already says, more cheaply. A mis-built production release resolves
+ * to `invalid` rather than `eval` and IS reported, because that one we need to hear about.
+ *
+ * Never throws. A telemetry property may not change behaviour (rule 5), and this one sits in front of
+ * key parsing, which is the part most likely to be handed something malformed.
+ */
+export function licenseFacts(now, env = process.env) {
+    try {
+        const report = describeLicense(now, env);
+        if (LicenseActivation.EVAL === report.status)
+            return {};
+        return {
+            licenseStatus: report.status,
+            ...(report.licenseId !== undefined ? { licenseId: report.licenseId } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}

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

@@ -130,6 +130,14 @@ export declare class SessionMetrics {
      * false so a session killed before it can exit is not lost entirely (see the flush note in cli.ts).
      */
     summarize(final: boolean, exit?: SessionSummary['exit']): SessionSummary;
+    /**
+     * Has an agent ever attached to this daemon?
+     *
+     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * a daemon nobody is using, and a daemon with an agent sitting on it that has no app to drive.
+     * The second is the funnel's failure case and the first is not a problem at all.
+     */
+    get agentEverAttached(): boolean;
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty(): boolean;
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */

package/dist/telemetry/session-metrics.js

@@ -572,6 +572,16 @@ export class SessionMetrics {
             return 'verified';
         return 'explored';
     }
+    /**
+     * Has an agent ever attached to this daemon?
+     *
+     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * a daemon nobody is using, and a daemon with an agent sitting on it that has no app to drive.
+     * The second is the funnel's failure case and the first is not a problem at all.
+     */
+    get agentEverAttached() {
+        return this.#clients.size > 0;
+    }
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty() {
         return (0 === this.#toolCalls &&

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type InstallSource, type McpConnection, type McpOutage, type ToolRefusal, type AppInstrumentation, type InstrumentationStall, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
 /**
  * Feedback gets its own, much larger budget — and a retry.
  *
@@ -78,6 +78,8 @@ export interface TelemetryExtra {
     outage?: McpOutage;
     /** `app_instrumented`: an app carrying the SDK reached this daemon for the first time. */
     instrumentation?: AppInstrumentation;
+    /** `instrumentation_stalled`: the daemon waited and no app ever arrived. */
+    stall?: InstrumentationStall;
     /** `reticle_installed` / `init_completed`: which published route brought this install in. */
     installSource?: InstallSource;
 }

package/dist/telemetry/telemetry.js

@@ -70,6 +70,8 @@ const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'con
     '.catch(()=>{}).finally(()=>process.exit(0))';
 /** Env var names — mirror cloud-sync's `RETICLE_*` convention. */
 import { isReticleSourceCheckout } from './dev-repo.js';
+import { projectInstallSource } from './install-source.js';
+import { licenseFacts } from './license-activation.js';
 import { gitFacts } from './git-facts.js';
 import { currentAutomationHint } from './automation-hint.js';
 const Env = {
@@ -274,6 +276,12 @@ export const createTelemetry = (opts) => {
      */
     const sessionId = randomUUID();
     const { projectId, source: projectIdSource } = projectFingerprint(opts.cwd ?? process.cwd());
+    // Resolved ONCE, beside projectId, and for the same reason: it is a property of this install, not
+    // of any one event. It used to be passed per-call and therefore rode only `reticle_installed` and
+    // `init_completed` — two of the rarest events there are — so the channel that brought a user in
+    // was unknown for every event that could show whether they got anywhere. Reading it here puts it
+    // on all of them, which is the only shape in which the question can be asked.
+    const installSource = projectInstallSource(opts.cwd ?? process.cwd());
     showNoticeOnce();
     const spawnDetached = opts.spawnImpl ??
         ((command, args) => {
@@ -295,13 +303,16 @@ export const createTelemetry = (opts) => {
         // feedback, and no metric is worth phoning home from a contributor's clone.
         if (feedbackOnly && TelemetryEventKind.FEEDBACK_SUBMITTED !== kind)
             return false;
+        // One clock read for the whole event: `ts` and the licence check must agree, and two calls to
+        // now() can straddle an expiry.
+        const eventTs = now();
         const event = {
             v: TELEMETRY_EVENT_VERSION,
             anonymousId,
             sessionId,
             projectId,
             event: kind,
-            ts: now(),
+            ts: eventTs,
             version: opts.version,
             ci,
             // A SCALAR, so it needs the event build and the wire schema and no `blocks` entry — the same
@@ -326,17 +337,25 @@ export const createTelemetry = (opts) => {
             ...(extra?.refusal !== undefined ? { refusal: extra.refusal } : {}),
             ...(extra?.outage !== undefined ? { outage: extra.outage } : {}),
             ...(extra?.instrumentation !== undefined ? { instrumentation: extra.instrumentation } : {}),
+            ...(extra?.stall !== undefined ? { stall: extra.stall } : {}),
             // A SCALAR, so it needs the event build and the wire schema but no entry in `blocks` below —
             // there is nothing to flatten. It still needs both of those, which is the trap `outage` fell
             // into: a field declared on TelemetryExtra and missing from either one is dropped in silence.
-            ...(extra?.installSource !== undefined ? { installSource: extra.installSource } : {}),
+            // Always present now, rather than only when a caller remembered to pass it. A per-call
+            // override still wins so a command that genuinely knows better can say so.
+            installSource: extra?.installSource ?? installSource,
+            // Enterprise activation: three SCALARS, so they need the event build and the wire schema and no
+            // `blocks` entry. Resolved per event off the event's own clock rather than once at startup — an
+            // eleven-hour session must not report the status it booted with. All three are absent unless a
+            // release has an issuer key baked, so an OSS payload is byte-identical to before.
+            ...licenseFacts(eventTs),
         };
         // Map the core contract onto PostHog's capture shape: id/name/time move up, the rest are properties.
         // The feedback body is FLATTENED into `feedback_*` properties rather than sent as a nested object:
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, stall, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -367,6 +386,7 @@ export const createTelemetry = (opts) => {
             refusal,
             outage,
             instrumentation,
+            stall,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {