@reticlehq/server 2.5.0 → 2.7.0

package/dist/session/session-info.d.ts

@@ -4,7 +4,8 @@ export interface SessionInfo {
     url: string;
     /** Stable build-stamped project identity; absent for v1.0 SDKs that don't send it. */
     projectId?: string;
-    title: string;
+    /** Absent when the page has no title — never the empty string. Fall back to `url`. */
+    title?: string;
     adapters: string[];
     hasCapabilities: boolean;
     /** Present only when the page's SDK version differs from the daemon's — see version-skew.ts. */
@@ -22,6 +23,21 @@ export interface SessionInfo {
     pendingMarks?: number;
     /** present with pendingMarks — nudges the agent to drain them with reticle_review. */
     review_suggestion?: string;
+    /**
+     * Continuity of this attachment — `{ connectedSinceMs, outages, lastOutage? }`.
+     *
+     * A tab that dropped for four seconds and came back is indistinguishable from one that never left
+     * (#117), and that difference decides whether a verdict over the window can be trusted. Attached
+     * by `SessionManager.list()`, which is the layer that sees every connect and disconnect.
+     */
+    attachment?: {
+        connectedSinceMs: number;
+        outages: number;
+        lastOutage?: {
+            startedMs: number;
+            durationMs: number;
+        };
+    };
 }
 /** The read-only slice of a Session that the projection needs. Keeps this module class-free. */
 interface SessionView {

package/dist/session/session-info.js

@@ -18,7 +18,11 @@ export function buildSessionInfo(session) {
         sessionId: session.id,
         url: session.url,
         ...(session.projectId === undefined ? {} : { projectId: session.projectId }),
-        title: session.title,
+        // Omitted when blank, never `""`. An empty title cannot be told apart from "we sampled before
+        // the page set one", and two such tabs make the listing unusable. Moving the sample later does
+        // not fix it — a page may set its title after connect, or never — so the projection refuses the
+        // bad answer and the reader falls back to `url`, which is right here in the same record.
+        ...('' === session.title.trim() ? {} : { title: session.title }),
         adapters: session.adapters,
         hasCapabilities: session.hasCapabilities,
         // On every listing, not buried in a log — skew explains failures that read as app bugs.

package/dist/session/session-manager.d.ts

@@ -1,4 +1,5 @@
 import { Session, type SessionInfo } from './session.js';
+import { AttachmentHistory } from './attachment-history.js';
 /**
  * The agent's active project, used to scope auto-selection. `projectId` is the stable build-stamped
  * identity (authoritative when present); `url` is the app origin, a fallback hint for older SDKs that
@@ -18,11 +19,22 @@ export declare class SessionManager {
     remove(session: Session): boolean;
     get(sessionId: string): Session | undefined;
     list(): SessionInfo[];
+    /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
+    attachmentOf(sessionId: string): ReturnType<AttachmentHistory['of']>;
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all(): Session[];
     count(): number;
     /** Wire the diagnosis provider (daemon boot). Absent ⇒ the plain, static message. */
     setNoSessionHint(hint: (() => string | undefined) | undefined): void;
+    /**
+     * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
+     *
+     * `reticle_sessions` is the first thing an agent reaches for and it returned a bare empty array —
+     * confidently, with nothing to act on. An agent cannot tell an empty list apart from a daemon that
+     * is down, an app with no SDK, or a tab that was closed, so it stops there. The diagnosis was
+     * already computed for the error path; this exposes it to the read path too.
+     */
+    noSessionHint(): string | undefined;
     everConnected(): boolean;
     /** Record a bridge-initiated close so `resolve` can explain a session that vanished. */
     noteClosure(reason: string, at: number): void;

package/dist/session/session-manager.js

@@ -1,6 +1,7 @@
 import { NO_SESSION_CONNECTED_ERROR } from '@reticlehq/core';
 import { declareDrivenRedactionKeys, forgetDrivenRedactionKeys, } from '../input/driven-redaction.js';
 import { Session } from './session.js';
+import { AttachmentHistory } from './attachment-history.js';
 /** The scheme://host:port of a URL, or undefined if it can't be parsed. Used to compare origins. */
 export function originOf(url) {
     if (url === undefined)
@@ -62,6 +63,12 @@ function scopeMissError(connected, scope) {
 const MAX_REMEMBERED_CLOSURES = 5;
 export class SessionManager {
     #sessions = new Map();
+    /**
+     * Continuity per session, so a listing can answer "was this attached the whole time".
+     *
+     * Owned here because this is the one place that sees both halves — every add and every remove.
+     */
+    #attachment = new AttachmentHistory();
     /**
      * The active project's scope, set once from the daemon's .reticle.json. When a tool resolves a session
      * without passing its own scope, this is applied — so auto-selection is project-scoped by default
@@ -80,6 +87,7 @@ export class SessionManager {
         // bridge because EVERY path that registers a session goes through this method, and a declaration
         // that silently fails to register is a leak nothing would report.
         declareDrivenRedactionKeys(session.id, session.redactKeys);
+        this.#attachment.attached(session.id);
         return previous;
     }
     remove(session) {
@@ -87,13 +95,24 @@ export class SessionManager {
             return false;
         session.rejectAll('session disconnected');
         forgetDrivenRedactionKeys(session.id);
+        // Recorded, not forgotten: a session that comes back needs its gap measured, and a listing after
+        // the reconnect is exactly where that matters.
+        this.#attachment.detached(session.id);
         return this.#sessions.delete(session.id);
     }
     get(sessionId) {
         return this.#sessions.get(sessionId);
     }
     list() {
-        return [...this.#sessions.values()].map((s) => s.info());
+        return [...this.#sessions.values()].map((s) => {
+            const info = s.info();
+            const attachment = this.#attachment.of(s.id);
+            return attachment === undefined ? info : { ...info, attachment };
+        });
+    }
+    /** Continuity for one session — "has this been attached the whole time I am reasoning about?" */
+    attachmentOf(sessionId) {
+        return this.#attachment.of(sessionId);
     }
     /** Every connected session — used by the liveness reaper to sweep for idle/disconnected ones. */
     all() {
@@ -142,6 +161,17 @@ export class SessionManager {
     setNoSessionHint(hint) {
         this.#noSessionHint = hint;
     }
+    /**
+     * The same diagnosis, for a caller that is ASKING about sessions rather than failing to get one.
+     *
+     * `reticle_sessions` is the first thing an agent reaches for and it returned a bare empty array —
+     * confidently, with nothing to act on. An agent cannot tell an empty list apart from a daemon that
+     * is down, an app with no SDK, or a tab that was closed, so it stops there. The diagnosis was
+     * already computed for the error path; this exposes it to the read path too.
+     */
+    noSessionHint() {
+        return this.#noSessionHint?.();
+    }
     /** Whether any session has connected since this daemon booted — half the diagnosis. */
     #everConnected = false;
     everConnected() {
@@ -157,11 +187,35 @@ export class SessionManager {
     lastClosure() {
         return this.#recentClosures[this.#recentClosures.length - 1];
     }
+    /**
+     * A dead `sessionId`, answered with what the caller needs to recover — not with an errand.
+     *
+     * Telemetry, 2026-08-10: one agent called `reticle_navigate` twelve times against an id that was
+     * no longer connected. That single loop is **12 of the 58 tool errors recorded all day, 21%**. The
+     * refusal said only `no connected session with id 'x'`, and the recovery hint told it to call
+     * `reticle_sessions` and retry — two extra round trips to learn something this method already
+     * knows at the moment it refuses. An agent charged two calls to recover will often just repeat the
+     * one it made.
+     *
+     * So: name the live ids inline, and when there are none say that instead, because "retry with a
+     * valid one" is advice nobody can act on when no valid one exists.
+     */
+    #unknownSessionError(sessionId) {
+        const live = [...this.#sessions.values()];
+        if (0 === live.length) {
+            return (`no connected session with id '${sessionId}', and no sessions are connected at all — so ` +
+                'there is no other id to retry with. The app is not dialling this daemon; call ' +
+                'reticle_sessions for the diagnosis rather than retrying this call.');
+        }
+        const named = live.map((s) => `'${s.id}' (${s.url})`).join(', ');
+        return (`no connected session with id '${sessionId}'. Connected right now: ${named}. ` +
+            'Retry with one of those, or omit sessionId entirely and let Reticle scope to your project.');
+    }
     resolve(sessionId, scope) {
         if (sessionId !== undefined) {
             const found = this.#sessions.get(sessionId);
             if (found === undefined) {
-                throw new Error(`no connected session with id '${sessionId}'`);
+                throw new Error(this.#unknownSessionError(sessionId));
             }
             found.markAgentActivity(); // liveness — a targeted tool keeps the session alive / revives it
             return found;
@@ -174,7 +228,7 @@ export class SessionManager {
                 throw new Error(hint);
             throw new Error(closure === undefined
                 ? NO_SESSION_CONNECTED_ERROR
-                : `${NO_SESSION_CONNECTED_ERROR} NOTE: the bridge closed a session recently — "${closure.reason}". The app is probably still running; it was disconnected, and the SDK does not retry after a policy close. Reload the page to reconnect.`);
+                : `${NO_SESSION_CONNECTED_ERROR} NOTE: the bridge REFUSED or closed a connection recently — "${closure.reason}". The app is probably still running and trying to connect: it was turned away, and the SDK does not retry after a policy close. The reason above names the fix — do not go looking for a stopped dev server.`);
         }
         // Scope to the agent's active project FIRST, so a stray tab from another app/origin (e.g. a
         // leftover dashboard on a different port) is structurally unselectable — it never enters the
@@ -197,6 +251,32 @@ export class SessionManager {
             only.markAgentActivity();
             return only;
         }
+        // Two projects and nothing to choose between them: refuse, BEFORE any scoring.
+        //
+        // Reported from the field: a call from `apps/next-app-router` was answered by a `rowy-*`
+        // session, and `act_and_wait` spent 16.9s returning `verified:'no'` about an app never under
+        // test — a confident false verdict, with a source pointer, about code the agent never touched.
+        //
+        // The recency rule below cannot prevent it. It asks "is one of these clearly fresher", which is
+        // the right question for two tabs of ONE app and the wrong question for two apps: the fresher
+        // tab of the wrong project is still the wrong project. The reported case had a clear winner,
+        // so the ambiguity check passed and the wrong app was selected.
+        //
+        // This sits ahead of scoring so freshness cannot rescue it. It only fires when nothing scoped
+        // the call — an explicit `sessionId` returns far above, and an explicit or default scope has
+        // already narrowed `all` to one project by here.
+        const projects = new Set(all.map((s) => s.projectId).filter((p) => p !== undefined));
+        if (projects.size > 1) {
+            const listed = all
+                .filter((s) => s.projectId !== undefined)
+                .map((s) => `'${String(s.projectId)}' (${s.url}, sessionId '${s.id}')`)
+                .join(', ');
+            throw new Error(`${String(projects.size)} different projects are connected and nothing says which one this ` +
+                `call is about: ${listed}. Pass sessionId to target one. Reticle refuses rather than ` +
+                'guessing here because picking the wrong app produces a confident verdict about code you ' +
+                'never touched — the daemon scopes to the directory it was started in, so running it above ' +
+                'several apps leaves it unable to tell them apart.');
+        }
         // Multiple sessions: score each (lower = better candidate for auto-selection).
         // 0 = non-throttled (visible + recently-heard), 1 = throttled (hidden or stale heartbeat).
         const scored = all.map((s) => ({ s, score: s.throttled() ? 1 : 0, ms: s.lastSeenMs() }));

package/dist/session/session.d.ts

@@ -135,7 +135,14 @@ export declare class Session {
         total: number;
         dropped: number;
     };
+    /**
+     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+     * moves for the age and churn evictions that every live page produces continuously.
+     */
+    lostSince(cursor: number): boolean;
     onEvent(listener: (event: ReticleEvent) => void): () => void;
+    onDisconnect(listener: () => void): () => void;
     /** Send a command to the browser and await its reply (or time out). */
     command(name: string, args?: Record<string, unknown>, timeoutMs?: number): Promise<CommandResult>;
     handleResult(result: CommandResult): void;
@@ -158,6 +165,8 @@ export declare class Session {
     drainInbox(): InboxMessage[];
     /** Diagnostic read of the inbox depth (does not clear). */
     inboxSize(): number;
+    /** Everything the human has said this session, delivered or not. Never clears. */
+    inboxHistory(): readonly InboxMessage[];
     /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark does. */
     pendingMarks(): ReviewMark[];
     /** Full mark history (pending + resolved), oldest first. */

package/dist/session/session.js

@@ -48,6 +48,7 @@ export class Session {
     #buffer = new RingBuffer();
     #pending = new PendingCommands();
     #listeners = new Set();
+    #disconnectListeners = new Set();
     #actionSeq = 0;
     #lastSeenAt;
     #hidden = false;
@@ -369,10 +370,22 @@ export class Session {
     bufferHealth() {
         return this.#buffer.bufferHealth();
     }
+    /**
+     * Did the buffer lose scarce evidence from a window opened at `cursor`? The input to whether a
+     * verdict's capture was clean — see `RingBuffer.lostSince`, and never the raw drop counter, which
+     * moves for the age and churn evictions that every live page produces continuously.
+     */
+    lostSince(cursor) {
+        return this.#buffer.lostSince(cursor);
+    }
     onEvent(listener) {
         this.#listeners.add(listener);
         return () => this.#listeners.delete(listener);
     }
+    onDisconnect(listener) {
+        this.#disconnectListeners.add(listener);
+        return () => this.#disconnectListeners.delete(listener);
+    }
     /** Send a command to the browser and await its reply (or time out). */
     command(name, args = {}, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
         // Recorded HERE rather than at the tool call sites: this is the one place every driven action
@@ -420,6 +433,9 @@ export class Session {
     /** Reject everything still in flight — used on disconnect. */
     rejectAll(reason) {
         this.#pending.rejectAll(reason);
+        for (const listener of this.#disconnectListeners)
+            listener();
+        this.#disconnectListeners.clear();
     }
     /** End this transport without letting a stale socket remove its replacement session. */
     disconnect(reason) {
@@ -462,6 +478,10 @@ export class Session {
     inboxSize() {
         return this.#live.size();
     }
+    /** Everything the human has said this session, delivered or not. Never clears. */
+    inboxHistory() {
+        return this.#live.history();
+    }
     // ── Human review marks: the "annotate the bug where you see it" inbox (server-owned) ──────────
     /** Human marks still awaiting a fix (oldest first). Reading does not consume — resolveMark does. */
     pendingMarks() {

package/dist/status-payload.d.ts

@@ -14,6 +14,18 @@ interface StatusPayload {
     contract: string;
     sessionCount: number;
     sessions: SessionInfo[];
+    /**
+     * Why nothing is connected — present ONLY when `sessionCount` is 0.
+     *
+     * `reticle status` is the most-run command in the field, and with no sessions it answered
+     * `sessionCount: 0` and stopped. That is the same dead end `reticle_sessions` used to be for
+     * agents, at the same point in the funnel — the daemon is up, the agent is attached, and the app
+     * never arrived — and it is where most installs stop. Agents got the diagnosis in 2.7.0; a human
+     * running the command we tell them to run in `init`'s closing line deserves the same sentence.
+     */
+    why?: string;
 }
-export declare function statusPayload(sessionCount: number, sessions: SessionInfo[]): StatusPayload;
+export declare function statusPayload(sessionCount: number, sessions: SessionInfo[], 
+/** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
+why?: string): StatusPayload;
 export {};

package/dist/status-payload.js

@@ -1,11 +1,16 @@
 import { CONTRACT_FINGERPRINT } from '@reticlehq/core';
 import { SERVER_VERSION } from './version/server-version.js';
-export function statusPayload(sessionCount, sessions) {
+export function statusPayload(sessionCount, sessions, 
+/** The no-session diagnosis, injected so this stays pure and the port probe stays off this path. */
+why) {
     return {
         running: true,
         version: SERVER_VERSION,
         contract: CONTRACT_FINGERPRINT,
         sessionCount,
         sessions,
+        // Only when there is nothing to explain away: a diagnosis printed beside a live session would
+        // contradict it.
+        ...(0 === sessionCount && why !== undefined ? { why } : {}),
     };
 }

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

@@ -0,0 +1,37 @@
+/**
+ * When an app carrying the SDK first reaches this daemon.
+ *
+ * This is the step the whole funnel turns on, and the one nothing could measure. Registering the MCP
+ * server and instrumenting an app are separate acts, done by different commands, and the data says
+ * almost everybody does the first and almost nobody does the second — but proving that required
+ * inferring it from a window counter that resets on every flush, and which therefore reported fewer
+ * instrumented users than there were users calling tools.
+ *
+ * Once per daemon run, on the FIRST app connect only. A page that reloads, or an app that opens five
+ * tabs, must not read as five instrumented installs — the question is "did this install ever get an
+ * app wired", and it has one answer per run.
+ *
+ * Names, never values: whether `init` had been run and whether an agent was attached — never the
+ * project path, the URL, or anything from the page. The stack is deliberately NOT repeated here;
+ * `project_profiled` already carries it on the same daemon run, so the two join on sessionId.
+ */
+export declare function markInstrumentationClock(now: number): void;
+export interface InstrumentationFacts {
+    /** Whether this project has a projectId stamped — i.e. `init` has run here. */
+    initialized: boolean;
+    /**
+     * Whether an MCP client was attached when the app arrived.
+     *
+     * Both halves present is the only state in which Reticle can do anything, and it is worth being
+     * able to see the two orders apart: an app that connects with no agent attached is a person
+     * setting up, while an agent that has been waiting is a session about to do work.
+     */
+    agentAttached: boolean;
+}
+/**
+ * Report the first instrumented app of this daemon run. Best-effort and idempotent — a metric must
+ * never be the reason a session fails to register.
+ */
+export declare function reportAppInstrumented(facts: InstrumentationFacts, now?: () => number): void;
+/** Tests only. */
+export declare function resetAppInstrumented(): void;

package/dist/telemetry/app-instrumented.js

@@ -0,0 +1,54 @@
+/**
+ * When an app carrying the SDK first reaches this daemon.
+ *
+ * This is the step the whole funnel turns on, and the one nothing could measure. Registering the MCP
+ * server and instrumenting an app are separate acts, done by different commands, and the data says
+ * almost everybody does the first and almost nobody does the second — but proving that required
+ * inferring it from a window counter that resets on every flush, and which therefore reported fewer
+ * instrumented users than there were users calling tools.
+ *
+ * Once per daemon run, on the FIRST app connect only. A page that reloads, or an app that opens five
+ * tabs, must not read as five instrumented installs — the question is "did this install ever get an
+ * app wired", and it has one answer per run.
+ *
+ * Names, never values: whether `init` had been run and whether an agent was attached — never the
+ * project path, the URL, or anything from the page. The stack is deliberately NOT repeated here;
+ * `project_profiled` already carries it on the same daemon run, so the two join on sessionId.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+let reported = false;
+/** Set at daemon start so the first connect can report how long the install sat un-instrumented. */
+let daemonStartedAt;
+export function markInstrumentationClock(now) {
+    daemonStartedAt = now;
+    reported = false;
+}
+/**
+ * Report the first instrumented app of this daemon run. Best-effort and idempotent — a metric must
+ * never be the reason a session fails to register.
+ */
+export function reportAppInstrumented(facts, now = () => Date.now()) {
+    if (reported)
+        return;
+    reported = true;
+    try {
+        void getTelemetry().emit(TelemetryEventKind.APP_INSTRUMENTED, {
+            instrumentation: {
+                initialized: facts.initialized,
+                agentAttached: facts.agentAttached,
+                // How long the daemon ran before an app showed up. Large values are the interesting ones:
+                // Reticle was up, the agent had the tools, and nothing was wired for that whole time.
+                msToFirstApp: daemonStartedAt === undefined ? 0 : Math.max(0, now() - daemonStartedAt),
+            },
+        });
+    }
+    catch {
+        /* never let a metric interfere with a page connecting */
+    }
+}
+/** Tests only. */
+export function resetAppInstrumented() {
+    reported = false;
+    daemonStartedAt = undefined;
+}

package/dist/telemetry/crash-cause.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What a crash was, when the stack cannot say where it was.
+ *
+ * `reticleFrames` keeps only frames inside our own published packages, on the rule that a crash
+ * stack is mostly the user's application and node internals and neither is ours to collect. That
+ * rule is right and stays. But a refused socket has a stack that is ENTIRELY node internals:
+ *
+ *     Error: connect ECONNREFUSED 127.0.0.1:4400
+ *         at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)
+ *
+ * so every crash of that shape arrives with an error type, a redacted message, and nothing else —
+ * 65 of them in one measured day, one fingerprint, zero location on all 65, and 63 of those from
+ * two people who emitted no other event of any kind. A loopback-heavy tool produces plenty of
+ * these, and the next one is just as blind.
+ *
+ * Everything here is derived from a Node SYSTEM ERROR's own structured properties, and every field
+ * is chosen so that it carries nothing of the reporter's: the syscall and errno are our own
+ * vocabulary, `loopback` is one bit, the port is compared against values we already know and
+ * reported as an enum, and the frame names a line in NODE's source. The address and the port number
+ * are read and deliberately thrown away.
+ */
+/** The structured cause of a crash, when the error carries one. Every field is optional. */
+export interface CrashCause {
+    syscall?: string;
+    errno?: string;
+    loopback?: boolean;
+    port?: CrashPort;
+    internalFrame?: string;
+}
+import { CrashPort } from '@reticlehq/core';
+/**
+ * The innermost frame that names NODE's own source.
+ *
+ * Innermost because that is where the failure actually happened, and it distinguishes a connect
+ * from a DNS lookup from a TLS handshake — the thing that, in the report this came from, had to be
+ * worked out by hand from a proxy's reject path. `node:net:1637` is a line in Node's published
+ * source: it carries nothing about the machine, the app, or anyone's directory layout, which is
+ * why it can be kept when the user's own frames cannot.
+ */
+export declare function innermostInternalFrame(stack: string): string | undefined;
+/**
+ * Read a Node system error's structured cause, keeping only what is ours to keep.
+ *
+ * `knownPorts` is passed IN rather than read from the environment so this stays pure and so the
+ * comparison is testable — the port itself is used to answer one enum and is then discarded.
+ */
+export declare function crashCause(value: unknown, knownPorts: readonly number[]): CrashCause;

package/dist/telemetry/crash-cause.js

@@ -0,0 +1,104 @@
+/**
+ * What a crash was, when the stack cannot say where it was.
+ *
+ * `reticleFrames` keeps only frames inside our own published packages, on the rule that a crash
+ * stack is mostly the user's application and node internals and neither is ours to collect. That
+ * rule is right and stays. But a refused socket has a stack that is ENTIRELY node internals:
+ *
+ *     Error: connect ECONNREFUSED 127.0.0.1:4400
+ *         at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)
+ *
+ * so every crash of that shape arrives with an error type, a redacted message, and nothing else —
+ * 65 of them in one measured day, one fingerprint, zero location on all 65, and 63 of those from
+ * two people who emitted no other event of any kind. A loopback-heavy tool produces plenty of
+ * these, and the next one is just as blind.
+ *
+ * Everything here is derived from a Node SYSTEM ERROR's own structured properties, and every field
+ * is chosen so that it carries nothing of the reporter's: the syscall and errno are our own
+ * vocabulary, `loopback` is one bit, the port is compared against values we already know and
+ * reported as an enum, and the frame names a line in NODE's source. The address and the port number
+ * are read and deliberately thrown away.
+ */
+import { CrashPort } from '@reticlehq/core';
+import { reticleFrames } from './error-fingerprint.js';
+/** IPv4 loopback is the whole 127/8 block, not just 127.0.0.1. */
+const IPV4_LOOPBACK = /^127\./;
+/** `node:net:1637` out of `at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1637:16)`. */
+const NODE_INTERNAL_FRAME = /\((node:[\w/.-]+):(\d+):\d+\)/;
+/** V8 renders an IPv4-mapped IPv6 address this way; the mapped half is what decides loopback. */
+const IPV6_MAPPED_PREFIX = '::ffff:';
+/**
+ * Was this aimed at the machine it was running on?
+ *
+ * One bit, and it splits two populations with different owners: refused ON loopback is a Reticle
+ * lifecycle problem (a daemon that is not up), refused off-box is a network problem that is not
+ * ours. Today they are indistinguishable in the data.
+ */
+function isLoopback(address) {
+    const host = address.toLowerCase();
+    if ('::1' === host || 'localhost' === host)
+        return true;
+    const unmapped = host.startsWith(IPV6_MAPPED_PREFIX)
+        ? host.slice(IPV6_MAPPED_PREFIX.length)
+        : host;
+    return IPV4_LOOPBACK.test(unmapped);
+}
+/**
+ * The innermost frame that names NODE's own source.
+ *
+ * Innermost because that is where the failure actually happened, and it distinguishes a connect
+ * from a DNS lookup from a TLS handshake — the thing that, in the report this came from, had to be
+ * worked out by hand from a proxy's reject path. `node:net:1637` is a line in Node's published
+ * source: it carries nothing about the machine, the app, or anyone's directory layout, which is
+ * why it can be kept when the user's own frames cannot.
+ */
+export function innermostInternalFrame(stack) {
+    for (const line of stack.split('\n')) {
+        const match = line.match(NODE_INTERNAL_FRAME);
+        if (null === match)
+            continue;
+        const [, module, lineNumber] = match;
+        if (module === undefined || lineNumber === undefined)
+            continue;
+        return `${module}:${lineNumber}`;
+    }
+    return undefined;
+}
+/**
+ * Read a Node system error's structured cause, keeping only what is ours to keep.
+ *
+ * `knownPorts` is passed IN rather than read from the environment so this stays pure and so the
+ * comparison is testable — the port itself is used to answer one enum and is then discarded.
+ */
+export function crashCause(value, knownPorts) {
+    if (!(value instanceof Error))
+        return {};
+    const error = value;
+    const cause = {};
+    if ('string' === typeof error.syscall && error.syscall.length > 0)
+        cause.syscall = error.syscall;
+    // `code` (`ECONNREFUSED`), not the numeric `errno` (-61): the symbolic name is stable across
+    // platforms, where the number is not.
+    if ('string' === typeof error.code && error.code.length > 0)
+        cause.errno = error.code;
+    if ('string' === typeof error.address)
+        cause.loopback = isLoopback(error.address);
+    if ('number' === typeof error.port) {
+        cause.port = knownPorts.includes(error.port) ? CrashPort.RETICLE : CrashPort.OTHER;
+    }
+    // Only for a SYSTEM error, and only when nothing of ours is on the stack.
+    //
+    // Both halves are about collecting the minimum that answers the question. Any error raised
+    // anywhere in Node carries `node:internal/*` frames from whatever called it, so an ungated rule
+    // would attach one to every crash — noise on the reports that already have a location, and more
+    // than we need. The blind reports are the ones with a syscall and no frames of our own, and they
+    // are the only ones this exists for.
+    if (cause.syscall === undefined && cause.errno === undefined)
+        return cause;
+    if (reticleFrames(error.stack ?? '').length > 0)
+        return cause;
+    const frame = innermostInternalFrame(error.stack ?? '');
+    if (frame !== undefined)
+        cause.internalFrame = frame;
+    return cause;
+}

package/dist/telemetry/daemon-telemetry.d.ts

@@ -1,12 +1,12 @@
 /**
- * How often a long-lived daemon flushes its counters.
+ * The daemon's telemetry lifecycle, in one place: start, the periodic flush that survives a kill, the
+ * one-shot project profile, and the rich summary on shutdown.
  *
- * ponytail: coarse on purpose. A daemon that is SIGKILLed — OOM, a closed laptop, `kill -9` — never
- * reaches its shutdown handler, so without this the whole session's counters die with it. Thirty
- * minutes bounds that loss to one window while keeping the event volume near zero for the common case
- * (most daemons stop cleanly and send exactly one summary). If the lost windows ever show up as a
- * real gap, the upgrade is a small on-disk journal replayed at the next start, not a shorter timer.
+ * Extracted from `cli.ts` because it is a cohesive unit with its own timers and its own failure rule
+ * (nothing here may ever be able to fail a daemon start), and because `cli.ts` is a dispatcher — the
+ * more of this that lives there, the harder it is to see what a command actually does.
  */
+import { type SessionSummary } from '@reticlehq/core';
 /**
  * How often a running daemon rolls up its window.
  *
@@ -17,6 +17,24 @@
  * serve a tool.
  */
 export declare const SESSION_FLUSH_MS: number;
+/**
+ * When a session first rolls up, independent of the periodic interval.
+ *
+ * The interval alone leaves a hole exactly the width of itself: a daemon SIGKILLed before its first
+ * tick — a closed laptop, OOM, `kill -9`, a force-quit editor — reaches no shutdown handler and has
+ * emitted nothing, so the whole session is invisible.
+ *
+ * In the field `daemon_started` outran `daemon_stopped` by a wide margin: **a meaningful share of
+ * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed only
+ * on the sessions that did, and undercounts by an unknown amount, which is the one thing a funnel
+ * metric must not do.
+ *
+ * Ninety seconds is chosen against what it protects: a session that did real work usually does it
+ * early (snapshot -> act -> assert is seconds), so one early tick captures nearly all of it. It
+ * costs nothing on the daemons that dominate the population, because only a NON-EMPTY window emits
+ * and 74% of daemons never serve a tool at all.
+ */
+export declare const FIRST_FLUSH_MS: number;
 /** Stops the timers this installed. Called from the daemon's shutdown path. */
 export interface DaemonTelemetry {
     /**
@@ -29,7 +47,7 @@ export interface DaemonTelemetry {
      * fails or hangs still cannot block the exit, because `emit` swallows its own errors and is bounded
      * by its own request timeout.
      */
-    shutdown(): Promise<void>;
+    shutdown(exit?: SessionSummary['exit']): Promise<void>;
 }
 /**
  * Report the daemon as started, profile the project once, and keep the session counters flushing.