@reticlehq/server 2.4.0 → 2.6.0

package/dist/telemetry/cli-telemetry.js

@@ -4,8 +4,8 @@
  * Lives in its own module so `cli.ts` stays a dispatcher, and so the `_daemon` exclusion below sits
  * next to the explanation of why it exists rather than buried in a startup function.
  */
-import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
-import { DAEMON_INNER_COMMAND, knownCommand } from '../cli-parse.js';
+import { TelemetryEventKind } from '@reticlehq/core';
+import { DAEMON_INNER_COMMAND, knownCommand } from '../cli/cli-parse.js';
 import { getTelemetry } from './telemetry.js';
 import { describeCliFlags } from './argument-shape.js';
 /**
@@ -20,22 +20,45 @@ import { describeCliFlags } from './argument-shape.js';
  * The daemon\'s own lifecycle is already reported by `daemon_started` / `daemon_stopped`; a spawned
  * daemon is not a CLI run.
  */
+/**
+ * The agent's MCP transport, not a person. `reticle mcp` is what an MCP client runs to open a stdio
+ * connection — nobody types it. Measured over one real day it was 475 of 561 `cli_command_run`
+ * events (85%), on an event whose whole purpose is human intent, and the agent attaching is already
+ * reported by `mcp_client_connected` with strictly more detail (reconnect, daemon age, client).
+ *
+ * `serve` is NOT excluded: nothing spawns it on a person's behalf, so typing it is a real act.
+ */
+const AGENT_TRANSPORT_COMMAND = 'mcp';
+/** True when this command represents a person typing something. Exported for the gate. */
+export function isHumanCliCommand(command) {
+    return command !== AGENT_TRANSPORT_COMMAND && command !== DAEMON_INNER_COMMAND;
+}
 export function reportCliRun(argv) {
     const firstArg = argv[0];
     if (firstArg === DAEMON_INNER_COMMAND)
         return;
+    const command = knownCommand(firstArg);
     const telemetry = getTelemetry();
+    // FIRST — before the human-command filter. The install happened whichever command ran, and on most
+    // machines the very first contact is the agent spawning `reticle mcp`, which that filter excludes.
+    // Measured over one sweep: 15 `init_completed` and ZERO `reticle_installed`, in a run that
+    // installed the SDK into nine apps — the top of every funnel, missing.
     // `detach` so a quick command (`version`/`gate`) exits immediately instead of waiting out the POST.
     if (telemetry.firstRun)
         void telemetry.emit(TelemetryEventKind.RETICLE_INSTALLED, { detach: true });
+    if (!isHumanCliCommand(command))
+        return;
     void telemetry.emit(TelemetryEventKind.CLI_COMMAND_RUN, {
         detach: true,
-        actor: TelemetryActor.HUMAN,
+        // No `actor`: with the agent's transport excluded, this event is human BY DEFINITION. It was
+        // constant `human` on all 561 events in a real day — zero information, and wrong for the 475
+        // that were the agent. `actor` stays where it earns its place: verification_completed and
+        // bug_found, where it splits the agent's own loop from a human/CI-triggered run.
         // A fixed, low-cardinality vocabulary WE define, so it is safe to send whole and it is the closest
         // honest read we have on intent: `verify` and `gate` mean something very different from `status`.
         // An unrecognized first arg reports as `unknown` rather than being echoed — an echo would put
         // whatever someone mistyped, including a path or a URL, straight onto the wire.
-        command: knownCommand(firstArg),
+        command,
         // Which flags were PRESENT, by name only — never their values. `--http-token` alone makes that
         // rule absolute rather than case-by-case; `--drive` and `--storage-state` carry a URL and a path.
         flags: describeCliFlags(argv),

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,3 +1,40 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Exported because it is the BOUND ON WHAT IS LOST: a daemon that has served a tool never
+ * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. At 30
+ * minutes against a median 28-minute session that meant the median session reported nothing at all.
+ * Only non-empty windows emit, so a shorter interval costs nothing on the 74% of daemons that never
+ * 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 {
     /**
@@ -10,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

@@ -15,15 +15,33 @@ 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.
+ * How often a running daemon rolls up its window.
  *
- * 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.
+ * Exported because it is the BOUND ON WHAT IS LOST: a daemon that has served a tool never
+ * idle-exits, so nothing calls shutdown, so its last partial window dies with the process. At 30
+ * minutes against a median 28-minute session that meant the median session reported nothing at all.
+ * Only non-empty windows emit, so a shorter interval costs nothing on the 74% of daemons that never
+ * serve a tool.
  */
-const SESSION_FLUSH_MS = 30 * 60 * 1000;
+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.
@@ -48,26 +66,33 @@ 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
-        void getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
+        // NOT daemon_stopped: the daemon is still running. See SESSION_PROGRESS.
+        void getTelemetry().emit(TelemetryEventKind.SESSION_PROGRESS, {
             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/dev-repo.js

@@ -21,7 +21,7 @@ export function isReticleSourceCheckout(cwd) {
         if (existsSync(pkg)) {
             try {
                 const parsed = JSON.parse(readFileSync(pkg, 'utf8'));
-                const name = typeof parsed === 'object' && parsed !== null
+                const name = 'object' === typeof parsed && parsed !== null
                     ? parsed.name
                     : undefined;
                 if (name === MONOREPO_NAME)
@@ -42,7 +42,7 @@ export function isReticleSourceCheckout(cwd) {
 /** Strip one layer of matching quotes from a .env value. */
 function unquote(value) {
     const first = value[0];
-    if ((first === '"' || first === "'") && value.endsWith(first) && value.length >= 2) {
+    if (('"' === first || "'" === first) && value.endsWith(first) && value.length >= 2) {
         return value.slice(1, -1);
     }
     return value;
@@ -67,13 +67,13 @@ export function loadDotEnv(dir, env = process.env) {
     }
     for (const raw of text.split('\n')) {
         const line = raw.trim();
-        if (line.length === 0 || line.startsWith('#'))
+        if (0 === line.length || line.startsWith('#'))
             continue;
         const eq = line.indexOf('=');
         if (eq <= 0)
             continue; // not a KEY=value pair — skip rather than fail the whole file
         const key = line.slice(0, eq).trim();
-        if (key.length === 0 || env[key] !== undefined)
+        if (0 === key.length || env[key] !== undefined)
             continue;
         env[key] = unquote(line.slice(eq + 1).trim());
     }

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/error-fingerprint.js

@@ -19,6 +19,25 @@ import { createHash } from 'node:crypto';
  * quoted value often contains the very numbers and paths the later rules would only partly catch.
  */
 const VARIABLE_PARTS = [
+    // ── Identifiers and credentials FIRST ────────────────────────────────────────────────────────
+    //
+    // The rules below this block were written to make messages GROUPABLE — blank the variable parts so
+    // the same defect hashes the same everywhere. Redaction was a side effect of that, and a side
+    // effect is not a guarantee. A telemetry audit caught `bob@acme.com` arriving verbatim in
+    // `crash_message`; probing further, API-key-shaped tokens survived intact and a JWT was only
+    // half-masked. This function also feeds `session.errors[]` on EVERY session summary, so the
+    // exposure was every session that logged an error naming a user, not a rare crash path.
+    //
+    // Order matters: these run before the generic patterns, because `\d+` and the hex rule would chew
+    // a token into pieces that no longer match a credential shape while still leaking most of it —
+    // which is exactly what happened to the JWT.
+    /[\w.+-]+@[\w-]+\.[\w.-]+/g, // email addresses
+    /\beyJ[\w-]*\.[\w-]*\.?[\w-]*/g, // JWTs (header segment is always base64 `eyJ`)
+    /\b(?:sk|pk|rk|ghp|gho|ghs|ghu|ghr|github_pat|xox[abposr]|AKIA|ASIA|glpat)[_-][A-Za-z0-9_-]{8,}/gi,
+    // Anything else long enough and dense enough to be a secret rather than a word. The catch-all for
+    // formats nobody here has seen: on a privacy boundary, unrecognised is not the same as safe.
+    /\b[A-Za-z0-9_-]{24,}\b/g,
+    // ── Then the grouping rules ──────────────────────────────────────────────────────────────────
     /"[^"]*"|'[^']*'|`[^`]*`/g, // quoted values — names, selectors, snippets
     /\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, // URLs
     /(?:\/[\w.-]+){2,}\/?/g, // POSIX-ish paths
@@ -53,7 +72,7 @@ export function reticleFrames(stack) {
         if (!/@reticlehq[/\\]|[/\\]reticle[/\\]dist[/\\]/.test(line))
             continue;
         const location = line.match(/([\w.-]+\.(?:js|mjs|cjs|ts)):(\d+)/);
-        if (location === null)
+        if (null === location)
             continue;
         // `at Object.runTool (/path/to/invoke-tool.js:88:3)` → `runTool`. The function name is half the
         // value of a frame in an RCA — "it died in act-tools.js" narrows to a file, "it died in
@@ -62,7 +81,7 @@ export function reticleFrames(stack) {
         const where = `${location[1] ?? ''}:${location[2] ?? ''}`;
         // `Object.` / `Module.` prefixes are V8 noise that make the same function look like two.
         const name = fn?.replace(/^(?:Object|Module|Function)\./, '');
-        frames.push(name === undefined || name === '' ? where : `${name}@${where}`);
+        frames.push(name === undefined || '' === name ? where : `${name}@${where}`);
     }
     return frames;
 }

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

@@ -1,15 +1,20 @@
-import { TelemetryAction } from '../cli-parse.js';
+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,34 +1,45 @@
 import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
-import { BUG_FLAG, RATING_FLAG } from '../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-parse.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) {
+    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,
+        text: '' === text ? `rated ${String(rating)}/5 with no comment` : text,
         ...(rating !== undefined ? { rating } : {}),
     });
     line(`sending      ${JSON.stringify(describeFeedbackPayload(receipt.context))}`);
@@ -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.