@reticlehq/server 2.9.0 → 2.10.0

package/dist/mcp/mcp.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { PredicateSchema } from '../events/predicate.js';
-import { isToonable, resultToToon } from '@reticlehq/core';
+import { isToonable, resultToToon, MCP_SERVER_NAME } from '@reticlehq/core';
 import { TOOLS } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-surface.js';
 import { ReticleTool } from '../tools/tool-names.js';
@@ -18,7 +18,6 @@ import { unadvertisedToolHelp } from '../tools/unadvertised-help.js';
 const CALL_TOOL_METHOD = 'tools/call';
 import { log } from '../log.js';
 import { SERVER_VERSION } from '../version/server-version.js';
-import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
 import { getSessionMetrics } from '../telemetry/session-metrics.js';
 import { parsePredicate } from '../events/predicate-parse.js';
@@ -201,11 +200,24 @@ export function encodeResult(result, encoding) {
  * "Call reticle_tools { names: [...] } for its parameters" — leaving it out made our own advice a
  * dead end on the one surface that advertises everything.
  */
-export function advertisedTools(surface) {
+export function advertisedTools(surface, 
+/**
+ * The full table to advertise from. Defaults to what this package ships.
+ *
+ * A consumer embedding the engine passes its own composition — ours plus its own — so its tools
+ * reach the wire without editing the shipped array.
+ */
+tools = TOOLS) {
     // The catalog reports which surface is live and what chose it — the only way an agent can see that
     // a setting did not take (the daemon read the value it started with).
     const origin = describeToolSurface(surface);
-    return [...filterTools(TOOLS, surface), ...buildDynamicTools(TOOLS, origin)];
+    // The profile trims OUR table only. A tool this package does not ship was appended deliberately by
+    // whoever is embedding us, and our `CORE_TOOL_NAMES` was never going to contain its name — so
+    // filtering it would drop every consumer tool and look exactly like the feature not working.
+    const shipped = new Set(TOOLS.map((tool) => tool.name));
+    const ours = tools.filter((tool) => shipped.has(tool.name));
+    const theirs = tools.filter((tool) => !shipped.has(tool.name));
+    return [...filterTools([...ours], surface), ...theirs, ...buildDynamicTools([...tools], origin)];
 }
 /**
  * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
@@ -364,7 +376,16 @@ export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT,
  * told to instrument a project that is already wired loses a paragraph, while an agent not told
  * loses the entire install — and the second is what the field overwhelmingly shows.
  */
-previouslyConnected = false) {
+previouslyConnected = false, 
+/**
+ * The full tool table this server serves. Defaults to what this package ships.
+ *
+ * Threaded rather than read from the module so a consumer can serve its own tools on one surface
+ * with ours. It reaches all three places that need the WHOLE table and not just the advertised
+ * slice: the profile filter, the `reticle_run` hatch, and the unadvertised-tool help — a consumer
+ * tool missing from either of the last two is a tool the agent is actively told does not exist.
+ */
+tools = TOOLS) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
     // Which surface this daemon advertises. The 18-tool default and the 48-tool full surface are
     // different products from inside an agent's context, so outcomes are only comparable when the
@@ -412,13 +433,13 @@ previouslyConnected = false) {
     // 11 tools were unreachable with no escape hatch — including reticle_annotate, which
     // reticle_flow_save's own description instructs the agent to call. `full` advertises everything
     // directly and needs no hatch.
-    const advertised = advertisedTools(profile);
+    const advertised = advertisedTools(profile, tools);
     installFriendlyArgErrors(server, new Map(advertised
         .filter((tool) => tool.example !== undefined)
         .map((tool) => [tool.name, JSON.stringify(tool.example)])), 
-    // Every tool in TOOLS, not just the advertised ones: reticle_run dispatches to the full table,
-    // so an unadvertised tool reached through the hatch must be just as strict.
-    new Map(TOOLS.map((tool) => [tool.name, new Set(Object.keys(tool.inputSchema))])));
+    // Every tool in the table, not just the advertised ones: reticle_run dispatches to the full
+    // table, so an unadvertised tool reached through the hatch must be just as strict.
+    new Map(tools.map((tool) => [tool.name, new Set(Object.keys(tool.inputSchema))])));
     for (const tool of advertised) {
         // Output schemas are now the largest slice of the per-request tax (55.6% of the hybrid payload
         // after the predicate fix) and we are the only one of the three MCP servers that sends them.
@@ -480,6 +501,6 @@ previouslyConnected = false) {
     // `tools/call` dispatcher lazily on the FIRST registerTool, so wrapping before this point finds
     // nothing to wrap and silently does nothing. Verified live rather than assumed — the first attempt
     // sat here doing exactly that.
-    installUnadvertisedToolHelp(server, new Set(advertised.map((tool) => tool.name)), new Set(TOOLS.map((tool) => tool.name)));
+    installUnadvertisedToolHelp(server, new Set(advertised.map((tool) => tool.name)), new Set(tools.map((tool) => tool.name)));
     return server;
 }

package/dist/mcp/proxy-daemon-probe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export declare function probeDaemon(port: number): Promise<boolean>;
+/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
+export declare function waitForDaemon(port: number): Promise<void>;

package/dist/mcp/proxy-daemon-probe.js

@@ -0,0 +1,48 @@
+import * as net from 'node:net';
+import { LOOPBACK_HOST } from '@reticlehq/core';
+const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
+/**
+ * How long to wait for the spawned daemon's port to accept connections before giving up. The default
+ * suits a normal machine; a slow CI/VM (heavy headless-browser launch) can raise it via the
+ * RETICLE_DAEMON_READY_TIMEOUT_MS env var. Invalid/absent values fall back to the default.
+ */
+const envDaemonReadyTimeoutMs = Number(process.env['RETICLE_DAEMON_READY_TIMEOUT_MS']);
+const DAEMON_READY_TIMEOUT_MS = Number.isFinite(envDaemonReadyTimeoutMs) && envDaemonReadyTimeoutMs > 0
+    ? envDaemonReadyTimeoutMs
+    : DEFAULT_DAEMON_READY_TIMEOUT_MS;
+const DAEMON_POLL_INTERVAL_MS = 100;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export function probeDaemon(port) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(500);
+        socket.on('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on('error', () => resolve(false));
+        socket.on('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, LOOPBACK_HOST);
+    });
+}
+/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
+export async function waitForDaemon(port) {
+    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        const reachable = await probeDaemon(port);
+        if (reachable)
+            return;
+        await delay(DAEMON_POLL_INTERVAL_MS);
+    }
+    throw new Error(`reticle daemon did not become ready on port ${port} within ${DAEMON_READY_TIMEOUT_MS}ms`);
+}

package/dist/mcp/proxy-handshake.js

@@ -14,8 +14,8 @@
  * Safe because the proxy replays the client's own `initialize` to the daemon whenever a session is
  * finally established (see `replayLines`), so the daemon still gets its handshake in order.
  */
-import { MCP_SERVER_NAME } from '../init/mcp.js';
 import { SERVER_VERSION } from '../version/server-version.js';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
 /** The version we answer with if the client proposed none. */
 const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
 /**

package/dist/mcp/server-instructions.js

@@ -22,7 +22,7 @@ import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
 /** The tools, and the rule that only two of them decide anything. Constant across both states. */
 const VERDICT_DISCIPLINE = `Reticle verifies a running web app from the inside: look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
 
-Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. A verdict of verified:"unknown" is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.`;
+Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.`;
 /**
  * The first move, for a project no app has ever connected to.
  *
@@ -41,7 +41,7 @@ const FEEDBACK_ASK = `Feedback is first-class here, not a courtesy. Reticle is b
 - You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
 - The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
 
-Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
+Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <one of those kinds> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
 /** The instructions this daemon should advertise, given what it knows about the project. */
 /**
  * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn. Measured on this

package/dist/mcp/sse-frame-parser.d.ts

@@ -0,0 +1,19 @@
+/** One parsed Server-Sent-Events frame: the event name (defaulted to "message") and its data. */
+export interface SseFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Incremental SSE frame parser for the MCP front door.
+ *
+ * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
+ * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
+ * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
+ * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
+ * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
+ * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
+ */
+export declare class SseFrameParser {
+    #private;
+    push(chunk: string): SseFrame[];
+}

package/dist/mcp/sse-frame-parser.js

@@ -0,0 +1,41 @@
+/**
+ * Incremental SSE frame parser for the MCP front door.
+ *
+ * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
+ * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
+ * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
+ * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
+ * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
+ * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
+ */
+export class SseFrameParser {
+    #buffer = '';
+    #event = '';
+    #data = '';
+    push(chunk) {
+        this.#buffer += chunk;
+        // Normalise CRLF/CR so the splitter only handles \n, then hold the trailing partial line for the
+        // next chunk (it may complete later).
+        const normalised = this.#buffer.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const lines = normalised.split('\n');
+        this.#buffer = lines.pop() ?? '';
+        const frames = [];
+        for (const line of lines) {
+            if ('' === line) {
+                if (this.#data !== '') {
+                    frames.push({ event: this.#event !== '' ? this.#event : 'message', data: this.#data });
+                }
+                this.#event = '';
+                this.#data = '';
+            }
+            else if (line.startsWith('event:')) {
+                this.#event = line.slice(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                const val = line.slice(5).trim();
+                this.#data = this.#data !== '' ? `${this.#data}\n${val}` : val;
+            }
+        }
+        return frames;
+    }
+}

package/dist/session/no-session-diagnosis.d.ts

@@ -100,6 +100,13 @@ export interface NoSessionFacts {
      * that a reader deserves to check it.
      */
     searchedDirectories?: readonly string[];
+    /**
+     * How long this daemon has been running with no app connected, in milliseconds.
+     *
+     * Present only when the stall clock is active and no app has arrived. Used to surface "the
+     * install never finished" to the user-facing diagnosis rather than only to telemetry.
+     */
+    daemonUpMs?: number;
 }
 /**
  * Every branch ends with this, and `recoveryFor` keys on it to suppress the generic no-session

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

@@ -19,6 +19,7 @@
  * the hot resolve() path and this stays unit-testable.
  */
 import { DEV_SERVER_PORTS } from '../cli/cli-port.js';
+import { STALL_AFTER_MS } from '../telemetry/instrumentation-stall.js';
 /** The one framework whose most likely cause differs from every other framework's. */
 const NUXT = 'nuxt';
 /**
@@ -248,6 +249,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.
@@ -322,7 +343,7 @@ export function diagnoseNoSession(facts) {
                 '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}`);
         }
-        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 ' +
@@ -353,7 +374,7 @@ 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}`);

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 '../telemetry/instrumentation-stall.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/telemetry/daemon-telemetry.js

@@ -13,7 +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 { 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;
@@ -80,12 +80,17 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
         // 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({
+        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.

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

@@ -46,5 +46,12 @@ export interface StallFacts {
 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

@@ -83,6 +83,19 @@ export function reportInstrumentationStall(facts, now = () => Date.now(), opts =
     }
     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;

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/telemetry.js

@@ -71,6 +71,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 +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
@@ -340,6 +344,11 @@ export const createTelemetry = (opts) => {
             // 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:

package/dist/tools/dynamic-tools.js

@@ -75,7 +75,7 @@ export function buildDynamicTools(allTools, profile) {
         };
     const reticleTools = {
         name: ReticleTool.TOOLS,
-        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_flow_verify (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
+        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_verify{action:"flows"} (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
         inputSchema: {
             names: z
                 .array(z.string())

package/dist/tools/error-recovery.js

@@ -129,7 +129,7 @@ export const RECOVERY = {
         'synchronous task, an alert/confirm dialog); reticle_console usually shows what it hit. Retry ' +
         'once the cause is addressed.',
     FLOW_STEP_MISSING: 'A recorded step points at an element that is not on the page now. Either the app changed under ' +
-        'the flow — run reticle_flow_heal to re-anchor it, then reticle_flow_verify — or an earlier step ' +
+        'the flow — run reticle_flow_heal to re-anchor it, then reticle_verify{action:"flows"} — or an earlier step ' +
         'did not do what it used to, leaving the run on the wrong page: check reticle_snapshot to see ' +
         'where it actually is. This is app/flow drift, which is exactly what the flow exists to catch.',
     NO_POOL: 'Reticle cannot launch its own browser here: the daemon-managed pool is absent, or Playwright ' +