@reticlehq/server 2.8.0 → 2.9.0

package/dist/telemetry/app-instrumented.d.ts

@@ -33,5 +33,13 @@ export interface InstrumentationFacts {
  * never be the reason a session fails to register.
  */
 export declare function reportAppInstrumented(facts: InstrumentationFacts, now?: () => number): void;
+/**
+ * Has an app connected to this daemon run at all?
+ *
+ * The same flag `reportAppInstrumented` uses for idempotency, read from outside. The stall check
+ * needs exactly this question and must not answer it from a window counter, which resets on every
+ * flush and would then report a long-instrumented daemon as freshly stalled.
+ */
+export declare function appEverConnected(): boolean;
 /** Tests only. */
 export declare function resetAppInstrumented(): void;

package/dist/telemetry/app-instrumented.js

@@ -47,6 +47,16 @@ export function reportAppInstrumented(facts, now = () => Date.now()) {
         /* never let a metric interfere with a page connecting */
     }
 }
+/**
+ * Has an app connected to this daemon run at all?
+ *
+ * The same flag `reportAppInstrumented` uses for idempotency, read from outside. The stall check
+ * needs exactly this question and must not answer it from a window counter, which resets on every
+ * flush and would then report a long-instrumented daemon as freshly stalled.
+ */
+export function appEverConnected() {
+    return reported;
+}
 /** Tests only. */
 export function resetAppInstrumented() {
     reported = false;

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 } 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,17 @@ 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.
+        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 (metrics.empty)
             return; // an idle window is not worth an event
         // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
@@ -93,6 +108,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,50 @@
+/**
+ * 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;
+/** Tests only. */
+export declare function resetInstrumentationStall(): void;

package/dist/telemetry/instrumentation-stall.js

@@ -0,0 +1,90 @@
+/**
+ * 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;
+}
+/** Tests only. */
+export function resetInstrumentationStall() {
+    reported = false;
+    daemonStartedAt = undefined;
+}

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,7 @@ 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 { gitFacts } from './git-facts.js';
 import { currentAutomationHint } from './automation-hint.js';
 const Env = {
@@ -274,6 +275,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) => {
@@ -326,17 +333,20 @@ 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,
         };
         // 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 +377,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 ?? {})) {