@reticlehq/server 2.9.0 → 2.11.0

package/dist/session/no-session-diagnosis.js

@@ -18,7 +18,9 @@
  * Pure: everything it needs is passed in, so the probe that discovers listening ports stays out of
  * the hot resolve() path and this stays unit-testable.
  */
+import { leaseCaveat } from './lease-availability.js';
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+import { STALL_AFTER_MS } from './stall-clock.js';
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
 /**
@@ -57,6 +59,17 @@ const RETRY = SELF_RECOVERING_MARKER;
 const URL_THEN_LEASE = 'Once you have that URL, open it with reticle_lease {action:"acquire", url} rather than a shell ' +
     'command — it needs no CLI on PATH (reach it with reticle_run {tool:"reticle_lease"} if it is ' +
     'not advertised directly).';
+/**
+ * The lease advice, with the reason it cannot be taken when that is the case.
+ *
+ * A function rather than a constant so the caveat cannot be forgotten at one of the six sites that
+ * offer the lease — which is exactly how the offer came to be made by the command that had already
+ * diagnosed the problem.
+ */
+function leaseAdvice(base, facts) {
+    const caveat = leaseCaveat(facts.leaseBrowser);
+    return caveat === undefined ? base : `${base} ${caveat}`;
+}
 const SELF_SERVE = 'You do not have to wait for the human: reticle_lease {action:"acquire", url} opens a browser ' +
     'Reticle drives itself, and returns a sessionId you can use immediately (reach it with ' +
     'reticle_run {tool:"reticle_lease"} if it is not advertised directly; release it when you finish).';
@@ -248,6 +261,26 @@ function searchedClause(facts) {
         return '';
     return ` I looked in: ${searched.join(', ')}. If your app is not in that list, that is the answer — this daemon is standing somewhere else.`;
 }
+/**
+ * A leading sentence when the daemon has been up long enough that no app is coming.
+ *
+ * Only fires for a WIRED project (initialized) that has NEVER connected and is past the
+ * threshold. An unwired project already names the install gap as its primary cause; adding a time
+ * sentence there would double-blame.
+ */
+function stallClause(facts) {
+    const { daemonUpMs, initialized, everConnected } = facts;
+    if (everConnected)
+        return '';
+    if (!initialized)
+        return '';
+    if (daemonUpMs === undefined || daemonUpMs < STALL_AFTER_MS)
+        return '';
+    const minutes = Math.round(daemonUpMs / 60_000);
+    return (`This daemon has been running for ${String(minutes)} minutes and no app has connected. ` +
+        'The most likely cause is that the dev server was not restarted after adding the Reticle ' +
+        'plugin, so the running bundle carries no SDK. Restart the dev server first. ');
+}
 export function diagnoseNoSession(facts) {
     const { everConnected, initialized, listening, port } = facts;
     // Named when known: a claim about a missing file is a claim about ONE directory.
@@ -271,7 +304,7 @@ export function diagnoseNoSession(facts) {
         }
         return ('no browser session connected, but one WAS connected to this daemon earlier, so the wiring ' +
             'is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen ' +
-            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${SELF_SERVE} ${RETRY}`);
+            `the app (or run ${OPEN_CMD_BARE}), or reload the tab. ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
     // Ranked ahead of every "we have never seen one" branch below, because it is the one fact that
     // OUTRANKS them: those branches all reason from an absence, and this reasons from a recorded
@@ -282,7 +315,7 @@ export function diagnoseNoSession(facts) {
             ? `${unattributedListeners(listening)} If the dev server is not running, start it first ` +
                 '(the command is in `next_action`).'
             : unattributedListeners(listening);
-        return `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`;
+        return `${RESTARTED_LEAD} ${OPEN_THE_APP} ${listeners} ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`;
     }
     // A config found elsewhere outranks every "you may have no SDK" branch below: those reason from
     // an absence in ONE directory, and this is a file we read in another. Ranked here so the reader is
@@ -290,7 +323,7 @@ export function diagnoseNoSession(facts) {
     if (!initialized && (facts.configsElsewhere ?? []).length > 0) {
         return ('no browser session connected, and this daemon has never seen one. ' +
             `${configsElsewhereClause(facts)} ${unattributedListeners(listening)} ${OPEN_THE_APP} ` +
-            `${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`);
+            `${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
     }
     if (0 === listening.length) {
         // Lead with the stronger EVIDENCE, and do not overstate what it is.
@@ -320,9 +353,9 @@ export function diagnoseNoSession(facts) {
                 `file ${INIT_CMD} writes, so the app may carry no Reticle SDK — but check the app's ` +
                 'OWN directory before re-running `init`: in a monorepo the daemon often runs at the root ' +
                 'while the app lives in a subdirectory, and an app wired by the Vite or Babel plugin ' +
-                `carries the SDK without that file at all.${searchedClause(facts)} ${URL_THEN_LEASE} ${RETRY}`);
+                `carries the SDK without that file at all.${searchedClause(facts)} ${leaseAdvice(URL_THEN_LEASE, facts)} ${RETRY}`);
         }
-        return (`no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
+        return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one. ${OPEN_THE_APP} ` +
             'Nothing is listening on the ports Reticle scans ' +
             `(${SCANNED_PORTS}) either, and the most common reason for that is a dev server that is not ` +
             'running: start it yourself in the background with the command in `next_action` — it is read ' +
@@ -338,7 +371,7 @@ export function diagnoseNoSession(facts) {
             // Deliberately NOT offering reticle_lease here, and a test pins that: a lease opens a URL, and
             // if nothing is listening there is nothing at any URL to open. Asking for the real one is the
             // only move that can recover the :7699 case.
-            `the app IS running, ask the human for its URL rather than assuming it is down. ${URL_THEN_LEASE} ` +
+            `the app IS running, ask the human for its URL rather than assuming it is down. ${leaseAdvice(URL_THEN_LEASE, facts)} ` +
             // Reachable only for a project that HAS been through `init` — the uninstrumented case is
             // answered above, leading with that certainty instead of behind this scan's guess.
             `${RETRY}`);
@@ -353,8 +386,8 @@ export function diagnoseNoSession(facts) {
             `has one, the app is wired and simply has no page open — ${OPEN_CMD}. ` +
             `${unattributedListeners(listening)}${searchedClause(facts)} ${RETRY}`);
     }
-    return ('no browser session connected, and this daemon has never seen one for this project, which is ' +
+    return (`${stallClause(facts)}no browser session connected, and this daemon has never seen one for this project, which is ` +
         `wired for Reticle. ${OPEN_THE_APP} ${unattributedListeners(listening)} ` +
         'If the page IS open and still does not appear, the app is wired and the SDK is not reaching ' +
-        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${SELF_SERVE} ${RETRY}`);
+        `this daemon (on ${String(port)}). ${rankedCauses(facts)} ${leaseAdvice(SELF_SERVE, facts)} ${RETRY}`);
 }

package/dist/session/no-session-watch.js

@@ -17,6 +17,7 @@ import { readProjectFramework, readProjectId, readProjectPort } from '../cli/cli
 import { discoverProjectConfigs } from '../cli/config-discovery.js';
 import { hasProjectConnectedBefore, rememberConnected } from './connection-memory.js';
 import { reticleStateHome } from '../daemon/daemon.js';
+import { stallUptime } from './stall-clock.js';
 /** Slow enough to be free, fast enough that a dev server started 15s ago is already reflected. */
 const REFRESH_MS = 15_000;
 /** The URL an auto-attach opens. `localhost` for the same reason the probe uses it: both stacks. */
@@ -193,6 +194,12 @@ export function startNoSessionWatch(options) {
             return framework === undefined ? {} : { framework };
         })(),
         leaseExpired: (options.reapedLeases?.() ?? 0) > 0,
+        // How long this daemon has been waiting with no app. The diagnosis uses it to surface
+        // "install never finished" — the same condition telemetry already knows about.
+        ...(() => {
+            const upMs = stallUptime(Date.now());
+            return upMs === undefined ? {} : { daemonUpMs: upMs };
+        })(),
         // Read here rather than at boot: `.reticle.json` can be written by `init` after this daemon
         // started, which is the ordinary first-install order, and a port cached from before it existed
         // would make the daemon confidently report no mismatch on the one run where there is one.

package/dist/session/session-readiness.js

@@ -11,7 +11,7 @@ const DEFAULT_POLL_MS = 25;
  */
 export const RETICLE_LOOP_GUIDE = 'Reticle loop — LOOK: reticle_snapshot / reticle_query / reticle_inspect · ACT: reticle_act (or reticle_act_and_wait) · ' +
     'OBSERVE: reticle_observe / reticle_wait_for / reticle_network / reticle_console · ASSERT: reticle_assert over program ' +
-    'truth, not just the DOM · REGRESS: reticle_record{action:"start"} → reticle_replay, or reticle_flow_verify for the whole ' +
+    'truth, not just the DOM · REGRESS: reticle_record{action:"start"} → reticle_replay, or reticle_verify{action:"flows"} for the whole ' +
     'suite. The human can flag bugs from the panel — drain them with reticle_session{action:"review"} and resolve each once fixed. ' +
     'MANDATORY: the moment you stop driving — finishing your reply or waiting on the human — call reticle_session {action:"yield"} ' +
     '(mode:"waiting", or mode:"ask" with the question) so the panel shows your real state; reticle_session{action:"end"} ' +

package/dist/session/session.d.ts

@@ -1,6 +1,7 @@
 import type { WebSocket } from 'ws';
 import type { ImpactSnapshot } from '@reticlehq/core';
 import { LastAct } from './last-act.js';
+import { GapLedger } from '../honesty/gap-ledger.js';
 import { type PageRuntime } from './command-timeout.js';
 import { type SessionHealth } from './session-health.js';
 export type { SessionHealth };
@@ -111,6 +112,14 @@ export declare class Session {
      * from it, and the split between those two tool calls is the whole reason it exists.
      */
     readonly lastAct: LastAct;
+    /**
+     * What this app still cannot tell Reticle, as of the most recent verdict.
+     *
+     * Lives on the session because that is the scope the question belongs to: "am I done with this
+     * app" is a session question, and a gap closed halfway through must not follow the agent to the
+     * end of it.
+     */
+    readonly gaps: GapLedger;
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).
      * If the reaper had auto-ended the session, a fresh command means the agent is alive again, so the

package/dist/session/session.js

@@ -1,5 +1,6 @@
 import { recordImpact } from '../impact/impact-recorder.js';
 import { LastAct } from './last-act.js';
+import { GapLedger } from '../honesty/gap-ledger.js';
 import { commandTimeoutMessage } from './command-timeout.js';
 import { readHealthEvent } from './session-health.js';
 /** The HUD does not need 200 frames to watch a counter climb; the last state always lands. */
@@ -370,6 +371,14 @@ export class Session {
      * from it, and the split between those two tool calls is the whole reason it exists.
      */
     lastAct = new LastAct();
+    /**
+     * What this app still cannot tell Reticle, as of the most recent verdict.
+     *
+     * Lives on the session because that is the scope the question belongs to: "am I done with this
+     * app" is a session question, and a gap closed halfway through must not follow the agent to the
+     * end of it.
+     */
+    gaps = new GapLedger();
     // ── Server-authoritative liveness (immune to browser-tab throttling) ──────────────
     /**
      * Stamp the wall-clock of the latest AGENT command (called whenever a tool resolves this session).

package/dist/session/stall-clock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * When a run with nothing connected is worth mentioning to a human.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and short enough that the warning still arrives while somebody is at the keyboard.
+ */
+export declare const STALL_AFTER_MS: number;
+/** Start the clock, from the same place the instrumentation clock is marked. */
+export declare function markStallClock(now: number): void;
+/**
+ * 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. A run that starts slowly and
+ * then works has nothing to report, which is why this returns undefined rather than a duration.
+ */
+export declare function stallUptime(now: number): number | undefined;
+/** Tests only. */
+export declare function resetStallClock(): void;

package/dist/session/stall-clock.js

@@ -0,0 +1,48 @@
+/**
+ * How long this daemon has waited with no app connected.
+ *
+ * This is what survived `instrumentation_stalled`. The EVENT was removed: it claimed to separate
+ * "never wired" from "died before reporting" and did not, because it only fired on a flush tick or a
+ * graceful shutdown, so a killed daemon was invisible to it exactly as before. Everything it carried
+ * is derivable from `daemon_started` minus `app_instrumented`, joined on `sessionId` — and that set
+ * difference is strictly MORE complete, because it does catch the killed daemons. A second way to
+ * compute the same number that disagrees with the first is worse than not having it.
+ *
+ * The CLOCK is a different thing and stays. Two live features read it, neither of them a metric: the
+ * no-session diagnosis tells an agent how long this daemon has been waiting, and the daemon warns on
+ * stderr when a run passes the threshold with nothing connected. Both are help for somebody stuck
+ * mid-install, which is the moment they are least able to work it out themselves.
+ *
+ * It lives under `session/` rather than `telemetry/` now, beside the two files that read it. The old
+ * home is why the removal looked like it would take the diagnosis with it.
+ */
+import { appEverConnected } from '../telemetry/app-instrumented.js';
+/**
+ * When a run with nothing connected is worth mentioning to a human.
+ *
+ * Ten minutes sits well past setup latency — reading a doc, restarting a dev server, opening a tab —
+ * and short enough that the warning still arrives while somebody is at the keyboard.
+ */
+export const STALL_AFTER_MS = 10 * 60 * 1000;
+let daemonStartedAt;
+/** Start the clock, from the same place the instrumentation clock is marked. */
+export function markStallClock(now) {
+    daemonStartedAt = now;
+}
+/**
+ * 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. A run that starts slowly and
+ * then works has nothing to report, which is why this returns undefined rather than a duration.
+ */
+export function stallUptime(now) {
+    if (daemonStartedAt === undefined)
+        return undefined;
+    if (appEverConnected())
+        return undefined;
+    return now - daemonStartedAt;
+}
+/** Tests only. */
+export function resetStallClock() {
+    daemonStartedAt = undefined;
+}

package/dist/telemetry/daemon-telemetry.js

@@ -13,8 +13,7 @@ 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 } from './instrumentation-stall.js';
-import { readProjectId } from '../cli/cli-port.js';
+import { markStallClock, STALL_AFTER_MS, stallUptime } from '../session/stall-clock.js';
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
 /**
@@ -74,18 +73,22 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             /* a profile is a nice-to-have; it must never touch the daemon */
         }
     }, PROJECT_PROFILE_DELAY_MS).unref();
+    // Once per daemon run: a warning repeated every ten minutes at somebody already stuck is noise.
+    let stallWarned = false;
     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.
-        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);
+        // BEFORE the idle return, and that ordering still matters for the reason the removed event
+        // documented: a stalled install produces an empty window by definition — no app, so no tool
+        // calls, so nothing to roll up — so checking after the early return would never fire on the one
+        // case worth warning about. What is left here is the WARNING, for a human watching the log; the
+        // metric that used to ride alongside it was removed as a second, less complete way to compute
+        // `daemon_started` minus `app_instrumented`.
+        const waited = stallUptime(now());
+        if (!stallWarned && waited !== undefined && waited >= STALL_AFTER_MS) {
+            stallWarned = true;
+            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.
@@ -108,15 +111,6 @@ 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/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

@@ -133,7 +133,7 @@ export declare class SessionMetrics {
     /**
      * Has an agent ever attached to this daemon?
      *
-     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * Read by the stall clock, 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.
      */

package/dist/telemetry/session-metrics.js

@@ -575,7 +575,7 @@ export class SessionMetrics {
     /**
      * Has an agent ever attached to this daemon?
      *
-     * Read by the instrumentation-stall check, which needs to tell two very different silences apart:
+     * Read by the stall clock, 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.
      */

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,15 @@
-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';
+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';
+/**
+ * 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
+ * than one per machine.
+ *
+ * The KEY is the licence id and nothing else. The organisation's NAME is never sent from a customer's
+ * machine, here or anywhere; the name reaches PostHog only if we push it ourselves from the issuance
+ * ledger, which is the one place that mapping lives. So an event still carries no identity, and the
+ * analytics side learns a customer list only when we deliberately upload one.
+ */
+export declare const POSTHOG_GROUP_ORGANIZATION = "organization";
 /**
  * Feedback gets its own, much larger budget — and a retry.
  *
@@ -78,8 +89,6 @@ 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

@@ -42,6 +42,17 @@ const POSTHOG_KEY = 'phc_q4yCxKMXHfWQ43VAz4HxJXZFLqFi4nBbg5v3avemggYo';
  * still key on distinct_id.
  */
 const POSTHOG_PERSONLESS = { $process_person_profile: false };
+/**
+ * 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
+ * than one per machine.
+ *
+ * The KEY is the licence id and nothing else. The organisation's NAME is never sent from a customer's
+ * machine, here or anywhere; the name reaches PostHog only if we push it ourselves from the issuance
+ * ledger, which is the one place that mapping lives. So an event still carries no identity, and the
+ * analytics side learns a customer list only when we deliberately upload one.
+ */
+export const POSTHOG_GROUP_ORGANIZATION = 'organization';
 const SEND_TIMEOUT_MS = 2000;
 /**
  * Feedback gets its own, much larger budget — and a retry.
@@ -71,6 +82,7 @@ const DETACHED_SEND_SCRIPT = "fetch(process.argv[1],{method:'POST',headers:{'con
 /** 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 = {
@@ -302,13 +314,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
@@ -333,20 +348,27 @@ 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.
             // 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.
+            // The RESOLVED env, not process.env: createTelemetry takes an env for injection, and reading
+            // the ambient one here would silently ignore it. Identical in production, wrong everywhere the
+            // seam is actually used.
+            ...licenseFacts(eventTs, env),
         };
         // 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, stall, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, bug, refusal, outage, instrumentation, ...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
@@ -377,7 +399,6 @@ export const createTelemetry = (opts) => {
             refusal,
             outage,
             instrumentation,
-            stall,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
@@ -388,7 +409,15 @@ export const createTelemetry = (opts) => {
             event: name,
             distinct_id: distinctId,
             timestamp: new Date(ts).toISOString(),
-            properties: { ...properties, ...POSTHOG_PERSONLESS },
+            properties: {
+                ...properties,
+                ...POSTHOG_PERSONLESS,
+                // Only on a licensed build. An unlicensed event has no organisation to belong to, and an
+                // empty group key would mint a phantom "no org" bucket that every OSS install falls into.
+                ...(event.licenseId !== undefined
+                    ? { $groups: { [POSTHOG_GROUP_ORGANIZATION]: event.licenseId } }
+                    : {}),
+            },
         };
         const body = JSON.stringify({ api_key: apiKey, batch: [capture] });
         const filePath = env[Env.FILE];