@reticlehq/server 2.5.0 → 2.6.0

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() {
@@ -157,11 +176,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 +217,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 +240,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

@@ -136,6 +136,7 @@ export declare class Session {
         dropped: number;
     };
     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;

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;
@@ -373,6 +374,10 @@ export class Session {
         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 +425,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) {

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.
+ *
+ * Measured 2026-08-10/11 (non-CI): **614 `daemon_started` against 499 `daemon_stopped` — 19% of
+ * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed on
+ * the 81% 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.

package/dist/telemetry/daemon-telemetry.js

@@ -14,15 +14,6 @@ import { startUpdateCheck } from '../update/update-nudge.js';
 import { markDaemonStart } from './mcp-connection.js';
 /** Let the daemon finish coming up before walking the source tree for a profile. */
 const PROJECT_PROFILE_DELAY_MS = 5_000;
-/**
- * How often a long-lived daemon flushes its counters.
- *
- * 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.
- */
 /**
  * How often a running daemon rolls up its window.
  *
@@ -33,6 +24,24 @@ const PROJECT_PROFILE_DELAY_MS = 5_000;
  * serve a tool.
  */
 export const SESSION_FLUSH_MS = 5 * 60 * 1000;
+/**
+ * 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.
+ *
+ * Measured 2026-08-10/11 (non-CI): **614 `daemon_started` against 499 `daemon_stopped` — 19% of
+ * sessions never reported a summary at all.** Every "did anyone use Reticle" number is computed on
+ * the 81% 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 const FIRST_FLUSH_MS = 90 * 1000;
 /**
  * Report the daemon as started, profile the project once, and keep the session counters flushing.
  * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
@@ -57,7 +66,7 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             /* a profile is a nice-to-have; it must never touch the daemon */
         }
     }, PROJECT_PROFILE_DELAY_MS).unref();
-    const flush = setInterval(() => {
+    const flushWindow = () => {
         if (metrics.empty)
             return; // an idle window is not worth an event
         // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
@@ -65,19 +74,25 @@ export function installDaemonTelemetry(cwd, now = () => Date.now()) {
             session: metrics.summarize(false),
         });
         metrics.reset();
-    }, SESSION_FLUSH_MS);
+    };
+    // The early one closes the hole the interval cannot: a session killed before its first tick had
+    // emitted nothing at all. See FIRST_FLUSH_MS.
+    const firstFlush = setTimeout(flushWindow, FIRST_FLUSH_MS);
+    firstFlush.unref();
+    const flush = setInterval(flushWindow, SESSION_FLUSH_MS);
     flush.unref();
     let stopped;
     return {
-        shutdown() {
+        shutdown(exit) {
             // Both SIGTERM and the idle-shutdown path can call this; the second caller awaits the first
             // send rather than emitting a duplicate summary.
             stopped ??= (async () => {
                 clearInterval(flush);
+                clearTimeout(firstFlush);
                 // 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, {
-                    session: metrics.summarize(true),
+                    session: metrics.summarize(true, exit),
                 });
             })();
             return stopped;

package/dist/telemetry/error-class.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Whose defect was that tool error?
+ *
+ * `toolErrors` was one number covering three failures with three different fixes, so the top-line
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
+ * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
+ * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * which is the only bucket we can fix by writing better descriptions.
+ *
+ * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps
+ * counts. The full message is already fingerprinted and skeletonised elsewhere.
+ */
+/** Whose defect. Ordered by which fix it implies. */
+export declare const ErrorClass: {
+    /** Missing/unknown parameter, wrong type, unparseable predicate. **Our schema is unclear.** */
+    readonly SCHEMA: "schema";
+    /** No session, stale ref, disconnected. The world moved under the agent; not a schema problem. */
+    readonly STATE: "state";
+    /** We said no on purpose — a destructive block, an unsupported capability. Working as intended. */
+    readonly REFUSAL: "refusal";
+    /** Unrecognised. The bucket to watch: a large one is a blind spot, not a long tail. */
+    readonly OTHER: "other";
+};
+export type ErrorClass = (typeof ErrorClass)[keyof typeof ErrorClass];
+/** Which bucket this message belongs to. Never throws — a classifier must not break a tool path. */
+export declare function classifyError(message: string): ErrorClass;

package/dist/telemetry/error-class.js

@@ -0,0 +1,52 @@
+/**
+ * Whose defect was that tool error?
+ *
+ * `toolErrors` was one number covering three failures with three different fixes, so the top-line
+ * count could be acted on only by unpacking `errors[]` by hand and reading the prose. Measured over
+ * 2026-08-10/11: 60 `state`, 22 `refusal`, 20 `schema` (serialized zod arrays) and 20 stale refs.
+ * Read as "126 tool errors" that hides the sixth of them where OUR schema failed to explain itself —
+ * which is the only bucket we can fix by writing better descriptions.
+ *
+ * Classified from the message SHAPE, never stored raw: this returns a bucket, and the caller keeps
+ * counts. The full message is already fingerprinted and skeletonised elsewhere.
+ */
+/** Whose defect. Ordered by which fix it implies. */
+export const ErrorClass = {
+    /** Missing/unknown parameter, wrong type, unparseable predicate. **Our schema is unclear.** */
+    SCHEMA: 'schema',
+    /** No session, stale ref, disconnected. The world moved under the agent; not a schema problem. */
+    STATE: 'state',
+    /** We said no on purpose — a destructive block, an unsupported capability. Working as intended. */
+    REFUSAL: 'refusal',
+    /** Unrecognised. The bucket to watch: a large one is a blind spot, not a long tail. */
+    OTHER: 'other',
+};
+/**
+ * Patterns, most specific first.
+ *
+ * REFUSAL is tested before STATE because a destructive block often names a session too, and
+ * "we refused on purpose" is the more useful reading of that event.
+ */
+const PATTERNS = [
+    [/confirmdangerous|destructive action blocked/i, ErrorClass.REFUSAL],
+    [
+        /\brefus(e|ed|es|ing)\b|not supported|unsupported|cannot .* a <|contenteditable/i,
+        ErrorClass.REFUSAL,
+    ],
+    [
+        /did not parse|unknown field|unrecognized_keys|missing required|requires a (string|number)|invalid parameter|expected .* received|is larger than/i,
+        ErrorClass.SCHEMA,
+    ],
+    [
+        /no browser session connected|no connected session|multiple sessions connected|session disconnected|no longer resolves|no such session|not connected/i,
+        ErrorClass.STATE,
+    ],
+];
+/** Which bucket this message belongs to. Never throws — a classifier must not break a tool path. */
+export function classifyError(message) {
+    for (const [pattern, cls] of PATTERNS) {
+        if (pattern.test(message))
+            return cls;
+    }
+    return ErrorClass.OTHER;
+}

package/dist/telemetry/feedback-cli.d.ts

@@ -1,15 +1,20 @@
 import { TelemetryAction } from '../cli/cli-parse.js';
 /**
- * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the feedback channel as a command.
  *
  * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
  * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
  * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
  *
+ * `--agent --kind <…>` is the same channel for an AGENT that cannot reach `reticle_feedback` — during
+ * `init`, while instrumentation is half-wired, or when the daemon will not start. Those are the
+ * reports we are least likely to hear and most need: every other path we have requires the tool
+ * surface to already work, so a Reticle that fails before it is running fails silently by design.
+ *
  * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
  * show you the payload is asking for trust it has not earned.
  */
-export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean): Promise<void>;
+export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean, feedbackKind?: string, agent?: boolean): Promise<void>;
 /**
  * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.
  *

package/dist/telemetry/feedback-cli.js

@@ -1,32 +1,43 @@
 import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
-import { BUG_FLAG, RATING_FLAG } from '../cli/cli-parse.js';
+import { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG } from '../cli/cli-parse.js';
 import { describeFeedbackPayload, submitFeedback } from './feedback.js';
 import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
 import { TelemetryAction } from '../cli/cli-parse.js';
 import { clearIdentity, IDENTIFY_NOTICE, readIdentity, saveIdentity, submitIdentity, UsageContextKind, } from './identify.js';
 /**
- * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the feedback channel as a command.
  *
  * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
  * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
  * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
  *
+ * `--agent --kind <…>` is the same channel for an AGENT that cannot reach `reticle_feedback` — during
+ * `init`, while instrumentation is half-wired, or when the daemon will not start. Those are the
+ * reports we are least likely to hear and most need: every other path we have requires the tool
+ * surface to already work, so a Reticle that fails before it is running fails silently by design.
+ *
  * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
  * show you the payload is asking for trust it has not earned.
  */
-export async function handleFeedback(text, rating, bug) {
+export async function handleFeedback(text, rating, bug, feedbackKind, agent = false) {
     const line = (s) => {
         process.stdout.write(`${s}\n`);
     };
     if ('' === text && rating === undefined) {
         line(`usage: reticle feedback [${RATING_FLAG} 1-5] [${BUG_FLAG}] "what worked, what didn't"`);
+        line(`       agents: reticle feedback ${AGENT_FLAG} ${KIND_FLAG} <${FEEDBACK_KINDS.join('|')}> "what happened"`);
         line('       your words go to the maintainers; nothing from your app is ever included.');
         process.exitCode = 1;
         return;
     }
     const receipt = await submitFeedback({
-        source: FeedbackSource.HUMAN,
-        kind: bug ? FeedbackKind.BUG : FeedbackKind.EXPERIENCE,
+        // An agent filing through the CLI must not land in the HUMAN bucket: that bucket carries the
+        // ratings and the experience reports, and a few hundred agent reports mixed into it would make
+        // the one number that says whether people like Reticle mean nothing.
+        source: agent ? FeedbackSource.AGENT : FeedbackSource.HUMAN,
+        // `--kind` wins when given; `--bug` stays the shorthand it always was.
+        kind: feedbackKind ??
+            (bug ? FeedbackKind.BUG : FeedbackKind.EXPERIENCE),
         // A rating with no words is a real report, but the schema wants text — say what the rating means.
         text: '' === text ? `rated ${String(rating)}/5 with no comment` : text,
         ...(rating !== undefined ? { rating } : {}),
@@ -38,6 +49,39 @@ export async function handleFeedback(text, rating, bug) {
     line(receipt.sent
         ? 'thanks       your feedback is in. it genuinely changes what gets built next.'
         : `not sent     ${receipt.reason ?? 'unknown reason'}`);
+    for (const extra of identifyInvite(agent))
+        line(extra);
+}
+/**
+ * Offer a HUMAN a way to be replied to — printed after the receipt, never as a prompt.
+ *
+ * Feedback is anonymous by design and stays that way: the report has already been sent by the time
+ * this prints, so nothing here gates or delays it. This is an offer, not a question.
+ *
+ * It routes through `reticle identify`, which already does consented identity properly — it prints
+ * what it will send, states that identifying links this machine's prior anonymous history to that
+ * identity, and has `--forget`. Capturing an address inline on `feedback_submitted` instead would
+ * put PII on the anonymous event stream and break what `docs/telemetry.md` promises in public:
+ * "no domain sniffing, no email inference" and "no personal data is collected".
+ *
+ * Only for humans (an agent has no email), and only when nobody has identified yet — so somebody
+ * who declined is never asked twice.
+ */
+function identifyInvite(agent) {
+    if (agent)
+        return [];
+    try {
+        if (readIdentity() !== undefined)
+            return [];
+    }
+    catch {
+        return []; // unreadable identity file: say nothing rather than risk asking twice
+    }
+    return [
+        '',
+        'want a reply? `reticle identify --context <company|side_project|oss|learning> --email you@example.com`',
+        '             optional, and it tells you exactly what it sends before sending it.',
+    ];
 }
 /**
  * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.