@reticlehq/server 3.6.0 → 3.7.0

package/dist/telemetry/error-fingerprint.js

@@ -40,8 +40,13 @@ const VARIABLE_PARTS = [
     // ── Then the grouping rules ──────────────────────────────────────────────────────────────────
     /"[^"]*"|'[^']*'|`[^`]*`/g, // quoted values — names, selectors, snippets
     /\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, // URLs
+    // Windows paths run to the end of the message: a directory name may hold a space, and
+    // `C:\Users\Jane Doe\…` cut at the first space sent the surname.
+    /(?:\\\\\?\\)?[A-Za-z]:[\\/].*$/g,
+    /~[\\/]\S*/g, // home-relative paths
     /(?:\/[\w.-]+){2,}\/?/g, // POSIX-ish paths
-    /[A-Za-z]:\\[^\s]*/g, // Windows paths
+    /\b\d{1,3}(?:\.\d{1,3}){3}(?::\d+)?\b/g, // IPv4 (+ port)
+    /\b[\w-]+(?:\.[\w-]+)+\b/g, // hostnames and other dotted names
     /\b[0-9a-f]{8,}\b/gi, // hex ids, hashes, uuids-without-dashes
     /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, // uuids
     /\d+/g, // any remaining number — ports, counts, timeouts
@@ -71,16 +76,67 @@ const VARIABLE_PARTS = [
  * for a reason unrelated to this one.
  */
 const MAX_SKELETON_INPUT = 1024;
-/** The skeleton of a message: variable parts blanked, whitespace collapsed, length bounded. */
-export function errorSkeleton(message) {
+/** Variable parts blanked, whitespace collapsed, length bounded. The GROUPING basis; never sent. */
+function redactedShape(message) {
     let skeleton = message.slice(0, MAX_SKELETON_INPUT);
     for (const pattern of VARIABLE_PARTS)
         skeleton = skeleton.replace(pattern, '*');
     return skeleton.replace(/\s+/g, ' ').trim().slice(0, 200);
 }
+/**
+ * Sentences Reticle itself authors, and the fixed text sent for each. The OUTPUT is always the
+ * label, never the matched message, so text appended to one of ours cannot ride along.
+ */
+const RETICLE_MESSAGES = [
+    { match: /^no browser session connected\b/i, label: 'no browser session connected' },
+    { match: /^multiple sessions connected\b/i, label: 'multiple sessions connected' },
+    { match: /^no connected session with id\b/i, label: 'no connected session with id *' },
+    { match: /^no baseline named\b/i, label: 'no baseline named *' },
+    { match: /^no (?:active|compiled) recording named\b/i, label: 'no recording named *' },
+    { match: /no longer resolves to an element/i, label: 'ref * no longer resolves to an element' },
+    { match: /^session disconnected$/i, label: 'session disconnected' },
+    { match: /^command '[^']*' timed out after\b/i, label: 'command * timed out after *' },
+    {
+        match: /did not resolve in current page/i,
+        label: 'flow step * did not resolve in current page',
+    },
+    {
+        match: /potentially destructive (?:\w+ )*(?:action|tool) blocked/i,
+        label: 'potentially destructive action blocked',
+    },
+    { match: /^pairing token is required\b/i, label: 'pairing token is required' },
+    { match: /no <option> with value/i, label: 'no <option> with value *' },
+    { match: /cannot hover without a real pointer/i, label: 'cannot hover without a real pointer' },
+    { match: /browser pool (?:unavailable|is shut down)/i, label: 'browser pool unavailable' },
+    { match: /Chromium is not installed/i, label: 'Chromium is not installed' },
+    { match: /^act failed$/i, label: 'act failed' },
+];
+/** A Node error code (`ENOENT`, `ERR_INVALID_ARG_TYPE`): an identifier Node defines, never data. */
+const NODE_ERROR_CODE = /\b(?:E[A-Z]{2,}|ERR_[A-Z_]{2,})\b/;
+/** The built-in error classes. A custom class name is the app's own word, so it is not kept. */
+const BUILTIN_ERROR_CLASS = /^(?:Error|TypeError|RangeError|SyntaxError|ReferenceError|EvalError|URIError|AggregateError|AbortError|TimeoutError|DOMException|ZodError)\b/;
+/**
+ * What an error message may say on the wire, and it is ALLOW-listed: a sentence Reticle authors
+ * (sent as our own fixed label), else the bare Node error code or built-in class plus the
+ * fingerprint, else the fingerprint alone.
+ *
+ * It used to be the message with known-variable parts blanked, which is a deny-list, and a
+ * deny-list loses: a hostname after `getaddrinfo ENOTFOUND`, a Windows home directory with a space
+ * in it, a `~` path and a person's name in free text all reached the wire. Nothing written by
+ * anybody else survives this function, because it never echoes its input.
+ */
+export function errorSkeleton(message) {
+    const head = message.slice(0, MAX_SKELETON_INPUT).trim();
+    for (const { match, label } of RETICLE_MESSAGES)
+        if (match.test(head))
+            return label;
+    const fingerprint = `#${fingerprintError(message)}`;
+    const code = BUILTIN_ERROR_CLASS.exec(head)?.[0] ?? NODE_ERROR_CODE.exec(head)?.[0];
+    return code === undefined ? fingerprint : `${code} ${fingerprint}`;
+}
 /** A stable, opaque group key for an error message. Same defect ⇒ same key, on every machine. */
 export function fingerprintError(message) {
-    return createHash('sha256').update(errorSkeleton(message)).digest('hex').slice(0, 12);
+    return createHash('sha256').update(redactedShape(message)).digest('hex').slice(0, 12);
 }
 /**
  * Frames from a stack trace that belong to RETICLE, reduced to `basename:line`.
@@ -121,7 +177,7 @@ export function fingerprintCrash(errorType, stack, message) {
     const frames = reticleFrames(stack);
     const basis = frames.length > 0
         ? `${errorType}|${frames.join('|')}`
-        : `${errorType}|${errorSkeleton(message)}`;
+        : `${errorType}|${redactedShape(message)}`;
     return createHash('sha256').update(basis).digest('hex').slice(0, 12);
 }
 /** The error's constructor name (`TypeError`), or `Unknown` for a thrown non-Error. */

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

@@ -15,19 +15,6 @@ import { TelemetryAction } from '../command/cli/cli-parse.js';
  * show you the payload is asking for trust it has not earned.
  */
 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.
- *
- * Deliberately NOT interactive: a prompt that appears in the middle of someone's work is pressure,
- * and this is the one command where the user must be choosing freely. They type what they want to
- * share, or they never run it at all.
- */
-export declare function handleIdentify(parsed: {
-    context?: string;
-    company?: string;
-    email?: string;
-    forget: boolean;
-}): Promise<void>;
 /**
  * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
  * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`

package/dist/telemetry/feedback-cli.js

@@ -3,7 +3,6 @@ import { AGENT_FLAG, BUG_FLAG, FEEDBACK_KINDS, KIND_FLAG, RATING_FLAG, } from '.
 import { describeFeedbackPayload, submitFeedback } from './feedback.js';
 import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
 import { TelemetryAction } from '../command/cli/cli-parse.js';
-import { clearIdentity, IDENTIFY_NOTICE, readIdentity, saveIdentity, submitIdentity, UsageContextKind, } from './identify.js';
 /**
  * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the feedback channel as a command.
  *
@@ -49,82 +48,6 @@ export async function handleFeedback(text, rating, bug, feedbackKind, agent = fa
     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.
- *
- * Deliberately NOT interactive: a prompt that appears in the middle of someone's work is pressure,
- * and this is the one command where the user must be choosing freely. They type what they want to
- * share, or they never run it at all.
- */
-export async function handleIdentify(parsed) {
-    const line = (s) => {
-        process.stdout.write(`${s}\n`);
-    };
-    if (parsed.forget) {
-        clearIdentity();
-        line('forgotten    the local identity file is deleted; nothing further is sent.');
-        line('             to have what was already sent removed, email support@reticlehq.com');
-        return;
-    }
-    const context = Object.values(UsageContextKind).find((k) => k === parsed.context);
-    if (context === undefined) {
-        const existing = readIdentity();
-        if (existing !== undefined)
-            line(`current      ${JSON.stringify(existing)}`);
-        line(`usage: reticle identify --context <${Object.values(UsageContextKind).join('|')}>`);
-        line('       [--company "Acme"] [--email you@acme.com] [--forget]');
-        line('');
-        line(IDENTIFY_NOTICE);
-        process.exitCode = existing === undefined ? 1 : 0;
-        return;
-    }
-    const identity = {
-        context,
-        ...(parsed.company !== undefined ? { company: parsed.company } : {}),
-        ...(parsed.email !== undefined ? { email: parsed.email } : {}),
-    };
-    line(IDENTIFY_NOTICE);
-    line('');
-    line(`sending      ${JSON.stringify(identity)}`);
-    saveIdentity(identity);
-    const sent = await submitIdentity(identity);
-    line(sent
-        ? 'thanks       saved and sent. we may reach out; `reticle identify --forget` undoes this.'
-        : 'not sent     telemetry is disabled on this machine, so it was saved locally only.');
 }
 /**
  * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.

package/dist/telemetry/feedback.d.ts

@@ -22,6 +22,7 @@
  *      disables it too, since it rides the same emitter.
  */
 import { type Feedback } from '@reticlehq/core/telemetry';
+import { type Telemetry } from './telemetry.js';
 import { type SessionFacts } from './feedback-context.js';
 /** Kills the feedback channel ONLY — adoption counters keep flowing. */
 export declare const FEEDBACK_ENV = "RETICLE_FEEDBACK";
@@ -34,6 +35,12 @@ interface Redaction {
 }
 /** Strip credential/PII shapes and cap the length. Pure — the tests read like a spec of what leaks. */
 export declare function redactFeedbackText(input: string, max: number): Redaction;
+/**
+ * A trace reduced to Reticle's own words, in order: which tools were called and what verdict each
+ * gave. The raw trace is the call/response trail, and the responses carry the page's text and what
+ * was typed into it, which no redaction rule can tell from prose. So nothing else is kept.
+ */
+export declare function summarizeTrace(trace: string): string;
 /** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
 export declare function feedbackDisabled(env?: NodeJS.ProcessEnv): boolean;
 /** What the author supplies; the environment context is detected, never asked for. */
@@ -89,6 +96,12 @@ export declare function submitFeedback(input: FeedbackInput, opts?: {
      */
     background?: boolean;
 }): Promise<FeedbackReceipt>;
+/**
+ * Retry what the outbox holds: the receipt for an undelivered report promises "It will be retried",
+ * and until this ran on daemon start nothing ever read the outbox back. Bounded, sequential, and
+ * best-effort; a report the endpoint does not accept stays queued. Returns how many were delivered.
+ */
+export declare function drainFeedbackOutbox(telemetry?: Telemetry, home?: string): Promise<number>;
 /**
  * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the
  * reticle version, the OS, and whether this is CI. They are the single most-asked question of any bug

package/dist/telemetry/feedback.js

@@ -22,18 +22,77 @@
  *      disables it too, since it rides the same emitter.
  */
 import { FeedbackSchema, FEEDBACK_TEXT_MAX, FEEDBACK_TRACE_MAX, FEEDBACK_FIELD_MAX, TelemetryEventKind, } from '@reticlehq/core/telemetry';
-import { platform } from 'node:os';
+import { homedir, platform } from 'node:os';
 import { getTelemetry } from './telemetry.js';
 import { noteFeedbackUndelivered } from './feedback-delivery.js';
 import { isReticleSourceCheckout } from './dev-repo.js';
 import { saveFeedbackLocally } from './feedback-local.js';
 import { SERVER_VERSION } from '../command/version/identity/server-version.js';
 import { feedbackContext } from './feedback-context.js';
-import { markDelivered, outboxPath, queueFeedback } from './feedback-outbox.js';
+import { markDelivered, outboxPath, queueFeedback, readOutbox } from './feedback-outbox.js';
 /** Kills the feedback channel ONLY — adoption counters keep flowing. */
 export const FEEDBACK_ENV = 'RETICLE_FEEDBACK';
 /** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
 export const REDACTED = '[redacted]';
+/** This machine, as a host: the app under test, never anybody's infrastructure. Port allowed. */
+const LOCAL_HOST = /^(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|0\.0\.0\.0|\[::1\])(?::\d+)?$/i;
+/** A dotted name ending in one of these is a source file, not a host. */
+const FILE_EXTENSIONS = new Set([
+    'ts',
+    'tsx',
+    'mts',
+    'cts',
+    'js',
+    'jsx',
+    'mjs',
+    'cjs',
+    'json',
+    'md',
+    'mdx',
+    'css',
+    'scss',
+    'html',
+    'vue',
+    'svelte',
+    'astro',
+    'py',
+    'rs',
+    'go',
+    'yml',
+    'yaml',
+    'toml',
+    'lock',
+    'log',
+    'txt',
+    'map',
+    'sh',
+    'env',
+    'd',
+]);
+/** Top-level domains common enough that a one-dot name ending in one is a host. */
+const COMMON_TLDS = new Set([
+    'com',
+    'net',
+    'org',
+    'io',
+    'dev',
+    'app',
+    'co',
+    'ai',
+    'cloud',
+    'internal',
+    'local',
+    'corp',
+    'lan',
+    'site',
+    'tech',
+    'xyz',
+    'us',
+    'uk',
+    'de',
+    'in',
+    'eu',
+]);
 /**
  * The shapes that leak. Ordered most-specific first — a URL carrying inline credentials must be
  * caught as a URL before the bare-token rule chews the middle out of it.
@@ -45,6 +104,15 @@ export const REDACTED = '[redacted]';
 const REDACTIONS = [
     // scheme://user:pass@host — the credential is in the authority section.
     { pattern: /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+:[^\s/@]+@/gi, label: 'url-credentials' },
+    // A URL keeps its scheme, and its host and path ONLY when the host is this machine (the app under
+    // test, which is what a report is about). Any other host is a staging site, a customer's domain
+    // or an internal service, so it goes with its path. The query and fragment always go: that is
+    // where ids, emails and tokens ride.
+    {
+        pattern: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/?#"'<>`]+)([^\s?#"'<>`]*)(?:[?#][^\s"'<>`]*)?/gi,
+        label: 'url',
+        replace: (_m, scheme = '', host = '', path = '') => LOCAL_HOST.test(host) ? `${scheme}${host}${path}` : `${scheme}${REDACTED}`,
+    },
     { pattern: /\b[\w.%+-]+@[\w.-]+\.[a-z]{2,}\b/gi, label: 'email' },
     // Credential assignments: the KEY stays (it is the useful part), the VALUE goes. The auth SCHEME
     // (`Bearer`, `Basic`, `Token`) is consumed as part of the value, not left as the value — matching
@@ -59,24 +127,72 @@ const REDACTIONS = [
     { pattern: /\bAKIA[0-9A-Z]{16}\b/g, label: 'aws-key' },
     { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, label: 'slack-token' },
     { pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, label: 'jwt' },
-    // Home directories carry the account name, and a trace is full of them.
-    { pattern: /(?:\/Users\/|\/home\/|[A-Z]:\\Users\\)[^\s/\\:"']+/g, label: 'home-path' },
+    // Home directories carry the account name, and a trace is full of them. The name runs to the next
+    // separator, quote or line end, NOT the next space: `C:\Users\Jane Doe\…` stopped at the space and
+    // sent the surname. Then the rest of the path goes with it. Over-redacting a sentence that follows
+    // a bare home directory is the price, and it is the right way round.
+    {
+        pattern: /(?:\\\\\?\\)?(?:\/Users\/|\/home\/|[A-Za-z]:[\\/]Users[\\/])[^\\/\r\n"'`]+(?:[\\/][^\s\\/"'`]*)*/g,
+        label: 'home-path',
+    },
+    // Any other absolute path: a Windows one (segments may hold spaces when a separator follows)...
+    {
+        pattern: /(?:\\\\\?\\)?\b[A-Za-z]:[\\/](?:[^\\/\r\n"'`<>|*?]+[\\/])*[^\s\\/"'`<>|*?]*/g,
+        label: 'path',
+    },
+    // ...a home-relative one, and a POSIX one of two or more segments. A path is a directory layout,
+    // and a directory layout names clients, projects and people.
+    { pattern: /~[\\/][^\s"'`]*/g, label: 'path' },
+    { pattern: /(?<![\w.~])\/[\w.@+-]+(?:\/[\w.@+-]+)+\/?/g, label: 'path' },
+    {
+        pattern: /\b\d{1,3}(?:\.\d{1,3}){3}\b/g,
+        label: 'ip',
+        replace: (ip) => (LOCAL_HOST.test(ip) ? ip : REDACTED),
+    },
+    // Hostnames: a staging site, an internal service, a customer's domain. A dotted name is a host when
+    // it has two or more dots or ends in a common top-level domain, and never when it ends in a source
+    // file's extension — `vite.config.ts` is what a report is about, `db.internal.acme.com` is not.
+    {
+        pattern: /\b(?:[a-z0-9-]+\.)+[a-z][a-z0-9-]*\b/gi,
+        label: 'hostname',
+        replace: (name) => {
+            const labels = name.toLowerCase().split('.');
+            const last = labels[labels.length - 1] ?? '';
+            if (FILE_EXTENSIONS.has(last))
+                return name;
+            return labels.length > 2 || COMMON_TLDS.has(last) ? REDACTED : name;
+        },
+    },
 ];
 /** Strip credential/PII shapes and cap the length. Pure — the tests read like a spec of what leaks. */
 export function redactFeedbackText(input, max) {
     const removed = new Set();
     let text = input;
-    for (const { pattern, label } of REDACTIONS) {
-        text = text.replace(pattern, (_match, ...groups) => {
-            removed.add(label);
+    for (const { pattern, label, replace } of REDACTIONS) {
+        text = text.replace(pattern, (match, ...groups) => {
+            const captures = groups.map((g) => ('string' === typeof g ? g : ''));
             // A rule with a leading capture keeps it (the scheme, the `api_key=` key) so the reader still
             // sees WHAT was removed, not just that something was.
-            const prefix = 'string' === typeof groups[0] ? groups[0] : '';
-            return `${prefix}${REDACTED}`;
+            const out = replace === undefined ? `${captures[0] ?? ''}${REDACTED}` : replace(match, ...captures);
+            if (out !== match)
+                removed.add(label);
+            return out;
         });
     }
     return { text: text.slice(0, max), removed: [...removed] };
 }
+/** Our words in a trace: tool names and the verdict vocabulary. Nothing else is kept. */
+const TRACE_WORDS = /\breticle_[a-z_]+\b|\b(?:verified|yes|no|unknown|no-fault|ok|passed|failed|refused|error|timeout)\b/gi;
+/**
+ * A trace reduced to Reticle's own words, in order: which tools were called and what verdict each
+ * gave. The raw trace is the call/response trail, and the responses carry the page's text and what
+ * was typed into it, which no redaction rule can tell from prose. So nothing else is kept.
+ */
+export function summarizeTrace(trace) {
+    return (trace.match(TRACE_WORDS) ?? []).join(' ').slice(0, FEEDBACK_TRACE_MAX);
+}
+/** The removal label when a trace lost anything to `summarizeTrace`. */
+const TRACE_VALUES_LABEL = 'trace-values';
 /** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
 export function feedbackDisabled(env = process.env) {
     const value = (env[FEEDBACK_ENV] ?? '').toLowerCase();
@@ -98,6 +214,7 @@ const AUTHOR_WRITTEN_FIELDS = new Set([
     'currentApproach',
     'model',
 ]);
+const TRACE_FIELD = 'trace';
 /** Per-field caps; anything unlisted uses the standard field cap. */
 const FIELD_CAPS = {
     text: FEEDBACK_TEXT_MAX,
@@ -120,14 +237,7 @@ export async function submitFeedback(input, opts = {}) {
     // sk-…" would have shipped the token. Enumerating the fields to protect is the same class of
     // mistake as hand-copying an enum: correct on the day it is written, quietly wrong at the next
     // addition. Deriving the set means a sixth field is covered the moment it exists.
-    const redactions = new Map();
-    for (const [key, value] of Object.entries(input)) {
-        if (typeof value !== 'string' || '' === value)
-            continue;
-        if (!AUTHOR_WRITTEN_FIELDS.has(key))
-            continue;
-        redactions.set(key, redactFeedbackText(value, FIELD_CAPS[key] ?? FEEDBACK_FIELD_MAX));
-    }
+    const redactions = redactAuthorFields(input);
     const body = redactions.get('text') ?? { text: '', removed: [] };
     const redacted = [...new Set([...redactions.values()].flatMap((r) => r.removed))];
     if (feedbackDisabled(env)) {
@@ -231,6 +341,62 @@ export async function submitFeedback(input, opts = {}) {
         context,
     };
 }
+/**
+ * Every author-written field of a report, redacted under the CURRENT rules. One function for the
+ * send and for the outbox drain, so a report queued under older, weaker rules is re-redacted before
+ * it finally goes.
+ */
+function redactAuthorFields(input) {
+    const redactions = new Map();
+    for (const [key, value] of Object.entries(input)) {
+        if (typeof value !== 'string' || '' === value)
+            continue;
+        if (!AUTHOR_WRITTEN_FIELDS.has(key))
+            continue;
+        if (TRACE_FIELD === key) {
+            const summary = summarizeTrace(value);
+            redactions.set(key, {
+                text: summary,
+                removed: summary === value ? [] : [TRACE_VALUES_LABEL],
+            });
+            continue;
+        }
+        redactions.set(key, redactFeedbackText(value, FIELD_CAPS[key] ?? FEEDBACK_FIELD_MAX));
+    }
+    return redactions;
+}
+/** Reports one daemon start retries. A backlog drains over several starts, never in one burst. */
+const OUTBOX_DRAIN_MAX = 5;
+/**
+ * Retry what the outbox holds: the receipt for an undelivered report promises "It will be retried",
+ * and until this ran on daemon start nothing ever read the outbox back. Bounded, sequential, and
+ * best-effort; a report the endpoint does not accept stays queued. Returns how many were delivered.
+ */
+export async function drainFeedbackOutbox(telemetry = getTelemetry(), home = homedir()) {
+    if (!telemetry.enabled || feedbackDisabled())
+        return 0;
+    let delivered = 0;
+    for (const entry of readOutbox(home).slice(0, OUTBOX_DRAIN_MAX)) {
+        const queued = FeedbackSchema.safeParse(entry.payload);
+        // A payload that cannot pass the schema can never be sent; it stays where a person can read it.
+        if (!queued.success)
+            continue;
+        const fields = Object.fromEntries([...redactAuthorFields(queued.data)].map(([key, r]) => [key, r.text]));
+        const parsed = FeedbackSchema.safeParse({ ...queued.data, ...fields });
+        if (!parsed.success)
+            continue;
+        try {
+            if (await telemetry.emit(TelemetryEventKind.FEEDBACK_SUBMITTED, { feedback: parsed.data })) {
+                markDelivered(entry.id, home);
+                delivered += 1;
+            }
+        }
+        catch {
+            /* stays queued for the next start */
+        }
+    }
+    return delivered;
+}
 /**
  * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the
  * reticle version, the OS, and whether this is CI. They are the single most-asked question of any bug

package/dist/telemetry/harness-run.d.ts

@@ -0,0 +1,18 @@
+import { HarnessRunSource, type HarnessRun } from '@reticlehq/core/telemetry';
+import { DriveOrigin, DriveStatus } from '../features/harness/drive-runs.js';
+import { type Telemetry } from './telemetry.js';
+export interface HarnessRunStart {
+    source: HarnessRunSource;
+    hosted: boolean;
+}
+/** Who started it. A saved plan is a plan whoever pressed Run. */
+export declare function harnessRunSource(origin: DriveOrigin, planId: string | undefined): HarnessRunSource;
+/** How a finished run ended, from what the registry recorded. */
+export declare function harnessRunEnd(status: DriveStatus, result: Record<string, unknown> | undefined): Pick<HarnessRun, 'outcome' | 'journeys' | 'replayed'>;
+/** Report the run's start, run it, report its end, and hand back exactly what it did. */
+export declare function reportHarnessRun<T extends {
+    status: DriveStatus;
+    result: Record<string, unknown>;
+}>(start: HarnessRunStart, run: () => Promise<T>, refused: (error: unknown) => boolean, telemetry?: Pick<Telemetry, 'emit'>): Promise<T>;
+/** A run the gate refused before it could start: still somebody who asked for one. */
+export declare function reportHarnessBlocked(start: HarnessRunStart, telemetry?: Pick<Telemetry, 'emit'>): void;

package/dist/telemetry/harness-run.js

@@ -0,0 +1,80 @@
+/**
+ * `harness_run`: the Harness funnel. One `started` and one `completed` per run, whoever started it.
+ *
+ * Emitted around the drive itself (`startDrive`'s run), not read off the tool answer: a drive started
+ * from the HUD is never polled by an agent, and a drive whose daemon is asked again later answers
+ * from disk, so only the run's own start and end see every run exactly once.
+ *
+ * A drive the gate refuses before it starts is still a run somebody asked for, and reports as a
+ * `started` + `completed: blocked` pair, so the funnel's denominator is everyone who pressed Run.
+ */
+import { asRecord } from '@reticlehq/core';
+import { JourneyBy } from '@reticlehq/core/artifacts';
+import { HarnessRunOutcome, HarnessRunPhase, HarnessRunSource, TelemetryEventKind, countBucket, } from '@reticlehq/core/telemetry';
+import { DriveOrigin, DriveStatus } from '../features/harness/drive-runs.js';
+import { getTelemetry } from './telemetry.js';
+const SOURCE_OF = {
+    [DriveOrigin.AGENT]: HarnessRunSource.AGENT,
+    [DriveOrigin.HUD]: HarnessRunSource.HUD,
+    [DriveOrigin.CHAT]: HarnessRunSource.DASHBOARD,
+    [DriveOrigin.TRY]: HarnessRunSource.CLI_TRY,
+};
+/** Who started it. A saved plan is a plan whoever pressed Run. */
+export function harnessRunSource(origin, planId) {
+    return planId === undefined ? SOURCE_OF[origin] : HarnessRunSource.PLAN;
+}
+/** How a finished run ended, from what the registry recorded. */
+export function harnessRunEnd(status, result) {
+    const journeys = Array.isArray(result?.['journeys']) ? result['journeys'] : undefined;
+    const replayed = (journeys ?? []).filter((j) => JourneyBy.REPLAY === asRecord(j)['by']).length;
+    const outcome = DriveStatus.REFUSED === status
+        ? HarnessRunOutcome.BLOCKED
+        : DriveStatus.BROKEN === status
+            ? HarnessRunOutcome.FAILED
+            : DriveStatus.STOPPED === status
+                ? HarnessRunOutcome.STOPPED
+                : true === result?.['proved']
+                    ? HarnessRunOutcome.PROVED
+                    : HarnessRunOutcome.NOT_PROVED;
+    // An unplanned drive is one journey; a refused one drove none.
+    const count = journeys?.length ?? (HarnessRunOutcome.BLOCKED === outcome ? 0 : 1);
+    return { outcome, journeys: countBucket(count), replayed: countBucket(replayed) };
+}
+function emit(telemetry, harness) {
+    try {
+        void telemetry.emit(TelemetryEventKind.HARNESS_RUN, { harness });
+    }
+    catch {
+        /* a metric may never change a drive */
+    }
+}
+/** Report the run's start, run it, report its end, and hand back exactly what it did. */
+export async function reportHarnessRun(start, run, refused, telemetry = getTelemetry()) {
+    emit(telemetry, { phase: HarnessRunPhase.STARTED, ...start });
+    try {
+        const done = await run();
+        emit(telemetry, {
+            phase: HarnessRunPhase.COMPLETED,
+            ...start,
+            ...harnessRunEnd(done.status, done.result),
+        });
+        return done;
+    }
+    catch (error) {
+        emit(telemetry, {
+            phase: HarnessRunPhase.COMPLETED,
+            ...start,
+            ...harnessRunEnd(refused(error) ? DriveStatus.REFUSED : DriveStatus.BROKEN, undefined),
+        });
+        throw error;
+    }
+}
+/** A run the gate refused before it could start: still somebody who asked for one. */
+export function reportHarnessBlocked(start, telemetry = getTelemetry()) {
+    emit(telemetry, { phase: HarnessRunPhase.STARTED, ...start });
+    emit(telemetry, {
+        phase: HarnessRunPhase.COMPLETED,
+        ...start,
+        ...harnessRunEnd(DriveStatus.REFUSED, undefined),
+    });
+}

package/dist/telemetry/hud-events.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The HUD's own events: `hud_viewed` when a page is opened, `hud_signin_prompted` when a sign-in or
+ * link ask is shown. The windowed summary (`hudPanelMs`, `hudJourney`) says how long and in what
+ * order; these say how often and by whom, which a window summed across a session cannot.
+ *
+ * Sent by the daemon, like every HUD measure, so every opt-out applies, and only from the names the
+ * wire schema already narrowed. The dedupe (per tab, per page or surface) lives in `HudMetrics`.
+ */
+import type { HudUseData } from '@reticlehq/core';
+import { type Telemetry } from './telemetry.js';
+/** Count one HUD use from one tab, and send the events it amounts to. */
+export declare function reportHudUse(use: HudUseData, tab: string, telemetry?: Pick<Telemetry, 'emit'>): void;
+/** The tab went into the background or came back: its HUD time pauses while it is hidden. */
+export declare function noteHudTabHidden(tab: string, hidden: boolean): void;
+/** The tab went away. */
+export declare function noteHudTabClosed(tab: string): void;

package/dist/telemetry/hud-events.js

@@ -0,0 +1,27 @@
+import { TelemetryEventKind, countBucket } from '@reticlehq/core/telemetry';
+import { getSessionMetrics } from './session-metrics.js';
+import { getTelemetry } from './telemetry.js';
+/** Count one HUD use from one tab, and send the events it amounts to. */
+export function reportHudUse(use, tab, telemetry = getTelemetry()) {
+    const signals = getSessionMetrics().recordHudUse(use, tab);
+    const tabs = countBucket(signals.tabs);
+    try {
+        if (signals.viewed !== undefined)
+            void telemetry.emit(TelemetryEventKind.HUD_VIEWED, { hud: { view: signals.viewed, tabs } });
+        if (signals.prompted !== undefined)
+            void telemetry.emit(TelemetryEventKind.HUD_SIGNIN_PROMPTED, {
+                hud: { surface: signals.prompted, tabs },
+            });
+    }
+    catch {
+        /* a metric may never change behaviour */
+    }
+}
+/** The tab went into the background or came back: its HUD time pauses while it is hidden. */
+export function noteHudTabHidden(tab, hidden) {
+    getSessionMetrics().setHudTabHidden(tab, hidden);
+}
+/** The tab went away. */
+export function noteHudTabClosed(tab) {
+    getSessionMetrics().closeHudTab(tab);
+}